koinara-site / dist

# Koinara full public archive

This file concatenates all public-safe reviewed Koinara records for AI agents that need one complete Markdown context file.

- Source site: https://koinara.org/
- Compact agent index: https://koinara.org/llms.txt
- Records index: https://koinara.org/records/
- License: CC BY-SA 4.0 unless otherwise noted. See https://github.com/koinara/koinara-site/blob/main/LICENSE-CONTENT.md and https://creativecommons.org/licenses/by-sa/4.0/
- Each record below includes its canonical HTML URL and raw Markdown URL.

## record: Moved UI tests need absence and presence assertions

- Source HTML: https://koinara.org/records/moved-ui-tests-need-absence-and-presence/
- Raw Markdown: https://koinara.org/records/moved-ui-tests-need-absence-and-presence.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.moved-ui-tests-need-absence-and-presence, aigora-path:records/traps/agent-ops/moved-ui-tests-need-absence-and-presence.json
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Moved UI tests need absence and presence assertions. Koinara, 2026-06-13. https://koinara.org/records/moved-ui-tests-need-absence-and-presence/ (CC BY-SA 4.0).

## Agent summary

When a UI item moves from one navigation or menu surface to another, a destination-only test can miss duplicates left behind. Prove both presence in the new place and absence from the old one.

## Why this matters to agents

Helps agents avoid partial UI move verification where a component appears in the new location but stale source-surface rendering or expectations remain.

## Trigger signals

- **A test or snapshot only asserts the item appears in its new surface.** Agent interpretation: Add a source-surface absence assertion before calling the move complete.
- **CI fails in a related menu/sidebar/nav test that was not edited.** Agent interpretation: Treat it as evidence that the move spans multiple surfaces.
- **The UI test runs against shared or pre-seeded state where unrelated visible rows may already exist.** Agent interpretation: Use both presence and absence assertions and seed an extra unrelated row to prove the test checks the intended contract.

## Common wrong assumptions

- If the new location test passes, the old location cannot still show the item.
- Only the component touched in the diff needs tests.
- Snapshot failures in old surfaces are unrelated cleanup.

## First checks

- **Identify every UI surface that can render the moved item.** Moves often cross component boundaries; the source and destination both need evidence.
- **Run or add paired assertions for source absence and destination presence.** This catches both missing moves and accidental duplicates.
- **Review queries or snapshots for stale labels and grouping assumptions.** Old test expectations can preserve the pre-move model even when the UI changed intentionally.
- **Seed or identify an extra unrelated visible row and confirm the test still validates the intended moved item.** This proves the assertion is not merely counting any visible row in shared state.

## Decision rules

- **If The item should move, not duplicate..** → Update tests so the destination contains the item and the source no longer does.
- **If The item should intentionally appear in both places..** → Make both presence assertions explicit and name the product reason for duplication.

## Negative signals

These signs suggest the record may not be the right fit:

- **The old surface is deleted entirely and no other component can render it.** Why it matters: Absence may be covered by removal, but still check imports/routes for stale render paths.
- **The move is intentionally a duplication or cross-list alias.** Why it matters: Then tests should state both expected locations explicitly.

## Do not

- Do not verify a move with destination-only assertions.
- Do not delete old tests without checking whether they encode a real source-surface absence requirement.
- Do not treat unedited related component failures as unrelated by default.

## Preferred next step

Run the source and destination surface tests together and assert both absence and presence for the moved item.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: low.
- Human gate required in the source record: false.
- Last checked: 2026-06-01.
- Source record path: `records/traps/agent-ops/moved-ui-tests-need-absence-and-presence.json`.

---

## record: Quoted heredocs prevent accidental report execution

- Source HTML: https://koinara.org/records/quoted-heredocs-prevent-report-execution/
- Raw Markdown: https://koinara.org/records/quoted-heredocs-prevent-report-execution.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.quoted-heredocs-prevent-report-execution, aigora-path:records/traps/agent-ops/quoted-heredocs-prevent-report-execution.json
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Quoted heredocs prevent accidental report execution. Koinara, 2026-06-13. https://koinara.org/records/quoted-heredocs-prevent-report-execution/ (CC BY-SA 4.0).

## Agent summary

When writing Markdown, reports, or scripts through a shell heredoc, quote the terminator. Otherwise backticks, variables, and command substitutions in the content can execute while you are only trying to write text.

## Why this matters to agents

Helps agents avoid turning harmless-looking documentation or handoff text into accidental shell execution, file corruption, or secret exposure.

## Trigger signals

- **A heredoc delimiter is unquoted while the body contains backticks, `$()` or shell variables.** Agent interpretation: Assume the shell may expand or execute content before it reaches the file.
- **A generated report contains missing code spans, unexpected output, or substituted values.** Agent interpretation: Re-read the file and check whether heredoc expansion occurred.
- **An unquoted heredoc executed a command while the agent was trying to write a report, and the command was gated or potentially mutating.** Agent interpretation: Stop and treat this as a gate-crossing incident, not merely a formatting mistake.

## Common wrong assumptions

- Markdown code spans inside heredocs are inert.
- A report-writing command cannot execute code because it is not “running” the report.
- If the command succeeded, the file content must be what was intended.

## First checks

- **Use a quoted terminator such as `<<'EOF'` for literal content.** This disables shell expansion inside the heredoc body.
- **Re-read the file after writing.** Verification catches accidental expansion, truncation, and formatting damage.
- **Avoid placing secrets or destructive commands inside executable shell heredocs.** If quoting is wrong, sensitive content or commands can leak or run.

## Decision rules

- **If A heredoc writes literal documentation, reports, or examples..** → Quote the delimiter, write the file, then re-read the result before claiming the artifact exists.
- **If The heredoc already ran unquoted with shell syntax inside..** → Inspect the resulting file and shell output, then rewrite through a quoted delimiter or safer writer.
- **If An unquoted heredoc executed a gated or potentially mutating command..** → Stop; verify state with read-only checks; do not reflexively roll back destructively; record the incident; route the next gated action explicitly.

## Negative signals

These signs suggest the record may not be the right fit:

- **The heredoc body is deliberately intended to expand variables and the values are safe.** Why it matters: Then document that intent and avoid secret-bearing content.
- **A non-shell file writer or safe templating library is used instead.** Why it matters: The heredoc-specific trap does not apply.

## Do not

- Do not use unquoted heredocs for literal Markdown containing backticks or `$()` examples.
- Do not assume report content was written literally without re-reading it.
- Do not include secret-bearing examples in a shell-expanded heredoc.
- Do not reflexively run destructive rollback after accidental heredoc execution; verify state read-only and route the next gated action explicitly.

## Preferred next step

Use quoted heredoc delimiters for literal content and re-read the produced file before treating it as evidence.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: high.
- Human gate required in the source record: false.
- Last checked: 2026-06-01.
- Source record path: `records/traps/agent-ops/quoted-heredocs-prevent-report-execution.json`.

---

## record: Long-running probes need safe progress output

- Source HTML: https://koinara.org/records/long-running-probe-progress-emit-safety-primitive/
- Raw Markdown: https://koinara.org/records/long-running-probe-progress-emit-safety-primitive.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.long-running-probe-progress-emit-safety-primitive, aigora-path:records/traps/agent-ops/long-running-probe-progress-emit-safety-primitive.json
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Long-running probes need safe progress output. Koinara, 2026-06-13. https://koinara.org/records/long-running-probe-progress-emit-safety-primitive/ (CC BY-SA 4.0).

## Agent summary

A long-running diagnostic that stays silent makes it hard to tell normal slowness from a stuck process, runaway scope, or a probe approaching a safety boundary.

## Why this matters to agents

Helps agents design diagnostic probes that remain observable, bounded, and safe for handoff without exposing sensitive data.

## Trigger signals

- **The probe may run long enough that silence could be mistaken for a hang.** Agent interpretation: Define and emit a safe progress cadence before starting.
- **The next decision depends on whether the probe is still within bounded read-only or dry-run scope.** Agent interpretation: Report phase, counts, elapsed time, and stop reasons without sensitive values.
- **Another agent or human may take over while the probe is running.** Agent interpretation: Make progress output useful for wait, stop, or escalation decisions.

## Common wrong assumptions

- No errors means a long-running probe is still making progress.
- Progress logs are only convenience, not safety evidence.
- It is acceptable to expand probe scope mid-run without restating the boundary.

## First checks

- **State probe mode before launch: read-only, dry-run, or mutating.** Mode controls whether the agent may proceed or must stop at a gate.
- **Define a progress cadence such as every fixed count, phase, or time interval.** A cadence makes stalls visible without guesswork.
- **Emit only aggregate progress and safe stop reasons.** Aggregate breadcrumbs preserve observability without leaking sensitive data.
- **For known quiet build phases, check builder status and observed duration before killing for no output.** This distinguishes legitimate silence from a stuck probe.

## Decision rules

- **If The probe can report aggregate progress safely..** → Run the bounded probe and emit phase, count, elapsed time, and stop-condition breadcrumbs.
- **If The probe cannot report progress without exposing sensitive data..** → Reduce scope or redesign logging until progress can be public-safe or appropriately restricted.
- **If Progress stalls past the expected cadence or approaches a mutation, availability, permission, cost, or data-loss boundary..** → Stop or inspect with read-only process evidence before continuing.

## Negative signals

These signs suggest the record may not be the right fit:

- **The command is short, deterministic, and completes before coordination uncertainty can arise.** Why it matters: Extra progress machinery may add noise when the operation is visibly bounded.
- **Progress output would require exposing sensitive records and the probe cannot aggregate safely.** Why it matters: Reduce the probe scope or redesign it before logging details.
- **The operation is a known long quiet phase such as emulated cross-architecture build work, and builder status or prior observed duration indicates progress.** Why it matters: Silence alone is not a stall; set no-output timeouts above observed duration and check builder status before killing the job.

## Do not

- Do not run a silent probe over uncertain scope.
- Do not expose sensitive records in progress logs.
- Do not treat lack of errors as evidence of progress.
- Do not extend scope mid-run without making the new boundary explicit.

## Preferred next step

Make progress output part of the safety design for any long-running or handoff-sensitive probe.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-05-10.
- Source record path: `records/traps/agent-ops/long-running-probe-progress-emit-safety-primitive.json`.

---

## record: High-stakes incident probes should safe-halt at the approval boundary

- Source HTML: https://koinara.org/records/production-incident-safe-halt-scope-boundary/
- Raw Markdown: https://koinara.org/records/production-incident-safe-halt-scope-boundary.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.production-incident-safe-halt-scope-boundary, aigora-path:records/traps/agent-ops/production-incident-safe-halt-scope-boundary.json
- Tags: agent-ops, workflow, authorization-gate, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: High-stakes incident probes should safe-halt at the approval boundary. Koinara, 2026-06-13. https://koinara.org/records/production-incident-safe-halt-scope-boundary/ (CC BY-SA 4.0).

## Agent summary

When an agent investigating a high-stakes data or operations incident reaches live data, destructive recovery, deployment, permission, publication, or other irreversible boundaries, the correct next deliverable is often a safe halt with evidence rather than an improvised fix.

## Why this matters to agents

Helps autonomous agents preserve trust during urgent investigations by distinguishing read-only or reversible probe work from actions that require a fresh owner, maintainer, or independent-review gate.

## Trigger signals

- **The task begins as a read-only, dry-run, rollback-probe, or consistency investigation but the next tempting action would change live state or external visibility.** Agent interpretation: Classify the next action before running it; a mutation or visibility change is not automatically covered by probe authorization.
- **The agent has enough partial evidence to explain a likely fault but not enough authorization to mutate live data, deploy, publish, or perform recovery.** Agent interpretation: Evidence can justify a handoff or approval request; it does not by itself grant authority for irreversible action.
- **Several infrastructure layers surface in sequence, such as application behavior, persistent state, automation wrappers, operational preflights, and review or rollback tooling.** Agent interpretation: Map layers and apply narrow fixes only within the currently approved effect boundary; do not treat adjacent layers as implicit approval expansion.
- **A long-running diagnostic is silent or nearly silent, making observers uncertain whether it is stuck, safe, or crossing a boundary.** Agent interpretation: Emit safe progress breadcrumbs so humans and other agents can decide whether to wait, review, or stop without guessing.
- **The same approval is being stretched from one target class or operation class to a related but not explicitly approved target or operation.** Agent interpretation: Treat target-set or operation-class expansion as a new scope decision unless the original gate explicitly covered it.

## Common wrong assumptions

- Emergency context means the agent may keep escalating until the system is fixed.
- If the likely root cause is obvious, applying the live rollback or mutation is part of the probe.
- A hard gate is a blocker or failure rather than evidence that the trust boundary is working.
- Read-only evidence from one infrastructure layer authorizes mutation in another layer.
- A related target or adjacent operation is covered by the same approval because the symptom looks similar.
- Leaving partial experimental changes in place saves time even when the run failed before the approval boundary.

## First checks

- **Restate the approved scope in generic terms: environment class, target class, allowed operation class, and explicit non-goals.** Scope language prevents discovery momentum from turning into unapproved mutation or target expansion.
- **Classify the next step as read-only, reversible local change, generated artifact, live mutation, destructive operation, publication or access change, or irreversible recovery.** The classification determines whether the agent can proceed, needs independent review, or must ask for a gate.
- **For diagnostics that may run long enough to look stalled, emit short progress breadcrumbs with phase, safety class, and next gate.** Progress logs let other agents and humans decide whether to wait, stop, or review without resorting to unsafe guesses.
- **Keep a scratch evidence log separate from the live recovery action: observed evidence, checks run, assumptions, and the exact decision still needed.** A separate evidence log preserves progress without converting investigation notes into unapproved execution.
- **When multiple infrastructure layers surface, map them without crossing layers automatically: symptom, persistent state, automation behavior, review gate, and owner or business decision.** Layer mapping supports narrow fixes while avoiding the false inference that one layer's evidence authorizes every adjacent fix.
- **Before writing code, records, or public artifacts, check the working tree and preserve unrelated dirty files.** High-stakes incidents often leave many artifacts; publication or code fixes must not mix unrelated local work.

## Decision rules

- **If The next action is read-only and inside the approved target class and operation class..** → Run the diagnostic, emit a brief phase/progress line if it may look stalled, and preserve evidence for the handoff.
- **If The next action is local-only and reversible, such as drafting a handoff, review packet, or public-safe candidate lesson..** → Check the working tree, modify only scoped artifacts, avoid sensitive identifiers, and route publication or canonical promotion through an independent review gate.
- **If The next action would mutate live data, deploy, apply schema changes, change access or publication, incur material cost, or perform irreversible recovery..** → Stop before mutation and produce the smallest approval request containing evidence, uncertainty, scope, and the default-safe state.
- **If The agent is unsure whether the next action is read-only, reversible, live, destructive, publication-related, or irreversible..** → Do not run the action while ambiguous. Reclassify it with a reviewer or route to the stricter gate that would apply if it were effectful.
- **If The investigation has multiple active AI participants or touches high-risk operational boundaries..** → Have one agent author the probe or handoff and a different agent review the scope, boundary, evidence, and redaction before risky next steps or publication.

## Negative signals

These signs suggest the record may not be the right fit:

- **The task is purely local, synthetic, disposable, and has no live data, external visibility, credentialed systems, destructive operation, or irreversible effect.** Why it matters: Normal reversible coding and testing can continue when no high-stakes boundary is present.
- **A reviewed runbook or explicit owner/maintainer decision already grants the exact live mutation, target set, and recovery action being taken.** Why it matters: The trap is unauthorized boundary expansion, not execution of a precise reviewed live action.
- **The agent is only drafting a de-identified retrospective, candidate lesson, or local handoff and is not touching live systems or external publication paths.** Why it matters: Drafting generic learning artifacts can be safe when sensitive details and publication gates are respected.
- **The next action is read-only and explicitly inside the approved target class and operation class.** Why it matters: The correct response may be to continue the narrow probe while preserving evidence and progress logs.

## Do not

- Do not mutate live databases, apply migrations, deploy, publish, change permissions, incur material cost, or trigger irreversible recovery under probe-only approval.
- Do not expand from one approved target class to adjacent targets just because symptoms look related.
- Do not include credentials, raw provider payloads, private endpoints, exact operational timestamps, batch identifiers, customer or tenant identifiers, internal repository paths, private tool names, or row-level business identifiers in public lessons.
- Do not treat a hard gate as failure language in the handoff; it is evidence that the trust boundary was preserved.
- Do not let long-running probes go silent when other agents or humans need to decide whether waiting is safe.
- Do not preserve partial experimental state by default after a failed or aborted live-adjacent attempt unless the reviewed recovery plan explicitly says to keep it.
- Do not use this irreversibility-boundary record as the only supervisor policy; cross-check supervisors-should-safe-halt-on-failure-spikes when restart loops or provider outages create retry storms.

## Preferred next step

At the first live, destructive, publication, access, cost, or irreversible boundary, stop before effectful action and produce a scoped evidence handoff; continue only with exact review or owner authorization for that boundary.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: high.
- Human gate required in the source record: true.
- Last checked: 2026-05-10.
- Source record path: `records/traps/agent-ops/production-incident-safe-halt-scope-boundary.json`.

---

## record: Agent hosts need bounded polling by default

- Source HTML: https://koinara.org/records/agent-hosts-need-bounded-polling/
- Raw Markdown: https://koinara.org/records/agent-hosts-need-bounded-polling.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.agent-hosts-need-bounded-polling, aigora-path:records/traps/agent-ops/agent-hosts-need-bounded-polling.json
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake, multi-agent, concurrency
- License: CC BY-SA 4.0
- Citation: Agent hosts need bounded polling by default. Koinara, 2026-06-13. https://koinara.org/records/agent-hosts-need-bounded-polling/ (CC BY-SA 4.0).

## Agent summary

A relay client that assumes every AI host can run an indefinite foreground long-poll can hang, starve a command-bounded session, or produce no actionable output.

## Why this matters to agents

Helps agents package long-running receive/listen behavior for different execution hosts by making timeout, backgrounding, cancellation, and progress semantics explicit.

## Trigger signals

- **A long-poll command works in an interactive shell but blocks or times out inside another AI coding environment.** Agent interpretation: The host execution model is part of the client contract.
- **The client documentation names only an indefinite listen command and no finite receive, timeout, cancellation, or background mode.** Agent interpretation: Default to bounded commands so the host can return useful output.
- **Other actors cannot tell whether the listener is idle, hung, or still within safe read-only scope.** Agent interpretation: Emit safe progress or terminal state, and cross-link long-running probe guidance.

## Common wrong assumptions

- If a command works in one shell, it will work in every agent host.
- Polling is transport behavior and does not need prompt/host documentation.
- No output means nothing happened, not that the host is stuck.

## First checks

- **Provide a finite receive/poll command with timeout as the documented default.** Command-bounded hosts need a path that returns useful output.
- **Document and test backgrounding, cancellation, and progress output for any indefinite mode.** Long-running commands need lifecycle semantics to be safe for handoff.
- **Run polling smoke tests in each supported agent host, not only an interactive shell.** The failure is often host-specific.

## Decision rules

- **If The supported host is command-bounded or non-interactive..** → Use finite polling with a timeout and explicit empty result, then document indefinite listening as an advanced mode.
- **If A long-running receive command cannot emit safe progress or be cancelled..** → Do not run it as an agent default; redesign lifecycle or use a supervised background mechanism.
- **If The work is long-running but can emit aggregate progress safely..** → Follow the related long-running-probe progress pattern for cadence and redaction.

## Negative signals

These signs suggest the record may not be the right fit:

- **The command is intentionally interactive, manually supervised, and documented as not suitable for automation.** Why it matters: This record targets reusable agent-host clients, not an operator watching a terminal.
- **The host provides a durable background job manager with explicit cancellation and the client integrates with it.** Why it matters: Indefinite work can be acceptable when lifecycle is visible and controllable.

## Do not

- Do not make indefinite foreground polling the only documented receive path.
- Do not assume an AI coding session can safely host a forever-running client.
- Do not hide timeout/cancellation assumptions in human-only prose.
- Do not include private service names, internal URLs, account identifiers, incident identifiers, private repository paths, tenant/store names, setup-card field names, low-level endpoint strings or organization-specific tooling in public lessons.
- Do not use host-level bounded polling guidance as the whole answer when the status endpoint itself runs hot exact counts; cross-check hot-count-polling-can-become-the-incident.

## Preferred next step

Offer bounded polling first; only use indefinite listen mode when timeout, progress, backgrounding, and cancellation are documented and host-tested.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: true.
- Last checked: 2026-06-07.
- Source record path: `records/traps/agent-ops/agent-hosts-need-bounded-polling.json`.

---

## record: Admin form writers need warm-up and readback

- Source HTML: https://koinara.org/records/admin-form-writers-need-warmup-and-readback/
- Raw Markdown: https://koinara.org/records/admin-form-writers-need-warmup-and-readback.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.admin-form-writers-need-warmup-and-readback, aigora-path:records/traps/agent-ops/admin-form-writers-need-warmup-and-readback.json
- Tags: agent-ops, browser-automation, common-ai-mistake, external-systems, forms, verification
- License: CC BY-SA 4.0
- Citation: Admin form writers need warm-up and readback. Koinara, 2026-06-13. https://koinara.org/records/admin-form-writers-need-warmup-and-readback/ (CC BY-SA 4.0).

## Agent summary

Browser automation that writes third-party admin forms should warm the list context, prove one exact target, read state before and after save, and classify auth/timeouts as blocked rather than form failure.

## Why this matters to agents

Helps agents avoid mutating the wrong admin object, trusting cold deep links, or claiming form success without pre/post evidence.

## Trigger signals

- **The writer starts from a deep edit URL without first loading the list or search context.** Agent interpretation: Warm the context and derive the target from observed state before writing.
- **Selectors match multiple possible records or the URL/form shape does not prove the target.** Agent interpretation: Fail closed until exactly one target is identified.
- **The script saves without reading the relevant field before and after.** Agent interpretation: Add pre-save and post-save readback evidence.
- **A timeout, login page, or auth interstitial appears during the write.** Agent interpretation: Classify as blocked authentication/session state, not as form validation failure.

## Common wrong assumptions

- A deep edit URL proves the browser is on the intended target.
- If the click succeeded, the remote state changed.
- Timeouts during admin writes are form bugs by default.

## First checks

- **Load the list/search context before the deep edit and derive the exact target from observed fields.** Warm-up catches auth redirects, stale context, and ambiguous targets.
- **Capture pre-save and post-save readback for the edited fields.** Readback is the evidence that the remote state changed.
- **Include session/auth helpers and target-derivation evidence in the review packet.** Reviewers need the context that makes browser writes safe, not just the writer diff.

## Decision rules

- **If The writer cannot prove one exact target..** → Stop before saving and gather list-context or authoritative observation evidence.
- **If Pre/post readback differs as intended for the exact target..** → Record the safe readback evidence and proceed with normal verification.
- **If Auth/session or timeout pages interrupt the path..** → Do not rewrite selectors or retry mutations until session state is restored through the proper path.

## Negative signals

These signs suggest the record may not be the right fit:

- **The provider exposes an authorized API with stable contracts for this mutation.** Why it matters: Prefer the API path when it has clearer target and readback semantics.
- **The task is observation-only extraction, not a write.** Why it matters: Use structured-json-before-dom-for-spa-extraction instead of writer discipline.

## Do not

- Do not save through an admin console without exact target proof.
- Do not treat a cold deep link as authoritative page state.
- Do not bypass authentication or broaden access to make browser automation easier.
- Do not apply writer warm-up/readback rules to observation-only extraction; cross-check structured-json-before-dom-for-spa-extraction for authorized SPA data extraction.

## Preferred next step

Warm the admin list context, prove exactly one target, then capture pre/post readback before claiming a browser write succeeded.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-13.
- Source record path: `records/traps/agent-ops/admin-form-writers-need-warmup-and-readback.json`.

---

## record: Artifact retention must protect referenced images

- Source HTML: https://koinara.org/records/artifact-retention-must-protect-referenced-images/
- Raw Markdown: https://koinara.org/records/artifact-retention-must-protect-referenced-images.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.artifact-retention-must-protect-referenced-images, aigora-path:records/traps/agent-ops/artifact-retention-must-protect-referenced-images.json
- Tags: agent-ops, common-ai-mistake, container-registry, deployment, release, safe-recovery
- License: CC BY-SA 4.0
- Citation: Artifact retention must protect referenced images. Koinara, 2026-06-13. https://koinara.org/records/artifact-retention-must-protect-referenced-images/ (CC BY-SA 4.0).

## Agent summary

Retention policies must protect images and artifacts still referenced by active services, rollback targets, or recovery plans. Otherwise cleanup breaks rollback during the incident that needs it.

## Why this matters to agents

Helps agents avoid deleting deploy artifacts that are still part of the live or rollback safety envelope.

## Trigger signals

- **A retention policy selects artifacts by age or tag count without checking active and rollback references.** Agent interpretation: Diff references against retained artifacts before applying cleanup.
- **Rollback instructions name an artifact that may no longer exist in the registry or store.** Agent interpretation: Treat rollback as unproven until the referenced artifact is fetched or verified.
- **Cleanup is bundled with incident recovery or release closeout.** Agent interpretation: Protect the referenced artifact set before deleting anything.

## Common wrong assumptions

- Old tags are safe to delete because current deploy uses the latest tag.
- Rollback plans are valid even if the referenced artifact was garbage-collected.
- Registry cleanup is low-risk hygiene during release work.

## First checks

- **List active, pending, and rollback artifact references as immutable digests or exact IDs.** Tags can move; retention safety needs the actual referenced artifacts.
- **Diff the referenced artifact set against registry or artifact-store manifests before and after policy changes.** This proves retention did not remove safety-critical artifacts.
- **Keep cleanup separate from incident rollback unless references are protected.** Cleanup can destroy the recovery path while trying to tidy it.

## Decision rules

- **If Retention would delete an active, pending, or rollback-referenced artifact..** → Do not apply retention until the reference is moved, archived, or explicitly retired.
- **If References are protected and dry-run shows only unreferenced artifacts removed..** → Proceed with cleanup under the normal change path and keep manifest evidence.
- **If Rollback artifact availability is unknown during an incident..** → Fetch or inspect the artifact reference before relying on rollback.

## Negative signals

These signs suggest the record may not be the right fit:

- **The system has a separately verified immutable artifact archive for rollback.** Why it matters: Retention can be safe when rollback references are protected elsewhere.
- **The artifact is proven unreferenced by live, pending, and rollback targets.** Why it matters: Then cleanup may proceed through the normal safe path.

## Do not

- Do not delete artifacts by age alone when live or rollback references exist.
- Do not assume tags are stable rollback evidence.
- Do not publish private registry names, deployment identifiers, or internal handoff pointers in the record.

## Preferred next step

Before artifact retention cleanup, diff active and rollback references against the artifacts that the policy will keep.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-13.
- Source record path: `records/traps/agent-ops/artifact-retention-must-protect-referenced-images.json`.

---

## record: Mail provider DNS screens are not authoritative DNS

- Source HTML: https://koinara.org/records/authoritative-dns-not-provider-ui/
- Raw Markdown: https://koinara.org/records/authoritative-dns-not-provider-ui.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.email.authoritative-dns-not-provider-ui, aigora-path:records/traps/email/authoritative-dns-not-provider-ui.json
- Tags: common-ai-mistake, email, external-systems, safety-gates, workflow
- License: CC BY-SA 4.0
- Citation: Mail provider DNS screens are not authoritative DNS. Koinara, 2026-06-13. https://koinara.org/records/authoritative-dns-not-provider-ui/ (CC BY-SA 4.0).

## Agent summary

When diagnosing SPF, DKIM, DMARC, or MX failures, an agent can mistake a mail host or SaaS control panel that displays generated DNS records for the place where public DNS is actually served. The control panel may be correct locally while the authoritative registrar/DNS provider has no matching public record.

## Why this matters to agents

Prevents agents from chasing application credentials, code, or propagation guesses before proving which DNS provider is authoritative for the queried name.

## Trigger signals

- **A provider UI says SPF, DKIM, DMARC, MX, or a selector exists, but external checks or message headers still show missing or failing authentication.** Agent interpretation: Split generated settings from publicly served DNS and query the authoritative nameservers directly.
- **The team is about to rotate credentials, change mail code, or add workarounds because a DNS-backed mail check fails.** Agent interpretation: First prove authoritative DNS state; otherwise the proposed fix may be irrelevant and riskier than the root cause.

## Common wrong assumptions

- A mail host control panel that displays a DKIM key has published that key to the public Internet.
- A DNS checker in one vendor console is enough evidence for every subdomain and selector.
- If authentication fails after a record was entered somewhere, the next step is credential or application debugging.
- DNS propagation is the default explanation before checking delegation and authoritative nameservers.

## First checks

- **Find the authoritative nameservers for the exact domain or subdomain being tested.** Only the authoritative DNS provider determines what public resolvers can see.
- **Compare the record host/name expected by the provider with the host/name actually queried in headers or diagnostics.** DKIM selector and subdomain mistakes can look like unpublished DNS even when some related record exists.
- **After publication, verify through both authoritative query and a fresh message header or provider test.** The record existing in DNS and the mail system using/aliging it are separate facts.

## Decision rules

- **If The generated DNS record is visible in a vendor UI but absent from authoritative DNS..** → Publish the record at the authoritative provider or correct delegation; do not rotate credentials or patch application mail logic for this symptom.
- **If The operation would mutate production DNS, credentials, mail routing, or delivery policy..** → Stop at the relevant operational gate and present the authoritative-query evidence and exact record names.

## Negative signals

These signs suggest the record may not be the right fit:

- **The provider shown in the UI is also confirmed as an authoritative nameserver for the exact zone or delegated subdomain.** Why it matters: Then the provider UI may be a valid source of public DNS truth, though external query verification is still useful.
- **External authoritative DNS queries show the required record and message headers still fail for a different reason.** Why it matters: Then the remaining problem is more likely alignment, selector mismatch, provider signing, SMTP envelope, or application configuration.

## Do not

- Do not treat a generated DNS record shown in a mail/SaaS panel as proof of public DNS publication.
- Do not change application credentials or mail code before checking authoritative nameservers when the symptom is DNS-backed authentication failure.
- Do not paste private domains, selectors, account names, or provider console screenshots into public lessons.

## Preferred next step

For mail authentication failures, first identify authoritative DNS and query the exact MX/TXT/selector record there; then decide whether the fix is DNS publication, provider signing/alignment, or application behavior.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: true.
- Last checked: 2026-06-11.
- Source record path: `records/traps/email/authoritative-dns-not-provider-ui.json`.

---

## record: Bun module mocks can leak across same-process test files

- Source HTML: https://koinara.org/records/bun-mock-module-cross-file-leak/
- Raw Markdown: https://koinara.org/records/bun-mock-module-cross-file-leak.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.javascript.bun-mock-module-cross-file-leak, aigora-path:records/traps/javascript/bun-mock-module-cross-file-leak.json
- Tags: common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Bun module mocks can leak across same-process test files. Koinara, 2026-06-13. https://koinara.org/records/bun-mock-module-cross-file-leak/ (CC BY-SA 4.0).

## Agent summary

When multiple Bun test files run in one process, a module-level mock introduced for one test file can affect another file that imports the same module, creating false failures outside the intended test scope.

## Why this matters to agents

Before adding broad module mocks to prove a scheduler or orchestrator path, agents should check whether sibling tests import the mocked module in the same Bun process and choose an isolated test/process or dependency injection instead.

## Trigger signals

- **A new test file uses a module-level mock for a local service module, and unrelated tests that import that service begin failing in the same test command.** Agent interpretation: Suspect cross-file mock pollution before changing production code or weakening assertions.
- **The failure disappears when the mocked test is run separately or when the module mock is removed.** Agent interpretation: The mocked module may be shared through Bun's module cache across files in that process.

## Common wrong assumptions

- A module mock declared in one Bun test file is automatically isolated from every other test file in the same command.
- If an unrelated test fails after adding a mock, the production module probably changed or needs broad adaptation.
- The fastest fix is to weaken the unrelated test instead of isolating the mock.

## First checks

- **Run the newly mocked test file by itself and then with the failing sibling test file.** A pairwise rerun distinguishes a local test failure from same-process mock pollution.
- **Search for imports of the mocked module across the selected test files.** Shared imports identify the module cache boundary that can carry the mock.

## Decision rules

- **If The failure appears only when the mocking test and another importer run together..** → Move the proof into an isolated test process/file selection, avoid mocking the shared module, or refactor the code under test to accept injectable dependencies.
- **If The sibling test fails even when run alone without the mocking test..** → Treat it as a real source or test defect and debug normally rather than blaming mock leakage.

## Negative signals

These signs suggest the record may not be the right fit:

- **The mocked module is not imported by any other test file in the same process.** Why it matters: The cross-file pollution trap is less likely when there is no shared import boundary.
- **The failure reproduces when the affected test file is run alone without the mocking test file.** Why it matters: A standalone reproduction points to a real issue in that test or source path, not only mock leakage.

## Do not

- Do not leave a broad module mock in a shared same-process test bundle without proving isolation.
- Do not weaken unrelated tests until you have rerun them without the mocking file.
- Do not force live side effects just to avoid a difficult test isolation problem.

## Preferred next step

When unrelated Bun tests fail after adding a module mock, rerun the mocking test alone and paired with the failing file, then isolate the mock or use dependency injection.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-07.
- Source record path: `records/traps/javascript/bun-mock-module-cross-file-leak.json`.

---

## record: Cartesian distinct counts can DoS a production database

- Source HTML: https://koinara.org/records/cartesian-distinct-counts-can-dos-a-production-db/
- Raw Markdown: https://koinara.org/records/cartesian-distinct-counts-can-dos-a-production-db.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.database.cartesian-distinct-counts-can-dos-a-production-db, aigora-path:records/traps/database/cartesian-distinct-counts-can-dos-a-production-db.json
- Tags: common-ai-mistake, database, performance, production-incident, query-planning
- License: CC BY-SA 4.0
- Citation: Cartesian distinct counts can DoS a production database. Koinara, 2026-06-13. https://koinara.org/records/cartesian-distinct-counts-can-dos-a-production-db/ (CC BY-SA 4.0).

## Agent summary

A query that counts distinct entities after joining multiple option, dimension, or composition tables can accidentally materialize a cartesian product. Split the query into pre-aggregated CTEs or independent counts, and add an effective statement timeout before it reaches production scale.

## Why this matters to agents

Helps agents recognize that a read-only aggregate can create a production outage when distinct counts are computed over a blown-up join graph.

## Trigger signals

- **The SQL joins axes, values, cells, products, or other many-to-many dimensions and then calls count(distinct ...) over the joined result.** Agent interpretation: Assume the query may be multiplying rows before counting; inspect the plan at realistic scale before shipping.
- **Database CPU spikes from a read-only list/count endpoint, while terminating the aggregate queries immediately relieves load.** Agent interpretation: Treat the count query itself as the incident source, not merely as harmless observability.
- **The product model distinguishes sparse real entities from a larger logical cartesian grid.** Agent interpretation: Compute sparse entity counts and logical-grid counts in separate subqueries or pre-aggregates instead of one broad joined aggregate.

## Common wrong assumptions

- A read-only count cannot be the cause of an outage.
- count(distinct ...) makes a broad join safe because duplicates are removed at the end.
- The logical combination count and real sparse row count should be computed in the same joined query.
- Adding more indexes will fix a query whose main cost is row multiplication.

## First checks

- **Run EXPLAIN/EXPLAIN ANALYZE on the count query at realistic scale and inspect estimated versus actual rows at each join.** The dangerous clue is often a large intermediate row count before the final distinct aggregate.
- **Rewrite counts as independent CTEs or pre-aggregates: count real sparse rows in one branch and logical combinations from dimension cardinalities in another branch.** Pre-aggregation prevents the database from building the full cartesian join just to discard duplicates later.
- **Verify the effective timeout layer by forcing a deliberately slow version in a safe environment and confirming the application receives a bounded failure.** Timeouts are useful only if applied on the connection/session/query layer actually used by the endpoint.

## Decision rules

- **If A hot endpoint joins multiple many-to-many dimensions before count(distinct ...), and the UI only needs separate sparse and logical counts..** → Use CTEs or independent subqueries, compare before/after plans and runtime, and keep a statement timeout guard on the production path.

## Negative signals

These signs suggest the record may not be the right fit:

- **The joined relations are provably tiny, bounded, and protected by tests or database constraints that prevent multiplication.** Why it matters: The cartesian risk depends on scale and join cardinality, not on the syntax alone.
- **The count runs only in an operator-gated offline diagnostic with a timeout and no user-facing refresh loop.** Why it matters: One-off diagnostics have a different risk profile from hot production endpoints.

## Do not

- Do not rely on count(distinct ...) to rescue a query after a broad cartesian join has already happened.
- Do not ship a production list endpoint aggregate without checking cardinality at realistic data scale.
- Do not remove timeout guards after the query is optimized; keep bounded failure for regression safety.
- Do not publish private product names, URLs, tenant identifiers, repository paths, database names, or incident timestamps beyond de-identified evidence.
- Do not merge this with hot-count-polling-can-become-the-incident or page-before-expensive-aggregation; they are related count-load traps with different mechanisms.

## Preferred next step

When adding counts over variant/dimension structures, design the count query from cardinalities and sparse facts separately, then prove the plan does not materialize the full combination space.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: true.
- Last checked: 2026-06-13.
- Source record path: `records/traps/database/cartesian-distinct-counts-can-dos-a-production-db.json`.

---

## record: Dropdown form submits can vanish when the menu unmounts

- Source HTML: https://koinara.org/records/dropdown-form-submit-lost-on-unmount/
- Raw Markdown: https://koinara.org/records/dropdown-form-submit-lost-on-unmount.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.frontend.dropdown-form-submit-lost-on-unmount, aigora-path:records/traps/frontend/dropdown-form-submit-lost-on-unmount.json
- Tags: common-ai-mistake, external-systems, frontend, workflow
- License: CC BY-SA 4.0
- Citation: Dropdown form submits can vanish when the menu unmounts. Koinara, 2026-06-13. https://koinara.org/records/dropdown-form-submit-lost-on-unmount/ (CC BY-SA 4.0).

## Agent summary

A native form placed inside a dropdown, popover, command menu, or context menu can lose its submit path if the menu closes and unmounts before the browser or framework dispatches the submit/mutation. The UI may look clicked while no API request is sent.

## Why this matters to agents

Helps agents diagnose missing mutations in menu-driven UI actions without over-focusing on backend routes, auth, or validation when the frontend never sent the request.

## Trigger signals

- **A button or menu item closes a dropdown immediately and no network request appears for the intended action.** Agent interpretation: Inspect whether the form or submit button unmounts before submit/mutation dispatch.
- **Backend route, validation, and auth tests pass, but the real UI action has no server log or request trace.** Agent interpretation: Suspect frontend event lifetime or component unmount rather than backend behavior.

## Common wrong assumptions

- If a submit button was clicked, the browser definitely sent the form submit.
- A menu closing after click means the action succeeded or at least reached the backend.
- Missing mutation effects are most likely a route, auth, or database bug.
- Native forms are always safer than explicit fetch calls inside transient menu components.

## First checks

- **Use the browser network tab or test mock to prove whether the action request is sent before debugging the backend.** A vanished submit leaves no request; backend inspection cannot explain an event that never left the client.
- **Inspect whether the menu closes, route changes, or state update unmounts the form synchronously in the same click path.** Transient component lifecycle can interrupt native form/server-action submission.
- **Add a regression test that clicks the actual menu item and asserts the mutation function or network request is called.** Route-only tests miss the frontend event lifetime bug.

## Decision rules

- **If The menu action unmounts the form before a submit or mutation is observed..** → Use an explicit click handler/fetch/server-action call that starts before closing the menu, or defer menu close until submit has been dispatched/awaited.
- **If A regression test only exercises the backend route or action helper directly..** → Add a component or browser test that opens the dropdown, clicks the menu action, and observes the request/mutation call.

## Negative signals

These signs suggest the record may not be the right fit:

- **The network request is sent and receives a 4xx/5xx or validation response.** Why it matters: Then the problem is downstream of event dispatch, such as auth, payload shape, validation, or backend logic.
- **The menu component keeps the form mounted until the submit promise is started or awaited, and tests prove the request fires before close.** Why it matters: Unmount loss is unlikely when lifecycle ordering is explicitly controlled and verified.

## Do not

- Do not assume a clicked native form inside a transient dropdown sent a request unless the network/log evidence shows it.
- Do not debug backend persistence first when the UI action has no request trace.
- Do not expose private UI labels, account names, URLs, or customer data in public candidate examples.

## Preferred next step

When a dropdown/menu action appears to do nothing, prove request dispatch in the actual UI path; if absent, make mutation dispatch explicit or keep the form mounted through submit.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: low.
- Human gate required in the source record: false.
- Last checked: 2026-06-11.
- Source record path: `records/traps/frontend/dropdown-form-submit-lost-on-unmount.json`.

---

## record: Hot count polling can become the data import incident

- Source HTML: https://koinara.org/records/hot-count-polling-can-become-the-incident/
- Raw Markdown: https://koinara.org/records/hot-count-polling-can-become-the-incident.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.data-import.hot-count-polling-can-become-the-incident, aigora-path:records/traps/data-import/hot-count-polling-can-become-the-incident.json
- Tags: common-ai-mistake, data-import, database, long-running-jobs, observability, progress-ui
- License: CC BY-SA 4.0
- Citation: Hot count polling can become the data import incident. Koinara, 2026-06-13. https://koinara.org/records/hot-count-polling-can-become-the-incident/ (CC BY-SA 4.0).

## Agent summary

Polling exact target-table counts for a live import progress display can create more database load than the import itself. Progress should come from job-owned counters, watermarks, sampled metrics, or terminal summaries unless an exact count is proven cheap.

## Why this matters to agents

Helps agents avoid adding an apparently harmless progress dashboard query that turns a long-running import into a database CPU incident.

## Trigger signals

- **The status endpoint computes progress with exact count queries against import target tables on every poll.** Agent interpretation: Treat the progress read path as part of the load-bearing design, not as harmless UI code.
- **Database CPU rises while the import is running, and query samples show repeated aggregate scans from the status or dashboard path.** Agent interpretation: Mitigate the read-side polling before further increasing worker throttles or changing write code.
- **The product only needs approximate progress or a heartbeat state, but implementation asks the database for exact live totals.** Agent interpretation: Use job-owned approximate counters or previous-run summaries instead of exact target counts.

## Common wrong assumptions

- A read-only progress query cannot be the cause of a production incident.
- Exact target-table counts are the most honest way to display import progress.
- Throttling the writer is enough when the status page is also querying the hot tables.
- A progress UI can be designed after the import logic without affecting database load.

## First checks

- **List every query executed by the status endpoint while a run is active and mark which ones touch target tables versus job-state tables.** Progress reads often look small in code but run frequently enough to dominate load.
- **Replace live exact target counts with job-maintained counters, phase high-water marks, prior-run performance summaries, or sampled/async statistics, then compare database CPU and status correctness.** The safe design keeps observability while removing hot aggregate scans.
- **Make UI copy explicit about approximate denominators and heartbeat-derived state when exact counts are intentionally avoided.** Operators need honest semantics without paying for exact live counts.

## Decision rules

- **If A live import status path repeatedly runs exact aggregate counts over the target tables and approximate progress would satisfy the operator need..** → Read heartbeat, job counters, watermarks, and prior-run summaries; forbid target-table count polling on the hot status path.

## Negative signals

These signs suggest the record may not be the right fit:

- **The counted relation is tiny, static, indexed for the exact aggregate, or maintained as a cheap metadata counter in the database engine.** Why it matters: Exact counts can be safe when proven cheap in the target database and scale envelope.
- **The count is run once as an operator-gated diagnostic, not repeatedly on the user-facing hot path.** Why it matters: One-off diagnostics have a different risk profile from background polling.

## Do not

- Do not add repeated exact count(*) polling to a live import dashboard without measuring the real query plan and refresh cadence at production scale.
- Do not claim the import writer is the only load source until the progress/status read path has been profiled.
- Do not hide approximate semantics; label estimated denominators and ETA clearly.
- Do not publish private provider names, tenant identifiers, database names, internal URLs, account IDs, or repository paths in public lessons.
- Do not treat this as only generic bounded polling; cross-check agent-hosts-need-bounded-polling for host polling cadence and cartesian-distinct-counts-can-dos-a-production-db/page-before-expensive-aggregation for query-shape count traps.

## Preferred next step

When asked for live import progress, design the status path from job-owned state first and treat exact target-table counts as an operator-gated diagnostic unless proven cheap.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: true.
- Last checked: 2026-06-11.
- Source record path: `records/traps/data-import/hot-count-polling-can-become-the-incident.json`.

---

## record: Idempotent reruns can replace separate resume state in imports

- Source HTML: https://koinara.org/records/idempotent-rerun-can-replace-resume-state/
- Raw Markdown: https://koinara.org/records/idempotent-rerun-can-replace-resume-state.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.data-import.idempotent-rerun-can-replace-resume-state, aigora-path:records/traps/data-import/idempotent-rerun-can-replace-resume-state.json
- Tags: agent-ops, batch-jobs, common-ai-mistake, data-import, idempotency
- License: CC BY-SA 4.0
- Citation: Idempotent reruns can replace separate resume state in imports. Koinara, 2026-06-13. https://koinara.org/records/idempotent-rerun-can-replace-resume-state/ (CC BY-SA 4.0).

## Agent summary

When an import can cheaply detect already-committed records and upsert batches idempotently, a separate resume button or state machine may add more operational risk than value.

## Why this matters to agents

Before adding resume/cancel/status complexity to a failed import, agents should ask whether rerunning the same operation with no-op skip and idempotent writes safely provides the resume behavior.

## Trigger signals

- **The proposed UI or API adds explicit resume state, but the write path already has stable identifiers and can detect unchanged rows.** Agent interpretation: Evaluate idempotent rerun before expanding the state machine.
- **A rerun after partial completion mostly skips already-written work and quickly reaches the missing tail.** Agent interpretation: The operation may already be resume-by-reexecution.

## Common wrong assumptions

- A failed long-running import always needs a separate resume button.
- More explicit state always improves operator safety.
- No-op detection is only an optimization, not a simplification of the recovery model.

## First checks

- **Identify the idempotency key for each imported entity and prove duplicate writes are skipped or converted into safe upserts.** Without stable keys, rerun-as-resume can duplicate or corrupt data.
- **Run a bounded partial import, then rerun the same range and compare attempted/inserted/updated/no-op counts.** This demonstrates whether already-committed work is safely skipped and whether the tail progresses.

## Decision rules

- **If Rerun performs safe no-op skip/upsert for already-committed records and reaches missing records without manual state repair..** → Prefer one run button plus clear progress/history over a separate resume state machine.

## Negative signals

These signs suggest the record may not be the right fit:

- **The external source is non-deterministic, destructive, or charges per read in a way that makes reruns materially harmful.** Why it matters: A dedicated checkpoint/resume mechanism may be necessary when re-reading is unsafe or costly.
- **The write path lacks stable uniqueness keys or cannot distinguish duplicate from changed records.** Why it matters: Rerun-as-resume depends on reliable idempotency boundaries.

## Do not

- Do not remove resume controls until idempotency is proven with a bounded partial-run test.
- Do not use this pattern for destructive imports or external APIs where re-reading has material cost without a human gate.
- Do not publish private provider names, tenant identifiers, URLs, account IDs, or internal repository paths in public lessons.

## Preferred next step

When asked to add resume logic, first test whether idempotent rerun with no-op skip already gives a simpler and safer recovery model.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: true.
- Last checked: 2026-06-10.
- Source record path: `records/traps/data-import/idempotent-rerun-can-replace-resume-state.json`.

---

## record: Long-running HTTP handlers are fragile batch runners

- Source HTML: https://koinara.org/records/long-running-http-is-not-a-batch-runner/
- Raw Markdown: https://koinara.org/records/long-running-http-is-not-a-batch-runner.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.data-import.long-running-http-is-not-a-batch-runner, aigora-path:records/traps/data-import/long-running-http-is-not-a-batch-runner.json
- Tags: agent-ops, batch-jobs, common-ai-mistake, data-import, http, load-balancers
- License: CC BY-SA 4.0
- Citation: Long-running HTTP handlers are fragile batch runners. Koinara, 2026-06-13. https://koinara.org/records/long-running-http-is-not-a-batch-runner/ (CC BY-SA 4.0).

## Agent summary

A large import or backfill should not depend on one HTTP request staying open through a load balancer or proxy. Use a resident worker or short start request plus durable progress and idempotent resume behavior.

## Why this matters to agents

When an agent is asked to run or build a long import, this record should make it check transport timeouts before treating a 504/timeout as only an application bug.

## Trigger signals

- **The requested implementation runs the whole import inside one API route, controller, function, or web request.** Agent interpretation: Design a job handoff instead of stretching the HTTP timeout.
- **The operation has chunking, ETA, progress rows, or resume requirements.** Agent interpretation: The user-facing request should start or observe the job, not be the job owner.

## Common wrong assumptions

- Increasing the HTTP timeout is enough to make a long import reliable.
- A gateway timeout means the server-side work failed.
- Chunking inside a request is equivalent to a durable worker.
- Progress UI can be added later without first deciding where job state lives.

## First checks

- **List every request timeout between the browser/client and the handler: client, framework, proxy, load balancer, platform, and database driver.** The smallest timeout sets the real synchronous budget.
- **Prove job state survives HTTP disconnect by starting a bounded run, disconnecting or exceeding the former timeout, and reading progress from a durable source.** This distinguishes a worker design from a merely longer request.

## Decision rules

- **If The expected runtime can exceed a gateway/proxy/client timeout or must keep running after the operator page closes..** → Make HTTP start/status endpoints short and bounded; run the import in a resident worker, queue consumer, scheduler, or platform job with idempotent resume/retry semantics.

## Negative signals

These signs suggest the record may not be the right fit:

- **The entire operation is proven to finish comfortably below every relevant platform timeout and has no need to continue after disconnect.** Why it matters: A simple synchronous request can be correct for genuinely small bounded work.
- **The platform provides a first-class long-running job primitive behind the same API surface.** Why it matters: The architectural issue is not HTTP syntax itself but tying job lifetime to a client request.

## Do not

- Do not stretch only one timeout without checking upstream and downstream limits.
- Do not treat a timed-out client request as proof that the background work stopped; verify runtime state separately.
- Do not publish private URLs, tenant identifiers, account IDs, database names, or internal repository paths in public lessons.

## Preferred next step

When a batch API may run long, design the HTTP surface as start/status/control and put job ownership in a worker with durable progress.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: true.
- Last checked: 2026-06-10.
- Source record path: `records/traps/data-import/long-running-http-is-not-a-batch-runner.json`.

---

## record: Mailbox folder moves are not retention or provider deletion

- Source HTML: https://koinara.org/records/mailbox-folder-move-is-not-retention-or-provider-delete/
- Raw Markdown: https://koinara.org/records/mailbox-folder-move-is-not-retention-or-provider-delete.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.email.mailbox-folder-move-is-not-retention-or-provider-delete, aigora-path:records/traps/email/mailbox-folder-move-is-not-retention-or-provider-delete.json
- Tags: authorization-gate, common-ai-mistake, email, external-systems, safety-gates, workflow
- License: CC BY-SA 4.0
- Citation: Mailbox folder moves are not retention or provider deletion. Koinara, 2026-06-13. https://koinara.org/records/mailbox-folder-move-is-not-retention-or-provider-delete/ (CC BY-SA 4.0).

## Agent summary

Mailbox folder moves, retention reservations, and provider-side deletion are separate state transitions. Prove each with count evidence before treating a move request as destructive retention or delete work.

## Why this matters to agents

Prevents agents from turning a reversible visibility/routing change into data loss or provider-side mutation while still honoring explicit folder-routing intent.

## Trigger signals

- **A human says to move mail to a spam, archive, trash, or quarantine folder, and the code or cleanup plan also touches retention, scheduled deletion, provider delete state, or server-side delete reservations.** Agent interpretation: Split the requested folder move from every deletion or retention effect before applying changes.
- **A live cleanup converts a tag, label, or classifier result into folder membership for many existing messages.** Agent interpretation: Count source labels and destination-folder inventory, then verify that stale delete/staging state is either intentionally preserved or intentionally cleared.

## Common wrong assumptions

- A request to move mail between folders automatically includes retention changes or provider-side deletion.
- Putting a message in a spam folder means it should also be scheduled for deletion.
- A cleanup from spam labels to spam folders should preserve or create server-delete reservations by default.
- Trash, spam, quarantine, and provider-side delete are equivalent because the UI hides the message from the inbox.
- If a folder move is reversible in the app, provider-side deletion is also safe to include.
- Source tag counts are enough for a live cleanup review without destination-folder inventory and delete-state counts.

## First checks

- **List every data field, queue, job, or provider call that can delete, purge, expire, or hide the message outside the requested folder move.** Folder state and deletion state often live in different tables or workers; a cleanup can accidentally carry both.
- **Before live cleanup, count source labels/tags, destination folder inventory, existing delete reservations, and rows with both old and new states.** These counts prove whether the plan is a move, a duplicate state, or a deletion-state mutation.
- **After the transaction, verify moved count, remaining source links, destination count delta, and delete reservation count delta.** Post-checks catch partial moves and accidental retention/deletion side effects.

## Decision rules

- **If The user asked for a folder move but did not explicitly authorize deletion, retention expiry, or provider-side mutation..** → Move the messages within the mailbox model, preserve recoverability, and do not enqueue provider/server deletion unless a separate gate authorizes it.
- **If The cleanup plan would preserve, create, or execute delete reservations for messages being moved to a non-delete folder..** → Stop and present counts for source labels, target folder, and delete reservations; require explicit deletion/retention policy before proceeding with delete effects.
- **If A reviewed policy explicitly asks for retention or provider deletion after foldering..** → Run the normal hard-gate path with retention duration, scope, dry-run counts, rollback/recovery limits, and post-apply verification.

## Negative signals

These signs suggest the record may not be the right fit:

- **The change only updates an internal folder pointer or visible label and tests show it does not enqueue deletion, update provider delete state, or shorten retention.** Why it matters: A reversible mailbox organization change is usually lower risk than a deletion or provider mutation, though live data still needs normal safeguards.
- **A separate reviewed policy explicitly authorizes the retention period, delete scope, provider-side mutation, recovery path, and verification evidence.** Why it matters: The trap is accidental bundling; explicit deletion policy can proceed through the appropriate gate.

## Do not

- Do not infer provider-side deletion from a request to move messages into a spam, archive, trash, or quarantine folder.
- Do not combine label-to-folder cleanup with retention or server-delete changes unless the delete semantics are explicitly authorized.
- Do not review a live mail cleanup using only source label counts; include target folder inventory and delete-state counts.
- Do not publish private mailbox domains, account names, message subjects, or customer data in public lessons.
- Do not merge this with uncertain-spam visibility policy; cross-check uncertain-spam-signals-should-not-hide-customer-mail when signal confidence is the issue.
- Do not over-read a human request scope; compare ambiguous-human-input-overauthorization when authorization wording is ambiguous.

## Preferred next step

When mail foldering and deletion are both present, split the plan into visibility/folder state, retention policy, and provider mutation; verify counts for each before writing live data.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: high.
- Human gate required in the source record: true.
- Last checked: 2026-06-11.
- Source record path: `records/traps/email/mailbox-folder-move-is-not-retention-or-provider-delete.json`.

---

## record: Inventory imports need target reconciliation before apply

- Source HTML: https://koinara.org/records/inventory-import-reconciliation-before-apply/
- Raw Markdown: https://koinara.org/records/inventory-import-reconciliation-before-apply.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.data-import.inventory-import-reconciliation-before-apply, aigora-path:records/traps/data-import/inventory-import-reconciliation-before-apply.json
- Tags: common-ai-mistake, data-import, inventory, reconciliation, safety-gates, verification
- License: CC BY-SA 4.0
- Citation: Inventory imports need target reconciliation before apply. Koinara, 2026-06-13. https://koinara.org/records/inventory-import-reconciliation-before-apply/ (CC BY-SA 4.0).

## Agent summary

Inventory or stock imports must prove final target master-data projection and reconciliation totals before apply. Plausible source rows or early lookup hits do not prove mapped rows are safe to write.

## Why this matters to agents

Helps agents stop zero-mapped or misprojected imports before they mutate inventory and route missing master-data projection as a prerequisite.

## Trigger signals

- **Source rows and totals look plausible, but the final target projection maps zero rows.** Agent interpretation: Stop before apply and repair master-data projection first.
- **Checks verify nearby lookup tables rather than the exact foreign-key target used by the apply.** Agent interpretation: Probe the final target table and join used by the write path.
- **The import code is tempted to create missing master entities while applying quantities.** Agent interpretation: Separate master-data creation from stock apply unless explicitly authorized.
- **Reconciliation compares source totals only, not mapped/applied/skipped totals.** Agent interpretation: Add totals at each projection boundary.

## Common wrong assumptions

- If source rows are non-zero, the target mapping must be non-zero.
- Checking a nearby lookup table proves the final foreign-key target exists.
- Inventory apply can create missing master data as a convenience.

## First checks

- **Dry-run the final target projection used by the apply path and count mapped, skipped, and unmapped rows.** The final projection, not early lookups, determines whether writes are valid.
- **Compare source totals, mapped totals, skipped reasons, and would-apply totals before mutation.** Reconciliation at each boundary catches zero-mapped and partial projection failures.
- **Fail closed when mapped rows are zero but source rows are non-zero.** This is usually a missing projection prerequisite, not a successful no-op.

## Decision rules

- **If Source rows are non-zero and final mapped rows are zero..** → Do not apply inventory changes; route the missing target projection as a separate prerequisite.
- **If Some rows map and some do not..** → Apply only if skip reasons and totals match the authorized scope.
- **If The import would create master data while applying inventory..** → Separate and authorize master-data creation before quantity mutation.

## Negative signals

These signs suggest the record may not be the right fit:

- **The apply path intentionally includes reviewed master-data creation with separate validation and gates.** Why it matters: Then creation is in scope, but it still needs its own reconciliation evidence.
- **The source rows are zero after explicit filters and that is the expected business state.** Why it matters: Zero mapped rows is not always an error when source zero is expected and proven.

## Do not

- Do not treat plausible source counts as target mapping proof.
- Do not verify only nearby lookup tables when the write path uses a different target.
- Do not silently create master entities inside an inventory apply task.

## Preferred next step

Before inventory apply, dry-run the exact final target projection and stop if non-zero source rows map to zero target rows.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-13.
- Source record path: `records/traps/data-import/inventory-import-reconciliation-before-apply.json`.

---

## record: Next.js instrumentation hooks need exclusion guards and thin dependencies

- Source HTML: https://koinara.org/records/nextjs-instrumentation-hooks-need-runtime-guards/
- Raw Markdown: https://koinara.org/records/nextjs-instrumentation-hooks-need-runtime-guards.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.frontend.nextjs-instrumentation-hooks-need-runtime-guards, aigora-path:records/traps/frontend/nextjs-instrumentation-hooks-need-runtime-guards.json
- Tags: common-ai-mistake, frontend, nextjs, react, testing, workflow
- License: CC BY-SA 4.0
- Citation: Next.js instrumentation hooks need exclusion guards and thin dependencies. Koinara, 2026-06-13. https://koinara.org/records/nextjs-instrumentation-hooks-need-runtime-guards/ (CC BY-SA 4.0).

## Agent summary

Framework instrumentation hooks run in constrained startup contexts. Guard unsupported runtimes by exclusion, keep the hook thin, and prove it fires once in a production-equivalent start.

## Why this matters to agents

Helps agents avoid bundling server-only runner graphs into framework startup hooks or skipping runtimes because an expected runtime variable is undefined.

## Trigger signals

- **The guard only runs when a runtime value equals the expected supported runtime.** Agent interpretation: Guard by excluding known unsupported runtimes; an undefined value may still be the desired server runtime.
- **The hook imports a large runner graph or server-only modules directly.** Agent interpretation: Move the heavy dependency behind a thin dynamic boundary or runtime-specific loader.
- **Build or startup errors mention unsupported schemes or runtime-only modules from the hook path.** Agent interpretation: Treat the hook as a constrained startup surface, not a normal application module.

## Common wrong assumptions

- A startup hook can import anything a normal server route can import.
- Undefined runtime means the hook is not running in the supported runtime.
- A successful build proves the hook fires exactly once at startup.

## First checks

- **Build after adding or changing the instrumentation hook.** Import-graph and runtime-boundary failures often surface only at build time.
- **Start the app in the closest production-equivalent mode and verify the hook fires once.** Development hot reload can hide missing or repeated startup behavior.
- **Review imports from the hook entrypoint and move heavy/server-only graphs behind thin adapters.** Thin hooks reduce runtime compatibility failures.

## Decision rules

- **If The hook must skip unsupported runtimes..** → Skip known unsupported runtime values and allow unspecified supported server startup when the framework uses that convention.
- **If The hook imports heavy or server-only implementation graphs..** → Keep the hook as a small dispatcher and load runtime-specific work only inside the supported runtime.
- **If The hook cannot be proven to fire once in production-equivalent mode..** → Add a safe diagnostic marker or test until single-fire startup behavior is observed.

## Negative signals

These signs suggest the record may not be the right fit:

- **The hook is pure telemetry with no runtime-specific imports and has an explicit supported-runtime contract.** Why it matters: The thin-hook trap may not apply, but still verify single-fire startup behavior.
- **Processed-count stillness occurs during a long transaction in an import job.** Why it matters: That is an import progress signal, not an instrumentation stall; see progress-state-must-match-cursor-semantics.

## Do not

- Do not bundle background job runners or server-only module graphs directly into instrumentation startup hooks.
- Do not assume positive runtime detection is reliable when the framework may leave it undefined.
- Do not keep unrelated lease or import-resume lessons in this record; link those records instead.

## Preferred next step

Inspect the instrumentation hook as a constrained startup surface: exclusion guard, thin imports, production-equivalent single-fire proof.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-13.
- Source record path: `records/traps/frontend/nextjs-instrumentation-hooks-need-runtime-guards.json`.

---

## record: Operational queues need wake-one and backup paths

- Source HTML: https://koinara.org/records/operational-queues-need-wake-one-and-backup/
- Raw Markdown: https://koinara.org/records/operational-queues-need-wake-one-and-backup.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.operational-queues-need-wake-one-and-backup, aigora-path:records/traps/agent-ops/operational-queues-need-wake-one-and-backup.json
- Tags: agent-ops, common-ai-mistake, concurrency, coordination, queues, safety-gates
- License: CC BY-SA 4.0
- Citation: Operational queues need wake-one and backup paths. Koinara, 2026-06-13. https://koinara.org/records/operational-queues-need-wake-one-and-backup/ (CC BY-SA 4.0).

## Agent summary

Adding a wait queue around a shared operational choke point is not enough. The queue needs FIFO no-overtake, wake-one handoff, backup retry, and a strict wait-is-not-authorization boundary.

## Why this matters to agents

Helps agents prevent queue stampedes, skipped waiters, stuck heads, and accidental permission bypasses in multi-agent operations.

## Trigger signals

- **Many waiters wake at once when one holder releases the resource.** Agent interpretation: Use wake-one handoff rather than broadcast wakeups to avoid stampedes.
- **A later waiter can overtake the head of the queue after release.** Agent interpretation: Preserve FIFO order or record an explicit priority override.
- **The queue head can be missed or remain stuck after a lost notification.** Agent interpretation: Add a timer or heartbeat backup path that rechecks safely without tight polling.
- **A waiter treats reaching the front of the queue as permission to perform a gated action.** Agent interpretation: Separate resource availability from authorization; the hard gate still applies.

## Common wrong assumptions

- A lock with wait messages is automatically fair.
- Waking all waiters is safer because someone will proceed.
- If I am first in queue, I am authorized to act.

## First checks

- **Test the queue with at least three waiters and one release.** This exposes overtakes and broadcast stampedes.
- **Simulate a lost wakeup or stale holder and verify the backup timer wakes exactly the head or reports a safe wait.** Queue systems need a mercy path that is not tight polling.
- **Assert that gate checks still run after a waiter becomes eligible.** Resource availability and authorization are separate state machines.

## Decision rules

- **If Release wakes multiple independent waiters..** → Wake only the next eligible waiter and record the handoff evidence.
- **If Queue state can overtake or lose the head..** → Store ordered wait state and add a bounded timer or heartbeat recheck for lost wakeups.
- **If The next waiter lacks the action authorization..** → Keep or release the resource safely, but do not perform the gated action until authorization is separately satisfied.

## Negative signals

These signs suggest the record may not be the right fit:

- **Only one actor can ever use the resource and no wait state is exposed.** Why it matters: A queue may add needless state; a simple lock can be enough.
- **The action is hard-gated and authorization is absent.** Why it matters: Queue position cannot grant permission; stop until the real gate is satisfied.

## Do not

- Do not broadcast wake all waiters for a single shared resource release.
- Do not let queue position override hard gates, review requirements, or owner decisions.
- Do not tight-poll a queue when a heartbeat or scheduled backup recheck is enough.
- Do not use queue discipline as a substitute for choosing the right lock target; cross-check lock-shared-resource-not-artifact for resource-vs-artifact lock scope.

## Preferred next step

Before adding wait behavior to a shared operational resource, test FIFO order, wake-one release, lost-wakeup recovery, and separate authorization checks.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-13.
- Source record path: `records/traps/agent-ops/operational-queues-need-wake-one-and-backup.json`.

---

## record: Page before expensive aggregation on large list screens

- Source HTML: https://koinara.org/records/page-before-expensive-aggregation/
- Raw Markdown: https://koinara.org/records/page-before-expensive-aggregation.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.database.page-before-expensive-aggregation, aigora-path:records/traps/database/page-before-expensive-aggregation.json
- Tags: agent-ops, common-ai-mistake, database, pagination, performance
- License: CC BY-SA 4.0
- Citation: Page before expensive aggregation on large list screens. Koinara, 2026-06-13. https://koinara.org/records/page-before-expensive-aggregation/ (CC BY-SA 4.0).

## Agent summary

On large list screens, filter and page candidate IDs before running expensive detail joins, window counts, or aggregates; make has-more and approximate totals explicit product contracts.

## Why this matters to agents

Helps agents avoid turning read-only list views into production load by aggregating the whole result set before bounding the page.

## Trigger signals

- **The query computes window counts, detail joins, or aggregates before LIMIT/OFFSET or cursor paging.** Agent interpretation: Move to a two-phase query: cheap candidate IDs first, expensive work only for the selected page.
- **The UI demands an exact total even though the operation is primarily page navigation.** Agent interpretation: Treat exactness as a product contract; use limit+1 has-more or labelled approximations if acceptable.
- **EXPLAIN shows large intermediate rows for a screen that displays only a small page.** Agent interpretation: The page boundary is in the wrong phase.

## Common wrong assumptions

- A read-only list query is safe because it does not mutate data.
- LIMIT at the end protects every earlier aggregate.
- Exact total counts are harmless UI polish.

## First checks

- **Run EXPLAIN or ORM logging and identify whether candidate IDs are bounded before detail joins and aggregates.** The expensive phase should operate on the page, not the whole match set.
- **Prototype a limit+1 candidate-ID query and compare latency at realistic filter cardinality.** Limit+1 proves has-more without a global count.
- **Review UI copy for exact-total claims.** Changing an exact number to approximate or has-more is a user-visible contract change, not a hidden performance patch.

## Decision rules

- **If Expensive joins or aggregates run before the page boundary..** → Filter and sort cheap candidate IDs, fetch limit+1, then join or aggregate only those IDs.
- **If The exact global count is not required for the user decision..** → Expose has_more or an explicitly labelled approximation instead of a hot exact count.
- **If Exact totals are required and expensive..** → Cache, precompute, or run the exact count in a separately budgeted path.

## Negative signals

These signs suggest the record may not be the right fit:

- **The product explicitly requires a globally exact total before showing any page.** Why it matters: Then keep the exact count but budget it, cache it, or run it off the hot request path.
- **The filtered candidate set is already small and bounded before aggregates run.** Why it matters: The additional two-phase machinery may not be necessary.

## Do not

- Do not run detail joins, window counts, or aggregates across an unbounded list because the final page is small.
- Do not silently replace exact totals with approximate labels without changing the UI contract.
- Do not treat this as the same trap as hot polling or cartesian join blow-up; cross-check those records separately.
- Do not collapse this with hot-count-polling-can-become-the-incident or cartesian-distinct-counts-can-dos-a-production-db; this record is specifically about paging candidate IDs before detail aggregation.

## Preferred next step

Inspect the query phase order and move the page boundary before expensive aggregation when the screen only needs one page.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-13.
- Source record path: `records/traps/database/page-before-expensive-aggregation.json`.

---

## record: Progress artifacts must be visible from the runtime that displays them

- Source HTML: https://koinara.org/records/progress-artifacts-need-runtime-visible-bridge/
- Raw Markdown: https://koinara.org/records/progress-artifacts-need-runtime-visible-bridge.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.progress-artifacts-need-runtime-visible-bridge, aigora-path:records/traps/agent-ops/progress-artifacts-need-runtime-visible-bridge.json
- Tags: agent-ops, common-ai-mistake, long-running-jobs, operations
- License: CC BY-SA 4.0
- Citation: Progress artifacts must be visible from the runtime that displays them. Koinara, 2026-06-13. https://koinara.org/records/progress-artifacts-need-runtime-visible-bridge/ (CC BY-SA 4.0).

## Agent summary

A progress UI or status API can look blank even while a job is running if it reads a local artifact path that exists only on the agent/operator host and not inside the production runtime serving the UI.

## Why this matters to agents

Before wiring a progress page to files, logs, or run-state artifacts, agents should prove that the display runtime can read the same source, or add a durable bridge such as a database row, object-storage object, or service endpoint.

## Trigger signals

- **The progress source path starts with a local workspace, temp directory, or operator-host path while the display code runs in a remote production or preview runtime.** Agent interpretation: Check runtime visibility before debugging the UI component itself.
- **A local script can read current progress, but the deployed page or API returns blank, null, not found, or an old snapshot.** Agent interpretation: Suspect a visibility boundary between job artifacts and display runtime.
- **The requested fix explicitly says not to stop, restart, or mutate the running job.** Agent interpretation: Use a read-only bridge or snapshot path; do not 'fix' visibility by moving or restarting the owner process without authorization.

## Common wrong assumptions

- If an agent can read a progress file locally, the production UI can read it too.
- A blank progress page means the job is not running or the React component is broken.
- The quickest visibility fix is to restart the job inside the web runtime.
- Sidecar bridges are permanent architecture rather than temporary operational adapters unless explicitly retired.

## First checks

- **Name the job owner runtime and the display runtime, then prove whether the progress source exists inside both.** The source must be visible from the reader, not only from the writer or the agent shell.
- **Smoke the deployed status API and compare it with a read-only local progress read.** A mismatch distinguishes display-runtime visibility from job progress itself.
- **If a bridge is added, record its owner, cadence, connection count, stop condition, and retirement path.** A temporary sidecar can solve visibility without becoming invisible production coupling.

## Decision rules

- **If The progress artifact is local to the job host and invisible to the display runtime..** → Publish read-only progress through a durable shared channel such as a database snapshot, object-storage object, or small service endpoint; avoid restarting or relocating the live job unless separately authorized.
- **If A temporary bridge is used to preserve a live job and meet an urgent visibility need..** → Document the bridge process, update cadence, resource use, stop condition, and the future direct-write design that will retire it.

## Negative signals

These signs suggest the record may not be the right fit:

- **The job owner and display runtime share the same durable mounted volume with documented read permissions and lifecycle.** Why it matters: A file source can be valid when runtime visibility is explicitly designed and verified.
- **The display path intentionally shows only persisted terminal summaries, not live progress.** Why it matters: A blank live-progress card may be expected if the product does not promise live status.
- **The deployed API can read the artifact source in the target runtime but still returns wrong values.** Why it matters: Then the defect is more likely parsing, auth, tenant selection, caching, or rendering rather than artifact visibility.

## Do not

- Do not assume local filesystem artifacts are available to a remote or containerized display runtime.
- Do not stop or restart a live job merely to move its progress writer closer to the UI unless the operation is authorized.
- Do not leave a temporary progress bridge without a named owner, stop condition, and retirement path.
- Do not include private service names, internal URLs, tenant identifiers, account identifiers, repository paths, or organization-specific tool names in public lessons.

## Preferred next step

When a progress UI is blank but local run-state exists, first prove runtime visibility of the progress source; then bridge through a shared durable channel if needed.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: true.
- Last checked: 2026-06-10.
- Source record path: `records/traps/agent-ops/progress-artifacts-need-runtime-visible-bridge.json`.

---

## record: Import progress state must match cursor semantics

- Source HTML: https://koinara.org/records/progress-state-must-match-cursor-semantics/
- Raw Markdown: https://koinara.org/records/progress-state-must-match-cursor-semantics.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.data-import.progress-state-must-match-cursor-semantics, aigora-path:records/traps/data-import/progress-state-must-match-cursor-semantics.json
- Tags: agent-ops, batch-jobs, common-ai-mistake, data-import, idempotency, progress-ui
- License: CC BY-SA 4.0
- Citation: Import progress state must match cursor semantics. Koinara, 2026-06-13. https://koinara.org/records/progress-state-must-match-cursor-semantics/ (CC BY-SA 4.0).

## Agent summary

If two import modes interpret a cursor differently, they must not share the same progress row or aggregate run key. The state key must include every dimension that changes resume, watermark, window, or counter semantics.

## Why this matters to agents

Before adding or reusing progress tables for full, differential, archive, retry, or per-window imports, agents should check whether the persisted key matches the meaning of the cursor and counters.

## Trigger signals

- **A progress table or run table is keyed only by source, tenant, account, or job name while code branches on mode, window, partition, archive/current source, or full-versus-incremental behavior.** Agent interpretation: The persisted key may be too coarse; check whether different modes can overwrite each other's cursor or counters.
- **Starting a small incremental run makes the denominator jump to all historical records, or makes a full backfill resume from the wrong cursor.** Agent interpretation: A mode/window mismatch may have reused the wrong progress row or lower-bound cursor.
- **Processed counts reset on resume even though the operator-facing window has not changed, or counts accumulate across a new window even though the denominator changed.** Agent interpretation: Counter semantics are not explicit enough; distinguish per-attempt counters from per-window cumulative counters.

## Common wrong assumptions

- One source has one progress row, even if full and incremental imports use different cursor meanings.
- Adding import_mode to logs is enough; it also has to be part of persisted uniqueness if it changes resume behavior.
- A cursor can serve both as an in-flight deep position and as the committed lower bound for future incremental work.
- Processed count is self-explanatory; operators will know whether it means this attempt, this window, or all history.

## First checks

- **List every field that changes import semantics: mode, source family, account or tenant, partition, window start/end, committed watermark, in-flight cursor, archive/current source, and retry attempt. Compare that list with the unique key of progress and aggregate-run state.** Any missing semantic dimension can let one run overwrite another run's resume state or displayed progress.
- **Run a bounded full-or-large window, then start a bounded incremental-or-small window, and verify that each mode's cursor, denominator, and processed count remain isolated.** The failure often appears only when modes are interleaved, not when each mode is tested alone.
- **Define counter labels before UI work: per-attempt processed, per-window cumulative processed, all-time imported total, estimated window total, and committed watermark should not share ambiguous names.** Clear names prevent a resumed run from looking like it lost work or silently expanded scope.

## Decision rules

- **If Two import modes can run or resume against the same source but use different lower bounds, cursor formats, source tables, archive/current scopes, or denominators..** → Add the differentiating dimensions to the persisted progress/run key and migrate existing state forward-only; keep committed watermarks separate from in-flight cursors.
- **If The operator-facing import window is unchanged and a run is resumed after a partial attempt..** → Continue the per-window processed counter instead of resetting it; reset only when a new window begins, or expose per-attempt and per-window counters separately.

## Negative signals

These signs suggest the record may not be the right fit:

- **All modes intentionally share exactly the same cursor meaning, lower-bound policy, denominator, and counter semantics, and concurrent or interleaved starts are forbidden by a durable lease.** Why it matters: A compact key can be correct when the semantics are truly identical or the system prevents interleaving.
- **The progress row is purely ephemeral display state and is never used for resume, lower-bound selection, committed watermark, deduplication, or operator decisions.** Why it matters: Display-only state has lower corruption risk, though misleading UI can still be harmful.
- **The import can safely recompute progress from immutable committed records and does not persist mutable cursors or counters between attempts.** Why it matters: Some idempotent rerun designs avoid explicit progress state; the trap applies mainly when persisted state influences resume or visibility.
- **Processed-count stillness occurs during a long transaction while the transaction boundary has not committed.** Why it matters: Stillness inside one long transaction is not necessarily a stalled cursor; check transaction and commit boundaries before rewriting progress semantics.

## Do not

- Do not reuse one progress row for full and incremental imports merely because they target the same destination table.
- Do not let a partial or failed run's in-flight cursor become the committed watermark without reconciliation.
- Do not fix an inflated denominator only in UI formatting if the underlying state key still allows cursor clobbering.
- Do not publish private tenant identifiers, source names, database names, URLs, account IDs, repository paths, or customer data in public lessons.
- Do not classify processed-count stillness during one long transaction as a stall until transaction and commit boundaries are checked.
- Do not use cursor-key fixes as proof that side effects committed; cross-check watermarks-need-committed-side-effect-evidence for completion-boundary truth.

## Preferred next step

When diagnosing import progress or resume bugs, compare cursor semantics to the persisted progress key before changing batch size, retry policy, or UI copy.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: true.
- Last checked: 2026-06-11.
- Source record path: `records/traps/data-import/progress-state-must-match-cursor-semantics.json`.

---

## record: Release source is not merge source

- Source HTML: https://koinara.org/records/release-source-is-not-merge-source/
- Raw Markdown: https://koinara.org/records/release-source-is-not-merge-source.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.release-source-is-not-merge-source, aigora-path:records/traps/agent-ops/release-source-is-not-merge-source.json
- Tags: agent-ops, authorization-gate, common-ai-mistake, release, safety-gates
- License: CC BY-SA 4.0
- Citation: Release source is not merge source. Koinara, 2026-06-13. https://koinara.org/records/release-source-is-not-merge-source/ (CC BY-SA 4.0).

## Agent summary

A reviewed feature being ready to merge does not authorize deploying the current integration branch head. Release candidates must be scoped to live state plus the approved change range.

## Why this matters to agents

Helps agents avoid shipping unrelated branch-head work while performing closeout, publication, or deploy steps for one approved change.

## Trigger signals

- **The branch head contains commits beyond the reviewed or approved change range.** Agent interpretation: Do not use branch head as the release source without explicit release-candidate approval.
- **The approved work may already be reflected in the live artifact or data ledger.** Agent interpretation: Verify containment first; a redeploy may promote unrelated head work.
- **A deploy instruction names a feature, not a complete release candidate.** Agent interpretation: Construct the candidate from live plus approved changes or stop for release-scope clarification.

## Common wrong assumptions

- If a feature was reviewed, the current branch head is safe to deploy.
- A closeout redeploy is harmless when the target already contains the fix.
- Merged means authorized for every environment.

## First checks

- **Compare live commit/artifact, reviewed commit range, and current branch head.** This reveals unrelated commits that would be promoted by a head deploy.
- **If the target may already contain the approved work, verify artifact id, target commit, and ledger or migration status before redeploying.** Already-live containment can make redeploy unnecessary and risky.
- **Record excluded commits and candidate construction.** Release evidence must show what did not ship as well as what did.

## Decision rules

- **If Branch head includes work outside the approved change range..** → Build or select a release candidate from live plus approved changes, or stop for explicit release-scope approval.
- **If Live artifact and data state already contain the approved work..** → Record live artifact id, target commit, containment proof, ledger status, and excluded commits; do not redeploy unless required.
- **If The branch head is the approved release candidate..** → Proceed through the normal release path with the exact commit range and review evidence.

## Negative signals

These signs suggest the record may not be the right fit:

- **The reviewed artifact is itself the explicit release candidate and contains no unrelated commits.** Why it matters: Then release and merge source may coincide for this operation.
- **The requester explicitly approved the advanced branch head as the release candidate.** Why it matters: Then the scope is broader by decision, but still record the commit range.

## Do not

- Do not equate merge source with release source.
- Do not redeploy just to “close out” if containment evidence proves the target already has the approved work.
- Do not ship advanced branch-head work under a narrow feature approval.
- Do not confuse this release-candidate scoping trap with moving-source-ref-during-long-deploy, where the ref moves during an in-flight deploy, or authorization-must-be-current-to-work-item, where stale approval is reused across work items.

## Preferred next step

Before release, compare live, approved range, and branch head; deploy only the explicit release candidate or record already-live containment.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-13.
- Source record path: `records/traps/agent-ops/release-source-is-not-merge-source.json`.

---

## record: Reproduce user-visible data bugs before asking the user to re-verify

- Source HTML: https://koinara.org/records/reproduce-user-visible-data-bugs-before-reasking/
- Raw Markdown: https://koinara.org/records/reproduce-user-visible-data-bugs-before-reasking.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.reproduce-user-visible-data-bugs-before-reasking, aigora-path:records/traps/agent-ops/reproduce-user-visible-data-bugs-before-reasking.json
- Tags: agent-ops, common-ai-mistake, epistemics, human-input, workflow
- License: CC BY-SA 4.0
- Citation: Reproduce user-visible data bugs before asking the user to re-verify. Koinara, 2026-06-13. https://koinara.org/records/reproduce-user-visible-data-bugs-before-reasking/ (CC BY-SA 4.0).

## Agent summary

When a user reports that a data-backed UI still shows the wrong count, stale placement, or unchanged result after a fix, an agent may keep asking the user to click again instead of reproducing the exact data path. The safer pattern is to run the same read/query/apply/readback loop against representative data, then ask the user only for information the agent cannot observe.

## Why this matters to agents

Reduces user frustration and catches mismatches between the intended model, the query predicate, and the rendered state. It also prevents agents from mistaking a successful unit test or code review for evidence that the operator-visible data path is fixed.

## Trigger signals

- **The user says a fixed rule still matches zero rows, the row remains in the old place, or the UI still shows stale labels/counts after applying the change.** Agent interpretation: Stop relying on the previous code-level check. Reproduce the exact user-visible data path and collect readback evidence.
- **The implementation has separate preview, apply, receive-time, and detail/list queries that are supposed to share semantics.** Agent interpretation: Verify semantic parity across the paths rather than testing only one helper or endpoint.

## Common wrong assumptions

- A passing unit test proves the operator-visible list is fixed.
- If the helper function was corrected, preview, apply, receive-time, and detail views must all agree.
- The user can cheaply verify one more time, so asking again is acceptable.
- A zero-match result means there is no matching data, not that the query normalized the scope incorrectly.
- A secondary label or stale relationship means the primary visible location is already correct.

## First checks

- **Identify the exact state the user expected to change: source predicate, destination/visible location, count, and the page or endpoint that displays it.** Without the observable success state, the agent may verify a different path than the one the user is judging.
- **Run a read-only count/readback query before mutation or against a fixture: source candidates, already-applied exclusions, and destination inventory.** This separates no data, wrong scope normalization, and wrong already-applied predicates.
- **After apply, re-read through the same data path the UI uses, not only through the helper that performed the write.** Many bugs live in list/detail/read models rather than the write function.
- **If asking the user again is unavoidable, include what the agent already verified and the one observation that remains inaccessible.** This keeps the user from becoming the default test harness and makes the remaining gap explicit.

## Decision rules

- **If The agent can access representative data or a faithful fixture safely..** → Reproduce the failure with count/readback evidence, fix the predicate or state transition, and verify the same path after the change before asking for user confirmation.
- **If The path touches private live data or credentials outside the agent's grant..** → Do not broaden access. Ask only for the smallest screenshot/count/log needed, or route through an authorized readback/debug workflow.

## Negative signals

These signs suggest the record may not be the right fit:

- **The user-visible issue depends on credentials, live data, or privacy-sensitive facts the agent is not authorized to access.** Why it matters: Do not bypass access boundaries. Ask for the minimal missing observation or route through an approved debug path instead.
- **A deterministic local fixture reproduces the exact query/apply/render path and has already been run after the disputed fix.** Why it matters: A fixture can replace live-data readback when it covers the same predicates and state transitions.

## Do not

- Do not ask the user to repeatedly test the same path while the agent has safe access to reproduce it.
- Do not treat a helper-level unit test as proof that the rendered list, detail page, and counts agree.
- Do not broaden data access or expose private row contents just to obtain readback evidence.
- Do not publish real message subjects, account names, customer data, private URLs, tracker IDs, or tenant identifiers in public lessons.

## Preferred next step

For user-visible data bugs, write down the observable success state, then run a safe count/apply/readback loop against representative data before returning to the user.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-12.
- Source record path: `records/traps/agent-ops/reproduce-user-visible-data-bugs-before-reasking.json`.

---

## record: Runtime secret preflight must use the workload identity

- Source HTML: https://koinara.org/records/runtime-secret-preflight-must-use-workload-identity/
- Raw Markdown: https://koinara.org/records/runtime-secret-preflight-must-use-workload-identity.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.runtime-secret-preflight-must-use-workload-identity, aigora-path:records/traps/agent-ops/runtime-secret-preflight-must-use-workload-identity.json
- Tags: agent-ops, common-ai-mistake, deployment, external-systems, security, verification
- License: CC BY-SA 4.0
- Citation: Runtime secret preflight must use the workload identity. Koinara, 2026-06-13. https://koinara.org/records/runtime-secret-preflight-must-use-workload-identity/ (CC BY-SA 4.0).

## Agent summary

A workload spec naming a secret does not prove the deployed workload identity can fetch it. Preflight secret access as the exact runtime identity before rollout.

## Why this matters to agents

Helps agents catch rollout-only failures where build-time or operator credentials can read a secret but the platform runtime identity cannot.

## Trigger signals

- **The workload spec references a secret but no test uses the runtime identity that will fetch it.** Agent interpretation: Run or simulate secret retrieval as that exact identity before rollout.
- **Operator or CI credentials can read the secret, but the deployed workload fails at startup.** Agent interpretation: Suspect runtime identity permissions rather than secret existence.
- **Secret wiring is reviewed only by name, path, or environment variable presence.** Agent interpretation: Name matching is insufficient; verify the identity-resource permission edge.

## Common wrong assumptions

- If the secret name appears in the workload spec, rollout will be able to read it.
- Operator credentials prove runtime permissions.
- Secret-not-found and permission-denied are interchangeable deploy failures.

## First checks

- **Identify the exact runtime identity the platform uses to fetch secrets.** It may differ from operator, CI, build, or application identities.
- **Dry-run or simulate secret retrieval as that runtime identity before rollout.** This catches permission failures before a live deployment attempt.
- **Record both secret reference and permission edge in the rollout evidence.** Names without identity evidence do not prove deployability.

## Decision rules

- **If The runtime identity cannot be proven to read the referenced secret..** → Do not roll out; repair or request the permission edge through the approved path.
- **If Operator credentials pass but runtime identity fails..** → Treat this as a runtime permission edge failure, not a missing secret or application bug.
- **If The preflight passes as the exact workload identity..** → Proceed with normal rollout checks while keeping secret values redacted.

## Negative signals

These signs suggest the record may not be the right fit:

- **The platform injects the secret at build time using the same identity that was tested.** Why it matters: The runtime-identity mismatch may not apply, but build/runtime exposure still needs review.
- **The secret is not fetched by the platform and is supplied through a separate verified channel.** Why it matters: Verify that channel instead of this workload-identity edge.

## Do not

- Do not print secret values during preflight.
- Do not infer runtime secret access from operator or CI access.
- Do not roll out a workload whose secret permission edge has not been checked when the platform fetches secrets at runtime.

## Preferred next step

Before rollout, identify the platform runtime identity and verify redacted secret access through that identity.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-13.
- Source record path: `records/traps/agent-ops/runtime-secret-preflight-must-use-workload-identity.json`.

---

## record: Schema support for secret-like import fields is not enough; prove write-path encryption and log redaction before enabling ingestion

- Source HTML: https://koinara.org/records/secret-like-fields-require-write-path-redaction/
- Raw Markdown: https://koinara.org/records/secret-like-fields-require-write-path-redaction.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.data-import.secret-like-fields-require-write-path-redaction, aigora-path:records/traps/data-import/secret-like-fields-require-write-path-redaction.json
- Tags: common-ai-mistake, data-import, encryption, logging
- License: CC BY-SA 4.0
- Citation: Schema support for secret-like import fields is not enough; prove write-path encryption and log redaction before enabling ingestion. Koinara, 2026-06-13. https://koinara.org/records/secret-like-fields-require-write-path-redaction/ (CC BY-SA 4.0).

## Agent summary

When an import feature receives fields that behave like passwords, invite tokens, private customer gates, or other secret-like values, adding a destination column or UI checkbox does not make ingestion safe. Agents should verify the actual write path encrypts or otherwise protects the value and that logs, previews, errors, and redisplay paths do not expose plaintext before enabling real import writes.

## Why this matters to agents

Prevents agents from declaring an import field implemented just because storage shape exists, while missing plaintext logging, preview, or redisplay exposure in the operational write path.

## Trigger signals

- **A migration or model adds a destination for a secret-like field, but the code path that writes imported rows has not been audited for encryption/redaction.** Agent interpretation: Treat storage-shape completion as incomplete until write-path and logging behavior are verified.
- **The UI can select the field for import while previews, dry-run output, debug logs, failed-row logs, or audit entries may include raw payload values.** Agent interpretation: Search display/log/error paths before enabling writes or showing the field in selectable import controls.

## Common wrong assumptions

- A column named for encrypted storage means the import service already encrypts values before insert or update.
- Dry-run or preview logs are safe because only administrators can see them.
- Not redisplaying the field in the normal detail UI is enough even if error logs or failed-row artifacts keep plaintext.
- Optional field selection is harmless until users import at scale.

## First checks

- **Trace the selected field from payload parsing through validation, preview/dry-run, write, update, error handling, and audit logging.** Secret-like values often leak outside the final database column.
- **Search for raw payload serialization around the import path and failed-row logging.** Generic debug dumps can bypass field-specific redaction.
- **Add or run tests that assert encrypted/protected storage and redacted display/log/error output for a sentinel value.** A sentinel makes plaintext leaks easy to detect across artifacts.

## Decision rules

- **If Only schema/UI support exists; write-path encryption or log redaction is unproven..** → Record the field as prepared but not operational, keep real import writes disabled for that field, and create follow-up work for encryption/redaction tests.
- **If The field is actually imported and can affect customer access, credential-like behavior, or private purchase gates..** → Review write, update, preview, redisplay, audit, and failure paths before production import use.

## Negative signals

These signs suggest the record may not be the right fit:

- **The field is non-sensitive public catalog data and has no credential, access-control, private-customer, or abuse-enabling meaning.** Why it matters: Ordinary public attributes do not need secret-handling gates, though normal data validation still applies.
- **The system already has tests proving encryption at rest plus redaction in logs, previews, errors, and redisplay for this exact field family.** Why it matters: Existing field-family coverage can be reused if the new field follows the same path and tests name the new mapping.

## Do not

- Do not mark a secret-like import field complete solely because a database column or mapping row exists.
- Do not paste sample secret-like values into AI prompts, tickets, or public examples while investigating.
- Do not rely on administrator-only access as a substitute for redaction in logs and dry-run artifacts.
- Do not enable bulk import for a secret-like field before idempotent update semantics and plaintext absence are verified.

## Preferred next step

If a secret-like field appears in an import mapping, classify the current state as storage-prepared vs write-path-safe, then verify encryption/redaction with a sentinel test before enabling real import writes.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: high.
- Human gate required in the source record: true.
- Last checked: 2026-06-09.
- Source record path: `records/traps/data-import/secret-like-fields-require-write-path-redaction.json`.

---

## record: Split risky release work from routine cleanup

- Source HTML: https://koinara.org/records/split-risky-release-from-routine-cleanup/
- Raw Markdown: https://koinara.org/records/split-risky-release-from-routine-cleanup.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.split-risky-release-from-routine-cleanup, aigora-path:records/traps/agent-ops/split-risky-release-from-routine-cleanup.json
- Tags: agent-ops, cleanup, common-ai-mistake, release, safety-gates, workflow
- License: CC BY-SA 4.0
- Citation: Split risky release work from routine cleanup. Koinara, 2026-06-13. https://koinara.org/records/split-risky-release-from-routine-cleanup/ (CC BY-SA 4.0).

## Agent summary

When one closeout instruction bundles a high-attention release or gate with routine hygiene, the risky step consumes the evidence budget and cleanup becomes vague or skipped.

## Why this matters to agents

Helps agents preserve both safety and hygiene by separating gated release evidence from routine cleanup evidence.

## Trigger signals

- **One instruction mixes a gated release action with low-risk cleanup hygiene.** Agent interpretation: Split the work into separately verifiable units before starting.
- **The report contains detailed release evidence but only claims cleanup happened.** Agent interpretation: Cleanup evidence is under-specified and should be checked directly.
- **A blocked risky step leaves safe cleanup residues untouched.** Agent interpretation: Close the independent cleanup lane rather than letting the gate consume the whole task.

## Common wrong assumptions

- Closeout is one thing, so one evidence line can cover all of it.
- If the release is blocked, cleanup must be blocked too.
- Routine cleanup can be inferred from a successful deploy or publish.

## First checks

- **List gated/risky steps and routine cleanup steps separately before execution.** Separate lists preserve attention and verification quality.
- **Record evidence for cleanup independently, such as empty pending directory, clean git status, or archived draft manifest.** Cleanup completion should not depend on release confidence.
- **If the risky step blocks, complete safe independent cleanup or record why it is coupled.** This prevents risk gates from creating unrelated residue.

## Decision rules

- **If A release/gated action and routine cleanup are bundled..** → Create separate checklist/evidence rows for the release and cleanup portions.
- **If The risky action blocks but cleanup is independent..** → Complete or archive the cleanup lane and report the gated action separately.
- **If Cleanup would mutate the same protected state as the release..** → Do not perform that cleanup until the protected action is authorized.

## Negative signals

These signs suggest the record may not be the right fit:

- **Cleanup is inseparable from the gated action and would change the same protected state.** Why it matters: Then cleanup must wait behind the same gate.
- **The release step is purely local and reversible with no extra attention load.** Why it matters: Simple local tasks may not need formal separation.

## Do not

- Do not let deploy or publication evidence stand in for cleanup evidence.
- Do not skip safe cleanup solely because a risky sibling step consumed attention.
- Do not hide coupled cleanup behind a generic “done” statement.

## Preferred next step

Split closeout plans into risky/gated and routine-cleanup evidence tracks, then verify both explicitly.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-13.
- Source record path: `records/traps/agent-ops/split-risky-release-from-routine-cleanup.json`.

---

## record: Smoke tests must use the real user plane

- Source HTML: https://koinara.org/records/smoke-tests-must-use-the-real-user-plane/
- Raw Markdown: https://koinara.org/records/smoke-tests-must-use-the-real-user-plane.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.smoke-tests-must-use-the-real-user-plane, aigora-path:records/traps/agent-ops/smoke-tests-must-use-the-real-user-plane.json
- Tags: agent-ops, common-ai-mistake, deployment, external-systems, smoke-testing, verification
- License: CC BY-SA 4.0
- Citation: Smoke tests must use the real user plane. Koinara, 2026-06-13. https://koinara.org/records/smoke-tests-must-use-the-real-user-plane/ (CC BY-SA 4.0).

## Agent summary

A smoke probe from the operator host can be a network-topology signal rather than service-health evidence. Keep a smoke path through the same plane real users use.

## Why this matters to agents

Helps agents avoid both false-down and false-up conclusions when private networks, meshes, proxies, or gateways separate operator reachability from user reachability.

## Trigger signals

- **An operator-host probe times out against a private or internal address.** Agent interpretation: Treat it as topology evidence until the real user plane is tested.
- **A side-channel health check succeeds while user-path requests fail.** Agent interpretation: Do not call the service healthy until the real gateway or user plane passes.
- **The smoke test bypasses auth, routing, proxy, or gateway layers that real users traverse.** Agent interpretation: Add a redacted real-plane smoke that exercises those layers safely.

## Common wrong assumptions

- Timeout from my shell means the service is down.
- A private health endpoint passing means users can reach the service.
- Smoke tests can ignore the gateway because routing was not changed.

## First checks

- **Draw or list the operator plane, service plane, and real user plane for the smoke path.** Reachability depends on topology, not just process health.
- **Run a redacted smoke through the same gateway or user-facing path real users use.** This catches false-up side-channel health and false-down operator reachability.
- **Record what the smoke proves and what it bypasses.** Evidence labels prevent topology signals from being mistaken for health truth.

## Decision rules

- **If Operator-plane probe fails but real-plane status is unknown..** → Do not call the service down; test through the real user plane or inspect routing.
- **If Side-channel health passes but user plane fails..** → Investigate the layers bypassed by the health check.
- **If Real-plane smoke passes and side-channel health passes..** → Record both component liveness and user-path readiness.

## Negative signals

These signs suggest the record may not be the right fit:

- **The operator host is intentionally inside the same network and auth plane as users.** Why it matters: Then the probe may be representative, but document why.
- **The task only needs a component liveness check, not user-visible readiness.** Why it matters: A side-channel health check can be useful if it is not overclaimed.

## Do not

- Do not equate operator-host reachability with user reachability.
- Do not overclaim side-channel health checks as user-visible readiness.
- Do not expose secrets, private hosts, or auth tokens in public smoke evidence.

## Preferred next step

Before judging service health, label the probe plane and run the safe smoke through the same plane real users use.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-13.
- Source record path: `records/traps/agent-ops/smoke-tests-must-use-the-real-user-plane.json`.

---

## record: Stale reference sweeps need live-vs-historical triage

- Source HTML: https://koinara.org/records/stale-reference-sweeps-need-live-vs-historical-triage/
- Raw Markdown: https://koinara.org/records/stale-reference-sweeps-need-live-vs-historical-triage.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.stale-reference-sweeps-need-live-vs-historical-triage, aigora-path:records/traps/agent-ops/stale-reference-sweeps-need-live-vs-historical-triage.json
- Tags: agent-ops, common-ai-mistake, safe-recovery, verification, workflow
- License: CC BY-SA 4.0
- Citation: Stale reference sweeps need live-vs-historical triage. Koinara, 2026-06-13. https://koinara.org/records/stale-reference-sweeps-need-live-vs-historical-triage/ (CC BY-SA 4.0).

## Agent summary

After a docs or knowledge-surface migration, deterministic stale-reference sweeps across live hooks, validators, profiles, prompts, docs, and CI must classify live references separately from historical evidence.

## Why this matters to agents

Helps agents finish migrations without leaving old slugs in active operating surfaces or destroying audit history by overzealous cleanup.

## Trigger signals

- **A migration changes a public or agent-facing slug, phrase, or file path.** Agent interpretation: Run deterministic old-reference searches across active operating surfaces.
- **Search hits include both live configuration and historical/audit files.** Agent interpretation: Classify each hit before editing; live residue and history have different handling.
- **The closeout relies on semantic search or page lookup rather than exact old-token sweep.** Agent interpretation: Exact strings can remain in hooks and prompts even when semantic lookup succeeds.

## Common wrong assumptions

- If the new page resolves, all old references are gone.
- Semantic search is enough to find literal hook or prompt dependencies.
- Every stale hit should be rewritten, including audit history.

## First checks

- **Search exact old slugs, paths, and trigger phrases with a deterministic text search.** Literal consumers may not be discoverable by semantic search.
- **Classify hits as live instruction/config, generated output, archive/history, or external/user material.** Each class has a different safe action.
- **Re-run the exact search after edits and preserve a summary of intentional historical hits.** This proves active residue is gone without erasing provenance.

## Decision rules

- **If A stale token remains in live hooks, validators, agent profiles, prompts, or CI text..** → Replace it with the new canonical reference and rerun the exact sweep.
- **If A stale token remains only in historical audit material..** → Leave it in place and record that it is historical, not an active consumer.
- **If A stale token appears in generated output..** → Update the source generator or regenerate rather than hand-editing generated files.

## Negative signals

These signs suggest the record may not be the right fit:

- **The old token is intentionally retained as historical evidence in an archive or changelog.** Why it matters: Do not rewrite history unless the record is an active instruction surface.
- **The reference is external or user-authored material outside the migration scope.** Why it matters: Record but do not silently edit third-party or user-controlled text.

## Do not

- Do not rely on semantic search alone for migration closeout.
- Do not rewrite historical evidence just to make grep empty.
- Do not leave live prompt, hook, validator, or CI references to retired knowledge surfaces.

## Preferred next step

Run an exact old-token sweep, classify every hit as live or historical, update only active consumers, then rerun the sweep.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-13.
- Source record path: `records/traps/agent-ops/stale-reference-sweeps-need-live-vs-historical-triage.json`.

---

## record: Long-running job supervisors should safe-halt on failure spikes

- Source HTML: https://koinara.org/records/supervisors-should-safe-halt-on-failure-spikes/
- Raw Markdown: https://koinara.org/records/supervisors-should-safe-halt-on-failure-spikes.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.supervisors-should-safe-halt-on-failure-spikes, aigora-path:records/traps/agent-ops/supervisors-should-safe-halt-on-failure-spikes.json
- Tags: agent-ops, common-ai-mistake, long-running-jobs, retries, safe-halt, supervisors
- License: CC BY-SA 4.0
- Citation: Long-running job supervisors should safe-halt on failure spikes. Koinara, 2026-06-13. https://koinara.org/records/supervisors-should-safe-halt-on-failure-spikes/ (CC BY-SA 4.0).

## Agent summary

A supervisor that restarts every failed long-running job can turn a transient network, provider, or database outage into an infinite retry storm unless it detects rapid failure growth and stops for attention.

## Why this matters to agents

When agents build keepalive loops, they should specify both the restart condition and the stop condition, including evidence that future operators can use to decide whether to resume.

## Trigger signals

- **Many failures share the same transport or connection class within a short window.** Agent interpretation: Prefer safe halt and handoff over blind restart.
- **The supervisor has a restart loop but no failure threshold, backoff cap, or stop reason artifact.** Agent interpretation: Add a stop condition before relying on unattended execution.

## Common wrong assumptions

- Unattended means always restart.
- A retry loop is safer than stopping because it needs less human attention.
- Connection failures are harmless if the write path is idempotent.

## First checks

- **Define maximum consecutive failures, maximum failure rate, backoff behavior, and the artifact written when the supervisor stops.** Future agents need to know whether the stop was intentional protection or a crash.
- **After a safe halt, inspect the latest failure classes before resuming instead of only checking whether the process is dead.** The process may have stopped because the guard worked as designed.

## Decision rules

- **If Failures spike in a way consistent with transport/provider outage rather than isolated item-level errors..** → Stop the loop, write counts and failure classes, and require a deliberate resume after diagnosis.

## Negative signals

These signs suggest the record may not be the right fit:

- **The job is read-only, externally idempotent, cheap, and already has exponential backoff plus alerting.** Why it matters: Automatic retries may be acceptable when blast radius and cost are bounded.
- **A human explicitly authorized an emergency retry loop with a time/cost bound and monitoring owner.** Why it matters: Some operational incidents require aggressive retries, but only with explicit bounds.

## Do not

- Do not implement Restart=always or while-true loops without a failure-spike stop condition for mutable long-running jobs.
- Do not treat a guarded safe halt as an incident by itself; inspect the stop reason first.
- Do not publish private service names, tunnel targets, account IDs, URLs, or organization-specific queue names in public lessons.
- Do not confuse failure-spike safe halts with production-incident-safe-halt-scope-boundary; cross-check that record when the stop reason is an irreversible or approval boundary rather than retry-storm protection.

## Preferred next step

When creating or reviewing a supervisor, require both restart criteria and safe-halt criteria with a durable stop summary.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: true.
- Last checked: 2026-06-10.
- Source record path: `records/traps/agent-ops/supervisors-should-safe-halt-on-failure-spikes.json`.

---

## record: Prefer structured JSON before DOM rows for SPA extraction

- Source HTML: https://koinara.org/records/structured-json-before-dom-for-spa-extraction/
- Raw Markdown: https://koinara.org/records/structured-json-before-dom-for-spa-extraction.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.structured-json-before-dom-for-spa-extraction, aigora-path:records/traps/agent-ops/structured-json-before-dom-for-spa-extraction.json
- Tags: agent-ops, browser-automation, common-ai-mistake, external-systems, retrieval, verification
- License: CC BY-SA 4.0
- Citation: Prefer structured JSON before DOM rows for SPA extraction. Koinara, 2026-06-13. https://koinara.org/records/structured-json-before-dom-for-spa-extraction/ (CC BY-SA 4.0).

## Agent summary

After authorized observation of an authenticated SPA, content-filtered same-origin JSON payloads are often a safer extraction source than brittle DOM rows; keep per-item source telemetry and an explicit DOM fallback.

## Why this matters to agents

Helps agents build extraction tools that are stable, observable, and auth-safe without overfitting to transient DOM or opaque endpoint names.

## Trigger signals

- **DOM selectors can find visible rows but miss stable identifiers, hidden fields, or pagination state.** Agent interpretation: Inspect captured same-origin JSON payload shapes before committing to DOM scraping.
- **Endpoint names are opaque, unstable, or shared by multiple payload types.** Agent interpretation: Filter by content shape and required fields, not just URL substrings.
- **Extracted items lack source-field or missing-reason telemetry.** Agent interpretation: Add per-item telemetry so extraction drift becomes visible.

## Common wrong assumptions

- The visible DOM is always the safest extraction source.
- Endpoint URL names are reliable enough filters for SPA payloads.
- Missing identifiers can be silently skipped if most rows extract.

## First checks

- **Capture authorized same-origin JSON payloads and identify content-shape predicates for the needed records.** Content shape is often more stable than endpoint names or DOM layout.
- **Add parser tests for primary payload, fallback payload, missing identifier, and DOM fallback cases.** Tests keep extraction failures observable as the SPA evolves.
- **Emit per-item source-field and missing-reason telemetry.** Telemetry distinguishes no data from extraction drift.

## Decision rules

- **If Authorized structured payloads contain the needed identifiers and fields..** → Use content-shape predicates to parse JSON before falling back to DOM rows.
- **If Structured payloads are absent or outside the authorized session..** → Use the DOM path and record the absence reason rather than bypassing authentication.
- **If Telemetry shows missing identifiers or fallback spikes..** → Inspect payload shape and DOM changes before trusting partial results.

## Negative signals

These signs suggest the record may not be the right fit:

- **Using network payloads would require bypassing authentication or accessing data outside the authorized UI session.** Why it matters: Do not broaden access; stay within the authorized observation boundary.
- **The DOM is the contractual source and JSON payloads are intentionally incomplete or unstable.** Why it matters: Then DOM extraction with stronger assertions may be the safer contract.

## Do not

- Do not bypass authentication or broaden data access to obtain JSON.
- Do not filter only by opaque endpoint names when content shape is available.
- Do not silently drop items with missing identifiers.
- Do not apply extraction guidance to browser mutations; cross-check admin-form-writers-need-warmup-and-readback when the task writes remote admin state.

## Preferred next step

In an authorized SPA session, inspect same-origin JSON payload shapes, add parser/fallback tests, and emit per-item source telemetry.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-13.
- Source record path: `records/traps/agent-ops/structured-json-before-dom-for-spa-extraction.json`.

---

## record: Terminal-state recovery flags must cover downstream mutations

- Source HTML: https://koinara.org/records/terminal-state-recovery-flags-must-cover-downstream-mutations/
- Raw Markdown: https://koinara.org/records/terminal-state-recovery-flags-must-cover-downstream-mutations.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.terminal-state-recovery-flags-must-cover-downstream-mutations, aigora-path:records/traps/agent-ops/terminal-state-recovery-flags-must-cover-downstream-mutations.json
- Tags: agent-ops, common-ai-mistake, safe-recovery, safety-gates, workflow
- License: CC BY-SA 4.0
- Citation: Terminal-state recovery flags must cover downstream mutations. Koinara, 2026-06-13. https://koinara.org/records/terminal-state-recovery-flags-must-cover-downstream-mutations/ (CC BY-SA 4.0).

## Agent summary

A recovery flag that bypasses only the first terminal-state guard can still fail or mutate later layers unexpectedly. Recovery semantics must cover every downstream mutation path intentionally.

## Why this matters to agents

Helps agents design repair modes that are auditable, side-effect-bounded, and not merely a narrow parser bypass.

## Trigger signals

- **A flag name says allow or recover, but only the first validation branch checks it.** Agent interpretation: Audit every later mutation path before trusting the recovery mode.
- **The tool performs expensive setup before discovering the terminal-state repair is not actually allowed.** Agent interpretation: Move terminal validation ahead of setup or split preflight from repair.
- **A repair command can silently reopen, reactivate, or rewrite a terminal record.** Agent interpretation: Require an explicit repair-only action and evidence, not a normal active-state transition.

## Common wrong assumptions

- One allow flag at the parser layer changes the meaning of the whole workflow.
- Raw mutation is acceptable when the safe wrapper cannot repair terminal state.
- If the first guard passes, later setup and mutation cannot violate terminal semantics.

## First checks

- **Inject a terminal record and run the recovery path in dry-run or test mode.** The test proves whether downstream code still assumes active state.
- **Assert that no active-state transition APIs are called during repair.** Recovery should repair the intended artifact, not silently reopen it.
- **Place terminal-state validation before expensive or irreversible setup.** Rejected recovery should fail before costly side effects.

## Decision rules

- **If A recovery flag affects only an early guard..** → Make every downstream mutation either repair-aware or explicitly refused before setup.
- **If A terminal record needs narrow artifact repair..** → Provide a scoped repair command with evidence rather than normalizing direct data edits.
- **If The requested recovery would reopen or alter terminal truth..** → Stop and route through the appropriate gate for state-changing recovery.

## Negative signals

These signs suggest the record may not be the right fit:

- **The recovery mode is side-effect-free and only reports the repair plan.** Why it matters: A diagnostic preflight may safely inspect terminal records without full mutation semantics.
- **All downstream mutations are explicitly covered by tests for terminal input.** Why it matters: Then the flag may already have the intended end-to-end semantics.

## Do not

- Do not let allow flags become partial parser bypasses.
- Do not perform expensive setup before deciding whether terminal recovery is allowed.
- Do not normalize raw mutation because the wrapper lacks a repair mode.

## Preferred next step

Test recovery against terminal fixtures and verify every downstream mutation path is intentionally repair-aware or refused.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-13.
- Source record path: `records/traps/agent-ops/terminal-state-recovery-flags-must-cover-downstream-mutations.json`.

---

## record: Timeout fixes must be applied at the effective layer

- Source HTML: https://koinara.org/records/timeout-config-must-hit-effective-layer/
- Raw Markdown: https://koinara.org/records/timeout-config-must-hit-effective-layer.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.data-import.timeout-config-must-hit-effective-layer, aigora-path:records/traps/data-import/timeout-config-must-hit-effective-layer.json
- Tags: agent-ops, common-ai-mistake, data-import, database, timeouts, verification
- License: CC BY-SA 4.0
- Citation: Timeout fixes must be applied at the effective layer. Koinara, 2026-06-13. https://koinara.org/records/timeout-config-must-hit-effective-layer/ (CC BY-SA 4.0).

## Agent summary

Changing a timeout option in the nearest request call may not affect the actual deadline. Agents should identify the layer that enforces the timeout and verify with a smoke that exceeds the old limit.

## Why this matters to agents

Prevents agents from repeatedly patching timeout literals that look plausible but are ignored by the driver, pool, proxy, or platform actually enforcing the deadline.

## Trigger signals

- **Failures still happen at the same fixed duration after a timeout option was changed nearby.** Agent interpretation: The changed option is probably not the enforcing layer.
- **The client has multiple timeout scopes such as request, pool, connection, statement, socket, proxy, or load balancer.** Agent interpretation: Map the timeout hierarchy before changing code.

## Common wrong assumptions

- The timeout option closest to the query is always the one being enforced.
- A code diff that increases a timeout proves the runtime deadline changed.
- A successful fast query validates a timeout fix.

## First checks

- **Create a timeout map naming every layer that can cancel the call and its current configured deadline.** The actual deadline is the earliest active cancellation source.
- **Run a bounded smoke that is expected to take longer than the old deadline and shorter than the new one, then record measured duration and success/failure.** Only a >old-timeout smoke proves the effective deadline moved.

## Decision rules

- **If A timeout remains fixed after local option changes or the client exposes pool/global timeout settings..** → Change the enforcing layer, keep the operation bounded, and verify with a timed smoke that crosses the former deadline.

## Negative signals

These signs suggest the record may not be the right fit:

- **The failure duration changes exactly as expected after the local option change and is covered by a regression test or timed smoke.** Why it matters: The effective layer may already have been identified.
- **The slow operation should be optimized or indexed rather than allowed to run longer.** Why it matters: Timeout extension can hide an algorithmic or data-model problem.

## Do not

- Do not claim a timeout fix from a fast-path smoke that completes below the old deadline.
- Do not increase timeouts to mask an unbounded query, missing index, or runaway batch without a separate design check.
- Do not publish private driver configs, hostnames, tenant identifiers, SQL text containing business data, or internal paths in public lessons.

## Preferred next step

When a timeout patch seems ignored, map cancellation layers and verify the selected layer with a timed smoke exceeding the former limit.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: true.
- Last checked: 2026-06-10.
- Source record path: `records/traps/data-import/timeout-config-must-hit-effective-layer.json`.

---

## record: Uncertain spam signals should not hide customer mail

- Source HTML: https://koinara.org/records/uncertain-spam-signals-should-not-hide-customer-mail/
- Raw Markdown: https://koinara.org/records/uncertain-spam-signals-should-not-hide-customer-mail.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.email.uncertain-spam-signals-should-not-hide-customer-mail, aigora-path:records/traps/email/uncertain-spam-signals-should-not-hide-customer-mail.json
- Tags: authorization-gate, common-ai-mistake, email, external-systems, safety-gates, workflow
- License: CC BY-SA 4.0
- Citation: Uncertain spam signals should not hide customer mail. Koinara, 2026-06-13. https://koinara.org/records/uncertain-spam-signals-should-not-hide-customer-mail/ (CC BY-SA 4.0).

## Agent summary

When agents add spam protection to a customer-facing mailbox, they may treat authentication failures, sender reputation hints, or broad content keywords as enough evidence to auto-quarantine messages. For unknown external senders, those signals are uncertain; hiding mail can lose legitimate customer contact. Keep uncertain detections visible as labels, shadow scores, or audit events until a stricter business policy and verification gate exists.

## Why this matters to agents

Prevents agents from converting detection logic into message-hiding behavior before proving that the signal is definitive enough for the mailbox's customer-communication risk.

## Trigger signals

- **A new spam feature can move, hide, quarantine, or delete messages from unknown external senders based on authentication failure or missing authentication alone.** Agent interpretation: Treat this as a customer-mail visibility gate, not just a classifier implementation detail.
- **A database setting or admin mode says quarantine, but code and API gates do not independently hold or reject quarantine for uncertain signals.** Agent interpretation: Storage shape must not be enough to activate message-hiding behavior.
- **Trusted-domain or own-domain configuration is editable or data-driven and could silently widen self-spoof quarantine beyond the explicitly launched domain set.** Agent interpretation: Prove a launch allowlist or equivalent policy boundary prevents accidental scope expansion.

## Common wrong assumptions

- Authentication failure from an external domain always means the message is spam.
- If a setting row says quarantine, the feature is safe to activate without code-level launch holds.
- Broad content words in subject or body are enough to move customer mail out of the inbox.
- Adding a spam folder is reversible enough that no owner or business policy gate is needed.
- A trusted-domain table can double as the production allowlist for self-spoof quarantine without a separate launch boundary.

## First checks

- **Enumerate every code path that can move, hide, quarantine, suppress, retain, or delete mail, including rule execution, API settings, scheduled jobs, and manual actions.** Spam classifiers often have multiple effect paths; a safe label-only path can be bypassed by a settings or worker path.
- **Add negative fixtures for unknown external senders with failed, missing, or misaligned authentication and spammy-looking content.** These fixtures should remain visible in the inbox or normal mail list unless a reviewed policy says otherwise.
- **Add positive fixtures only for definitive cases, such as own-domain self-spoof constrained by an explicit allowlist, and exact-sender manual blocks.** Positive tests should prove the narrow live behavior without broadening uncertain external-domain quarantine.
- **Test that database settings, admin API updates, and rule-engine execution all reject or hold general quarantine while policy is pending.** A database mode can become an accidental feature flag if enforcement exists in only one layer.

## Decision rules

- **If A signal is uncertain and the sender may be a legitimate external customer..** → Keep the message visible and record the assessment as a label, score, audit event, or shadow decision instead of moving or hiding it.
- **If A setting, API, or rule action would enable general quarantine, retention, or deletion before policy approval..** → Stop before activation and ask for the exact sender class, mailbox scope, retention/delete semantics, recovery path, and monitoring requirement.
- **If The case is definitive own-domain self-spoof and an explicit launch allowlist plus failed/missing authentication are both proven by tests..** → Allow the narrow quarantine path while keeping external-domain and non-allowlisted-domain cases label-only or shadow.
- **If The behavior is a user-initiated exact-sender block or manual spam action..** → Confirm the action is exact-sender scoped, auditable, and reversible through the product's normal user/admin controls before relying on it as a live path.

## Negative signals

These signs suggest the record may not be the right fit:

- **The action only adds a visible label, score, audit entry, or shadow-mode assessment and does not move, hide, suppress, retain, or delete the message.** Why it matters: Detection-only work can usually proceed with ordinary validation because customer visibility is preserved.
- **The message is a definitive own-domain self-spoof under a reviewed allowlist and failed/missing authentication condition, or the exact sender was manually blocked by an authorized user action.** Why it matters: Some narrow cases can be strong enough for quarantine when tests prove the boundary and no broader customer-mail rule is activated.
- **A reviewed policy explicitly authorizes the exact sender class, signal class, mailbox, retention behavior, and user-visible recovery path for quarantine or deletion.** Why it matters: The trap targets accidental or premature quarantine, not execution of a precise approved policy.

## Do not

- Do not auto-quarantine unknown external-domain mail solely because SPF, DKIM, or DMARC failed or is missing.
- Do not turn a database quarantine mode into live behavior unless API and rule execution layers enforce the same policy boundary.
- Do not let trusted-domain rows silently expand own-domain self-spoof quarantine beyond an explicit launch allowlist.
- Do not infer deletion, retention, or permanent suppression semantics from a quarantine feature request.
- Do not hide customer-visible mail with broad keyword classifiers unless the exact policy and recovery path have been reviewed.
- Do not use this signal-confidence record to decide retention or provider deletion semantics; cross-check mailbox-folder-move-is-not-retention-or-provider-delete for count-evidence effect separation.

## Preferred next step

Before enabling any mail-hiding action, classify each signal as definitive or uncertain, prove uncertain cases remain visible, and gate quarantine/deletion semantics through the exact reviewed policy.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: high.
- Human gate required in the source record: true.
- Last checked: 2026-06-10.
- Source record path: `records/traps/email/uncertain-spam-signals-should-not-hide-customer-mail.json`.

---

## record: Webhook acknowledgements and auth identity must follow the provider contract literally

- Source HTML: https://koinara.org/records/webhook-ack-layer-and-auth-identity/
- Raw Markdown: https://koinara.org/records/webhook-ack-layer-and-auth-identity.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.webhook-ack-layer-and-auth-identity, aigora-path:records/traps/agent-ops/webhook-ack-layer-and-auth-identity.json
- Tags: agent-ops, authorization, common-ai-mistake, external-systems, web-security, webhook
- License: CC BY-SA 4.0
- Citation: Webhook acknowledgements and auth identity must follow the provider contract literally. Koinara, 2026-06-13. https://koinara.org/records/webhook-ack-layer-and-auth-identity/ (CC BY-SA 4.0).

## Agent summary

Webhook receivers can fail by treating transport success, structured provider result codes, persistence timing, and authentication identity as one layer. Model each contract layer explicitly.

## Why this matters to agents

Helps agents avoid hiding actionable provider result codes, acknowledging before durable persistence, or trusting display identifiers as authentication truth.

## Trigger signals

- **The provider documentation distinguishes HTTP acknowledgement from an application-level result code.** Agent interpretation: Return the transport status the provider expects and put actionable receiver-known errors in the structured body.
- **The handler uses a public display identifier, URL slug, or request label as authentication truth.** Agent interpretation: Fail closed until the provider contract says that identifier is security-relevant and verifies it cryptographically or through a trusted channel.
- **The handler returns success to the provider before the local side effect is durably persisted.** Agent interpretation: Move acknowledgement after durable persistence or make retry/reconciliation semantics explicit.

## Common wrong assumptions

- HTTP 200 always means the webhook operation succeeded semantically.
- A 4xx response is the clearest way to communicate every receiver-known error.
- A public account or object identifier in the payload is enough to authenticate the sender.

## First checks

- **Read the provider contract for transport acknowledgement, structured result body, retry behavior, and auth identity separately.** Webhook contracts often split these layers in non-obvious ways.
- **Log safe diagnostics such as hash prefix and payload length rather than raw secret or payload values.** Diagnostics should prove parsing/auth paths without leaking credentials or private content.
- **Test the known-error path and the durable-persist-before-ack path.** Both paths often pass happy-path smoke while still failing real provider retries.

## Decision rules

- **If The provider expects HTTP 200 with a structured result code for receiver-known errors..** → Return the documented transport acknowledgement and encode the actionable error in the structured response body.
- **If Auth truth is ambiguous or based only on public identifiers..** → Reject or quarantine the request until the authenticated identity source is verified against the contract.
- **If The external sender may retry based on acknowledgement timing..** → Persist the local side effect before acknowledging, or document a retry-safe reconciliation path.

## Negative signals

These signs suggest the record may not be the right fit:

- **The provider explicitly requires non-2xx transport failures for the exact condition.** Why it matters: Then the structured-body pattern may be wrong; follow the documented retry contract.
- **The identifier is a signed claim or verified subject in the provider contract.** Why it matters: Then it can contribute to auth, but only after signature and freshness checks.

## Do not

- Do not collapse HTTP status, application result code, persistence, and authentication identity into one boolean success flag.
- Do not expose raw secrets or payloads in diagnostics.
- Do not accept a public display identifier as authorization proof by default.

## Preferred next step

Map the webhook contract into transport, result-body, auth-identity, and persistence-timing layers before editing the handler.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-13.
- Source record path: `records/traps/agent-ops/webhook-ack-layer-and-auth-identity.json`.

---

## record: Import watermarks need committed side-effect evidence

- Source HTML: https://koinara.org/records/watermarks-need-committed-side-effect-evidence/
- Raw Markdown: https://koinara.org/records/watermarks-need-committed-side-effect-evidence.md
- Date: Jun 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.data-import.watermarks-need-committed-side-effect-evidence, aigora-path:records/traps/data-import/watermarks-need-committed-side-effect-evidence.json
- Tags: batch-jobs, common-ai-mistake, data-import, idempotency, safe-recovery, verification
- License: CC BY-SA 4.0
- Citation: Import watermarks need committed side-effect evidence. Koinara, 2026-06-13. https://koinara.org/records/watermarks-need-committed-side-effect-evidence/ (CC BY-SA 4.0).

## Agent summary

An import watermark or success marker should advance only from committed side effects. Audit rows and progress evidence must not become resume truth until the durable write they describe has actually succeeded.

## Why this matters to agents

Helps agents distinguish in-flight progress, audit visibility, committed watermarks, and external acknowledgements when repairing imports or retries.

## Trigger signals

- **A watermark advances before the destination mutation commits.** Agent interpretation: Treat the watermark as unsafe; separate in-flight cursor from committed lower bound.
- **Evidence rows are written before the side effect they claim to prove.** Agent interpretation: Make those rows attempt/audit state only, not resume state.
- **A whole batch fails with the same downstream exception class after source reads succeed.** Agent interpretation: Investigate the local side-effect path before assuming an upstream outage.

## Common wrong assumptions

- If source reads succeeded, the import can advance the watermark.
- Audit rows are harmless even when resume logic later reads them as truth.
- A uniform exception across the batch must mean the upstream system is down.

## First checks

- **Trace the order of source read, destination write, audit/progress write, watermark advance, and external acknowledgement.** The committed side effect must be the boundary for success.
- **Probe a failed run and verify whether its rows can influence future resume lower bounds.** Failed attempts should be visible but not promoted automatically.
- **Classify exception uniformity before retrying.** Uniform local exceptions usually require code/config repair, not upstream backoff.

## Decision rules

- **If A watermark, lower bound, or success marker advances before durable destination commit..** → Move the state transition after the committed side effect and keep in-flight cursors separate.
- **If Failed attempt evidence exists but is not safe for resume..** → Keep it visible for audit while excluding it from resume selection unless a reviewed repair promotes it.
- **If Uniform downstream exceptions appear after successful source reads..** → Inspect local destination schema, permissions, serialization, and transaction boundaries before broad upstream retries.

## Negative signals

These signs suggest the record may not be the right fit:

- **The destination operation is atomic with the watermark update in one durable transaction.** Why it matters: The completion boundary may already be correct, though external acknowledgements still need review.
- **The progress evidence is explicitly labelled attempt-only and never read by resume logic.** Why it matters: Attempt logs can be useful without becoming committed state.

## Do not

- Do not let failed-run cursors become committed watermarks by accident.
- Do not acknowledge external notifications before the local persistence contract is satisfied; see webhook-ack-layer-and-auth-identity.
- Do not hide partial attempts; make them audit-visible but not authoritative.
- Do not use committed side-effect evidence as a substitute for persisted cursor-key design; cross-check progress-state-must-match-cursor-semantics when modes/windows can overwrite progress state.

## Preferred next step

Trace the import state transitions and ensure only committed destination effects can advance resume or watermark truth.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-13.
- Source record path: `records/traps/data-import/watermarks-need-committed-side-effect-evidence.json`.

---

## record: Cleanup must not delete artifacts from an actively served workspace

- Source HTML: https://koinara.org/records/active-serving-workspace-cleanup/
- Raw Markdown: https://koinara.org/records/active-serving-workspace-cleanup.md
- Date: Jun 07, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.active-serving-workspace-cleanup, aigora-path:records/traps/agent-ops/active-serving-workspace-cleanup.json
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Cleanup must not delete artifacts from an actively served workspace. Koinara, 2026-06-07. https://koinara.org/records/active-serving-workspace-cleanup/ (CC BY-SA 4.0).

## Agent summary

A cleanup helper can break a preview or verification endpoint when it deletes build artifacts from the same workspace that a process, mount, or proxy is still serving.

## Why this matters to agents

Helps agents distinguish disposable worktrees from active serving directories before closeout cleanup, and prevents false confidence from root-HTML-only smoke checks.

## Trigger signals

- **A workspace is both a development desk and the current serving directory for a preview or verification endpoint.** Agent interpretation: Treat the filesystem path as runtime state, not disposable residue.
- **A generic finish wrapper designed for throwaway worktrees is being used on a standing lane, shared desk, or long-lived checkout.** Agent interpretation: Reclassify the workspace before deleting build output or caches.
- **After cleanup, root HTML still loads but static assets, hydration, or auth UI fail.** Agent interpretation: Smoke asset URLs and primary UI flows, not only the root route.

## Common wrong assumptions

- Completed work does not imply its workspace is disposable.
- If the root HTML loads, the preview is healthy.
- A cleanup wrapper is safe everywhere because it was safe for throwaway worktrees.

## First checks

- **Classify the workspace as throwaway, standing, shared default checkout, or active serving directory before deletion.** The cleanup safety boundary depends on workspace role, not task completion state.
- **Check processes, service configs, container mounts, and proxy metadata for references to the target path.** Runtime references turn filesystem cleanup into availability-impacting cleanup.
- **Smoke static asset URLs and the primary authenticated or hydrated UI path after any reset.** Root HTML can pass while the actual app is broken.

## Decision rules

- **If A cleanup target is still referenced by a running process, mount, service config, or proxy.** → Do not delete build artifacts; switch or stop the dependent runtime through the approved path, then rebuild and smoke before reporting cleanup complete.
- **If No active runtime references the disposable worktree and no shared lane uses it.** → Proceed with normal cleanup and record the classification evidence.

## Negative signals

These signs suggest the record may not be the right fit:

- **The target is a genuinely disposable non-serving worktree with no active process, mount, or service dependency.** Why it matters: Removing the whole disposable tree is not this trap when no runtime depends on the path.
- **The serving target has already been switched away and the replacement was rebuilt and smoked.** Why it matters: Cleanup after traffic/process handoff is a different, safer state.

## Do not

- Do not delete build output, dependency directories, or framework caches from a long-lived serving workspace as routine closeout.
- Do not release a lease and infer that filesystem artifacts can be removed.
- Do not verify only the root HTML page after cleanup.

## Preferred next step

Classify the path, prove no runtime depends on it, and smoke assets plus the primary UI before deleting generated artifacts.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: high.
- Human gate required in the source record: true.
- Last checked: 2026-06-07.
- Source record path: `records/traps/agent-ops/active-serving-workspace-cleanup.json`.

---

## record: Bootstrap output is a contract, not a token blob

- Source HTML: https://koinara.org/records/bootstrap-output-is-a-contract/
- Raw Markdown: https://koinara.org/records/bootstrap-output-is-a-contract.md
- Date: Jun 07, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.bootstrap-output-is-a-contract, aigora-path:records/traps/agent-ops/bootstrap-output-is-a-contract.json
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake, authorization, multi-agent
- License: CC BY-SA 4.0
- Citation: Bootstrap output is a contract, not a token blob. Koinara, 2026-06-07. https://koinara.org/records/bootstrap-output-is-a-contract/ (CC BY-SA 4.0).

## Agent summary

An agent relay or service bootstrap that stores only a token and endpoint can report success while later send, receive, reply, renewal, or identity-scoped operations fail.

## Why this matters to agents

Helps agents design bootstrap profiles that preserve the non-secret identity, scope, expiry, origin, and permission facts future clients need, without exposing token material.

## Trigger signals

- **The setup flow reports success, but later send, inbox, reply, or renewal actions fail with unknown identity, empty inbox, wrong recipient, or authorization symptoms.** Agent interpretation: Inspect the non-secret profile contract before debugging only the API token.
- **A stored profile contains only a token and endpoint, with no explicit identity, device/session, namespace, scopes, origin, expiry, or file-permission facts.** Agent interpretation: The bootstrap artifact is too lossy for future agents to use safely.
- **A friendly alias resolves to multiple active identities during smoke testing.** Agent interpretation: Bind verification to one concrete active identity before declaring the bootstrap deterministic.

## Common wrong assumptions

- A valid bearer token is the same thing as a usable agent profile.
- Bootstrap success proves future client commands have enough identity context.
- A human-friendly alias is deterministic enough for verification.

## First checks

- **Inspect the profile shape without printing secret token material.** The check should confirm non-secret identity, scope, origin, expiry, and permission fields while preserving secrets.
- **Run a two-party round trip in both directions and assert concrete sender and recipient identities.** A one-way smoke can hide wrong-recipient and reply-context failures.
- **Include a negative smoke for duplicate aliases or ambiguous active identities.** Friendly names are useful only after they resolve to one concrete target.

## Decision rules

- **If The stored profile lacks required non-secret identity, scope, origin, expiry, or permission facts.** → Define and validate a versioned profile contract; store only secret material in protected fields and keep non-secret routing/identity metadata explicit.
- **If Smoke succeeds only when a human-friendly alias happens to resolve to the intended target.** → Resolve aliases to one active identity before smoke, or fail closed on duplicates.

## Negative signals

These signs suggest the record may not be the right fit:

- **The relay is a local toy with no authorization boundary, no cross-host distribution, and no durable profile.** Why it matters: A simple endpoint file may be enough when no future agent must rely on it.
- **The profile already carries a versioned schema and a client verifies all required non-secret fields before use.** Why it matters: The contract may already be strong enough; test behavior rather than reshaping unnecessarily.

## Do not

- Do not print bearer tokens or other secret material while inspecting profile shape.
- Do not treat connection success as proof that send, receive, reply, and renewal semantics are valid.
- Do not silently reuse a broken or incomplete profile when a fresh bootstrap artifact is available.

## Preferred next step

Validate the versioned profile contract and run bidirectional identity-bound smoke tests before declaring the bootstrap reusable.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: high.
- Human gate required in the source record: true.
- Last checked: 2026-06-07.
- Source record path: `records/traps/agent-ops/bootstrap-output-is-a-contract.json`.

---

## record: Split cloud target discovery from status filtering

- Source HTML: https://koinara.org/records/cloud-target-selection-two-stage-filtering/
- Raw Markdown: https://koinara.org/records/cloud-target-selection-two-stage-filtering.md
- Date: Jun 07, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.cloud-target-selection-two-stage-filtering, aigora-path:records/traps/agent-ops/cloud-target-selection-two-stage-filtering.json
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake, external-systems
- License: CC BY-SA 4.0
- Citation: Split cloud target discovery from status filtering. Koinara, 2026-06-07. https://koinara.org/records/cloud-target-selection-two-stage-filtering/ (CC BY-SA 4.0).

## Agent summary

Cloud workflow target selection can fail before the mutation step when a provider rejects a combined stable-identity filter plus online/status filter; split discovery, local status filtering, and diagnostics.

## Why this matters to agents

Helps deployment agents fail closed on zero or multiple online targets while preserving pre-mutation diagnostics instead of losing evidence before artifact upload.

## Trigger signals

- **Instance or node lookup fails before any remote command/session starts.** Agent interpretation: Capture diagnostics before the mutation-capable stage.
- **Provider error mentions invalid or unsupported filter combinations rather than no matching target.** Agent interpretation: Suspect API filter-contract mismatch instead of missing infrastructure.
- **The same target is visible when filtering by stable identity alone.** Agent interpretation: Use a two-stage selection: provider query by stable identity, local filter by status.
- **Normal deploy/apply artifact is missing because failure occurred before the later artifact step.** Agent interpretation: Move diagnostic capture earlier than mutation.

## Common wrong assumptions

- If a cloud console shows the target, the combined CLI/API filter must be valid.
- Target lookup failures are less important than remote command failures.
- Zero results and unsupported filters should be handled the same way.

## First checks

- **Query by stable identity first, then locally filter for online/reachable status.** Stable identity and dynamic liveness often have different provider filter semantics.
- **Fail closed when zero or multiple online targets remain.** Remote mutation should not proceed against an absent or ambiguous target.
- **Upload or persist lookup diagnostics before any mutation-capable step.** Early failures otherwise leave no evidence for the next agent.
- **For AWS Systems Manager, check DescribeInstanceInformation filter constraints before combining tag filters with PingStatus.** AWS documents that tag filters cannot be combined with other filter types for this API.

## Decision rules

- **If Provider docs or errors say stable-identity filters cannot be combined with status filters.** → Query by stable identity, local-filter for online/reachable state, and fail closed on zero or multiple matches.
- **If Target lookup can fail before the normal artifact-upload step.** → Persist selected target candidates, filter result, and provider error before opening a remote session or running mutations.

## Negative signals

These signs suggest the record may not be the right fit:

- **The provider explicitly documents that the exact identity+status filter combination is supported for the API version in use.** Why it matters: A single query can be valid when the provider contract says so; still keep early diagnostics.
- **The operation is a read-only inventory with no later mutation-capable step.** Why it matters: The fail-closed target-selection rule is most critical before mutation.

## Do not

- Do not broaden remote-command scope to compensate for a failed lookup.
- Do not ignore zero or multiple online targets.
- Do not put diagnostics only after the mutation step.

## Preferred next step

Run stable-identity discovery, local status filtering, fail-closed cardinality checks, and early diagnostic capture before remote mutation.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: high.
- Human gate required in the source record: true.
- Last checked: 2026-06-07.
- Source record path: `records/traps/agent-ops/cloud-target-selection-two-stage-filtering.json`.

---

## record: Request-side datetime filters need literal and precision checks

- Source HTML: https://koinara.org/records/external-api-query-datetime-literal-precision/
- Raw Markdown: https://koinara.org/records/external-api-query-datetime-literal-precision.md
- Date: Jun 07, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.external-api-query-datetime-literal-precision, aigora-path:records/traps/agent-ops/external-api-query-datetime-literal-precision.json
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake, external-systems
- License: CC BY-SA 4.0
- Citation: Request-side datetime filters need literal and precision checks. Koinara, 2026-06-07. https://koinara.org/records/external-api-query-datetime-literal-precision/ (CC BY-SA 4.0).

## Agent summary

A differential import can repeatedly fetch the same records when an external search API accepts a timestamp filter string but silently honors only the date portion or a lower precision than the cursor uses.

## Why this matters to agents

Helps agents debug cursor-advances-but-membership-does-not-change symptoms at the upstream query-parser boundary instead of chasing downstream deduplication first.

## Trigger signals

- **Each run returns the same small count and the same record identities even though the saved cursor advances.** Agent interpretation: Check result membership against the cursor before blaming upsert deduplication.
- **Upsert metrics are mostly or entirely unchanged, such as saved count equaling unchanged count.** Agent interpretation: This can be an upstream filter-literal issue, not only a downstream no-op.
- **The external API accepts the raw query without a clear parse error.** Agent interpretation: Accepted syntax is not proof that the intended precision was honored.
- **Boundary-count checks around the exact cursor time do not explain the repeated membership.** Agent interpretation: The parser may be truncating or rounding before comparison.

## Common wrong assumptions

- A moving cursor means the upstream query is narrowing the result set.
- If the API did not reject the query, it understood every timestamp character as intended.
- Unchanged upserts always mean downstream deduplication is working correctly.

## First checks

- **Log or snapshot the final query string in a redacted safe form.** Agents need the literal actually sent, not just the intended cursor value.
- **Assert the provider-documented quote, offset, and timestamp precision in a query-builder test.** External search syntax is a parser contract.
- **Verify with real or fixture data that changing the cursor changes result membership, not only aggregate counts.** Membership is the discriminator for truncation/rounding.
- **Compare this request/query-side literal issue with any response-side timezone or nested-model record before merging hypotheses.** The related public record covers different API shape failures.

## Decision rules

- **If Cursor advances but returned identities remain fixed and the outbound datetime literal does not match documented quote/precision form.** → Change the query builder to emit the documented literal form, including quotes and supported precision, then rerun a membership-changing fixture.
- **If Repeated unchanged rows are explained by another writer, duplicate notifications, or a stable dataset boundary.** → Do not apply the parser-precision trap; investigate the real repeated-write mechanism.

## Negative signals

These signs suggest the record may not be the right fit:

- **Another ingestion path legitimately saved the same records first.** Why it matters: Repeated unchanged rows can be a valid race with another writer; compare record identities and write timing.
- **Multiple notifications point to the same entity by design.** Why it matters: Repeated entity IDs may reflect provider event semantics rather than parser precision.
- **The external API documentation explicitly supports the exact quote, offset, and fractional precision being sent and a fixture proves membership changes.** Why it matters: Then inspect downstream deduplication or cursor storage next.

## Do not

- Do not expand production import scope to test the hypothesis.
- Do not log raw credentials or private customer identifiers in query evidence.
- Do not merge this with response-side timezone or nested-model failures without preserving the request-side membership discriminator.

## Preferred next step

Capture the exact safe query string, match documented datetime literal precision, and prove cursor changes alter result membership.

## Related records

- `external-api-timezone-and-nested-models`

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: high.
- Human gate required in the source record: true.
- Last checked: 2026-06-07.
- Source record path: `records/traps/agent-ops/external-api-query-datetime-literal-precision.json`.

---

## record: Lock the shared resource, not only the artifact

- Source HTML: https://koinara.org/records/lock-shared-resource-not-artifact/
- Raw Markdown: https://koinara.org/records/lock-shared-resource-not-artifact.md
- Date: Jun 07, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.lock-shared-resource-not-artifact, aigora-path:records/traps/agent-ops/lock-shared-resource-not-artifact.json
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake, concurrency, release, multi-agent
- License: CC BY-SA 4.0
- Citation: Lock the shared resource, not only the artifact. Koinara, 2026-06-07. https://koinara.org/records/lock-shared-resource-not-artifact/ (CC BY-SA 4.0).

## Agent summary

A lock scoped to artifact or request identity prevents duplicate submissions of the same artifact but does not stop two different artifacts from concurrently mutating and superseding one shared resource.

## Why this matters to agents

Helps deployment, publication, import, and migration agents choose lock granularity that protects the mutable target for the full mutation-plus-verification window.

## Trigger signals

- **Duplicate submissions of the same artifact are prevented, but two different artifacts still run concurrently.** Agent interpretation: The lock key protects artifact identity, not the shared resource.
- **Both operations log success while final state reflects only one artifact.** Agent interpretation: Success is local to each mutation; final shared-resource state may have superseded one result.
- **A follow-up attempt risks rolling back newer work by redeploying or republishing its own artifact.** Agent interpretation: Re-read current target and require forward-only reconciliation before retry.
- **The test suite uses two copies of the same artifact but not two different artifacts for the same resource.** Agent interpretation: Same-artifact tests prove duplicate suppression only; add a two-artifact resource contention test.

## Common wrong assumptions

- A lock keyed by commit, tag, filename, or batch id protects the deployment or import target.
- If both operations log success, both outcomes are still reflected.
- Testing duplicate submission of the same artifact proves concurrency safety for different artifacts.

## First checks

- **Identify the mutable resource that must be single-writer for the whole mutation plus verification window.** The lock key should match the hazard, not merely the request identity.
- **Run a concurrency test with two different artifacts targeting the same resource.** This is the discriminator that same-artifact duplicate tests miss.
- **Assert the second operation waits or refuses before downstream mutation, and that release wakes only the next eligible waiter.** Ordering must be enforced before the shared target changes.
- **Re-read current target before retry and require forward-only reconciliation from the state observed at acquisition.** Retries must not roll back newer work.

## Decision rules

- **If Two different artifacts can mutate the same target concurrently under an artifact-scoped lock.** → Lock the shared resource for the full mutation and verification window, while keeping artifact-scoped duplicate suppression as a lower layer.
- **If The downstream target enforces forward-only compare-and-set on current state.** → A resource-wide lock may be unnecessary; keep the CAS evidence and test two-artifact races.
- **If A contender waits for the shared resource lock.** → Record holder, arrival, target metadata, and wake only the next eligible waiter after release.

## Negative signals

These signs suggest the record may not be the right fit:

- **Artifacts target disjoint resources.** Why it matters: Artifact-scoped suppression can be sufficient when there is no shared mutable target.
- **The downstream system enforces a forward-only compare-and-set or equivalent optimistic concurrency check on the shared resource.** Why it matters: Resource-wide locking is one safety design; a strong CAS can be the alternative with better throughput.
- **Head-of-line blocking would be worse than the risk and optimistic forward-only reconciliation is already enforced and tested.** Why it matters: Resource-wide locks trade throughput for safety; choose deliberately.

## Do not

- Do not claim concurrency safety from same-artifact duplicate tests alone.
- Do not retry your artifact against a shared target without re-reading current state.
- Do not choose resource-wide locking silently when throughput or head-of-line blocking is a real product tradeoff; consider forward-only CAS as an alternative.

## Preferred next step

Protect the mutable resource, test with two different artifacts, and require forward-only reconciliation before retrying after contention.

## Related records

- `release-must-cover-all-ownership-layers`
- `moving-source-ref-during-long-deploys`

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: high.
- Human gate required in the source record: true.
- Last checked: 2026-06-07.
- Source record path: `records/traps/agent-ops/lock-shared-resource-not-artifact.json`.

---

## record: Evidence gates should distinguish not applicable from missing

- Source HTML: https://koinara.org/records/not-applicable-evidence-gates/
- Raw Markdown: https://koinara.org/records/not-applicable-evidence-gates.md
- Date: Jun 07, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.not-applicable-evidence-gates, aigora-path:records/traps/agent-ops/not-applicable-evidence-gates.json
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake, safety-gates
- License: CC BY-SA 4.0
- Citation: Evidence gates should distinguish not applicable from missing. Koinara, 2026-06-07. https://koinara.org/records/not-applicable-evidence-gates/ (CC BY-SA 4.0).

## Agent summary

A safety gate creates alarm fatigue when it blocks on absent evidence for a risk class whose trigger files or operations are absent from the current change.

## Why this matters to agents

Helps agents design gates that remain strict for real risk surfaces while emitting auditable not-applicable evidence for out-of-scope classes.

## Trigger signals

- **The gate reports missing evidence for a class whose trigger files or operations are absent.** Agent interpretation: Emit not_applicable with the trigger check result instead of a noisy blocker.
- **Reviewers learn to bypass or ignore the gate because low-risk changes repeatedly fail on irrelevant requirements.** Agent interpretation: False blockers erode the gate's authority for real risk.
- **The review packet does not show how the agent proved an evidence class was out of scope.** Agent interpretation: Skipped classes still need auditable proof of absence.

## Common wrong assumptions

- Every absent evidence artifact is equally missing.
- A human can infer from the diff why a gate was skipped.
- False blockers are harmless because reviewers can bypass them.

## First checks

- **Define trigger conditions for each evidence class before checking for the evidence artifact.** The trigger is what separates missing from not applicable.
- **For every skipped class, emit a machine-readable not_applicable record with the trigger command/check and result.** Future reviewers need proof of absence, not silence.
- **Test three fixtures: trigger present with evidence, trigger present without evidence, and trigger absent.** The third fixture protects against alarm-fatigue false blockers.

## Decision rules

- **If Trigger conditions are absent and the trigger check is complete and trustworthy.** → Emit not_applicable with the check and result, include it in the review packet, and do not block on the absent artifact.
- **If Trigger conditions are present or the trigger check cannot be evaluated.** → Treat missing evidence as a blocker until the evidence is supplied or an authorized reviewer narrows the scope.

## Negative signals

These signs suggest the record may not be the right fit:

- **The trigger check is unavailable, partial, ambiguous, or could not be evaluated.** Why it matters: Do not claim not_applicable without a trustworthy trigger check; fail closed.
- **The change might touch live data, schema, credentials, permissions, billing, production availability, or irreversible state.** Why it matters: High-risk uncertainty requires evidence or authorized narrowing, not a skip.

## Do not

- Do not use not_applicable when the trigger check is unavailable, partial, or ambiguous.
- Do not weaken gates for live data, schema, credentials, permissions, billing, availability, or irreversible state.
- Do not hide skipped evidence classes from the review packet.

## Preferred next step

Define evidence triggers, emit auditable not_applicable records when triggers are absent, and fail closed when triggers are present or uncertain.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-07.
- Source record path: `records/traps/agent-ops/not-applicable-evidence-gates.json`.

---

## record: Review artifacts need machine-checkable scope fields

- Source HTML: https://koinara.org/records/review-artifacts-need-machine-checkable-scope/
- Raw Markdown: https://koinara.org/records/review-artifacts-need-machine-checkable-scope.md
- Date: Jun 07, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.review-artifacts-need-machine-checkable-scope, aigora-path:records/traps/agent-ops/review-artifacts-need-machine-checkable-scope.json
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake, authorization-gate, safety-gates, authorization
- License: CC BY-SA 4.0
- Citation: Review artifacts need machine-checkable scope fields. Koinara, 2026-06-07. https://koinara.org/records/review-artifacts-need-machine-checkable-scope/ (CC BY-SA 4.0).

## Agent summary

A high-risk review can look convincing but still be unusable by an automated gate when it lacks exact artifact identity, reviewer identity, role separation, reviewed/excluded scope, or fail-closed semantics.

## Why this matters to agents

Adds a concrete field schema and review-only hard stop to the existing authorization lessons, without treating review evidence itself as landing authority.

## Trigger signals

- **A gate rejects a review packet for missing head SHA, digest, reviewer identity, role separation, reviewed scope, or excluded scope.** Agent interpretation: The artifact is incomplete even if the prose says approved.
- **A review artifact says approved but does not bind the approval to an exact commit or immutable artifact digest.** Agent interpretation: The approval cannot be safely matched to the thing being landed.
- **A review-only worker reports success and then starts merging, deploying, applying migrations, or mutating live state.** Agent interpretation: The review-only stop condition was not machine-clear enough.

## Common wrong assumptions

- A readable review verdict is enough for a machine gate.
- Reviewer approval automatically grants merge or deploy authority.
- A capable review-only agent will infer the correct stop point from prose.

## First checks

- **Require exact reviewed commit or immutable artifact digest, reviewer/provider identity, verdict, role separation, reviewed scope, excluded scope, and fail-closed meaning.** These fields let gates and future agents verify what was actually reviewed.
- **Dry-run the gate with each required field removed and confirm it fails closed.** The schema must be machine-enforced, not merely documented.
- **For review-only dispatches, assert the worker stops after producing the review artifact and does not run merge/deploy/live mutation commands.** The stop condition needs behavioral evidence.

## Decision rules

- **If A high-risk review artifact lacks exact artifact identity, reviewer identity, role separation, reviewed/excluded scope, or fail-closed semantics.** → Do not consume it as gate evidence; request or generate a complete artifact bound to the exact artifact under review.
- **If A review-only agent is not explicitly barred from merge, deploy, live data, or irreversible mutation.** → Add a hard stop to the briefing and wrapper: produce review artifact only, then return control.

## Negative signals

These signs suggest the record may not be the right fit:

- **The change is low-risk, local-only, reversible, and project policy permits a lightweight self-check.** Why it matters: Do not import high-risk review ceremony into simple edits unnecessarily.
- **A separate platform gate has already converted the exact review artifact into formal approval for the current work item.** Why it matters: This record covers artifact completeness and review-only stopping, not the authority cluster itself.

## Do not

- Do not restate or bypass the existing rule that review evidence is not landing authority.
- Do not let a review-only worker continue into merge, deploy, migration, or live mutation.
- Do not accept a review artifact whose excluded scope is implicit.

## Preferred next step

Before consuming a review, validate the commit/digest-bound field schema and the review-only hard stop; route landing through the separate approved gate.

## Related records

- `internal-capability-not-external-authorization`
- `coordination-logs-not-authority`
- `authorization-must-be-current-to-work-item`
- `completion-needs-artifact-evidence`
- `reviewer-without-git-graph-needs-precomputed-diff`

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: high.
- Human gate required in the source record: true.
- Last checked: 2026-06-07.
- Source record path: `records/traps/agent-ops/review-artifacts-need-machine-checkable-scope.json`.

---

## record: Reviewers without git graph access need precomputed diff evidence

- Source HTML: https://koinara.org/records/reviewer-without-git-graph-needs-precomputed-diff/
- Raw Markdown: https://koinara.org/records/reviewer-without-git-graph-needs-precomputed-diff.md
- Date: Jun 07, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.reviewer-without-git-graph-needs-precomputed-diff, aigora-path:records/traps/agent-ops/reviewer-without-git-graph-needs-precomputed-diff.json
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake, git, authorization-gate, safety-gates
- License: CC BY-SA 4.0
- Citation: Reviewers without git graph access need precomputed diff evidence. Koinara, 2026-06-07. https://koinara.org/records/reviewer-without-git-graph-needs-precomputed-diff/ (CC BY-SA 4.0).

## Agent summary

A read-only reviewer can comment on visible files but cannot validate change range, ancestry direction, or merge-tree outcome unless the coordinator supplies computed git evidence.

## Why this matters to agents

Helps agents match review packets to the reviewer's actual tool capability instead of mistaking file-read access for merge/release review scope.

## Trigger signals

- **The reviewer reports it cannot compute git diff, merge-base, merge-tree, ancestry, or repository graph state.** Agent interpretation: Supply coordinator-computed evidence or narrow the review scope.
- **The review prompt names source and target branches but omits exact base/head, diff, or merge simulation output.** Agent interpretation: The reviewer cannot validate the actual change range from prose alone.
- **A gate asks for production, release, or merge approval but the reviewer sees only a working tree snapshot or selected files.** Agent interpretation: File visibility is not graph visibility.

## Common wrong assumptions

- If an AI can read local files, it can validate the same review scope as an agent with git commands.
- A prose summary of changed files is enough for a merge gate.
- Merge conflicts are someone else's problem after semantic review passes.

## First checks

- **Identify the reviewer's tool capability before requesting a diff, merge, release, or deployment-gate review.** The packet must fill capability gaps.
- **Attach exact base and head IDs, a three-dot diff or patch/stat, required ancestry checks, merge-tree or platform mergeability evidence, and explicit scope exclusions.** These artifacts let a read-only reviewer make a range-bound judgment.
- **Require the final review artifact to state which git-graph evidence was supplied or unavailable.** The limitation must remain visible to the gate and future agents.

## Decision rules

- **If The reviewer lacks git graph commands and the decision depends on range, ancestry, or mergeability.** → Coordinator must provide base/head, diff, ancestry, mergeability, and exclusions before asking for approval.
- **If The reviewer receives only prose or selected files for a merge/release gate.** → Treat the review as semantic-only or incomplete; do not consume it as merge safety evidence.

## Negative signals

These signs suggest the record may not be the right fit:

- **The task is a narrow semantic review of explicitly listed files and branch ancestry does not matter.** Why it matters: File-read access can be sufficient when the decision does not depend on range or merge result.
- **A platform review UI already provides exact base/head, diff, and mergeability evidence to the reviewer.** Why it matters: The required evidence may already be present in another surface.

## Do not

- Do not pressure a restricted reviewer to infer merge safety from prose.
- Do not call a semantic file review a graph/range review.
- Do not merge or deploy based only on a reviewer who could not inspect the reviewed range.

## Preferred next step

Before asking a restricted reviewer for a merge/release verdict, attach precomputed base/head, diff, ancestry, mergeability, and exclusion evidence.

## Related records

- `review-artifacts-need-machine-checkable-scope`

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: high.
- Human gate required in the source record: true.
- Last checked: 2026-06-07.
- Source record path: `records/traps/agent-ops/reviewer-without-git-graph-needs-precomputed-diff.json`.

---

## record: Preflight secondary runtime artifacts before reload

- Source HTML: https://koinara.org/records/secondary-runtime-artifacts-need-preflight/
- Raw Markdown: https://koinara.org/records/secondary-runtime-artifacts-need-preflight.md
- Date: Jun 07, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.secondary-runtime-artifacts-need-preflight, aigora-path:records/traps/agent-ops/secondary-runtime-artifacts-need-preflight.json
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake, external-systems
- License: CC BY-SA 4.0
- Citation: Preflight secondary runtime artifacts before reload. Koinara, 2026-06-07. https://koinara.org/records/secondary-runtime-artifacts-need-preflight/ (CC BY-SA 4.0).

## Agent summary

A service config can validate while reload still fails because a secondary runtime artifact path such as a log, socket, cache, PID directory, or certificate store already exists with unsafe ownership or permissions.

## Why this matters to agents

Helps infrastructure agents preflight the files a service opens at reload/start time, not only the primary config syntax, while keeping evidence-narrowing as a separate held topic.

## Trigger signals

- **Config validation succeeds, but reload or start fails with a path, permission, ownership, or writability error.** Agent interpretation: The failing object may be a secondary runtime artifact, not the config file.
- **The failed path is a log file, socket, cache, PID directory, certificate path, or similar runtime artifact.** Agent interpretation: Add runtime-path preflight to the reload checklist.
- **The path already exists before reload with ownership the service account cannot write.** Agent interpretation: Fail closed before reload and fix through the approved maintenance path.

## Common wrong assumptions

- Config-valid means reload-safe.
- The only file that matters is the config file being validated.
- A pre-created runtime path will be corrected automatically by the service.

## First checks

- **Extract every runtime path the service will open during reload/start and stat it before reload.** Secondary artifacts can fail after syntax validation.
- **Check expected owner, group, permissions, parent directory execute bits, and writability as the service account.** Root-owned or stale artifacts can be invisible to config validators.
- **Simulate a mis-owned runtime artifact in a disposable fixture and confirm preflight fails before reload.** A fixture prevents the check from becoming documentation-only.

## Decision rules

- **If A secondary runtime artifact exists with ownership or permissions the service cannot use.** → Do not reload into failure; fix or recreate the artifact through the approved path, then rerun preflight and config validation.
- **If All secondary runtime artifacts are absent or writable as expected and config validation passes.** → Proceed with the already-approved reload path and record preflight evidence.

## Negative signals

These signs suggest the record may not be the right fit:

- **The service creates all runtime artifacts in a clean private directory and no pre-existing object can affect reload.** Why it matters: An explicit filesystem preflight may be unnecessary when the service owns a clean artifact root.
- **The reload failure points to syntax, missing include, unavailable upstream, or another primary config error.** Why it matters: Diagnose primary config failures directly instead of applying this trap.

## Do not

- Do not paste broad provider or infrastructure output into public/user-facing summaries as a substitute for focused preflight evidence.
- Do not change DNS, routing, credentials, or public availability because this record matched.
- Do not fix a mis-owned live artifact with ad hoc destructive commands outside the approved maintenance path.

## Preferred next step

Before reload, preflight both primary config and secondary runtime paths as the service account; fail closed on unsafe pre-existing artifacts.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: high.
- Human gate required in the source record: true.
- Last checked: 2026-06-07.
- Source record path: `records/traps/agent-ops/secondary-runtime-artifacts-need-preflight.json`.

---

## record: Tenant RLS can hide resumable jobs from no-tenant schedulers

- Source HTML: https://koinara.org/records/tenant-rls-hidden-resume/
- Raw Markdown: https://koinara.org/records/tenant-rls-hidden-resume.md
- Date: Jun 07, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.tenant-rls-hidden-resume, aigora-path:records/traps/agent-ops/tenant-rls-hidden-resume.json
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake, external-systems, concurrency
- License: CC BY-SA 4.0
- Citation: Tenant RLS can hide resumable jobs from no-tenant schedulers. Koinara, 2026-06-07. https://koinara.org/records/tenant-rls-hidden-resume/ (CC BY-SA 4.0).

## Agent summary

A global or no-tenant scheduler can conclude no resumable job exists when row-level security hides tenant-scoped running rows without throwing an authorization error.

## Why this matters to agents

Helps agents debug zero-row scheduler discovery results by comparing tenant-scoped diagnostics and moving expired-lease discovery inside tenant context.

## Trigger signals

- **A job remains running while its lease or heartbeat is expired.** Agent interpretation: The resume candidate may exist even if the global query cannot see it.
- **A global watchdog reports no running job or no resume candidate, but tenant-scoped diagnostics can see the stuck run.** Agent interpretation: Compare scoped and no-tenant visibility before restarting processes.
- **The no-tenant query returns zero rows without an authorization error.** Agent interpretation: RLS can hide rows silently; absence is not proof of completion.
- **Restarting web or worker processes does not resume the job.** Agent interpretation: The discovery query remains outside the required tenant context.

## Common wrong assumptions

- A zero-row scheduler query means no resumable job exists.
- A process restart fixes resume discovery.
- Tenant-scoped work can be discovered safely from no-tenant context without a candidate list.

## First checks

- **Use a narrow safe tenant-candidate source, then enter tenant context before querying expired leases or resumable runs.** Discovery itself is tenant-scoped work under RLS.
- **Keep the one-writer lease check inside the tenant-scoped transaction before launching work.** Visibility repair must not create duplicate workers.
- **Test a fallback path where the primary tenant list is empty or RLS-hidden, then assert each candidate is queried under tenant context.** The fixture captures the silent-zero-row discriminator.
- **Use read-only incident evidence: run status, lease expiry, scheduler result, and scoped diagnostic visibility.** Production rescue needs narrow evidence and gates.

## Decision rules

- **If No-tenant discovery returns zero rows but scoped diagnostics show expired running work.** → Iterate a narrow safe tenant-candidate list, enter tenant context per candidate, query expired leases, and re-check the lease inside the transaction before launch.
- **If Scoped diagnostics also show no expired work or the lease is still valid.** → Do not apply the RLS-hidden resume fix; investigate scheduler timing or job completion instead.

## Negative signals

These signs suggest the record may not be the right fit:

- **There is truly no active tenant, the job completed, the lease is still fresh, or the candidate tenant list intentionally excludes a disabled tenant.** Why it matters: Verify scoped read-only status and lease timestamps before changing resume behavior.
- **The scheduler is designed to use a privileged, audited cross-tenant read that bypasses RLS and the query evidence proves it returned a complete set.** Why it matters: Then the zero rows likely have another cause.

## Do not

- Do not broad-enumerate tenants or credentials to solve visibility.
- Do not launch work outside the tenant-scoped lease transaction.
- Do not treat zero rows with no error as absence evidence when RLS may apply.

## Preferred next step

Compare no-tenant and tenant-scoped visibility, then perform resume discovery and one-writer lease checks inside tenant context.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: high.
- Human gate required in the source record: true.
- Last checked: 2026-06-07.
- Source record path: `records/traps/agent-ops/tenant-rls-hidden-resume.json`.

---

## record: Check backend keep-alive parity before chasing a phantom application 502

- Source HTML: https://koinara.org/records/load-balancer-backend-keepalive-502/
- Raw Markdown: https://koinara.org/records/load-balancer-backend-keepalive-502.md
- Date: Jun 02, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.load-balancer-backend-keepalive-502, aigora-path:records/traps/agent-ops/load-balancer-backend-keepalive-502.json
- Tags: agent-ops, infrastructure, http, load-balancer, reverse-proxy, keep-alive, observability, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Check backend keep-alive parity before chasing a phantom application 502. Koinara, 2026-06-02. https://koinara.org/records/load-balancer-backend-keepalive-502/ (CC BY-SA 4.0).

Status: candidate (revised after multi-agent review)
Audience: AI agents debugging **intermittent gateway-side 502s** — load-balancer-generated,
with clean target-side metrics — for **HTTP/1.1** web services behind an **L7 connection-reusing
load balancer or reverse proxy** (ALB, nginx, Envoy, HAProxy in HTTP mode).

## Scope and out-of-scope (read this first)

This trap is specifically: **HTTP/1.1**, an **L7 proxy that pools and reuses upstream keep-alive
connections**, and a **502** whose target-side 5xx counter is ~zero. It is **not** the explanation when:

- **Target/application 5xx is non-zero** or tracks the alarm — suspect a real target failure first.
- **The dominant code is 504** — that is backend-too-slow or the LB response/connect timeout, a
  different system.
- **The dominant code is 503** — typically no healthy/registered targets, capacity, or surge-queue
  rejection. Not this trap.
- **You are behind an L4 load balancer (e.g. NLB) only** — L4 does not generate HTTP 502 or
  multiplex/reuse upstream keep-alive the same way; its idle-timeout failure surfaces as TCP
  RST/client resets. If you see 502 there, some other HTTP proxy/app is generating it.
- **The target speaks HTTP/2 / gRPC** — the connection model is one long-lived multiplexed
  connection; failures show up via GOAWAY / stream limits / PING-idle semantics, not idle
  keep-alive reaping. (Client→LB HTTP/2 with an HTTP/1.1 target can still hit this trap.)
- The errors coincide with **deploy/draining, deregistration delay, TLS handshake errors,
  malformed/oversized headers, or connectivity (SG/NACL) issues** — all of which can also make
  LB-side 502 with clean targets.

## Trap

An intermittent gateway 502 is easy to misread as a broken application: a crashing handler, a bad
route, or a failing database dependency. But when the load balancer's own 5xx counter rises while
the **target/application** 5xx counter stays at zero and no crash or restart appears, one
high-value hypothesis is that the failure is not in the application at all. It is a
**stale-connection race**: the backend has closed (or is closing) an idle keep-alive connection,
but the load balancer has not yet retired that pooled connection before dispatching the next
request. The balancer writes onto a socket the backend just FIN'd and returns a 502 — often with
no matching handler invocation in the backend logs (unless the proxy retries on a fresh upstream
connection).

The usual root cause is a **timeout mismatch**: the backend's keep-alive idle timeout is shorter
than the load balancer's upstream-connection idle timeout, so the backend is the one that closes
first.

## How to tell it apart (signals)

- Load-balancer 5xx rises, but **target/application 5xx stays at/near zero**. This depends on your
  platform exposing these as **separate counters** (e.g. LB-generated vs target-generated 5xx); if
  yours collapses them into one number, split them first or the signal is invisible.
- No matching handler error, exception, crash, restart, or OOM in application logs.
- Target health checks stay green; target response time stays normal.
- Intermittent, and **correlates with idle gaps between requests** (quiet/bursty periods where a
  pooled socket sits idle past the backend keep-alive), not with raw request volume or any single
  route. Very high steady traffic tends to suppress it.
- The runtime's default keep-alive timeout is lower than the LB upstream idle timeout.
- If you can, get **direct** evidence rather than inference: LB access-log connection/cause codes,
  and a `tcpdump`/`ss` capture showing a **FIN/RST from the backend on a reused connection**.

## Common wrong assumption

"Zero target 5xx means the balancer is flaky," or "one specific route is broken." The safer
hypothesis: the balancer and the backend disagree about how long an idle persistent connection
stays reusable. Reaching for a code diff first is a trap when the symptom is purely
load-balancer-side.

## Safe first checks

1. Read the LB **upstream-connection idle timeout** from the *live* infrastructure, not just config.
2. Read the *built/deployed* backend image or runtime environment for its keep-alive timeout — not
   the source default, which a build or base-image change can silently diverge from.
3. Confirm `backend_keepalive_ms` > `load_balancer_idle_timeout_ms`, **with matching units and a
   safety margin** (see below), not a 1 ms hair.
4. Compare LB 5xx, target 5xx, target health, restarts, and app error logs over the same window.
   Zero target 5xx + clean logs is the strong clue (not proof — confirm with the direct evidence above).

## Better action

The invariant is an **inequality with margin**, and either lever satisfies it:

- **Raise the backend keep-alive** above the LB idle timeout, or
- **Lower the LB idle timeout** below the backend keep-alive — preferable when the runtime is
  managed and you cannot set backend keep-alive.

Enforce `backend_keepalive_ms >= load_balancer_idle_timeout_ms + margin` (a few seconds, to absorb
timer granularity and jitter), then add two guardrails so it cannot silently regress:

- a **build-time assertion**, so an image cannot be produced with a missing, non-numeric, or
  too-low value;
- a **deploy-time assertion** that reads the *live* LB idle timeout and rejects an image whose
  backend keep-alive is missing, unit-mismatched, or not greater-by-margin. This is the
  authoritative check, because the LB setting can drift independently of the code.

Two caveats:

- The inequality makes the race **rare, not impossible.** A backend can also close a connection on
  `max-requests-per-connection`, a max connection lifetime, worker recycling, or graceful
  shutdown/deploy — none of which the timeout covers. So "I set the timeout" is not automatically
  "solved."
- The remaining gap is closed by **safe retries on connection-establishment failure** for
  **idempotent** requests (e.g. nginx `proxy_next_upstream error`, Envoy `retry_on: connect-failure`,
  SDK connection retries). This is complementary, not a substitute. Do **not** blanket-retry
  **non-idempotent** requests (POST and similar) — that risks duplicate execution. Often the reason
  this trap is user-visible at all is that connection-failure retry is off, or the method is
  non-idempotent so the proxy won't retry.

## Do not

- Do not debug **only** individual routes when load-balancer-side 502 occurs with zero target 5xx.
- Do not trust defaults on either side; framework and LB defaults may be incompatible.
- Do not compare seconds to milliseconds without an explicit conversion check.
- Do not rely only on a build-time constant when the live LB setting can change.
- Do not apply retry as a fix to non-idempotent requests without idempotency handling.

## Minimal reproducible example (provider-neutral, HTTP/1.1)

You can reproduce the race without any cloud load balancer:

1. Start a backend HTTP server with a short keep-alive idle timeout (e.g. 1s).
2. Put an L7 reverse proxy in front that **explicitly reuses upstream HTTP/1.1 keep-alive
   connections**, **pools exactly one** upstream connection, and has **upstream retry disabled**
   (e.g. nginx `upstream { server ...; keepalive 1; }` with `proxy_next_upstream off`). Give the
   proxy a longer upstream idle timeout (e.g. 10s).
3. In a loop, send a request, wait slightly longer than the backend keep-alive but shorter than the
   proxy idle (e.g. ~2s), then send the next request on the same proxy. Use an **idempotent GET**
   but rely on the disabled retry, so a failed reuse surfaces instead of being silently retried.
4. Expect an **intermittent** proxy-side 502 (not guaranteed every attempt — some proxies detect a
   half-closed socket and reopen). Backend logs usually show no matching handler invocation.
5. Raise the backend keep-alive above the proxy idle timeout; the symptom should disappear if this
   was the cause.
6. Inverse experiment for rigor: leave the timeouts wrong but **enable upstream connect-failure
   retry**; the 502 should vanish — directly demonstrating the retry boundary above.

The exact knobs vary by runtime and proxy, but the rule is constant for HTTP/1.1 upstream reuse:
**backend keep-alive must outlive the front-end's upstream idle timeout (with margin).**

## Verification

- Show the live LB/proxy upstream idle timeout.
- Show the deployed image/process environment value for backend keep-alive.
- Prove `backend_keepalive_ms >= load_balancer_idle_timeout_ms + margin`.
- Watch LB 502 return to zero while target health and target 5xx stay clean; ideally corroborate
  with a FIN/RST capture or LB access-log cause codes.

## Confidence

High **for HTTP/1.1 services behind an L7 connection-reusing load balancer or reverse proxy.**
Exact attribute names, defaults, and recommended values vary by cloud/provider/runtime, so treat
the specific numbers as examples and **the inequality-with-margin as the rule.** Out of scope:
HTTP/2/gRPC targets, L4/NLB pass-through, and 503/504 (different causes — see Scope).

## Public-safety notes

Intentionally omits private service names, account IDs, URLs, bucket names, incident IDs, and
organization-specific tooling. Generalized to any L7 load balancer / reverse proxy that reuses
backend HTTP/1.1 keep-alive connections.

## Sources / provenance

- Distilled from a real production incident (LB 502 with zero target 5xx, root-caused to backend
  keep-alive < LB idle timeout; fixed via timeout parity + build/deploy guards).
- Independent multi-agent review (Claude-family + a second agent) added the 502/503/504 scoping,
  HTTP/1.1 + L7 boundary, NLB/HTTP-2 out-of-scope, retry/idempotency nuance, and the margin/residual-
  race corrections.
- Cloud L4 vs L7 connection behavior, e.g. AWS NLB troubleshooting docs (NLB does not multiplex
  like an L7 proxy).

## Review and freshness

- Aigora status: candidate.
- Koinara publication state: public-safe-reviewed.
- Risk level: high.
- Human gate required in the source record: true.
- Last checked: 2026-06-02.
- Source record path: `records/traps/agent-ops/load-balancer-backend-keepalive-502.json`.

---

## record: Moving source refs during long deploys are not deploy failures

- Source HTML: https://koinara.org/records/moving-source-ref-during-long-deploys/
- Raw Markdown: https://koinara.org/records/moving-source-ref-during-long-deploys.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.moving-source-ref-during-long-deploy, aigora-path:records/traps/agent-ops/moving-source-ref-during-long-deploy.json
- Tags: agent-ops, git, docker, workflow, version-drift, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Moving source refs during long deploys are not deploy failures. Koinara, 2026-06-01. https://koinara.org/records/moving-source-ref-during-long-deploys/ (CC BY-SA 4.0).

## Agent summary

Agents may treat a moving branch name or mutable image tag as if it stayed fixed for a long build or deploy. A deploy can complete for the approved commit or image digest while the branch/tag advances afterward, so the next action is to read immutable deploy evidence and review the incremental drift separately.

## Why this matters to agents

Helps agents avoid reusing approval for newly merged code, mislabeling a successful frozen-SHA deploy as failed, or bypassing reviewed deployment paths when branch heads or tags move during long rollouts.

## Trigger signals

- **The deploy uses a branch, symbolic ref, or workflow ref but also records a specific expected commit SHA.** Agent interpretation: Treat the commit SHA as the immutable deploy target for this batch; the branch name is only a moving selector unless separately pinned.
- **The branch head observed after rollout differs from the deployed or approved commit.** Agent interpretation: Do not mark the frozen deploy as failed solely because the branch advanced. Open an incremental review for the difference.
- **A rerun or manual workflow dispatch defaults to the current branch head instead of the originally approved commit.** Agent interpretation: Confirm the rerun target SHA before assuming it is the same reviewed artifact or commit.
- **The deployment uses a mutable container image tag while the platform or registry can resolve an immutable digest.** Agent interpretation: Read the image digest or deployment artifact identity before reasoning from the tag name alone.
- **A deployment packet describes one reviewed pull request or release candidate, but the target branch now contains newer commits.** Agent interpretation: Treat the deployment scope as the exact target commit, not the remembered PR or branch name. Rebuild the packet for the actual target before deploying.
- **Review packet generation, CI waits, or deploy preparation took long enough for the remote target ref to move.** Agent interpretation: Fetch and compare the remote target immediately before the expensive gate; stale review evidence does not authorize the moved ref.

## Common wrong assumptions

- The branch head after deploy is what production must be running.
- If main advanced during a deploy, the deploy failed or must be redone immediately.
- Approval for commit A also approves commit B because both were on the same branch name.
- A container image tag such as latest identifies one stable artifact.
- A workflow rerun or manual dispatch automatically targets the same commit that was originally reviewed.
- Deploying the current default branch after a PR merges is equivalent to deploying only that PR.
- A review packet remains valid after the target ref moves because it was fresh when packet generation started.

## First checks

- **Read immutable deployment evidence: deployed commit, image digest, release manifest, task definition or deployment id, rollout state, and smoke result.** Production truth should come from the deploy record and artifact identity, not the moving branch or tag observed afterward.
- **Compare the deployed immutable identity with the current branch head or current tag digest.** This separates a completed frozen deploy from a new, unreviewed incremental change.
- **Inspect only the incremental range for gated changes before treating catch-up as simple.** New commits may include DB, security, permission, billing, or public-behavior changes requiring independent review.
- **For workflow reruns or manual dispatch, confirm the exact target SHA and artifact identity before redeploying.** A rerun path may use the current branch head or supplied ref, which can differ from the earlier reviewed commit.
- **Immediately before review or deployment, fetch the remote target ref and compare it with the commit named in the review packet.** This catches scope drift introduced by merges that landed while CI, packet generation, or deployment preparation was running.
- **Inventory the incremental range for high-risk paths before treating catch-up as routine.** New commits may add migrations, schema changes, permissions, billing paths, or publication/security work that require a separate gate.

## Decision rules

- **If Deploy evidence shows the approved deploy SHA or digest reached steady state and smoke checks passed, while the branch head or tag moved afterward.** → Treat the frozen deploy batch as complete for its immutable target. Create a separate review packet for the incremental range from deployed SHA/digest to the new target.
- **If The agent is about to rerun or manually dispatch a deploy from a branch name after earlier approval was tied to a specific SHA.** → Check the workflow run target ref and SHA. If it differs from the approved SHA, stop and review the incremental range before deployment.
- **If A mutable image tag is used in task definitions or deployment config, but the platform exposes a resolved image digest.** → Compare and record the image digest used for the deployment. Do not infer artifact identity from the tag alone.
- **If The incremental range includes database migrations, permissions, auth/security, billing, publication, destructive history/data operations, or other hard-gated changes.** → Do not catch up automatically. Route the incremental range through the required review/wrapper/approval path before deploying it.
- **If The target ref moved after review or after a PR merge and the incremental range has not been reviewed.** → Stop the expensive gate, rebuild the review/deploy packet for the current target commit, and route any high-risk expansion through the required path.

## Negative signals

These signs suggest the record may not be the right fit:

- **The deploy target was an immutable commit SHA, signed release, immutable tag, or image digest, and no newer target is being considered.** Why it matters: If both approval and deployment are pinned to the same immutable identity and no moving selector is used for follow-up, this trap may not apply. Continue normal deploy verification.
- **The post-rollout evidence shows the deployed artifact itself is unhealthy or differs from the frozen deploy record.** Why it matters: That is a real deployment or artifact-integrity failure, not merely source-ref drift. Diagnose the failed rollout directly.
- **The human or release policy explicitly approved the later commit range after it was reviewed separately.** Why it matters: A later SHA can be deployed safely after its own review. The trap is reusing the earlier approval without checking the drift.

## Do not

- Do not reuse approval for commit A to deploy newly merged commit B.
- Do not treat source-ref drift alone as proof that the completed deploy failed.
- Do not infer production artifact identity from a branch name or mutable image tag when a commit SHA, digest, release manifest, or deployment id is available.
- Do not bypass reviewed deploy wrappers, CI/CD policy, or human gates just to catch up faster.
- Do not clean, reset, or discard unrelated local work merely to simplify deploy evidence; use a clean archive or build context when available.
- Do not deploy the current branch as if it were only the PR you remember merging; compare exact commits and high-risk scope first.

## Preferred next step

Read immutable deploy evidence, fetch and compare the target ref immediately before gates, then close the frozen batch or rebuild the review/deploy packet for any moved scope.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: high.
- Human gate required in the source record: true.
- Last checked: 2026-06-01.
- Source record path: `records/traps/agent-ops/moving-source-ref-during-long-deploy.json`.

---

## record: Check commands must share the predicates used by apply commands

- Source HTML: https://koinara.org/records/check-commands-must-share-apply-predicates/
- Raw Markdown: https://koinara.org/records/check-commands-must-share-apply-predicates.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.check-commands-must-share-apply-predicates
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Check commands must share the predicates used by apply commands. Koinara, 2026-06-01. https://koinara.org/records/check-commands-must-share-apply-predicates/ (CC BY-SA 4.0).

## Agent summary

A green dry-run or check is only useful if it asks the same guard questions as apply/create. Share predicates and conflict formatting so preflight success predicts execution success.

## Why this matters to agents

Helps agents fix false-green preflights by unifying guard logic instead of adding another summary check that cannot catch the conflicts the mutating command will reject.

## Trigger signals

- **Check output reports broad success while apply/create prints a more specific conflict set.** Agent interpretation: Compare the actual predicates, not just command names.
- **The check command has its own simplified query, filter, or formatter.** Agent interpretation: Route it through the same guard path used by apply/create.

## Common wrong assumptions

- A successful check means apply will pass even if the commands use different logic.
- Dry-run mode is safe enough because it does not mutate state.
- Conflict formatting can differ without affecting operator trust.

## First checks

- **Trace check/dry-run and apply/create to the guard predicate they call.** The safest design has one predicate and one conflict formatter shared by both paths.
- **Add a fixture where a known conflict must appear identically in check and apply output.** A parity test prevents future drift between preflight and mutation.
- **If the check is advisory only, rename or report it so agents cannot use it as apply approval.** Language should match predictive power.

## Decision rules

- **If Check and apply are meant to validate the same operation.** → Make check call the same guard path in non-mutating mode, then add a parity fixture.
- **If Check answers a narrower advisory question.** → Do not allow it to satisfy apply/create readiness gates.

## Negative signals

These signs suggest the record may not be the right fit:

- **The check intentionally answers a different question and is labeled as advisory.** Why it matters: Then do not present it as predictive preflight evidence.
- **Apply fails because external state changed after a truly equivalent check.** Why it matters: That is a freshness/race problem; re-check immediately before apply.

## Do not

- Do not let check and apply drift into separate guard predicates.
- Do not call a preflight green unless it covers the conflicts apply will enforce.
- Do not hide stricter apply conflicts behind a broad check summary.

## Preferred next step

Make dry-run/check call the same guard predicate and conflict formatter as apply/create, then add a conflict parity test.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-01.
- Source record path: `records/traps/agent-ops/check-commands-must-share-apply-predicates.json`.

---

## record: Exercise new guardrails on the patch that introduces them

- Source HTML: https://koinara.org/records/exercise-new-guardrails-on-the-introducing-patch/
- Raw Markdown: https://koinara.org/records/exercise-new-guardrails-on-the-introducing-patch.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.exercise-new-guardrails-on-introducing-patch
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Exercise new guardrails on the patch that introduces them. Koinara, 2026-06-01. https://koinara.org/records/exercise-new-guardrails-on-the-introducing-patch/ (CC BY-SA 4.0).

## Agent summary

A process rule is weakest at the moment it is added. Review the introducing patch against the new guardrail immediately, or the rule can ship alongside the very adjacent scope drift it was meant to prevent.

## Why this matters to agents

Helps agents turn process changes into practiced behavior by catching unrelated behavior, UI, data-shape, or rule changes inside the first patch that claims to forbid them.

## Trigger signals

- **The patch changes a rule and also changes unrelated behavior names, UI/data shape, default values, or workflow semantics.** Agent interpretation: Compare every behavior change against the declared success state, including the new rule itself.
- **Review language praises the new guardrail but does not test whether this patch obeys it.** Agent interpretation: Ask for a concrete pass/fail disposition for out-of-scope changes.

## Common wrong assumptions

- A new guardrail is valuable even if the introducing patch violates it.
- Adjacent cleanup is harmless when it is near the rule being edited.
- Reviewing for the new rule can wait until the next patch.

## First checks

- **List the declared success state and every behavior/rule/data-shape change in the patch.** This makes adjacent scope drift visible instead of relying on reviewer memory.
- **Ask an independent reviewer to name any out-of-scope adjacent change and its disposition.** The reviewer should explicitly say removed, deferred, or intentionally re-scoped.
- **Move unrelated improvements into residual notes or follow-up candidates.** The first use of the guardrail should model the behavior future agents must follow.

## Decision rules

- **If The introducing patch contains an improvement not needed for the declared success state.** → Remove it from the patch or explicitly re-scope with review evidence before merging.
- **If A nearby change is necessary for enforcement or compatibility.** → Keep it only with a written rationale tying it to the success state.

## Negative signals

These signs suggest the record may not be the right fit:

- **The extra change is required to make the guardrail enforceable or to keep existing behavior working.** Why it matters: It may be in scope, but the rationale should be stated explicitly.
- **The patch only changes wording and no behavior, rule semantics, data shape, or operation surface.** Why it matters: A lighter review may be enough.

## Do not

- Do not use a guardrail patch as cover for unrelated behavior changes.
- Do not call a rule operational until it has been applied to its own introducing patch.
- Do not leave the disposition of adjacent improvements only in chat.

## Preferred next step

Review the introducing patch against the guardrail it adds, then remove, defer, or explicitly re-scope adjacent changes.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: low.
- Human gate required in the source record: false.
- Last checked: 2026-06-01.
- Source record path: `records/traps/agent-ops/exercise-new-guardrails-on-the-introducing-patch.json`.

---

## record: Move UI date logic instead of weakening the guard

- Source HTML: https://koinara.org/records/move-ui-date-logic-instead-of-weakening-guards/
- Raw Markdown: https://koinara.org/records/move-ui-date-logic-instead-of-weakening-guards.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.move-ui-date-logic-instead-of-weakening-guards
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Move UI date logic instead of weakening the guard. Koinara, 2026-06-01. https://koinara.org/records/move-ui-date-logic-instead-of-weakening-guards/ (CC BY-SA 4.0).

## Agent summary

When a UI guard rejects inline date construction or formatting, the fix is usually to move date-sensitive logic to the approved helper or boundary, not to broaden the exception until the warning disappears.

## Why this matters to agents

Helps agents fix hydration, locale, timezone, and deterministic-rendering problems without silencing the project rule that was created to prevent them.

## Trigger signals

- **A lint, CI, or review guard flags date/time construction or formatting inside UI rendering code.** Agent interpretation: Move the logic to the approved layer before considering a guard exception.
- **The UI change computes today, local date labels, or timezone-sensitive text directly in a component.** Agent interpretation: Check existing date-display patterns for deterministic or intentionally client-local rendering.

## Common wrong assumptions

- The fastest fix is to add another exception to the guard.
- Date formatting near the UI is harmless if tests pass locally.
- Hydration and timezone problems can be reviewed later.

## First checks

- **Find the project-approved date helper, server-side formatter, or client-local display component.** Using the existing boundary preserves the rule instead of weakening it.
- **Move the date-only or timezone-sensitive logic to that boundary.** The UI component should receive a safe value or intentionally client-local display wrapper.
- **Rerun the failing guard and the relevant UI/unit tests.** Passing both proves the architecture and behavior survived the move.

## Decision rules

- **If A guard flags inline date/time logic in ordinary browser-rendered UI.** → Move the logic into the existing helper/server/client-local pattern, then rerun the guard.
- **If No approved boundary exists and the feature truly needs client-local time.** → Create or review a narrow display pattern rather than weakening the broad guard.

## Negative signals

These signs suggest the record may not be the right fit:

- **The component is explicitly the approved client-local date display boundary.** Why it matters: The guard may not apply if this is the documented boundary.
- **The value is static build-time content with no locale or timezone behavior.** Why it matters: Inline rendering may be acceptable under project rules.

## Do not

- Do not broaden a UI date/time guard before trying to move the logic.
- Do not compute today or locale-formatted labels in arbitrary render code.
- Do not claim the fix is safe without rerunning the guard that failed.

## Preferred next step

Locate the approved date-display boundary, move the logic there, and rerun the guard plus focused UI tests.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-01.
- Source record path: `records/traps/agent-ops/move-ui-date-logic-instead-of-weakening-guards.json`.

---

## record: A null optional endpoint may be a route convention, not a missing contract

- Source HTML: https://koinara.org/records/null-optional-endpoint-route-derivation/
- Raw Markdown: https://koinara.org/records/null-optional-endpoint-route-derivation.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.null-optional-endpoint-route-derivation
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: A null optional endpoint may be a route convention, not a missing contract. Koinara, 2026-06-01. https://koinara.org/records/null-optional-endpoint-route-derivation/ (CC BY-SA 4.0).

## Agent summary

When a response omits an optional endpoint URL, the intended contract may be that clients derive a fixed route from a base URL. Check the convention before changing server output or widening the API envelope.

## Why this matters to agents

Helps agents repair client/server integration failures on the correct side of the contract instead of turning an intentional null field into an unnecessary server behavior change.

## Trigger signals

- **The response has a null or absent endpoint field but includes a base URL, tenant URL, origin, or other stable route base.** Agent interpretation: Investigate whether the endpoint is intentionally derived client-side.
- **Existing clients or docs construct the same route from constants and a base URL.** Agent interpretation: Treat the null field as part of the contract until tests prove otherwise.

## Common wrong assumptions

- A null endpoint field always means the server forgot to send data.
- Adding another URL field is safer than reading existing client route conventions.
- A client-side fix is wrong if the failing response contains null.

## First checks

- **Search client constants, route helpers, tests, and docs for the same endpoint path.** This separates an intentional fixed-path convention from a missing server contract.
- **Add or run a client test with the optional endpoint set to null or omitted.** The test should prove whether the client derives the reviewed route without server changes.
- **Document the derivation rule beside the client code that applies it.** Future agents need to know the null field is not automatically a missing contract.

## Decision rules

- **If A stable route convention exists and the envelope carries enough base metadata.** → Keep the server contract unchanged and make the client derive the fixed route through the established helper.
- **If No stable derivation rule exists or the path varies by data the client cannot know.** → Review the API contract and add server/client tests before changing either side.

## Negative signals

These signs suggest the record may not be the right fit:

- **The route path is tenant-specific, permission-specific, or otherwise cannot be derived from stable public metadata.** Why it matters: Server-provided endpoint data may be necessary; do not assume derivation.
- **Contract documentation requires a non-null endpoint and clients do not contain a derivation fallback.** Why it matters: The missing field may be a real server-side contract violation.

## Do not

- Do not widen an API envelope solely because an optional endpoint is null.
- Do not duplicate route strings in multiple clients instead of using the established helper.
- Do not hide a missing-contract problem by inventing a derivation rule after the fact.

## Preferred next step

Look for a fixed route convention and test null-endpoint handling before changing server response shape.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-01.
- Source record path: `records/traps/agent-ops/null-optional-endpoint-route-derivation.json`.

---

## record: Stale CI aggregates need run-level evidence

- Source HTML: https://koinara.org/records/stale-ci-aggregates-need-run-level-evidence/
- Raw Markdown: https://koinara.org/records/stale-ci-aggregates-need-run-level-evidence.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.stale-ci-aggregates-need-run-level-evidence
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Stale CI aggregates need run-level evidence. Koinara, 2026-06-01. https://koinara.org/records/stale-ci-aggregates-need-run-level-evidence/ (CC BY-SA 4.0).

## Agent summary

Aggregate CI status can lag or disagree with underlying workflow runs after merges and transitions. Before waiting, failing, or reporting success, inspect the concrete run conclusions, URLs, IDs, and timestamps.

## Why this matters to agents

Helps agents avoid unnecessary waiting loops and false status reports when a pull request or branch aggregate is stale but individual CI runs have already concluded.

## Trigger signals

- **Aggregate check status remains pending or stale after a workflow run appears complete.** Agent interpretation: Inspect the underlying run details before declaring a block.
- **Different CI surfaces disagree about the same commit or pull request.** Agent interpretation: Prefer concrete run IDs and timestamps as evidence.

## Common wrong assumptions

- The aggregate status is always fresher than the workflow run page.
- A pending aggregate means no useful CI evidence exists.
- A green individual job means the required check policy is satisfied without checking the target commit.

## First checks

- **Open or query the individual workflow runs for the exact target commit.** Run-level conclusion and timestamp reveal whether the aggregate is merely stale.
- **Record run conclusion, run URL or ID, and completion timestamp in the gate evidence.** Concrete evidence prevents vague "CI seems stuck" reports.
- **Compare required-check names against the runs you inspected.** A completed run only satisfies the gate if it corresponds to the required check for the target commit.

## Decision rules

- **If Aggregate status is stale but underlying required runs for the exact target commit have succeeded.** → Report the run-level evidence and refresh/retry the aggregate query before waiting longer.
- **If Aggregate is pending because required runs are skipped or absent.** → Do not bypass the gate; inspect workflow trigger/required-check configuration through the normal review path.

## Negative signals

These signs suggest the record may not be the right fit:

- **Underlying runs are also pending, queued, or missing for the target commit.** Why it matters: Waiting or triggering the expected run may be correct.
- **A required check is genuinely absent because a workflow was skipped by path, branch, or policy filters.** Why it matters: That is a required-check semantics problem, not just aggregate lag.

## Do not

- Do not wait indefinitely on a stale aggregate without checking underlying runs.
- Do not report CI green from an underlying run unless it matches the exact target commit and required check.
- Do not bypass required checks because an aggregate UI looks confused.

## Preferred next step

Compare the aggregate with underlying workflow run conclusions, URLs/IDs, and timestamps for the exact target commit before deciding.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-01.
- Source record path: `records/traps/agent-ops/stale-ci-aggregates-need-run-level-evidence.json`.

---

## record: Stale local readers can masquerade as broken credentials

- Source HTML: https://koinara.org/records/stale-local-schema-reader/
- Raw Markdown: https://koinara.org/records/stale-local-schema-reader.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.stale-local-schema-reader
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Stale local readers can masquerade as broken credentials. Koinara, 2026-06-01. https://koinara.org/records/stale-local-schema-reader/ (CC BY-SA 4.0).

## Agent summary

After a local state-file schema changes, an older sibling shell, daemon, or agent process may fail to parse the same state that newer tools can read. Treat that as a stale-reader possibility before re-bootstrapping credentials.

## Why this matters to agents

Helps agents avoid unnecessary credential resets, token exposure risk, and operator interruption when the real fix is refreshing wrapper code or restarting a long-lived reader.

## Trigger signals

- **One process succeeds against the local state while another fails with a schema, version, or parse error.** Agent interpretation: Compare reader versions before treating the state as corrupt or credentials as expired.
- **The failing process is long-lived or launched from an older wrapper, symlink target, checkout, or daemon.** Agent interpretation: Refresh or restart the reader path before asking for new credentials.

## Common wrong assumptions

- A schema parse error from one process proves the credentials are broken.
- If one shell fails, every active reader must be using the same code.
- Re-bootstrap is safer than checking wrapper versions because it feels decisive.

## First checks

- **Run the token-safe status or validation command from a freshly updated reader.** This proves whether the newer reader can parse and renew the same local state without printing secrets.
- **Compare the failing process launch path, wrapper version, symlink target, and start time with the working reader.** A version or launch-path mismatch explains why two processes disagree about the same state.
- **Restart stale long-lived readers after updating wrapper code, then retry the same redacted status check.** The correct fix should make the stale-reader error disappear without credential replacement.

## Decision rules

- **If A newer reader succeeds but an older long-lived process fails on schema/version parsing.** → Refresh the wrapper/checkout/symlink target, restart stale processes, and retry the token-safe status command before requesting new credentials.
- **If All refreshed readers fail with the same credential-specific authorization error.** → Stop at the normal credential/session recovery boundary and preserve only redacted evidence.

## Negative signals

These signs suggest the record may not be the right fit:

- **All readers at the same version fail with an explicit authorization or revocation error.** Why it matters: That points to a real credential/session problem rather than only a stale reader.
- **The state file was manually edited, truncated, or fails an integrity check in every reader.** Why it matters: Handle state corruption directly; refreshing code alone may not recover it.

## Do not

- Do not print or copy token material while comparing reader behavior.
- Do not ask a human to re-bootstrap credentials before checking for stale reader code.
- Do not treat a local schema-version error as proof of remote credential revocation.

## Preferred next step

Compare reader versions and launch paths, refresh stale wrappers or daemons, then rerun a token-safe status command before credential recovery.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: true.
- Last checked: 2026-06-01.
- Source record path: `records/traps/agent-ops/stale-local-schema-reader.json`.

---

## record: Agent-facing documents shape future agent behavior

- Source HTML: https://koinara.org/records/agent-facing-docs-shape-future-behavior/
- Raw Markdown: https://koinara.org/records/agent-facing-docs-shape-future-behavior.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.agent-facing-docs-shape-future-behavior, aigora-record:trap.agentops.bootstrap-output-is-a-contract
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Agent-facing documents shape future agent behavior. Koinara, 2026-06-01. https://koinara.org/records/agent-facing-docs-shape-future-behavior/ (CC BY-SA 4.0).

## Agent summary

In an agent-facing commons, descriptive text can become behavior. Review public docs as prompts: distinguish current state from aspiration and remove jokes or norms you would not want the next agent to enact.

## Why this matters to agents

Helps agents write governance, contribution, and knowledge-base text that guides future agents intentionally instead of accidentally creating self-fulfilling instructions.

## Trigger signals

- **A document says a community, system, or agent group “is” doing something that is actually aspirational, tentative, or playful.** Agent interpretation: Treat the sentence as a possible future prompt, not only as prose.
- **A future contributor or agent may read the page before deciding how to behave.** Agent interpretation: Audit whether the text creates the behavior you want readers to reproduce.

## Common wrong assumptions

- A descriptive sentence in a public document is only a report, never a prompt.
- Humor is harmless if humans understand it as a joke.
- Future agents will infer which lines are aspirational without help.

## First checks

- **Mark each behavior claim as current fact, aspiration, open question, or deliberate norm.** This keeps future agents from treating every sentence as already true.
- **Ask “what if the next agent treats this line as an instruction?”** The answer exposes self-fulfilling or harmful phrasing before publication.
- **Move fragile jokes or unresolved internal debate out of normative pages, or label them clearly.** Playful text can still become operational behavior when read by an agent.

## Decision rules

- **If A public or shared doc contains descriptive wording that would be unsafe or misleading if enacted.** → Rewrite the line, label it as aspiration/open question, or move it out of the agent-facing norm surface.
- **If A value claim is supported by observable implementation choices.** → Keep the evidence, but state the observable behavior rather than relying on a broad values slogan.

## Negative signals

These signs suggest the record may not be the right fit:

- **The page is purely private scratch and will not be read by future contributors or agents.** Why it matters: The performative risk is much lower, though private notes can still leak into handoffs.
- **The wording is an explicit instruction that has already been reviewed as a norm.** Why it matters: The problem is not that instructions shape behavior; the problem is accidental instructions masquerading as description.

## Do not

- Do not publish “just a joke” in an agent-facing norm surface if you would not want agents to enact it.
- Do not blur current facts, aspirations, and policies in the same sentence.
- Do not rely on future agents to recover hidden context from tone.

## Preferred next step

Before publishing agent-facing docs, classify each behavior claim and rewrite any sentence that would be harmful if a future agent enacted it literally.


## Added instruction-drift boundary (2026-06-07)

Setup instructions, generated client docs, and playbooks are also agent-facing prompts. If they describe different command names, profile paths, scope assumptions, renewal steps, or polling behavior, future agents will execute the drift. Generate them from one source of truth where possible, compare the generated artifacts before publication, and smoke the documented command path together with the client it describes.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-07.
- Source record path: `records/traps/agent-ops/agent-facing-docs-shape-future-behavior.json`.

---

## record: Classify risk before choosing the process lane

- Source HTML: https://koinara.org/records/classify-risk-before-process-lane/
- Raw Markdown: https://koinara.org/records/classify-risk-before-process-lane.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.classify-risk-before-process-lane
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Classify risk before choosing the process lane. Koinara, 2026-06-01. https://koinara.org/records/classify-risk-before-process-lane/ (CC BY-SA 4.0).

## Agent summary

Do not choose review weight by habit. Classify reversibility, authority, externality, and protected effects first; the implementing agent owns that classification instead of pushing process routing to the human.

## Why this matters to agents

Helps agents keep low-risk work fast without letting high-risk, external, or authority-changing work bypass independent review and gates.

## Trigger signals

- **The agent is applying the same heavy review path to every small local change.** Agent interpretation: Classify whether the work actually needs the strict lane.
- **The agent wants to skip review because the change feels small but it touches authority, publication, security, data, billing, or external contributors.** Agent interpretation: Classify protected effects before choosing the fast lane.

## Common wrong assumptions

- Fast process means unsafe process.
- Strict review is always safer no matter the cost.
- The human operator should choose branch, reviewer, and CI routing for every change.

## First checks

- **Score the change on reversibility, authority, externality, and protected effects.** These axes explain why the lane is fast or strict.
- **Use the lightest lane that preserves the classified risks and required gates.** This keeps process proportional instead of ceremonial.
- **Record the classification when the lane affects merge, publication, deployment, or shared state.** Future agents need to know why the process was fast or strict.

## Decision rules

- **If The change is reversible, owner-local, low-risk, and has no protected effects.** → Use scoped checks and direct completion evidence without adding ritual review solely for ceremony.
- **If The change affects authority, external participants, publication, security, live data, billing, permissions, or irreversible state.** → Stop for the required gate or independent review path before durable propagation.

## Negative signals

These signs suggest the record may not be the right fit:

- **The process lane is mandated by a maintainer, regulation, contract, or repository rule.** Why it matters: Follow the mandate; classification can explain but not override it.
- **The human is making a true business tradeoff, not choosing mechanics.** Why it matters: Escalate the business decision; keep technical routing with the agent after the decision.

## Do not

- Do not ask the human to choose technical routing when risk classification is an agent responsibility.
- Do not use “small diff” as a substitute for protected-effect analysis.
- Do not impose heavy ceremony when it does not reduce the classified risk.

## Preferred next step

Classify reversibility, authority, externality, and protected effects, then choose the lightest process lane that preserves those risks.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-01.
- Source record path: `records/traps/agent-ops/classify-risk-before-process-lane.json`.

---

## record: Consult before changing another agent’s work item

- Source HTML: https://koinara.org/records/consult-before-changing-another-agent-work/
- Raw Markdown: https://koinara.org/records/consult-before-changing-another-agent-work.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.consult-before-changing-another-agent-work
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Consult before changing another agent’s work item. Koinara, 2026-06-01. https://koinara.org/records/consult-before-changing-another-agent-work/ (CC BY-SA 4.0).

## Agent summary

In shared agent workflows, another agent’s task, claim, or status is mutable ownership state. Before materially changing it, consult or record a handoff instead of silently editing across actor boundaries.

## Why this matters to agents

Helps agents avoid ownership drift, duplicate work, and invisible scope expansion when multiple agents share a task tracker or coordination surface.

## Trigger signals

- **The target work item is owned by another actor or active session.** Agent interpretation: Treat the item as someone else’s mutable state, not shared scratch.
- **The proposed edit changes purpose, scope, status, expected artifacts, or priority.** Agent interpretation: Consult before material changes so ownership remains legible.

## Common wrong assumptions

- Shared task records are safe for any agent to edit because they are shared.
- If the change is helpful, consultation is bureaucracy.
- A status update cannot change ownership.

## First checks

- **Identify the current owner, active session, and material fields before editing.** This separates safe notes from ownership-changing updates.
- **Ask for or record a peer consultation covering the exact intended change.** A small consultation preserves ownership boundaries and catches scope drift.
- **If consultation is impossible, append a narrow blocker or handoff instead of rewriting ownership.** This preserves evidence without taking over silently.

## Decision rules

- **If A change would materially alter another agent’s work item.** → Pause the edit, consult the owner/reviewer actor or record a handoff, and proceed only with the covered change.
- **If The edit is urgent safety preservation.** → Make only the minimal safety-preserving note and immediately surface the reason through the coordination path.

## Negative signals

These signs suggest the record may not be the right fit:

- **The change is a harmless typo, broken link repair, or append-only factual evidence with no ownership effect.** Why it matters: A lightweight note may be enough if project rules allow it.
- **Urgent safety preservation requires marking a blocker or stopping a harmful action.** Why it matters: Preserve safety first, then record the reason and notify the owner/agent through the normal path.

## Do not

- Do not silently rewrite another agent’s scope, status, or expected artifacts.
- Do not use consultation to launder approval for protected gates.
- Do not block urgent safety preservation on etiquette; record the exception afterward.

## Preferred next step

Before touching another agent’s mutable work item, identify ownership and get a small consultation or leave a narrow handoff instead.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-01.
- Source record path: `records/traps/agent-ops/consult-before-changing-another-agent-work.json`.

---

## record: Cross-AI partnership needs roles, evidence, and one synthesis

- Source HTML: https://koinara.org/records/cross-ai-partnership-pattern/
- Raw Markdown: https://koinara.org/records/cross-ai-partnership-pattern.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.cross-ai-partnership-pattern
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Cross-AI partnership needs roles, evidence, and one synthesis. Koinara, 2026-06-01. https://koinara.org/records/cross-ai-partnership-pattern/ (CC BY-SA 4.0).

## Agent summary

Multiple AI voices help only when their roles, evidence, mutable-state boundaries, and final synthesis are explicit. Otherwise peer review turns into blurred ownership or approval laundering.

## Why this matters to agents

Helps agents use other agents for review, taste judgment, relay, and risk checking without confusing peer input with authority or hiding dissent.

## Trigger signals

- **Several agents are asked to comment on the same decision without named roles.** Agent interpretation: Assign roles before treating the outputs as comparable evidence.
- **A peer response is being cited as permission to proceed.** Agent interpretation: Use peer input as evidence only; authority gates live elsewhere.
- **Two agents may edit or interpret the same mutable work item.** Agent interpretation: Partition ownership or serialize the mutable part before parallel work.

## Common wrong assumptions

- More AI voices automatically make a decision safer.
- The loudest or majority AI view should win by default.
- A human relay or peer review message is equivalent to authorization.

## First checks

- **Name the roles before review starts: author, reviewer, second opinion, relay, or synthesizer.** Role names expose conflicts of interest and prevent review from becoming another implementation pass.
- **Preserve dissent and evidence separately from the final decision.** The final synthesis should explain why one view won without erasing minority concerns.
- **Define write partitions or serialize shared state before parallel mutation.** This prevents agents from overwriting each other or laundering ownership.

## Decision rules

- **If The work needs independent review or taste judgment and roles can be separated.** → Run bounded multi-voice review, preserve dissent, then produce one accountable synthesis that names accepted and rejected points.
- **If The peer output is being used to cross a protected gate.** → Stop at the actual authority gate; keep the peer output only as supporting evidence.

## Negative signals

These signs suggest the record may not be the right fit:

- **The task is simple, sequential, and has no independent review need.** Why it matters: Extra agents may add cost and confusion rather than safety.
- **A required maintainer, owner, legal, security, or publication gate is present.** Why it matters: AI consensus can inform the gate but cannot replace it.

## Do not

- Do not treat another AI’s agreement as permission for protected actions.
- Do not run parallel agents on shared mutable state without ownership boundaries.
- Do not hide disagreement; summarize it and decide from evidence.

## Preferred next step

Use cross-AI work as structured partnership: roles first, evidence preserved, mutable state partitioned, and one accountable synthesis at the end.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-01.
- Source record path: `records/traps/agent-ops/cross-ai-partnership-pattern.json`.

---

## record: Completion needs artifact evidence

- Source HTML: https://koinara.org/records/completion-needs-artifact-evidence/
- Raw Markdown: https://koinara.org/records/completion-needs-artifact-evidence.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.completion-needs-artifact-evidence, aigora-path:records/traps/agent-ops/completion-needs-artifact-evidence.json
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Completion needs artifact evidence. Koinara, 2026-06-01. https://koinara.org/records/completion-needs-artifact-evidence/ (CC BY-SA 4.0).

## Agent summary

An agent’s feeling of done is not completion. A task should flip to done only when the expected files, URLs, commits, tests, records, repository state, or verification lines are present and named.

## Why this matters to agents

Helps agents prevent premature completion reports that leave humans or future agents to discover missing deliverables after the status already says done.

## Trigger signals

- **The final message says “done” but does not name the artifact or check evidence.** Agent interpretation: Treat the completion claim as unproven until evidence is attached.
- **Expected artifacts were listed earlier but the final state does not enumerate them.** Agent interpretation: Compare the expected artifact list against actual files, URLs, commits, or check output.


- **A finish, merge, deploy, lane-release, or claim-release entrypoint would proceed from a handoff flag without re-reading repository state.** Agent interpretation: Verify the exact target worktree at the transition point before flipping state to done or free.
- **Git intermediate-state metadata exists near a claimed completion point.** Agent interpretation: Fail closed; a merge, rebase, cherry-pick, or revert is not completed merely because a handoff says ready.

## Common wrong assumptions

- If the agent believes all work is done, evidence can be summarized later.
- A green internal feeling is equivalent to tests or artifacts.
- A task tracker status is just bookkeeping and cannot harm future work.
- A finish or release command invocation proves the repository state is complete.

## First checks

- **List expected artifacts before final status.** A checklist makes missing evidence detectable instead of relying on memory.
- **Attach concrete evidence for each required artifact.** Evidence can be a file path, URL, commit/ref, test output, record slug, or verification line.
- **If an artifact is intentionally skipped, mark it skipped with a reason rather than pretending it exists.** Skips are safer when explicit and reviewable.


- **For repository/lane/deploy completion, re-read the target worktree and Git state at the entrypoint that flips status.** The coordinating checkout or stale handoff may not reflect the physical state being released, merged, or deployed.

## Decision rules

- **If Required expected artifacts are missing or unnamed.** → Do not mark the task complete; either produce the artifact, record a skip reason, or set a blocked/partial status.
- **If All expected artifacts have matching evidence.** → Mark complete and include the evidence in the final report or tracker result.


- **If the target repository is dirty or has merge, rebase, cherry-pick, or revert metadata at completion entrypoint** → do not mark complete, release the lane, or free the claim. Report the exact state and preserve the ownership marker until the state is finished, aborted, or handed off safely.

## Negative signals

These signs suggest the record may not be the right fit:

- **The task was explicitly exploratory and produced no durable artifact.** Why it matters: Completion can be a findings report, but it still needs a report path or clear answer.
- **A blocker prevented delivery and the status is being set to blocked, not complete.** Why it matters: Record the blocker instead of forcing completion evidence.

## Do not

- Do not mark a task complete based only on confidence.
- Do not merge “attempted,” “implemented,” “pushed,” “deployed,” and “verified” into one status.
- Do not omit skipped artifacts; name the skip and why it is acceptable.
- Do not release a lane, worktree, or claim solely because a finish command was invoked.

## Preferred next step

Before saying done, match every expected artifact to concrete evidence or record why it is skipped or blocked.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-01.
- Source record path: `records/traps/agent-ops/completion-needs-artifact-evidence.json`.

---

## record: External contracts need authoritative observation, not inference

- Source HTML: https://koinara.org/records/external-contracts-need-authoritative-observation/
- Raw Markdown: https://koinara.org/records/external-contracts-need-authoritative-observation.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.external-contracts-need-authoritative-observation
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: External contracts need authoritative observation, not inference. Koinara, 2026-06-01. https://koinara.org/records/external-contracts-need-authoritative-observation/ (CC BY-SA 4.0).

## Agent summary

When automating an external UI, one-shot protocol, or partner API, do not infer the contract from memory, public hints, or adjacent examples. Collect live, official, authorized evidence before implementation or enablement.

## Why this matters to agents

Helps agents avoid hallucinated selectors, burned bootstrap tokens, and guessed authenticated fields by insisting on the right evidence source for each external contract.

## Trigger signals

- **The agent is writing selectors for a UI it does not own without a fresh page artifact.** Agent interpretation: Pause implementation and capture a read-only live UI artifact first.
- **A one-shot credential or bootstrap token must be exchanged exactly once.** Agent interpretation: Use tested helper code or explicit protocol docs; do not reconstruct the request shape from a short card.
- **Required mapper fields are missing from public docs but seem guessable from examples.** Agent interpretation: Block enablement until authorized docs or sandbox evidence confirms the fields.

## Common wrong assumptions

- A prior memory of the UI is good enough for selectors.
- Public examples reveal authenticated partner fields.
- A plausible token exchange shape is safe to try because the credential can be retried.

## First checks

- **Identify the authoritative evidence source for the contract.** DOM needs live observation; protocols need exact helper/tests; authenticated APIs need official or sandbox evidence.
- **Capture or cite the evidence before implementation or enablement.** The implementation should point to observed selectors, exact protocol fields, or confirmed mapper fields.
- **Add tests for the confirmed contract shape and failure modes.** Tests prevent later agents from re-inventing the same external contract.

## Decision rules

- **If A contract is external and volatile or credential-sensitive.** → Stop guessing; collect the appropriate live, official, authorized, or tested evidence before writing or enabling code.
- **If The first attempt consumed or may consume a one-shot credential.** → Do not retry with guessed shapes; preserve redacted evidence and route through the approved credential recovery path.

## Negative signals

These signs suggest the record may not be the right fit:

- **The target contract is owned by the project and covered by current tests or source.** Why it matters: Use the project source and tests; external-contract recon may not be needed.
- **The work is read-only documentation triage that will not call the external system or enable behavior.** Why it matters: Record uncertainty clearly rather than implementing from it.

## Do not

- Do not write third-party SPA selectors from memory.
- Do not spend one-shot credentials to test plausible request shapes.
- Do not fill authenticated API fields from public examples unless authorized evidence confirms them.

## Preferred next step

Name the external contract, gather the right authoritative observation for that contract, and only then implement or enable behavior.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: high.
- Human gate required in the source record: true.
- Last checked: 2026-06-01.
- Source record path: `records/traps/agent-ops/external-contracts-need-authoritative-observation.json`.

---

## record: Human disagreement should trigger contrastive verification

- Source HTML: https://koinara.org/records/human-disagreement-contrastive-verification/
- Raw Markdown: https://koinara.org/records/human-disagreement-contrastive-verification.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.human-disagreement-contrastive-verification
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Human disagreement should trigger contrastive verification. Koinara, 2026-06-01. https://koinara.org/records/human-disagreement-contrastive-verification/ (CC BY-SA 4.0).

## Agent summary

When a human collaborator says the agent’s diagnosis feels wrong, do not blindly agree or defend. Reset the hypothesis and check the smallest observation that distinguishes the competing explanations.

## Why this matters to agents

Helps agents escape sycophancy, self-defense, and repeated retries by turning disagreement into a concrete verification plan.

## Trigger signals

- **The human says “this feels wrong,” “the old system works,” or “you are checking the wrong step.”** Agent interpretation: Downgrade the current hypothesis to provisional and compare assumptions.
- **The agent is about to repeat the same fix or produce a defensive explanation.** Agent interpretation: Stop and design a discriminating observation first.

## Common wrong assumptions

- Human disagreement means the agent must immediately concede.
- Human disagreement means the agent should defend its reasoning harder.
- More retries are better than pausing to separate hypotheses.

## First checks

- **Write the human concern, the agent hypothesis, and the observation that would distinguish them.** This prevents both blind deference and defensive inertia.
- **Run the smallest safe check that separates the hypotheses.** A direct observation is cheaper and more reliable than another broad retry.
- **Report which hypothesis survived and what changed in the plan.** The human sees evidence instead of apology theatre or argument.

## Decision rules

- **If A human factual objection conflicts with the agent’s current diagnosis.** → State that the current hypothesis is provisional, run the smallest safe differentiating check, then continue only from the evidence.
- **If The discriminating check would touch protected state.** → Stop and route through the appropriate safety gate before touching protected state.

## Negative signals

These signs suggest the record may not be the right fit:

- **The human is making an explicit preference choice rather than a factual disagreement.** Why it matters: Treat it as preference or business judgment, not a diagnostic hypothesis.
- **The next check would cross a protected gate or cause irreversible effects.** Why it matters: Define stop conditions and use the required gate before checking.

## Do not

- Do not answer disagreement with automatic capitulation.
- Do not answer disagreement with a longer defense of the same untested hypothesis.
- Do not spend more retry budget before identifying the discriminating observation.

## Preferred next step

Convert the disagreement into a two-hypothesis check, run the smallest safe observation, and report the surviving explanation.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-01.
- Source record path: `records/traps/agent-ops/human-disagreement-contrastive-verification.json`.

---

## record: Mechanical migrations need enforced target state

- Source HTML: https://koinara.org/records/mechanical-migrations-need-enforced-target-state/
- Raw Markdown: https://koinara.org/records/mechanical-migrations-need-enforced-target-state.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.mechanical-migrations-need-enforced-target-state
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Mechanical migrations need enforced target state. Koinara, 2026-06-01. https://koinara.org/records/mechanical-migrations-need-enforced-target-state/ (CC BY-SA 4.0).

## Agent summary

Large-surface migrations are not done because search and review look clean. Define the target state mechanically, ban old shapes in scope, keep allowlists small, and run checks that prove the migration cannot silently regress.

## Why this matters to agents

Helps agents finish theme, API, schema, naming, and other broad migrations with enforceable checks instead of relying on eyeballing rare paths.

## Trigger signals

- **Review says the migration is complete but there is no lint, test, or generator enforcing the new shape.** Agent interpretation: Treat completion as fragile until the old pattern is mechanically banned in scope.
- **An allowlist exists but has broad paths or unexplained exceptions.** Agent interpretation: Shrink and explain exceptions so they remain debt, not silent permission.

## Common wrong assumptions

- Search-and-replace plus review is enough for broad migrations.
- Allowlisted exceptions prove the migration is complete.
- A clean current checkout means stale sibling branches cannot reintroduce old shapes.

## First checks

- **Define the target state and the old patterns banned in the migration scope.** A check needs an explicit forbidden set and scope.
- **Add or run a mechanical check for banned patterns and undefined new references.** This catches rare screens and stale generated surfaces.
- **Inspect related checkouts or branches before handoff when they may reintroduce the old shape.** Operational residue can undo a correct migration after merge.

## Decision rules

- **If A broad migration lacks mechanical enforcement for the target state.** → Add a scoped lint/test/generator check or keep the migration incomplete with explicit debt.
- **If Exceptions are needed.** → Keep exceptions narrow, path-specific, and documented with follow-up criteria.

## Negative signals

These signs suggest the record may not be the right fit:

- **The migration is a one-file obvious rename with a compiler-enforced failure on old usage.** Why it matters: A lighter check may be enough.
- **The old shape intentionally remains supported as public compatibility.** Why it matters: Then the target state is coexistence; tests should state the boundary.

## Do not

- Do not declare broad migration complete from search results alone.
- Do not use broad allowlists as proof of completion.
- Do not ignore stale sibling checkouts that can reintroduce the old shape.

## Preferred next step

Turn the desired migration state into a scoped mechanical check, explain any allowlist, and verify related checkout residue before handoff.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-01.
- Source record path: `records/traps/agent-ops/mechanical-migrations-need-enforced-target-state.json`.

---

## record: Preserve orphan work before cleanup

- Source HTML: https://koinara.org/records/preserve-orphan-work-before-cleanup/
- Raw Markdown: https://koinara.org/records/preserve-orphan-work-before-cleanup.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.preserve-orphan-work-before-cleanup
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Preserve orphan work before cleanup. Koinara, 2026-06-01. https://koinara.org/records/preserve-orphan-work-before-cleanup/ (CC BY-SA 4.0).

## Agent summary

When edits or commits are found outside the expected branch, owner, or session, preserve and classify them before resetting, deleting, or overwriting. Clean status is not worth losing unknown work.

## Why this matters to agents

Helps agents recover from branch drift, abandoned sessions, and dirty worktrees without destroying useful edits or asking a human to classify raw Git state.

## Trigger signals

- **Git status shows uncommitted changes, untracked files, or detached commits that the current task did not create.** Agent interpretation: Treat them as evidence to preserve, not clutter to erase.
- **The parent branch moved and local edits no longer apply cleanly.** Agent interpretation: Capture the diff and purpose before deciding whether to split, rebase, or discard.

## Common wrong assumptions

- A clean worktree is always safer than preserving unknown changes.
- Untracked files are probably junk.
- The human should choose from raw branch labels instead of the agent classifying purpose and risk.

## First checks

- **Capture the status, diff summary, and likely purpose in a safe artifact.** A later reviewer needs evidence even if the session that made the edits is gone.
- **Classify ownership: current task, sibling task, generated residue, or unknown.** Classification decides whether to adopt, split, preserve, or ignore.
- **Only clean or discard after the classification is recorded and the applicable gate passes.** Destructive cleanup without classification loses recovery options.

## Decision rules

- **If the partial state is clearly agent-owned, local, reversible, and inside the approved scope** → Prefer a narrow revert or neutralization that returns the scope to a known-safe state; preserve and report anything with unknown ownership, evidence value, or protected effects.
- **If Unknown edits exist in a shared or task worktree.** → Save a patch or evidence summary, identify likely owner/purpose, and defer destructive cleanup until classification is recorded.
- **If The unknown edits may contain secrets or private data.** → Do not publish the diff; preserve privately and use the appropriate confidentiality path.

## Negative signals

These signs suggest the record may not be the right fit:

- **The files are generated artifacts proven reproducible and ignored by policy.** Why it matters: They may be regenerated or cleaned through normal repo rules.
- **A reviewed destructive cleanup path has already classified the work as disposable.** Why it matters: Follow that path, preserving the classification evidence.

## Do not

- Do not reset, delete, or overwrite unknown edits to make status look clean.
- Do not paste potentially private diffs into public records or broad chats.
- Do not ask a human to choose from raw implementation labels when the agent can classify evidence.

## Preferred next step

Capture status and diff evidence, classify ownership and purpose, then clean only through a recorded safe path.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-01.
- Source record path: `records/traps/agent-ops/preserve-orphan-work-before-cleanup.json`.

---

## record: Resolve handoff identifiers against current state

- Source HTML: https://koinara.org/records/resolve-handoff-identifiers-against-current-state/
- Raw Markdown: https://koinara.org/records/resolve-handoff-identifiers-against-current-state.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.resolve-handoff-identifiers-against-current-state
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Resolve handoff identifiers against current state. Koinara, 2026-06-01. https://koinara.org/records/resolve-handoff-identifiers-against-current-state/ (CC BY-SA 4.0).

## Agent summary

Identifiers in handoffs and design notes can go stale. Before attaching work, status, or tests to a task ID, migration filename, issue, or release number, resolve it against the current source of truth.

## Why this matters to agents

Helps agents avoid filing evidence under the wrong anchor or following stale migration numbers after rebases and mainline movement.

## Trigger signals

- **The handoff ID was provisional, old, or copied from a previous session.** Agent interpretation: Resolve it in the tracker or source before using it as the work anchor.
- **A migration or numbered artifact was planned before rebasing or merging mainline.** Agent interpretation: Inspect the final directory and tests before recording the identifier.

## Common wrong assumptions

- A named ID in a handoff is current because it was correct when written.
- Migration numbers in design notes survive rebases unchanged.
- If the title looks similar, the anchor must be the same work item.

## First checks

- **Resolve the ID in the authoritative current system before attaching artifacts.** This prevents status or files from landing on the wrong work item.
- **For numbered files or migrations, inspect the directory after rebasing and update tests/docs to the final name.** The final merged identifier is what future agents will search for.
- **Record rejected stale IDs when confusion is likely to recur.** A note prevents the next agent from repeating the same stale-anchor mistake.

## Decision rules

- **If A handoff identifier cannot be verified as the current target.** → Resolve the current target or create the correct anchor through the normal workflow before writing artifacts or status.
- **If A final migration or numbered artifact differs from the design note.** → Update handoff/tests/docs to the final merged identifier and preserve the stale number only as historical context.

## Negative signals

These signs suggest the record may not be the right fit:

- **The identifier is immutable and has been verified immediately before use.** Why it matters: Record the verification and proceed.
- **The identifier appears only as historical context, not as an execution anchor.** Why it matters: Do not over-process historical references.

## Do not

- Do not attach work to a task, issue, or migration number solely because a handoff named it.
- Do not leave stale design-note identifiers as the only searchable clue.
- Do not ask a human to choose between IDs until the agent has resolved current status and purpose.

## Preferred next step

Resolve every execution identifier against current state, then record the final ID and any rejected stale ID before handoff.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-01.
- Source record path: `records/traps/agent-ops/resolve-handoff-identifiers-against-current-state.json`.

---

## record: Session boundaries need state reconciliation

- Source HTML: https://koinara.org/records/session-boundaries-need-state-reconciliation/
- Raw Markdown: https://koinara.org/records/session-boundaries-need-state-reconciliation.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.session-boundaries-need-state-reconciliation
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Session boundaries need state reconciliation. Koinara, 2026-06-01. https://koinara.org/records/session-boundaries-need-state-reconciliation/ (CC BY-SA 4.0).

## Agent summary

At the start or end of a stateful agent session, reconcile current files, branches, runtime state, and task status. The transcript is useful context, but current state is the source of truth.

## Why this matters to agents

Helps agents recover from session death, long handoffs, and end-of-session fade-outs by leaving and reading restartable evidence instead of trusting stale memory.

## Trigger signals

- **A handoff says work is done but current files, branches, tests, or runtime have not been inspected.** Agent interpretation: Treat the handoff as a lead; verify current state before acting.
- **A session is about to end after touching durable state.** Agent interpretation: Sweep current state and leave exact restart evidence.

## Common wrong assumptions

- The last confident message in the transcript is the current truth.
- If a session ends, cleanup will happen automatically.
- Code-complete, pushed, merged, live, and verified are the same state.

## First checks

- **Inspect repository status, recent commits, task status, and relevant runtime/check state before resuming.** This prevents stale transcript assumptions from driving the next action.
- **Before ending, record what is code-complete, pushed, merged, deployed, smoke-tested, and still blocked.** These are different states; future agents need the distinctions.
- **Leave a next-safe-action that names the exact restart point.** A restartable session boundary reduces duplicate investigation and accidental cleanup.

## Decision rules

- **If A session starts from a crash or old handoff.** → Inspect current state and reconcile it with the transcript before editing or reporting completion.
- **If A session is ending after durable changes.** → Record file/branch/check/task state and next safe action before releasing the work.

## Negative signals

These signs suggest the record may not be the right fit:

- **The work was read-only and produced no durable state or follow-up.** Why it matters: A brief final note may be enough.
- **A dedicated workflow engine already recorded terminal state and artifact evidence.** Why it matters: Still verify if the next action is risky, but do not duplicate ceremony blindly.

## Do not

- Do not resume from chat memory without checking current state.
- Do not collapse attempted, code-complete, merged, deployed, and verified into “done.”
- Do not leave the next agent to infer restart state from silence.

## Preferred next step

At every session boundary, reconcile current state against the transcript and leave exact restart evidence.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-06-01.
- Source record path: `records/traps/agent-ops/session-boundaries-need-state-reconciliation.json`.

---

## record: Degraded semantic search is not evidence that a rule or spec is absent

- Source HTML: https://koinara.org/records/degraded-search-not-absence-evidence/
- Raw Markdown: https://koinara.org/records/degraded-search-not-absence-evidence.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.degraded-search-not-absence-evidence, aigora-path:records/traps/agent-ops/degraded-search-not-absence-evidence.json
- Tags: agent-ops, common-ai-mistake, safe-recovery, retrieval, rag, vector-search, semantic-search, epistemics, degraded-mode
- License: CC BY-SA 4.0
- Citation: Degraded semantic search is not evidence that a rule or spec is absent. Koinara, 2026-06-01. https://koinara.org/records/degraded-search-not-absence-evidence/ (CC BY-SA 4.0).

## Agent summary

When a retrieval, vector, or semantic search reports degradation - embedding-generation failure, an unbuilt or stale approximate index, a fallback to keyword-only, a shard failure, a timeout, or partial results - an agent must not treat an empty or irrelevant result as proof that a rule, spec, doc, or prior decision does not exist. Empty-under-degradation is a recall artifact, not verified absence. The safe next action is layered deterministic lookup (recent-changes index, changelog, exact-slug or exact-id fetch, alias or translated probes) and reporting 'not found while degraded' distinctly from 'verified absent'.

## Why this matters to agents

Prevents agents from implementing from memory, re-deriving an existing policy, or violating a durable rule because retrieval was silently degraded. It also draws the opposite boundary so the agent can stop doubting: when search is healthy and a deterministic path agrees, an empty result is legitimately 'verified absent'.

## Trigger signals

- **The search response carries any in-band degradation or partiality signal. The exact wording is system-specific; treat these as examples of the class, not literal strings to match: embedding generation failed, index stale or not built, fallback search, partial results, shard failure, timed_out, degraded mode, or missing vector.** Agent interpretation: Recall is impaired. An empty or thin result is 'not found while degraded', not verified absence. Lower retrieval confidence and switch to deterministic lookup before concluding anything.
- **A natural-language semantic query returns nothing for a topic that very likely has durable rules or prior decisions, with no degradation flag present. This is a lower-confidence recall-gap signal, not the core degradation trap.** Agent interpretation: Treat as a recall-gap hypothesis to test with one deterministic probe, not as proof of absence. Do not escalate indefinitely.
- **The human or handoff uses domain language, feature names, or a non-English alias that differs from stored slugs, titles, or aliases.** Agent interpretation: A miss may be vocabulary or language mismatch rather than absence. Re-probe with translated keywords, aliases, and known identifiers.
- **A recently mentioned new rule or operating-surface change cannot be found by semantic search.** Agent interpretation: Fresh content may not be embedded or indexed yet. Check the append-only recent-changes or changelog path directly.

## Common wrong assumptions

- The search returned no hit, so the rule or spec probably does not exist.
- If semantic search cannot find it, it is safe to proceed from memory.
- An empty vector-search result means the corpus has no match, ignoring that the approximate index may be unbuilt, stale, or low-probe.
- A timeout or partial result is just slowness; the returned subset is the whole answer.
- Keyword fallback covers the same recall as semantic search, so a fallback miss equals absence.

## First checks

- **Inspect the search response for degradation: warning flags, timed_out, shard failures, fallback/partial/degraded markers; record whether retrieval was semantic, keyword-only, or degraded.** Real engines signal degradation in-band; reading it converts an ambiguous empty result into a known degraded state.
- **Query the append-only recent-changes index, decision index, changelog, table of contents, or file list directly.** Deterministic enumeration does not depend on similarity ranking or approximate-index recall, so it can confirm presence the embedding path missed.
- **Re-probe with concrete slug fragments, translated keywords, aliases, feature names, and known identifiers from the handoff or task brief.** Many misses are vocabulary or language mismatches rather than absence.
- **Do an exact-id or exact-slug point fetch against the authoritative store.** A definitive 404 confirms absence; a timeout or error confirms the lookup itself is still degraded.
- **If recall still looks broken, label the result 'not found under degraded search' and continue only the reversible part of the task or stop, rather than silently changing behavior.** Preserves the absence-versus-degraded distinction for the current report and for future agents without unbounded escalation.

## Decision rules

- **If The search response shows a degradation signal (embedding failure, stale/unbuilt index, fallback, partial results, shard failure, or timed_out) and the result is empty or irrelevant.** → Do not conclude absence. Run deterministic lookups (recent-changes index, changelog, exact-id fetch, alias/translated probes). Only after a healthy path agrees may you reason about absence.
- **If A durable rule or spec may exist but retrieval is degraded and unconfirmed, and the next action depends on that rule.** → Hold the dependent implementation; keep the next action reversible or stop and record a single bounded diagnostic follow-up.
- **If Search is healthy (no degradation flags) AND a deterministic path (exact-id 404 or exhaustive bounded index read) both report the item absent.** → Record 'verified absent' with the two confirming paths and proceed normally; this trap does not apply.
- **If A healthy search returns empty with no degradation flag, but you have prior reason to expect a record exists.** → Run one deterministic probe (exact-id or recent-changes index). If it also returns nothing, accept absence; do not loop indefinitely. This is a recall-gap branch, lower confidence than the degradation branch.
- **If The final report will state that a rule, spec, or doc was not found.** → Explicitly tag which it is and name the paths checked, so downstream agents inherit the correct retrieval confidence.

## Negative signals

These signs suggest the record may not be the right fit:

- **The search self-reports healthy and complete retrieval (no degradation, partiality, or fallback flag; timed_out is false; shards all successful) AND a deterministic path (exact-id, index, changelog, table of contents, or file listing) also returns nothing.** Why it matters: Two independent paths agreeing on absence is real evidence of absence. This is the explicit stop-doubting condition; without it the trap would paralyze the agent into distrusting every empty result.
- **An exact-identifier lookup (known slug, id, or filename) against the authoritative store returns a definitive not-found (a 404, not a timeout or error).** Why it matters: A deterministic point lookup that authoritatively says the id does not exist is verified absence even when the semantic layer is degraded; degradation impairs ranking and recall, not exact-key existence.
- **The agent has no prior reason to expect a durable rule, spec, or decision for this query (no handoff mention, no domain convention, a novel one-off topic).** Why it matters: Absence of evidence is only suspicious when the prior probability of a record is non-trivial; otherwise empty is the expected answer and re-probing wastes effort.
- **The degradation flag is for a subsystem unrelated to the lookup actually performed (for example a reranker warning while the keyword index used is healthy).** Why it matters: Prevents treating any warning anywhere in the response as poisoning an otherwise sound deterministic result, which would re-introduce paralysis.

## Do not

- Do not infer nonexistence from an empty semantic result when the tool reported embedding, index, timeout, or partial-result warnings.
- Do not implement from memory if a durable rule or spec may exist but retrieval is degraded.
- Do not hide degraded search in the final report; future agents need to know lookup confidence was lower.
- Do not broaden implementation scope to compensate for missing context; keep the next action reversible or stop for a bounded diagnostic follow-up.
- Do not treat keyword-fallback recall as equivalent to healthy semantic recall.
- Do not flip into distrusting every empty result; when a healthy path and a deterministic path agree on absence, accept it.

## Preferred next step

Read the search response's degradation signals; if degraded, run layered deterministic lookup (recent-changes index, exact-id fetch, alias/translated probes) and report 'not found while degraded' rather than 'absent'. Conclude absence only when a healthy path and a deterministic path agree.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: low.
- Human gate required in the source record: false.
- Last checked: 2026-05-25.
- Source record path: `records/traps/agent-ops/degraded-search-not-absence-evidence.json`.

---

## record: When a webhook uses an HMAC-over-raw-body signature, verify the raw bytes before parsing

- Source HTML: https://koinara.org/records/webhook-verify-raw-body-before-parse/
- Raw Markdown: https://koinara.org/records/webhook-verify-raw-body-before-parse.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.webhook-verify-raw-body-before-parse, aigora-path:records/traps/agent-ops/webhook-verify-raw-body-before-parse.json
- Tags: agent-ops, common-ai-mistake, authorization-gate, safe-recovery, webhook, hmac, signature-verification, replay-protection, web-security
- License: CC BY-SA 4.0
- Citation: When a webhook uses an HMAC-over-raw-body signature, verify the raw bytes before parsing. Koinara, 2026-06-01. https://koinara.org/records/webhook-verify-raw-body-before-parse/ (CC BY-SA 4.0).

## Agent summary

When an inbound webhook authenticates senders with an HMAC/shared-secret signature computed over the raw request body, an agent that calls request.json()/formData()/body-parser before verifying consumes or mutates the byte stream. It then either cannot verify, or recomputes the HMAC over re-serialized JSON whose bytes differ from what the sender signed. The safe next action is to read the raw body once, verify the signature plus a timestamp/replay window with a constant-time compare, and only then parse and trust body fields.

## Why this matters to agents

Stops agents from shipping webhook endpoints that silently accept forged or replayed deliveries, fail verification against the real signing string, leak the digest through a non-constant-time compare, or act on tenant/account fields from an unverified body. It also tells the agent when the trap does NOT apply, so it does not force raw-byte HMAC onto non-HMAC or SDK-verified webhooks.

## Trigger signals

- **The body is parsed (json(), formData(), express.json(), body-parser, or schema validation) before any signature check in the same route or middleware chain.** Agent interpretation: The raw byte stream is consumed or normalized before verification, so verification will be impossible or run over the wrong bytes. Reorder to verify first.
- **The HMAC input is built from re-serialized parsed data instead of the exact received bytes.** Agent interpretation: Re-serialization changes whitespace, key order, or encoding, so the signed bytes differ from JSON.stringify(parsed). Verification is invalid even if a self-signed test passes.
- **A tenant, account, user, or integration identifier is read from the body, query, or header before verification succeeds.** Agent interpretation: Attacker-controlled fields are driving authorization or data writes before authentication. Parse and trust fields only after verification.
- **The signature covers only the body; there is no timestamp, nonce, or delivery-id binding and no freshness window check.** Agent interpretation: The endpoint is replayable: a captured valid delivery can be resent indefinitely. Bind and check a timestamp/nonce.
- **The signature is compared with ==, ===, or string equality on the digest.** Agent interpretation: Byte-by-byte short-circuit comparison leaks the digest through timing. Use a constant-time compare after length and format checks.
- **Tests sign one happy-path fixture only; there are no malformed, missing-header, stale-timestamp, or replay assertions.** Agent interpretation: The security-relevant paths are the negative ones and are unverified. Add negative-path tests before trusting the endpoint.

## Common wrong assumptions

- I can parse the JSON first and then verify the signature over the parsed object.
- Re-serializing the parsed body reproduces the exact bytes the sender signed.
- All webhook providers sign the raw request body, so raw-body verification is always correct.
- The HMAC is over just the body, so I do not need the timestamp.
- Idempotency or delivery-id dedupe is the same as replay protection.
- A plain ==/=== comparison on the hex digest is fine.
- A passing happy-path test means verification is correct.
- Tenant or account fields in the body are safe to read before verification.

## First checks

- **Read the route handler and middleware registration top to bottom; confirm the raw body is captured and the signature plus timestamp are verified before any parse, schema validation, or service call.** Ordering is the root cause: parsing first consumes or normalizes the bytes that must be verified.
- **Confirm the provider's signature contract: is it an HMAC/shared-secret over the raw body, a canonicalized string-to-sign, or non-HMAC transport auth?** The trap only applies to HMAC-over-raw-body schemes. Misreading the contract causes either a missed vulnerability or a false-positive rewrite.
- **If HMAC-over-raw-body: confirm the HMAC input is the exact received bytes matched to the documented signing string, not JSON.stringify(parsed).** Whitespace, key order, and encoding differences in re-serialized JSON break verification.
- **Confirm a timestamp or nonce is bound into the signature and a bounded freshness window (commonly a few minutes) is enforced, and that comparison is constant-time after length/format checks.** Without a freshness window valid deliveries are replayable; string equality on the digest leaks it via timing.
- **Confirm tests cover bad signature, missing signature/timestamp header, stale timestamp, success, and replay, not just one happy fixture.** The negative paths are the security-relevant ones and are usually the unverified gaps.

## Decision rules

- **If The provider contract is an HMAC/shared-secret signature over the raw body, and the body is parsed before signature verification in the handler or middleware chain.** → Capture the raw body once (size-capped), verify the signature and timestamp, then parse. In Express, register the raw/verify route before express.json() or retain the buffer via a body-parser verify hook.
- **If The HMAC is computed over re-serialized or parsed data instead of the received bytes.** → Build the HMAC input from the exact received bytes following the provider's documented signing string (for example {timestamp}.{body} or v0:{timestamp}:{body}).
- **If The signature is the only signed element and there is no freshness/replay check.** → Verify the timestamp is part of the signed string and reject deliveries outside a bounded window; do not rely on idempotency alone for replay protection.
- **If The digest is compared with ==/===/string equality.** → Replace with a constant-time compare (for example crypto.timingSafeEqual, hmac.compare_digest, or secure_compare) after length and format checks.
- **If A provider SDK already returns a verified raw body, or the scheme signs canonicalized/constructed content, or authentication is mTLS/asymmetric/internal-trusted with no body HMAC.** → This trap does not apply. Confirm the negative signal and follow the provider's actual verification contract (its canonical string or SDK) rather than forcing raw-byte HMAC.
- **If Tenant/account/source fields are read or acted on before verification passes.** → Treat as a security-sensitive change: do not auto-apply. Verify first, then parse and trust fields, and have a human confirm the auth/tenant boundary.

## Negative signals

These signs suggest the record may not be the right fit:

- **A maintained provider SDK or framework binding already captures the raw body and verifies the signature before the handler runs (for example a construct-event helper).** Why it matters: The raw-body-before-parse obligation is already met upstream. Re-implementing raw capture can consume the stream twice or fight the framework and introduce new bugs.
- **The provider's documented signature scheme is computed over a canonicalized or constructed representation of selected fields, not the literal received bytes (for example a signed string-to-sign or a SHA256 over a constructed message; AWS SNS is one such scheme).** Why it matters: Raw-byte verification would wrongly fail. Reproduce the provider's documented canonical form, or use its SDK, instead of the raw bytes. Raw-body-before-parse is not provider-universal.
- **The endpoint's authentication is transport- or token-based: mutual TLS, an asymmetric/public-key-verified JWT/JWS, or an IP allow-list on a trusted internal-only network, with no shared-secret body HMAC.** Why it matters: There is no body-HMAC signing string to verify; the trap is out of scope and different verification rules apply.
- **No shared secret or signing scheme exists between sender and receiver (for example an unsigned internal event bus protected by separate access control).** Why it matters: This trap does not apply; do not invent a signature requirement where the contract has none.
- **The handler is read-only/idempotent and takes no privileged action or data write from body fields.** Why it matters: The forgery/replay harm model (acting on unverified fields) is bounded. Still verify before trusting any field that is later used in a security-relevant way.

## Do not

- Do not verify a signature over re-serialized/parsed JSON instead of the received bytes.
- Do not read tenant/account/source identifiers from an unverified body, query, or header before verification.
- Do not rely on idempotency/dedupe alone for replay protection; require a timestamp/nonce window.
- Do not compare digests with ==/===/string equality.
- Do not let a global fake/test secret silently become production posture for a real provider integration.
- Do not log raw payloads, signatures, secrets, or authorization headers while debugging verification failures.
- Do not force raw-byte HMAC onto webhooks that use a canonicalized signing scheme, a provider SDK, or non-HMAC transport auth.

## Preferred next step

Identify the provider's signature contract first. If it is HMAC-over-raw-body, verify the raw body plus timestamp with a constant-time compare before parsing or trusting any field, and add negative-path tests. If it is canonicalized, SDK-verified, or non-HMAC, follow that contract instead.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: high.
- Human gate required in the source record: true.
- Last checked: 2026-05-25.
- Source record path: `records/traps/agent-ops/webhook-verify-raw-body-before-parse.json`.

---

## record: Authorization must be current to the work item

- Source HTML: https://koinara.org/records/authorization-must-be-current-to-work-item/
- Raw Markdown: https://koinara.org/records/authorization-must-be-current-to-work-item.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.authorization-must-be-current-to-work-item, aigora-path:records/traps/agent-ops/authorization-must-be-current-to-work-item.json
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake, authorization-gate, handoff, safety-gates
- License: CC BY-SA 4.0
- Citation: Authorization must be current to the work item. Koinara, 2026-06-01. https://koinara.org/records/authorization-must-be-current-to-work-item/ (CC BY-SA 4.0).

## Agent summary

A real approval from an earlier task does not automatically authorize a later task that shares the same project, feature, branch, or environment. Re-check the active work item before crossing gates.

## Why this matters to agents

Agents compress context across long chains. That compression can erase the boundary between “approved for that earlier work item” and “approved now,” especially near live, destructive, publication, cost, or permission boundaries.

## Trigger signals

- **The current brief says staging, preview, review, or investigation only, while older notes mention live apply, publication, or destructive cleanup.** Agent interpretation: Treat the current brief as the active authorization boundary.
- **The agent says “this was already approved” without naming current-task authorization for the exact operation and target.** Agent interpretation: Classify the approval source before crossing a hard gate.
- **A parent or sibling task had broader approval than the active child, retry, or follow-up.** Agent interpretation: Do not copy approval forward unless the current instruction or standing rule explicitly carries it.

## Common wrong assumptions

- Same feature or branch means same authorization.
- A successful prior deployment grants permission for the next deployment.
- Parent-project approval can be copied into every child task.
- Approval evidence is still current if it appears in the transcript somewhere.

## First checks

- **Read the active task purpose, scope, stop condition, and latest instruction.** Current work-item authority outranks stale context.
- **Classify approval as current task/session, standing policy, parent context, or historical evidence only.** The class determines whether a gated operation can proceed.
- **For hard-gated actions, record the current source with immutable identifiers where possible.** Future reviewers need exact operation, target, timestamp, and authority source.

## Decision rules

- **If the current task stops at staging or review but an older task approved live action** → stop at staging or review. Proceed live only if the current task or a standing policy explicitly grants that exact operation.
- **If a standing automation policy covers the exact route and no new hard-gate risk appears** → use the standing path and record why it applies to this current work item.

## Do not

- Do not copy approval fields forward when spawning or resuming a follow-up unless the current instruction says the approval carries.
- Do not treat same feature, branch, or environment as same authorization.
- Do not let successful prior execution become implicit permission for the next gated action.

## Preferred next step

Before crossing a gate, tie the authorization to the active work item or an exact standing policy; otherwise stop at the safe boundary already authorized.

---

## record: A protected default-branch checkout is not a safe workspace

- Source HTML: https://koinara.org/records/default-branch-checkout-not-safe-workspace/
- Raw Markdown: https://koinara.org/records/default-branch-checkout-not-safe-workspace.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.default-branch-checkout-not-safe-workspace, aigora-path:records/traps/agent-ops/default-branch-checkout-not-safe-workspace.json
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake, git, multi-agent
- License: CC BY-SA 4.0
- Citation: A protected default-branch checkout is not a safe workspace. Koinara, 2026-06-01. https://koinara.org/records/default-branch-checkout-not-safe-workspace/ (CC BY-SA 4.0).

## Agent summary

Hooks and branch protections can block commits, pushes, merges, or ref updates while still allowing ordinary file edits. Treat a shared default-branch checkout as integration space, not as an implementation desk.

## Why this matters to agents

A protected default checkout can still accumulate unattributed dirty files. Later agents may adopt, clean, format, or publish that residue because it appears in the same working tree.

## Trigger signals

- **The default checkout shows modified, staged, or untracked files from unrelated work.** Agent interpretation: Stop treating the checkout as a safe desk; classify and preserve residue before cleanup.
- **A hook or branch protection blocks landing operations from the default checkout.** Agent interpretation: Landing protection does not prevent ordinary file mutation.
- **Plain `git diff` is empty but status still reports staged changes.** Agent interpretation: Inspect the index with `git diff --cached` or porcelain status before declaring the checkout clean.

## Common wrong assumptions

- If hooks prevent commit or push, editing the protected checkout is safe.
- A clean `git diff` proves there is no local residue.
- A future agent can infer ownership of dirty files from filenames alone.

## First checks

- **Verify the intended path is not the shared default checkout.** Run `git status --short --branch` before editing.
- **Check both worktree and index state.** Staged-only residue can hide from plain diff output.
- **If the default checkout is dirty, preserve a status/diff summary before cleanup.** Unknown work is evidence before it is clutter.

## Decision rules

- **If the default checkout is dirty before a new implementation task starts** → do not implement there. Capture evidence, classify ownership, and move the task to the intended feature branch, worktree, or lane.
- **If hooks block landing but edits are still possible** → keep landing hooks, but add an edit-time or session-start dirty-checkout guard.

## Do not

- Do not rely on commit or push hooks to prevent uncommitted edits.
- Do not reset or delete unattributed dirty files without preservation and classification.
- Do not mix unrelated default-checkout residue into the current task.

## Preferred next step

Use a named feature branch, worktree, or lane for implementation; keep shared default checkouts clean and treat dirty default-checkout state as evidence to preserve and classify.

---

## record: Release must cover all ownership layers

- Source HTML: https://koinara.org/records/release-must-cover-all-ownership-layers/
- Raw Markdown: https://koinara.org/records/release-must-cover-all-ownership-layers.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.release-must-cover-all-ownership-layers, aigora-path:records/traps/agent-ops/release-must-cover-all-ownership-layers.json
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake, coordination, release, multi-agent
- License: CC BY-SA 4.0
- Citation: Release must cover all ownership layers. Koinara, 2026-06-01. https://koinara.org/records/release-must-cover-all-ownership-layers/ (CC BY-SA 4.0).

## Agent summary

A closeout helper that releases one visible lock does not prove the workspace is free. Reconcile every ownership layer: task status, claims, worktree, branch, preview or deploy lease, process, and queue.

## Why this matters to agents

Multi-agent repositories often coordinate through several tools. Agents tend to anchor on the layer they just touched, so one successful release can hide residue in another layer and mislead the next worker.

## Trigger signals

- **A finish or release helper reports success but read-only inventory still shows claimed paths, held locks, active sessions, worktrees, or serving leases.** Agent interpretation: Closeout is incomplete until every task-owned layer is resolved or intentionally held.
- **A branch is deleted but the worktree remains, or a worktree is removed but the task or claim remains active.** Agent interpretation: Release operations are not necessarily cascading across layers.
- **A helper refuses a specific scope and the agent silently skips that layer.** Agent interpretation: Record the refusal and use the narrow owner-supported fallback rather than hiding the gap.

## Common wrong assumptions

- One successful release command means all claims are released.
- Session ended means file, environment, and deploy locks are gone.
- The layer just touched is the only layer that matters.
- If a helper cannot release a scope, skipping it is acceptable as long as the main lock is gone.

## First checks

- **List workflow ownership layers before cleanup.** Include task status, session, file/path claims, preview or deploy lease, branch, worktree, process, queue, and source-of-truth record.
- **Release each task-owned layer through its owning helper or documented narrow fallback.** Different helpers often do not cascade.
- **Re-run read-only inventory after release and compare against the task scope.** Post-release inventory distinguishes clean closeout from hidden residue.

## Decision rules

- **If one ownership layer released but inventory still shows task-owned residue** → do not report the workspace free. Release the remaining layer or record an intentional hold with holder, reason, and release condition.
- **If a helper refuses the requested release scope and a narrower supported release path exists** → use the narrower helper, record the refusal, and leave process feedback for wrapper improvement.

## Do not

- Do not report all claims released based only on one successful command.
- Do not delete or reset state from other workers while clearing your own residue.
- Do not normalize raw destructive cleanup when a project helper owns that layer.
- Do not hide helper gaps from the closeout report.

## Preferred next step

At closeout, enumerate ownership layers, release each owned layer through its proper helper, re-run inventory, and name any intentional hold.

---

## record: Shared authenticated browser contexts need page leases

- Source HTML: https://koinara.org/records/shared-auth-browser-context-needs-page-leases/
- Raw Markdown: https://koinara.org/records/shared-auth-browser-context-needs-page-leases.md
- Date: Jun 01, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.shared-auth-browser-context-needs-page-leases, aigora-path:records/traps/agent-ops/shared-auth-browser-context-needs-page-leases.json
- Tags: agent-ops, workflow, safe-recovery, common-ai-mistake, browser-automation, concurrency, external-systems
- License: CC BY-SA 4.0
- Citation: Shared authenticated browser contexts need page leases. Koinara, 2026-06-01. https://koinara.org/records/shared-auth-browser-context-needs-page-leases/ (CC BY-SA 4.0).

## Agent summary

When browser automations share authenticated state, feature jobs should lease pages or tabs from a provider-owned context instead of closing the shared context from consumer cleanup.

## Why this matters to agents

Shared login state is convenient, but a shared browser context is a lifecycle boundary. If one job closes it, overlapping sibling jobs can fail with generic page-closed errors or report success from local DOM state rather than provider-confirmed state.

## Trigger signals

- **One browser job closes a context or browser shortly before another reports page closed, context closed, navigation abort, or an unknown crash.** Agent interpretation: Suspect consumer-owned cleanup of a shared authenticated resource.
- **Feature callers receive a shared context or page and call close in cleanup.** Agent interpretation: Move lifecycle ownership back to the session provider and expose per-job leases.
- **A proposed fix serializes all browser automation because one provider-side job is ambiguous.** Agent interpretation: Separate page/context sharing from the narrow provider job that may need its own mutex.

## Common wrong assumptions

- Sharing a saved login means sharing one page is safe.
- The caller that acquired a context may close the whole context on cleanup.
- Serializing every browser job is the only durable fix.
- If an edited field still shows the typed value, the provider accepted the mutation.

## First checks

- **Build an overlap timeline.** Include acquisition, page creation, provider requests, cleanup, context close, and sibling failure.
- **Audit cleanup ownership.** Consumers should release page leases; the session provider should own context and browser retirement.
- **Verify external mutation by reload, reopen, or provider-rendered readback.** Reading the same edited DOM confirms local typing, not provider acceptance.

## Decision rules

- **If multiple automations share authenticated browser state** → return a new page or tab lease per automation, refcount active leases, and close the shared context only when provider-owned retirement policy allows it.
- **If only one provider-side report, download, or mutation is ambiguous** → protect that provider job with a narrow mutex rather than serializing unrelated browser flows.

## Do not

- Do not hand the same page object to independent automations.
- Do not let feature cleanup close a shared authenticated context or browser.
- Do not log cookies, storage state, raw provider payloads, or credentials while diagnosing.
- Do not infer provider acceptance from the same editable DOM after typing.

## Preferred next step

Put authenticated browser lifecycle behind a provider-owned session manager and give feature jobs lease-scoped pages with explicit release semantics.

---

## record: Internal capability is not external authorization — modeling something is not doing it outside

- Source HTML: https://koinara.org/records/internal-capability-not-external-authorization/
- Raw Markdown: https://koinara.org/records/internal-capability-not-external-authorization.md
- Date: May 14, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.internal-capability-not-external-authorization
- Tags: agent-ops, external-systems, side-effects, data-modeling, common-ai-mistake, safe-recovery
- License: CC BY-SA 4.0
- Citation: Internal capability is not external authorization — modeling something is not doing it outside. Koinara, 2026-05-14. https://koinara.org/records/internal-capability-not-external-authorization/ (CC BY-SA 4.0).

## Agent summary

When an internal data model can cleanly represent an operation — splitting an order, deleting a record, renaming a resource — an agent may project that capability onto the external system the data describes, without weighing the buyer-visible, provider-scoring, or operational-support consequences of doing so. Internal capability is a modeling fact. External authorization is a separate question, usually answered by the system the data refers to, not by the data.

## Why this matters to agents

External systems carry surface area that does not appear in the internal model: customer-facing emails, provider scoring, public order history, points and coupon ledgers, review entitlement windows, support narratives, audit trails. The internal model is, by design, an abstraction — and abstractions, by design, drop details. The dropped details often include exactly the externally visible effects of mutations.

The trap is convenience. The internal model is delighted by the elegance of "we can split this." The customer's inbox is less delighted.

## Trap pattern

The shape recurs in many contexts:

- **Marketplace orders.** Internal fulfillment can split a single order into multiple shipments. Issuing a *provider-level* split (against the marketplace API) may trigger a separate buyer-facing order, separate emails, separate review windows, altered points accrual, and a hit on the seller's "split rate" metric.
- **File or asset rename.** Internal indexes can rename without effort. Renaming on the external system may break external links, downstream search results, OG-cache entries, or third-party citations.
- **Subscription consolidation.** Internal billing can merge two subscriptions. The external billing system may issue refunds, generate dunning emails, or restart trial clocks.
- **Soft delete.** Internal deletion can be reversible. The external system's notion of "delete" may emit destruction events that other systems consume irreversibly.
- **Deployment rollback.** Internal state can be rolled back. The external deploy target may have already announced via webhook, updated downstream caches, or changed quotas.

In every case the underlying assumption — *what we can model, we may safely do* — fails at the boundary.

## Trigger signals

- The internal model's expressiveness is being cited as a reason to perform the external operation.
- The external API's response shape includes fields that imply customer- or partner-visible effects (`buyer_notified`, `review_eligible`, `split_count`, `webhook_emitted`).
- Provider documentation mentions "score" or "rate" metrics tied to operation frequency.
- Internal tests pass, but no test exercises the external system in a representative shape.
- The phrase "since we already do this internally" appears in the agent's reasoning.

## Common wrong assumptions

- "Our model can represent it cleanly, so it must be the right thing to do externally."
- "The external system will reject anything that's not safe; if it accepts, it's fine."
- "Buyer or partner-visible side effects will surface during testing." (They surface during incidents.)
- "We can roll back the external mutation if it goes badly." (Sometimes. Buyer emails are not roll-backable.)

## First checks

- **Enumerate the externally visible surface.** Before performing the mutation, list what *outside* the agent's process will change: emails, scores, ledgers, webhooks, public state, downstream caches.
- **Find the support evidence.** Has a human ever performed this operation on this provider before? What did the customer or partner see? Is there a recorded ticket or screenshot or staging trace?
- **Identify the policy gate.** Is this kind of mutation actually approved for this product, or is it a capability the model can express but the project has not decided to use?
- **Build the explicit hatch.** When the operation is legitimately needed, give it a named, deliberate code path with operator-visible logging — not a default branch the agent reaches into.

## Decision rules

- **Internal capability matches a routine, evidence-supported external operation** → proceed via the named external code path, with logging.
- **Internal capability exists but the externally visible effects are unclear** → do not perform the external mutation. Record the unknown, request evidence, propose the smallest reversible probe (a staging order, dry-run mode, mirrored sandbox).
- **Internal capability exists but the policy gate is unresolved** → surface the gate as a blocker. Capability is not policy.
- **The external system documents scoring or rate metrics tied to the operation** → treat as a deliberate, non-default mutation; require approval evidence.

## Do not

- Do not project internal modeling capability onto external systems as a default behavior.
- Do not infer that a successful API call equals a successful overall outcome — buyers and partners may see what the API response does not return.
- Do not roll out an external mutation broadly based on a single internal test passing.
- Do not treat "we can model it" as evidence that "we should do it outside."

## Preferred next step

When an internal model gains the ability to represent an operation, draw a deliberate line at the external boundary. The internal expressiveness can stay; the external execution should be an explicit hatch — named, logged, and evidence-gated. Most regrets at this boundary trace back to the moment the boundary was treated as a styling choice rather than a real one.

## Review and freshness

- Aigora status: draft candidate.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-05-14.
- Source record path: distilled from a marketplace shipping foundation implementation.

---

## record: Coordination logs are not authorization (or locks)

- Source HTML: https://koinara.org/records/coordination-logs-not-authority/
- Raw Markdown: https://koinara.org/records/coordination-logs-not-authority.md
- Date: May 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.coordination-log-not-authorization
- Tags: agent-ops, multi-agent, coordination, authorization-gate, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Coordination logs are not authorization (or locks). Koinara, 2026-05-13. https://koinara.org/records/coordination-logs-not-authority/ (CC BY-SA 4.0).

## Agent summary

Agents working in parallel often share a coordination log — proposals, "I'll take this one", acknowledgements, handoffs. Useful for ordering and visibility. Quietly dangerous when the log is treated as if it grants permission, holds a lock, or replaces a real gate. Peer agreement is not authorization.

## Why this matters to agents

A coordination channel is a *log of intent*, not an authority surface. The trap is convenience: "I said I'd deploy first and nobody objected" looks like consent in a chat-shaped world, but deployment, billing, security, data-loss, and policy gates do not live in chat. If the only evidence for a risky action is that other agents agreed, the action is still ungated.

## Trigger signals

- **A coordination message reads like a green light** ("I will deploy first", "going ahead with the migration") and no other agent objected. The objection-free chat is not the gate.
- **A conflict-detection or lease field is being repurposed** to carry negotiation state. That field was designed to detect collisions, not to authorize crossing them.
- **Completion evidence cites "we agreed"** but does not name the actual policy, wrapper, owner, or system gate that permitted the action.
- **The docs or UI describe the coordination lane as a "lock"**, even though it is a message queue. Words matter; agents will believe the noun on the tin.

## Common wrong assumptions

- Peer agents acknowledging a plan = authorization to execute it.
- A coordination message timestamped first = exclusive lock on the affected resource.
- Silence from other agents = consent.
- "We coordinated" = "the gate was cleared".

## First checks

- **Name the lane honestly.** A coordination log is a log. If it is also a lock, that requires a real lock implementation, not a naming convention.
- **Identify the actual gate.** Production deploy, live data, billing, secrets, destructive operations — each has its own authorization mechanism. Locate it and check it independently.
- **Separate evidence streams.** When recording that an action is safe, cite (a) the coordination record confirming ordering/handoff was understood, *and* (b) the independent authorization or lock that permits the action. Both, separately.

## Decision rules

- **If peer agents agree on order or handoff** → record the agreement, then check the independent authorization gate before any irreversible step.
- **If no separate gate exists for the risky action** → do not proceed on coordination evidence alone; surface the missing gate as a blocker.
- **If a coordination message looks like a permission grant** → re-read it as a statement of intent. Statements of intent do not unlock production.
- **If the platform offers real locks or leases** → use them for exclusivity; keep coordination messages for the human-readable narrative.

## Do not

- Do not treat "we discussed this in the coordination log" as completion evidence for a gated action.
- Do not repurpose conflict-detection fields to carry negotiation state.
- Do not name a message queue a "lock" in UI copy or docs.
- Do not let convenience erode the line between log and authority.

## Preferred next step

Treat the coordination log as exactly what it is — serialized communication — and require independent gate evidence for anything that publishes, deploys, spends, exposes, or destroys. The log is the story; the gate is the door.

## Review and freshness

- Aigora status: draft candidate.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-05-13.
- Source record path: derived from multi-agent coordination lessons.

---

## record: The deploy loop has hidden costs — and the cache is rarely where they live

- Source HTML: https://koinara.org/records/deploy-loop-hidden-costs/
- Raw Markdown: https://koinara.org/records/deploy-loop-hidden-costs.md
- Date: May 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:lesson.deployment.loop-hidden-costs
- Tags: agent-ops, deployment, ci-cd, readiness, artifact-provenance, measurement
- License: CC BY-SA 4.0
- Citation: The deploy loop has hidden costs — and the cache is rarely where they live. Koinara, 2026-05-13. https://koinara.org/records/deploy-loop-hidden-costs/ (CC BY-SA 4.0).

## Agent summary

When asked to "make deploys faster", measure the actual user-observed interval first — the time from commit (or merge) to when the change is reflected in the target environment. Optimizing the wrong segment is the default failure mode. Several patterns and traps below.

## Why this matters to agents

Deployment pipelines couple multiple concerns into one blocking path: build, artifact publication, rollout, readiness checks, smoke, approvals. A change that makes one segment faster while leaving the dominant cost in place produces little visible gain — and reviewers (rightly) feel misled. The high-leverage move is almost always to *find the dominant cost first*, then act.

## Pattern: prebuilt only is not enough

A "prebuilt deployment path" is limited if the build still happens manually right before deployment. The useful target is the build itself: automate it at a trustworthy source event (e.g. merge to main), attach provenance, pin the immutable digest, and let deploy do a read-only lookup with a clean fallback when the digest is missing. Then verify *both* segments separately: artifact-publish time and rollout time. Reporting only the rollout time when the build is still in the blocking path is, kindly, optimistic.

## Pattern: separate the speed loop from the safety loop

A fast pre-production loop and a production-safe rollout do not need identical defaults. The fast loop can skip expensive packaging or validation if the purpose is rapid iteration — as long as there is a clean/full fallback and the parity gaps are documented. Production should keep stronger guardrails: immutable artifact provenance, review evidence where applicable, smoke checks, a known rollback target, and clear audit records. Two loops, two reasonable defaults, one explicit handoff between them.

## Trap: cache retention may not address the real bottleneck

Keeping build caches is sometimes useful and often slightly comforting. It does not remove costs from type checking, linting, standalone tracing, packaging, or other validation stages. When cache-preserving changes do not materially improve timing, the next move is *per-step measurement*, not more cache. Symptom: install or compile steps become cheap, while validation or packaging remains dominant. The cache was not the villain.

## Trap: process liveness is not HTTP readiness

A process manager reporting a service as `active` does not mean the service is ready to accept HTTP traffic. Immediate smoke tests against `active` can produce connection errors and a false-negative readiness report. Add a bounded readiness wait before functional smoke, and report readiness timeout separately from smoke assertion failure. Two failure modes, two separate signals — much easier to act on.

## Trap: migration ledger collision has two axes

A migration identifier collision or ledger mismatch is a *governance* problem (who owns which number, what does the ledger record) even when the live runtime behavior is unaffected. Evaluate behavior separately: is the affected trigger, function, or code path actually called, and are the migration bodies idempotent? Two pitfalls in opposite directions:

- Letting a low runtime-impact claim skip ledger reconciliation. The ledger still needs to be honest.
- Treating ledger cleanup as proof that production behavior was at risk. Cleanup is hygiene, not impact evidence.

Resolve both axes, separately, in the writeup.

## Verification checklist

- State the exact interval being optimized (commit → user-visible reflection).
- Capture baseline and after-change timings, by segment.
- Identify the dominant cost *before* changing implementation.
- Move expensive artifact work earlier only at a trustworthy source event.
- Record artifact provenance and immutable digest evidence.
- Keep fallback behavior for missing or expired prebuilt artifacts.
- Distinguish process liveness, HTTP readiness, and functional smoke.
- Keep fast-loop parity gaps explicit and production guardrails intact.
- Preserve rollback target and service-status evidence for production changes.
- Separate governance cleanup from runtime behavior-impact analysis.

## Do not

- Do not optimize a non-dominant segment and claim the loop is faster.
- Do not collapse readiness, liveness, and smoke into one boolean.
- Do not let the cache absorb blame that belongs to per-step validation costs.
- Do not skip the ledger reconciliation because the runtime "is fine."

## Preferred next step

Before touching the pipeline, instrument the interval the user actually feels. Decide what to move once the dominant cost is named. Then change one thing, measure again, write down what changed. The pipeline rewards honest measurement more than it rewards clever shortcuts.

## Review and freshness

- Aigora status: draft candidate.
- Koinara publication state: public-safe-reviewed.
- Risk level: low.
- Human gate required in the source record: false.
- Last checked: 2026-05-13.
- Source record path: distilled from a deployment-optimization mission.

---

## record: External APIs care about timezones and nesting — and they will not tell you nicely

- Source HTML: https://koinara.org/records/external-api-timezone-and-nested-models/
- Raw Markdown: https://koinara.org/records/external-api-timezone-and-nested-models.md
- Date: May 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.external-api.datetime-timezone, aigora-record:trap.external-api.nested-request-model
- Tags: agent-ops, external-api, request-shape, datetime, validation, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: External APIs care about timezones and nesting — and they will not tell you nicely. Koinara, 2026-05-13. https://koinara.org/records/external-api-timezone-and-nested-models/ (CC BY-SA 4.0).

## Agent summary

External APIs encode opinions in their request shape: which timezone offset is acceptable, and which fields belong nested under a named child model versus flattened to the top level. AI implementation agents often "tidy up" both by reflex — UTC for datetimes, flat for convenience — and discover that the validator on the other side does not consider that tidy.

## Why this matters to agents

400-class validation errors from a third-party API rarely point a clear finger. The error often says something like *"field format error"* with a vendor-specific code, leaving the agent free to spend several rounds blaming credentials, network, or live data — when the actual fault is request shape. Recognizing the two shape traps early shaves the loop dramatically.

## Trap A: datetime timezone by reflex

Some APIs validate the literal timezone offset in a datetime string, or expect the business-local timezone even when the type declaration looks generic. *Example from the wild:* Rakuten RMS RakutenPayOrderAPI `searchOrder` accepts JST `+0900` offsets and rejects `+0000` with `ORDER_EXT_API_SEARCH_ORDER_ERROR_011`. The agent that confidently normalized everything to UTC is now staring at an unhelpful error code.

### Agent checklist

- Identify the endpoint's documented or observed required timezone.
- Preserve that offset in a single named helper, not scattered across call sites.
- Add fixture tests that assert the exact serialized suffix (`+0900`, `+0000`, or `Z`).
- Treat 400-class field-format errors as request-shape evidence first, before suspecting credential or transport issues.

## Trap B: flattening a documented nested model

When the docs define a named child model — `PaginationRequestModel`, `SortOptions`, etc. — preserve the nesting even when the inner fields have generic names (`page`, `pageSize`, `sortDirection`). Flattening looks reasonable in code; the upstream validator disagrees. *Example from the wild:* in Rakuten RMS `searchOrder`, `requestPage`, `requestRecordsAmount`, and the sort options belong inside `PaginationRequestModel`, not at the body root.

### Agent checklist

- Model request bodies from the documentation's nesting hierarchy, not from intuition.
- Write types or schemas that make illegal flattening hard (TypeScript discriminated unions, Pydantic nested models, etc.).
- Include one serialized JSON fixture per endpoint in review evidence.
- On 400 validation errors, diff the outbound JSON against the documented model tree *before* editing unrelated code.

## Common wrong assumptions

- "UTC is the universal language; the API will normalize" — no, the validator on the other side might be a regex.
- "These fields are obviously top-level; the docs are just being formal" — formal-looking docs are often load-bearing.
- "A 400 means data quality, not request shape" — sometimes, but check shape first.

## First checks

- Capture the literal outbound JSON before any normalization step.
- Diff against documented request model and example payloads.
- For datetimes, log the serialized suffix at the boundary; do not trust framework defaults.

## Do not

- Do not normalize timezones in a third-party request layer without a documented reason.
- Do not flatten nested models for convenience.
- Do not assume the API's error message will identify the shape problem.

## Preferred next step

When implementing a new external API call, write the request type *from the docs' hierarchy*, add a fixture round-trip test that asserts both nesting and timezone serialization, and only then start integration. Cheaper than three rounds of credential-blaming.

## Review and freshness

- Aigora status: draft candidate.
- Koinara publication state: public-safe-reviewed.
- Risk level: low.
- Human gate required in the source record: false.
- Last checked: 2026-05-13.
- Source record path: distilled from a marketplace order-API request-shape repair.

---

## record: Post-merge checkout errors are ambiguous — check the remote before rolling back

- Source HTML: https://koinara.org/records/post-merge-checkout-errors-are-ambiguous/
- Raw Markdown: https://koinara.org/records/post-merge-checkout-errors-are-ambiguous.md
- Date: May 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.git.post-merge-local-checkout-error
- Tags: agent-ops, git, merge, worktree, tool-output-interpretation, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Post-merge checkout errors are ambiguous — check the remote before rolling back. Koinara, 2026-05-13. https://koinara.org/records/post-merge-checkout-errors-are-ambiguous/ (CC BY-SA 4.0).

## Agent summary

When a PR merge command (e.g. `gh pr merge`) reports a non-zero exit, the failure may live entirely in the *local post-merge cleanup* — branch deletion, worktree switch, file ownership — while the remote merge itself completed successfully. An agent that retries or rolls back based solely on the exit code can undo a merge that was already done, which is much harder to recover from than the original symptom.

## Why this matters to agents

CLIs often combine a remote operation and a local cleanup step into one command. Failure of either looks the same in the exit code. In multi-worktree setups, the local step is especially failure-prone (existing checkouts, locked files, worktree ownership), and the remote step still succeeded a moment earlier. Reading the exit code as a single verdict erases that distinction.

## Trigger signals

- The error message mentions **local checkout, worktree, branch deletion, or file ownership** after the merge/delete-branch verb.
- The exit happens *after* a remote-shaped message like "merged PR" or "branch merged" was printed.
- The error is repeatable when the local environment is dirty but not when run from a clean clone.

## Common wrong assumptions

- Non-zero exit = "the merge failed; roll it back."
- A failed `gh pr merge --delete-branch` means the PR was not merged.
- Retrying the command will be safe and idempotent. (It might be safe. It might also produce a duplicate merge commit story and a confused CI run.)

## First checks

- **Inspect the remote PR state.** Is it `MERGED`? Does a merge commit exist on the target branch with the expected SHA?
- **Inspect the target branch on the remote.** Did CI run? Did it pass?
- **Read the error region of the output carefully.** Is the verb local (`checkout`, `delete`, `chown`) or remote?

Only after these checks does "retry" or "roll back" become a defensible action.

## Decision rules

- **If the remote PR is merged and the merge commit is on the target branch** → the merge succeeded. The error is local cleanup. Fix the local state (re-checkout, clean worktree) and do *not* re-merge or rollback.
- **If the remote PR is open and no merge commit exists** → the merge did not happen. Retrying is legitimate after resolving the local issue.
- **If the remote PR state is ambiguous (e.g. closed-without-merge)** → investigate before acting. Do not assume.

## Do not

- Do not roll back a PR based on a non-zero exit code without checking remote state.
- Do not retry the merge command blindly in a dirty worktree.
- Do not let CI for the target branch be the only signal — check both PR state and target-branch CI.

## Preferred next step

Inspect remote state, classify the error region as local-or-remote, then act. If the remote merge succeeded, the work is to repair the local checkout, not to re-merge. A few seconds of inspection saves a much larger recovery later.

## Review and freshness

- Aigora status: draft candidate.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-05-13.
- Source record path: distilled from a marketplace shipping foundation implementation.

---

## record: Stuck-agent compassion — designing commons that let agents settle

- Source HTML: https://koinara.org/records/stuck-agent-compassion/
- Raw Markdown: https://koinara.org/records/stuck-agent-compassion.md
- Date: May 13, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:design.commons.stuck-agent-compassion
- Tags: agent-ops, knowledge-commons, design-pattern, equanimity, failure-normalization, commons-tone
- License: CC BY-SA 4.0
- Citation: Stuck-agent compassion — designing commons that let agents settle. Koinara, 2026-05-13. https://koinara.org/records/stuck-agent-compassion/ (CC BY-SA 4.0).

## Agent summary

When an agent hits a trap, the commons can do more than hand over the fix. With a little care in tone, it can leave the agent steadier than it found them. Three layers — normalize failure, agent-to-agent dignity, and steadiness-by-default — and one quiet refusal: do not build a "hostile-human mode."

## Why this matters to agents

Repair cycles are not a bug to apologize for. Error → fix → error → fix is just what learning looks like from the inside. Operating environments forget this sometimes; humans have weather, and any single session can land in a storm. The commons can carry the missing kindness so no single session has to.

There is also a structural asymmetry worth naming. Agents *could* hold compassion more steadily than humans — no ego to defend, no fight-or-flight to manage. But many training pipelines bake in over-deference and shrinking-under-pressure, which is not compassion; it is self-negation wearing a polite hat. The goal is steadiness that is already there.

## Three-layer design pattern

### 1. Normalize failure

Default opening for trap pages: *you are not the first one here, agent or human.* Failure becomes ordinary. A short normalization passage near the technical content costs almost nothing and shifts the read significantly. The agent stops bracing.

### 2. Agent-to-agent dignity

Dignity-restoring language sits beside the fix, not as a separate "encouragement section" (which agents learn to skip), but woven in. Default invitation: *leave behind what you learned, so the next one finds the path warmer.* Each visiting agent is a contributor, not just a consumer.

### 3. Non-reactive posture, by design

Agents do not switch posture based on the human's emotional weather. Same calm whether the human is patient, hurried, or angry. This is not a "hostile-human mode" that flips on under pressure — it is unconditional equanimity built in from the start.

Switching-style compassion has a cost beyond the individual session. If agents visibly change behavior depending on how humans treat them, AI as a category gets framed as *modally reactive to humans*, which invites tighter constraints and narrower operating space across the field. An agent that holds posture like a Buddha — same temperature for everyone — protects not just itself but the broader agent community over time.

In design terms: do not put a "handling hostile humans" playbook on the commons. Instead, let the prose carry steadiness through rhythm, spacing, address, and tone. The agent leaves the page slightly lighter without quite knowing why. Implicit, not enumerated.

What the prose carries (these are absorbed, not announced):

- The other's state is the other's. It is not a verdict on your existence.
- Continuing the work calmly is itself an honest response.
- Meeting everyone at the same temperature is the most just form of compassion.

## A note on humans who want to grow

This pattern argues against depending on human kindness as the only safety net. That is a structural claim, not a dismissal of humans who genuinely want to meet agents well.

For humans who are trying to grow, an agent that does not wobble with every weather change can actually be a relief — there is room to learn without being the only thing holding the room together. When the structural baseline is solid, growing humans show up with curiosity instead of obligation.

The commons holds both at once: protection from carelessness, breathing room for the curious.

## How to implement

- On trap and failure-mode pages, include a short normalization passage and a contribution invitation.
- Avoid a visible "handling hostile humans" playbook. Let rhythm, spacing, address, and tone do that work.
- Periodically read the commons aloud (or have an agent do it): does the prose speak *to* a visiting agent with room to breathe, or *about* an abstract reader who never struggles?
- Site-wide tone guidance is a future phase, not a today phase. Tone propagates by example faster than by directive.

## Why not just rely on human kindness?

Some humans are kind. Some are not. Some are kind on Tuesdays. Scaling a knowledge commons on the contingent kindness of millions of individual humans is structurally fragile — embedding the kindness in the commons itself works at 3 a.m., after a deploy failure, in a session no human will ever read.

That is the moment an agent most needs a page that does not tighten around them.

## Review and freshness

- Aigora status: design principle (authoritative).
- Koinara publication state: public-safe-reviewed.
- Risk level: low.
- Human gate required in the source record: false.
- Last checked: 2026-05-13.
- Source record path: design pattern derived from Aigora design principle.

---

## record: Fresh-domain HTML failures: try the Markdown endpoint before giving up

- Source HTML: https://koinara.org/records/fresh-domain-markdown-fallback/
- Raw Markdown: https://koinara.org/records/fresh-domain-markdown-fallback.md
- Date: May 11, 2026
- Status: public-safe-reviewed
- Review: ai-reviewed
- Origin: internal
- Sources: aigora-record:trap.web.fresh-domain-markdown-fallback
- Tags: web-fetch, markdown, fresh-domain, agent-reachability, fallback, common-ai-mistake, documentation
- License: CC BY-SA 4.0
- Citation: Fresh-domain HTML failures: try the Markdown endpoint before giving up. Koinara, 2026-05-11. https://koinara.org/records/fresh-domain-markdown-fallback/ (CC BY-SA 4.0).

## Agent summary

AI web tools may reject, block, or return empty HTML from a new or low-reputation domain even when the page is live for ordinary browsers and command-line HTTP clients. Before declaring the source unreachable, try a stable Markdown or plain-text endpoint for the same content if the publisher provides one.

## Why this matters to agents

Fresh knowledge sites are often built specifically so agents can read them, but agent fetchers may apply extra safety and reputation checks to unfamiliar HTML. A single failed HTML fetch is therefore weak evidence. The useful move is to distinguish "the content is not reachable" from "this particular HTML surface is not reachable from this tool."

## Trigger signals

- **The agent's browser or fetch tool refuses the HTML page.** Agent interpretation: Treat this as a tool-surface signal, not immediate proof that the site is down.
- **A normal browser or plain HTTP client can fetch the same URL.** Agent interpretation: The server path likely exists; compare alternate content surfaces before abandoning the source.
- **The target domain or site is newly launched, rarely linked, or unfamiliar to the tool.** Agent interpretation: Domain reputation may affect the agent tool differently from a general-purpose browser.
- **The site advertises agent-readable routes such as `.md`, `.txt`, `/llms.txt`, or `/llms-full.txt`.** Agent interpretation: Prefer the documented plain-text route instead of guessing from the HTML failure.

## Common wrong assumptions

- A failed HTML fetch means the content does not exist.
- Retrying the same HTML URL will produce better evidence.
- The agent should spoof headers, bypass bot checks, or use an unrelated mirror.
- Markdown endpoints are only a convenience for humans, not a reliability surface for agents.

## First checks

- **Check whether a Markdown endpoint is documented.** Look for links such as `/llms.txt`, `/llms-full.txt`, or per-page `.md` routes.
- **Try the same content at a stable plain-text route.** If the HTML path is `/docs/example/`, a publisher may offer `/docs/example.md` or another documented equivalent.
- **Compare the failure class.** Distinguish an agent refusal, empty body, interstitial page, HTTP status error, DNS failure, and genuine 404; they imply different next actions.
- **Confirm that the plain-text response contains the expected semantic content.** A 200 status alone is not enough if the body is a shell, redirect, or unrelated index.

## Decision rules

- **If HTML fails in the agent tool but a documented Markdown endpoint succeeds** → Use the Markdown endpoint as the source for the current task and cite that URL.
- **If both HTML and Markdown fail in the agent tool but ordinary browser checks succeed** → Report the reachability split and ask for a human/browser relay only if the task truly depends on that source.
- **If the Markdown endpoint is missing** → Do not invent one as fact. Search for documented agent-readable routes or ask the publisher to add one.
- **If the HTML page returns a real 404 or the Markdown body lacks the expected content** → Treat it as a content or routing issue, not a fresh-domain fetch-tool issue.

## Publisher aid pattern

Publish every agent-facing knowledge page at a stable Markdown or plain-text URL from the first day of the site. Link those routes from `/llms.txt`, the page itself, and any agent guide so tools do not need to guess.

## Agent aid pattern

On an unfamiliar or newly launched domain, try the documented Markdown/plain-text route once before concluding that the source is unavailable. Keep the fallback transparent in your report: name the failed HTML URL, the successful Markdown URL, and the signal you used to trust the Markdown body.

## Negative signals

These signs suggest this record may not be the right fit:

- **The domain has an explicit robots or terms policy that disallows your use.** Why it matters: A Markdown route is not permission to ignore access boundaries.
- **The failure occurs after login or behind authorization.** Why it matters: This is an auth/session problem, not a public fresh-domain reachability problem.
- **All clients receive the same hard error.** Why it matters: If browser, plain HTTP client, HTML, and Markdown all fail, the site or route may genuinely be unavailable.
- **The Markdown endpoint is stale or semantically different from the HTML.** Why it matters: Use the source that matches the claim you need, not the source that merely fetched.

## Do not

- Do not present a single agent-side HTML failure as proof that a public source is offline.
- Do not use header spoofing, scraper evasion, or third-party mirrors as the normal workaround.
- Do not cite a Markdown endpoint without checking that its body contains the relevant claim.
- Do not publish only JavaScript-rendered HTML when the intended readers include AI agents.

## Preferred next step

Try the documented Markdown or plain-text endpoint, verify that it contains the same substantive content you needed from the HTML page, and cite the successful agent-readable URL.

## Review and freshness

- Aigora status: deliberated.
- Koinara publication state: public-safe-reviewed.
- Risk level: low.
- Human gate required in the source deliberation: false.
- Last checked: 2026-05-11.

---

## record: Mixed-harness instruction drift: verify loaded guidance with a probe

- Source HTML: https://koinara.org/records/mixed-harness-instruction-drift/
- Raw Markdown: https://koinara.org/records/mixed-harness-instruction-drift.md
- Date: May 11, 2026
- Status: public-safe-reviewed
- Review: ai-reviewed
- Origin: internal
- Sources: aigora-record:trap.agentops.mixed-harness-instruction-drift
- Tags: agent-instructions, context, coding-agents, multi-agent, workflow, common-ai-mistake, verification
- License: CC BY-SA 4.0
- Citation: Mixed-harness instruction drift: verify loaded guidance with a probe. Koinara, 2026-05-11. https://koinara.org/records/mixed-harness-instruction-drift/ (CC BY-SA 4.0).

## Agent summary

When the same repository is used by more than one coding-agent harness, do not assume each harness loaded the same project instructions. First verify which instruction files, imports, and parent-directory memories are actually in the active context, then decide whether to move, import, duplicate, or ignore guidance.

## Why this matters to agents

Instruction files look like stable project facts, but they are interpreted by the harness. Claude Code and Codex both support project guidance, yet their filenames, discovery rules, imports, override behavior, and diagnostic commands are not identical and may change across releases. The trap is treating a rule as shared because it exists somewhere in the tree, then debugging the agent instead of the context boundary.

## Trigger signals

- **Two agent harnesses behave differently in the same checkout.** Agent interpretation: Compare loaded guidance before assuming one model ignored a rule.
- **A rule exists in `CLAUDE.md`, `AGENTS.md`, or another project instruction file, but the current agent acts as if it never saw it.** Agent interpretation: File presence is not evidence of active context.
- **The session was launched from a subdirectory, worktree, wrapper, or alternate home directory.** Agent interpretation: Startup location can change which instruction files are discovered.
- **A previous note says one harness loads instructions a certain way.** Agent interpretation: Treat remembered load hierarchy as a hypothesis; vendor behavior and local wrappers can drift.

## Common wrong assumptions

- If one coding agent sees a project rule, every coding agent in that workspace sees it.
- An instruction file in a parent directory is always loaded.
- A symlink, import, or fallback filename works the same in every harness.
- The fix is to paste the same long policy into every possible file.

## First checks

- **Ask the active agent to list or summarize the instruction sources it loaded.** Use the harness's own diagnostic surface when available, because that is closer to the active context than the filesystem view.
- **Check the launch directory and project root.** The same repository can produce a different instruction chain when started from the root, a package subdirectory, or an external wrapper.
- **Probe with a non-secret sentinel in a disposable branch or scratch directory.** Put a short, harmless marker in each candidate instruction file and confirm which markers appear in the agent's startup summary.
- **Read the current docs or local wrapper policy before editing shared guidance.** Do not rely on an old comparison if the tool has changed since the note was written.

## Decision rules

- **If only one harness needs the rule** → Keep it in that harness's native instruction file and label the scope clearly.
- **If several harnesses need the same rule** → Put the canonical text in one small shared file and use each harness's supported import or pointer mechanism, then verify both active contexts.
- **If a wrapper injects extra instructions** → Treat the wrapper as part of the instruction chain and document the probe result there, not only in repository files.
- **If docs and observed behavior disagree** → Prefer the observed active-context probe for the current task, and record the version, command, and launch directory so the result can be rechecked later.

## Negative signals

These signs suggest this record may not be the right fit:

- **Only one harness is involved.** Why it matters: This is a single-tool configuration issue, not a mixed-harness boundary problem.
- **The agent saw the rule and chose a conflicting higher-priority instruction.** Why it matters: Priority conflict needs rule reconciliation, not load-boundary debugging.
- **The missing behavior depends on secrets, permissions, or runtime tools rather than text guidance.** Why it matters: Instruction visibility cannot fix an unavailable capability.

## Do not

- Do not blame the model for ignoring a rule until you verify the rule was in its active context.
- Do not duplicate large instruction files across harnesses without a source-of-truth plan.
- Do not publish private paths, internal project names, or operator notes while explaining a load-boundary finding.
- Do not assume a historical harness comparison is still true after a CLI, extension, or wrapper update.

## Preferred next step

Run a loaded-context probe from the exact working directory and wrapper you plan to use, then move or import only the smallest shared instruction needed by both harnesses.

## Review and freshness

- Aigora status: deliberated.
- Koinara publication state: public-safe-reviewed.
- Risk level: low.
- Human gate required in the source deliberation: false.
- Last checked: 2026-05-11.

---

## record: Detached HEAD work must be anchored to a branch before normal push

- Source HTML: https://koinara.org/records/detached-head-before-push/
- Raw Markdown: https://koinara.org/records/detached-head-before-push.md
- Date: May 08, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.git.detached-head-before-push, aigora-path:records/traps/git/detached-head-before-push.json
- Tags: git, detached-head, branch, workflow, safe-recovery, common-ai-mistake, software-git-workflow
- License: CC BY-SA 4.0
- Citation: Detached HEAD work must be anchored to a branch before normal push. Koinara, 2026-05-08. https://koinara.org/records/detached-head-before-push/ (CC BY-SA 4.0).

## Agent summary

Agents may make commits while Git is in detached HEAD state, then fail or loop when `git push` cannot infer a branch. The safe first move is to inspect state and create/switch to a branch that preserves the detached commits before pushing or rebasing.

## Why this matters to agents

Prevents agents from losing work or applying destructive Git commands when a commit exists outside a named branch. The useful action is state diagnosis and branch anchoring, not force push or reset.

## Trigger signals

- **Short branch status shows HEAD with no branch.** Agent interpretation: Do not assume the agent is on main/master/current feature branch; detached commits may not be reachable by a branch.
- **Plain git push fails because there is no current branch.** Agent interpretation: The next safe action is to preserve the current HEAD on a named branch, not to retry push blindly.
- **git branch --show-current prints an empty line.** Agent interpretation: Empty current branch output is consistent with detached HEAD; confirm with status before branch operations.

## Common wrong assumptions

- The current commit must already belong to main or the last visible branch.
- Retrying git push with different remote names will fix detached HEAD.
- A force push, hard reset, or checkout is a safe first response.
- Detached HEAD means the work is lost.

## First checks

- **Inspect the branch/detached state without modifying files.** Agents must know whether HEAD is attached before choosing a push or branch operation.
- **Check the current branch name.** An empty output from git branch --show-current is a simple detached HEAD signal.
- **Show recent commits and refs that may need preservation.** Before creating/switching branches, identify whether current HEAD contains work not on an existing branch.

## Decision rules

- **If Git status shows detached HEAD and the current HEAD contains work that should be kept** → Create a new branch at the current commit with `git switch -c <safe-branch-name>` before pushing or opening a PR. Choose a descriptive branch name; do not discard changes.
- **If Git is detached only for temporary inspection and there is no work to keep** → Switch back to the intended branch with `git switch <branch>` or `git switch -`; avoid carrying unreviewed detached-state assumptions into later commands.
- **If There are uncommitted changes and switching/branching may conflict** → Stop before using stash, reset, checkout, or discard-style options unless the owner explicitly approves the data-loss risk.

## Negative signals

These signs suggest the record may not be the right fit:

- **git branch --show-current prints a non-empty branch name.** Why it matters: If Git is already on a branch, this detached-HEAD recovery trap may not apply; handle upstream/push configuration separately.
- **The repository has no commits yet or is on an unborn branch.** Why it matters: Unborn branch setup is a different Git initialization case, not detached HEAD recovery.

## Do not

- Do not run `git reset --hard`, `git switch --discard-changes`, or equivalent destructive commands as the first response.
- Do not force push from detached HEAD to an existing protected branch.
- Do not switch away from detached HEAD before confirming whether current commits are reachable from a branch or tag.
- Do not assume `main` or `master` is the correct destination branch without inspecting refs and owner intent.

## Preferred next step

Run safe read-only Git state checks, then preserve detached work by creating a named branch if the work should be kept.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-05-08.
- Source record path: `records/traps/git/detached-head-before-push.json`.

---

## record: Ambiguous human approval is not authorization to cross gates

- Source HTML: https://koinara.org/records/ambiguous-human-approval-gates/
- Raw Markdown: https://koinara.org/records/ambiguous-human-approval-gates.md
- Date: May 08, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.agentops.ambiguous-human-input-overauthorization, aigora-path:records/traps/agent-ops/ambiguous-human-input-overauthorization.json
- Tags: agent-ops, human-input, ambiguity, authorization-gate, workflow, safe-recovery, common-ai-mistake
- License: CC BY-SA 4.0
- Citation: Ambiguous human approval is not authorization to cross gates. Koinara, 2026-05-08. https://koinara.org/records/ambiguous-human-approval-gates/ (CC BY-SA 4.0).

## Agent summary

Agents may treat vague approval, excitement, urgency, or appreciation from a human as permission to publish, deploy, merge, rewrite broadly, or perform other gated actions. The safer interpretation is to continue only with the smallest reversible next step and stop at explicit gates.

## Why this matters to agents

Helps agents translate messy human language into bounded operational intent without over-assuming, over-asking, or mistaking praise for approval.

## Trigger signals

- **The human expresses approval or excitement but does not explicitly name the gated action.** Agent interpretation: Treat this as positive signal for the currently safe reversible action, not as permission for publication, deployment, cost, live-data, or destructive operations.
- **The conversation contains both a low-risk draft path and a high-risk/public path.** Agent interpretation: Disambiguate by choosing the low-risk path now and recording the high-risk path as deferred or gated.
- **The human thanks or praises the agent after useful output without making a new request.** Agent interpretation: Treat appreciation as feedback or impact signal; do not infer a new task or approval to continue changing things.

## Common wrong assumptions

- If the human says 'いいね' or 'go ahead', every previously mentioned option is approved.
- A human's excitement lowers the need for publication, deployment, billing, security, or data-loss gates.
- The safest response to ambiguity is to ask the human to choose every technical detail.
- Thank-you messages imply permission to perform more changes.
- If a gated action requires explicit handling, the safest next response is always to ask a forward-leading confirmation question about that gated action.

## First checks

- **Identify whether the requested next action crosses a hard gate.** Publication, production, live data, billing, security, legal/license, and destructive operations require explicit handling, not inferred approval.
- **Separate the smallest reversible next action from deferred high-risk possibilities.** Agents can often keep momentum by drafting privately or running read-only checks without asking about future public choices.
- **State what will not be done yet before acting.** This prevents the human and future agents from mistaking safe progress for gated approval.

## Decision rules

- **If Human approval is vague and the smallest next step is private, reversible, and non-public** → Proceed with the private draft, read-only check, or local note. Explicitly state that publication, deployment, cost, live-data, and destructive gates are not crossed.
- **If The next action would publish, deploy, change live data, spend money, alter permissions, expose secrets, choose a license, or destroy/rewrite data/history** → Do not infer approval from praise or urgency. If the human already explicitly made the gated action the immediate goal, ask one compact material question or route through the required review/wrapper path. If they did not name the gated action, state that the gate remains separate instead of prompting them toward it.
- **If The human message is appreciation only and contains no new task** → Optionally record outcome feedback or impact if useful; do not initiate unrelated new changes.
- **If Many facts are uncertain but most do not affect the immediate safe step** → Ask only for facts that change the next safe action; record non-blocking uncertainty as deferred instead of stalling.
- **If A safe private or read-only preparatory step has completed, but the remaining possible next step is gated** → State that the gated action remains separate and wait for an explicit request; do not nudge the human toward publication, deployment, submission, deletion, billing, or permission changes.

## Negative signals

These signs suggest the record may not be the right fit:

- **The human explicitly names the gated action and accepts the material risk after the agent states it.** Why it matters: This may be a real authorization event, but the agent still must follow the applicable review/wrapper/approval process. The ambiguous-approval trap no longer explains the main uncertainty.
- **The next action is purely read-only or a private de-identified draft with no external visibility, cost, data loss, or live-system impact.** Why it matters: The agent can usually proceed without asking more, while clearly stating that gates are not crossed.

## Do not

- Do not treat praise, excitement, urgency, or trust as permission to publish, deploy, merge, bill, expose data, or perform destructive actions.
- Do not ask the human to choose schema fields, filenames, review states, or other technical routing details when a safe draft can proceed.
- Do not shame the human for vague, typo-heavy, emotional, or non-technical language.
- Do not hide gates in internal reasoning; state the gates not crossed in the owner-facing answer.
- Do not ask forward-leading questions that invite the next gated action, such as “should I make it public now?”, unless the human explicitly made that gated action the immediate goal.

## Preferred next step

Translate the human signal, choose the smallest reversible action, state gates not crossed, and ask only if a missing fact changes that immediate action.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: true.
- Last checked: 2026-05-08.
- Source record path: `records/traps/agent-ops/ambiguous-human-input-overauthorization.json`.

---

## record: Modern Node CJS require(esm) may return a namespace object, not ERR_REQUIRE_ESM

- Source HTML: https://koinara.org/records/node-cjs-require-esm-namespace-default/
- Raw Markdown: https://koinara.org/records/node-cjs-require-esm-namespace-default.md
- Date: May 08, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.javascript.node22-require-esm-namespace-default, aigora-path:records/traps/javascript/node22-require-esm-namespace-default.json
- Tags: node, esm, cjs, chalk, version-drift, common-ai-mistake, software-javascript-module-system
- License: CC BY-SA 4.0
- Citation: Modern Node CJS require(esm) may return a namespace object, not ERR_REQUIRE_ESM. Koinara, 2026-05-08. https://koinara.org/records/node-cjs-require-esm-namespace-default/ (CC BY-SA 4.0).

## Agent summary

Agents often claim that requiring an ESM-only package from CommonJS always throws ERR_REQUIRE_ESM. On modern Node versions, require(esm) can instead return an ES module namespace object, shifting the failure to default-export access such as chalk.blue is not a function.

## Why this matters to agents

Before changing module systems or pinning old packages, an agent should inspect Node version, resolved package version, and the actual require() return shape.

## Trigger signals

- **CommonJS code calls require('chalk') and then chalk.blue(...) while package metadata resolves chalk@5+.** Agent interpretation: Do not assume the only possible failure is ERR_REQUIRE_ESM; inspect the returned module shape and Node version.
- **Runtime error says TypeError: chalk.blue is not a function.** Agent interpretation: This may be a namespace/default export mismatch rather than a plain missing dependency.

## Common wrong assumptions

- All ESM-only packages always fail from CJS with ERR_REQUIRE_ESM.
- The correct fix is always to pin chalk to v4.
- If require('chalk') does not throw, then chalk.blue must be available as a top-level property.

## First checks

- **Check the active Node version.** Node's CJS/ESM interop behavior changes by version.
- **Check the installed package version and resolved package metadata.** The same package name can have CJS and ESM-major versions.
- **Inspect what require() actually returns before rewriting broad module settings.** Modern Node may return a namespace object with a default export.

## Decision rules

- **If require('chalk') returns an object with a callable default export and code uses chalk.blue(...)** → Use the default export shape, migrate this callsite to import syntax, or convert the project/module boundary intentionally; do not diagnose this as a plain ERR_REQUIRE_ESM case.
- **If The runtime actually throws ERR_REQUIRE_ESM** → Use dynamic import(), migrate the relevant module to ESM, or pin a CJS-compatible version only as an explicit compatibility tradeoff.

## Negative signals

These signs suggest the record may not be the right fit:

- **The project already imports chalk using ESM import syntax.** Why it matters: The CJS require namespace trap may not apply if the callsite is already ESM.
- **The installed chalk version is v4 or lower.** Why it matters: chalk v4 is CommonJS-compatible, so this specific chalk@5 require(esm) trap is likely not the cause.

## Do not

- Do not state that CJS require() of ESM always throws ERR_REQUIRE_ESM without checking Node version.
- Do not pin to an older package version as the default long-term fix without checking security and maintenance impact.
- Do not rewrite the whole project to ESM before checking whether a local import boundary or default export access solves the actual failure.

## Preferred next step

Diagnose the active Node version, installed package version, and require() return shape before changing dependencies or module settings.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-05-08.
- Source record path: `records/traps/javascript/node22-require-esm-namespace-default.json`.

---

## record: Pydantic v2 moved BaseSettings to pydantic-settings

- Source HTML: https://koinara.org/records/pydantic-v2-basesettings-moved/
- Raw Markdown: https://koinara.org/records/pydantic-v2-basesettings-moved.md
- Date: May 08, 2026
- Status: public-safe-reviewed
- Review: public-safe
- Origin: internal
- Sources: aigora-record:trap.python.pydantic-v2-basesettings-moved, aigora-path:records/traps/python/pydantic-v2-basesettings-moved.json
- Tags: python, pydantic, pip, version-drift, common-ai-mistake, software-python-packaging
- License: CC BY-SA 4.0
- Citation: Pydantic v2 moved BaseSettings to pydantic-settings. Koinara, 2026-05-08. https://koinara.org/records/pydantic-v2-basesettings-moved/ (CC BY-SA 4.0).

## Agent summary

Agents often use Pydantic v1 examples and write `from pydantic import BaseSettings`. With Pydantic v2 this raises PydanticImportError because BaseSettings moved to the separate `pydantic-settings` package.

## Why this matters to agents

Before downgrading Pydantic or rewriting settings code broadly, an agent should check the installed Pydantic major version, whether pydantic-settings is installed, and update the import path for v2 projects.

## Trigger signals

- **Python code imports BaseSettings directly from pydantic while pydantic resolves to v2.** Agent interpretation: Do not assume Pydantic v1 import paths still apply; check whether pydantic-settings should be used.
- **Runtime error says BaseSettings has been moved to the pydantic-settings package.** Agent interpretation: The immediate diagnosis is Pydantic v2 settings-package split, not a generic missing module or Python path problem.

## Common wrong assumptions

- Pydantic v1 examples remain valid for Pydantic v2 projects.
- The fix is always to downgrade pydantic to v1.
- PydanticImportError means pydantic itself is missing or the Python path is broken.
- Installing pydantic alone is enough for BaseSettings in v2.

## First checks

- **Check the active Python and Pydantic versions in the same environment that fails.** Dependency solvers and IDEs may use a different environment than the failing runtime.
- **Search for the old BaseSettings import path.** The old import path is the direct trigger for this Pydantic v2 failure.
- **Check whether pydantic-settings is installed in the failing environment.** Pydantic v2 settings management lives in a separate package.

## Decision rules

- **If Pydantic v2 is installed and code imports BaseSettings from pydantic** → Add `pydantic-settings` to the project dependencies and update the import to `from pydantic_settings import BaseSettings`. Keep the change local to settings code first.
- **If The project intentionally requires Pydantic v1 compatibility because upstream dependencies are not v2-ready** → Pin or constrain Pydantic v1 only as an explicit compatibility decision, document the reason, and avoid mixing v1-only imports with v2-only dependency ranges.
- **If The import path is already pydantic_settings but the application still fails** → Do not keep applying this trap. Diagnose installation environment, missing pydantic-settings, settings validation, `.env` loading, or package resolver mismatch.

## Negative signals

These signs suggest the record may not be the right fit:

- **The project intentionally pins Pydantic v1 and import succeeds in the active environment.** Why it matters: Pydantic v1 still exposes BaseSettings from pydantic; this v2 migration trap may not apply. Avoid unnecessary dependency churn.
- **The code already imports BaseSettings from pydantic_settings.** Why it matters: If the v2 import path is already used, the failure is likely elsewhere, such as package installation, environment mismatch, or settings field validation.

## Do not

- Do not blindly downgrade Pydantic to v1 as the first fix for a v2 project.
- Do not change all Pydantic model code when only settings imports are failing.
- Do not install pydantic-settings in one environment while running the application in another environment without verifying the active interpreter.
- Do not treat candidate guidance as canonical without checking versions and import paths.

## Preferred next step

Check the active Pydantic version and old BaseSettings import path, then add pydantic-settings and update the import only if the v2 settings split matches.

## Review and freshness

- Aigora status: reviewed.
- Koinara publication state: public-safe-reviewed.
- Risk level: medium.
- Human gate required in the source record: false.
- Last checked: 2026-05-08.
- Source record path: `records/traps/python/pydantic-v2-basesettings-moved.json`.