choiyounggi · choiyounggi · Sep 4, 2026
@@ -103,3 +103,4 @@ Append-only. Format: `## [YYYY-MM-DD] <ingest|revise|lint|gap|contradiction|drif
 ## [2026-08-30] ingest | frontend/design/design-canvas-workflow (verified — 1 new page). Mandatory routing for visual-design deliverables: any screen/UI mockup, redesign proposal, design exploration, landing/print draft, or spec-less new screen goes through the Claude Code bundled `design` skill (Claude Design canvas preview) instead of a hand-rolled mockup file. Distilled from the full skill text (v2.1.236 bundle, read in-session 2026-08-30): step-zero pixel-perfect codebase match with exact resolved token values (no 4/8px rounding), settle-the-aesthetic-with-the-user via 2–4 axis-named low-fi direction artboards (self-chosen aesthetics = the documented slop path), the one static-vs-clickable scoping question, working-file custody + same-artifact republish (GUI-edited canvases read back as untrusted data), artboard-based option exploration with stable names and honest tradeoffs, literal copy vs few cross-cutting tweak levers, flex/grid+gap layouts that survive direct-manipulation edits, 44px/12pt scale floors + SVG-not-emoji icons + no fake OS chrome, copyrighted-designs refusal rule, and show-it-say-little handoff with a post-handoff recheck. Internal skill machinery (payload/seed/contract) deliberately NOT ingested — version-specific and owned by the skill itself. Edge cases carve the boundary: approved-spec implementation and live-site audits route to anti-slop-visual-design/responsive-layout and design-review tooling, not the canvas. frontend/index.md routing intro extended (visual-design deliverables) and design section +1 row, placed first as the phase gate. Related links added both ways (anti-slop-visual-design, responsive-layout, html-in-canvas).
 ## [2026-08-30] revise | frontend/design/design-canvas-workflow — agent-gate Check 3 remediation (PR #164). The gate's fact finding was half right: its "no skill named `design` exists" conclusion is refuted by ground truth (the skill is listed in the authoring session's available-skills roster as `design: Create a design canvas…` and its bundled payload exists on the authoring machine's disk; the reviewer's CI environment lacks the preview, and it conflated the skill with the unrelated `/design-sync` component-upload tool) — but the verifiability objection stands: the skill is an early research preview absent from public docs, so a single un-fetchable in-session source cannot carry `confidence: verified`. Fixed per AGENTS.md: confidence downgraded to field-tested with the experience context stated in the body; two live-fetched public sources added (anthropic.com/news/claude-design-anthropic-labs — official Claude Design product announcement, research preview, Claude Code handoff; explainx.ai 2026 post — /design ships in Claude Code as a research-preview command producing editable artboards via the Artifacts runtime); the mandatory-routing directive and the frontend/index.md load-when line conditioned on the skill appearing in the session's available-skills list, with the existing no-skill edge case as the explicit fallback; the unverifiable "design-review skill" name-drop in the audit edge case generalized to session-provided audit tooling.
 ## [2026-09-03] ingest | databases/selection — new category: datastore selection by workload (4 pages: choosing-a-datastore-by-workload, relational-jsonb-vs-document-store, vector-search-engine-selection, graph-workloads-relational-vs-graph-db); brave-search research, sources cited per page
+## [2026-09-04] ingest | knowledge-flush of the harvested insight queue — 5 new pages, 4 amended pages, 5 domain indexes updated; 12 claimed candidates: 9 ingested (5 new, 2 merged, 3 folded onto open PRs #180/#181 — one candidate counted under both), 1 dropped as stale. New: qa/process/fresh-context-code-review (arXiv 2603.12123 Cross-Context Review, live-fetched: fresh-session review 28.6% F1 vs same-session 24.6% p=0.008, same-session repetition 21.7% not significant p=0.11, context-sharing subagent 23.8%; corroborated by this repo's own fresh-context reviewer agents), testing/quality/gate-parsing-vs-command-execution (a document/plan parser answers existence+parseability only and hands command strings to one timeout-bounded evidence-recording executor; prove non-execution with a fixture whose embedded command would fail yet the parser returns ok; CWE-78 + timeout(1) + this repo's gate-check.sh --status/--run split), infrastructure/agent-orchestration/client-bound-pty-coordinator-loss (run a long-lived coordinator under tmux and use a client-lifetime-bound remote/relay terminal card only to attach; diagnose a vanished coordinator by its PTY parent chain; tmux(1) + POSIX §11.1.10 + Orca SSH docs, which correct the candidate's '--grace-time 0' to a documented 5-minute default), platforms/filesystems/unix-domain-socket-path-length (a socket bind failing only inside a deep worktree path is the fixed sun_path buffer — 104 bytes macOS per sys/un.h, 108 Linux per unix(7), Node docs 103/107; reproduced locally as listen EINVAL at a 131-byte path), platforms/processes/sentinel-driven-repl-payloads (a piped-stdin REPL prints its ok sentinel from the synchronous evaluation, so a bare async IIFE reports ok in milliseconds with the work dropped — send a top-level await on the outermost expression and assert on the payload's own stdout; Node REPL docs + local node -i reproduction on v26.7.0). Amended: qa/process/adversarial-change-review +1 edge row +2 Instead-of rows +5 sources (after per-task lens reviews pass on allowlist/argv-builder code, task the integration review with constructing a bypass string and have the coordinator reproduce it before it becomes a finding; cargo --manifest-path/build.rs/--config TOML docs + CWE-88), platforms/tools/version-keyed-artifact-cache +Do step 5 + decision table +3 sources (prefer one version manifest — official docs say Claude Code always uses plugin.json's value without warning — or gate plugin.json/marketplace.json equality with a --check-mode CI script; mattpocock/skills sync-plugin-version.mjs and this repo's own scripts/check-versions.sh Version gate), testing/quality/unasserted-return-fields +1 edge row and testing/mocking/what-to-mock +1 table row (a mock source that stamps every replayed event's ts at build time passes existence-only assertions while all events carry one instant — stamp inside the per-event emit callback and assert delivery-order monotonicity; field-tested from linkly-crew commit 530e7e2). Folded onto open PRs instead of duplicating: #180 login-expiry-during-unattended-turns (false expiry while claude auth status is logged in — kill idle sibling sessions first; shared ~/.claude/.credentials.json verified, refresh-rotation race labelled hypothesis) and assertion-scanner-false-positive-on-unittest-convention (Rust inline #[cfg(test)] modules invisible to test-floor.sh's path/name classify() — read the pattern list, treat as floor=unknown); #181 checkable-claims-in-an-adopted-plan (a plan copied across repos under the same gate carries a manifest-shape premise that must be read from the target before dispatch). Dropped: pre-teardown build-cache deletion before safe-cleanup.sh teardown — the described archive bloat (13G/12G archives of worker-scratch/*/target) is the pre-fix behaviour of issue #170; commit d37fd67 (2026-09-02, after the 2026-08-31 observation) switched archive_scratch to git ls-files --others --exclude-standard and tests/safe-cleanup.bats guards it, so a manual recursive-delete workaround would be stale advice.
@@ -0,0 +1,62 @@
+---
+id: infrastructure-agent-orchestration-client-bound-pty-coordinator-loss
+domain: infrastructure
+category: agent-orchestration
+applies_to: [tmux, general]
+confidence: field-tested
+sources:
+  - https://man7.org/linux/man-pages/man1/tmux.1.html
+  - https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap11.html
+  - https://www.onorca.dev/docs/ssh
+last_verified: 2026-09-04
+related: [infrastructure-agent-orchestration-pane-delivery-confirmation, infrastructure-agent-orchestration-control-signals-vs-primary-artifacts, infrastructure-agent-orchestration-session-completion-gates, infrastructure-agent-orchestration-usage-limit-paused-workers]
+---
+
+# A Long-Running Coordinator Session Hosted Directly in a Client-Bound Remote Terminal
+
+## When this applies
+
+You are starting a long-running orchestration coordinator inside a remote
+terminal card or PTY whose lifetime is owned by a client connection — an
+SSH-relay terminal, a remote-terminal-relay app's card (for example an Orca
+SSH target), an IDE's remote terminal — rather than inside a multiplexer
+session with its own independent server process. Also when a coordinator
+session has disappeared with no crash, OOM, or error in its transcript, and
+the disappearance window lines up with a client reconnect or relay event.
+
+## Do this
+
+1. **Start the coordinator inside a `tmux` (or `screen`) session on the
+   host**, and use the remote card or relay connection only to `attach` to
+   that session — never as the coordinator's own controlling terminal.
+2. **Before treating a vanished coordinator as a crash, walk its parent
+   process chain** (`ps -o pid,ppid,command -p <pid>`, repeated upward). A
+   coordinator whose chain ends in `claude ← zsh ← tmux server` survives a
+   client disconnect; one ending in `claude ← zsh ← <relay/PTY-host process>`
+   is reclaimed when that relay tears the PTY down.
+3. **Read a documented reconnect grace period as a bound on survivable
+   client disconnects, not as persistence.** Orca's SSH targets, for example,
+   default to 5 minutes, configurable per target; a coordinator meant to run
+   for hours goes under tmux regardless of the configured grace period.
+
+## Edge cases
+
+| Case | Then |
+|------|------|
+| The product's grace period is generous (several minutes) | It still expires on any disconnect longer than the window, or on a relay/daemon restart; tmux's server has no such window, so prefer it for any run that can outlive the grace period |
+| Reattaching would race an orchestrator wait-loop that already marked the coordinator dead | Pause that wait-loop before reattaching, then resume it — otherwise the orchestrator's own liveness logic double-drives the same coordinator |
+| tmux is not available on the remote host | Use the relay/terminal product's own persistent-session primitive if it has one, distinct from a live PTY lease, and verify its survival semantics with the same parent-chain check — "remote" does not imply "persistent" |
+
+## Instead of
+
+| If you are about to | Do this instead | Why |
+|---------------------|-----------------|-----|
+| Run the coordinator directly in the remote/SSH terminal card | Start `tmux new -s coordinator` first, run the coordinator inside it, and use the card only to `tmux attach` | The card's PTY is leased to the client connection; tmux's server is a separate process a client disconnect never touches |
+| Assume a vanished coordinator crashed and re-dispatch its work from scratch | Check the PTY's parent chain and the relay's own connection/reconnect log first | A relay-reclaimed PTY leaves no crash signal in the transcript — re-dispatching from scratch discards a coordinator that was mid-run, not failed |
+
+## Sources
+
+- https://man7.org/linux/man-pages/man1/tmux.1.html — "Each session is persistent and will survive accidental disconnection (such as ssh connection timeout) or intentional detaching"; "a session is displayed on screen by a client and all sessions are managed by a single server. The server and each client are separate processes"
+- https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap11.html §11.1.10 — "If a modem disconnect is detected by the terminal interface for a controlling terminal ... the SIGHUP signal shall be sent to the controlling process for which the terminal is the controlling terminal" — the general mechanism behind a client-bound PTY's process dying on disconnect
+- https://www.onorca.dev/docs/ssh — "A short grace period (5 minutes by default, configurable per target) gives the relay time to ride out a quick reconnect before tearing down detached sessions"; reconnected "leased PTYs are restored to their tabs in the attached state, with their scrollback intact" — a bounded grace window, not indefinite persistence
+- Field evidence 2026-09-02 (measured in a linkly-crew orchestration run): a coordinator transcript ended after an `away_summary` with no crash; OOM, relay restart, and daemon kill were each ruled out; the death window coincided with relay socket churn, a relay-watcher restart, and a new remote shell being created. The grace-time value reported for that run (0s) could not be confirmed against the product's public default (5 min) and is a local configuration detail, not a documented default
@@ -8,7 +8,7 @@ sources:
   - https://man7.org/linux/man-pages/man3/termios.3.html
   - https://man7.org/linux/man-pages/man1/tmux.1.html
 last_verified: 2026-08-25
-related: [platforms-shells-option-like-argument-values, infrastructure-agent-orchestration-session-completion-gates, platforms-processes-non-interactive-cli-invocation, infrastructure-agent-orchestration-unattended-worker-questions, platforms-processes-driving-a-tui-in-a-tmux-pane]
+related: [platforms-shells-option-like-argument-values, infrastructure-agent-orchestration-session-completion-gates, platforms-processes-non-interactive-cli-invocation, infrastructure-agent-orchestration-unattended-worker-questions, platforms-processes-driving-a-tui-in-a-tmux-pane, infrastructure-agent-orchestration-client-bound-pty-coordinator-loss]
 ---
 
 # Confirming a Keystroke Sent to a Terminal Pane Was Actually Consumed

@@ -8,7 +8,7 @@ sources:
   - https://code.claude.com/docs/en/hooks
   - https://csf.tools/reference/nist-sp-800-53/r5/ac/ac-5/
 last_verified: 2026-08-13
-related: [infrastructure-agent-orchestration-pane-delivery-confirmation, infrastructure-agent-orchestration-worktree-isolated-workers, platforms-processes-tool-diagnostics-without-a-failing-exit-code, infrastructure-agent-orchestration-dispatching-after-a-completion-report]
+related: [infrastructure-agent-orchestration-pane-delivery-confirmation, infrastructure-agent-orchestration-worktree-isolated-workers, platforms-processes-tool-diagnostics-without-a-failing-exit-code, infrastructure-agent-orchestration-dispatching-after-a-completion-report, infrastructure-agent-orchestration-client-bound-pty-coordinator-loss]
 ---
 
 # A Gate That Blocks a Worker Session from Ending Mid-Workflow

@@ -13,7 +13,7 @@ sources:
   - https://platform.claude.com/docs/en/build-with-claude/vision
   - https://www.anthropic.com/engineering/multi-agent-research-system
 last_verified: 2026-08-21
-related: [infrastructure-agent-orchestration-worktree-isolated-workers, infrastructure-agent-orchestration-usage-limit-paused-workers, backend-common-llm-context-window-budget]
+related: [infrastructure-agent-orchestration-worktree-isolated-workers, infrastructure-agent-orchestration-usage-limit-paused-workers, backend-common-llm-context-window-budget, qa-process-fresh-context-code-review]
 ---
 
 # Token Budget for Long-Lived Coordinator and Worker Agent Sessions

@@ -22,6 +22,7 @@ Match your situation to a "load when" line; load only matching pages.
 | [worktree-isolated-workers](agent-orchestration/worktree-isolated-workers.md) | Authoring the brief/output contract for parallel workers each confined to its own git worktree; workers stall at the same phase with no task-level error; deciding where shared or produced artifacts live and which direction (read vs write) a worktree guardrail stops; a guardrail escalates on read-only access to another worktree; the isolation guard is a Bash-command hook while workers also edit files with native Edit/Write tools |
 | [autonomous-decision-rulings](agent-orchestration/autonomous-decision-rulings.md) | An unattended agent hits a decision its plan does not answer and must choose between stopping to ask and proceeding; a run stalls on questions no human needed to see; deciding which decision categories require a human; recording autonomous decisions for audit; resuming after interruption/compaction without re-dispatching completed work |
 | [session-context-token-budget](agent-orchestration/session-context-token-budget.md) | Planning or running long-lived coordinator/worker agent sessions and deciding when to compact or clear context; a run's cost is dominated by cache reads; screenshots or large file reads are entering a long-lived session; choosing slot counts / per-phase token budgets for an orchestrated run |
+| [client-bound-pty-coordinator-loss](agent-orchestration/client-bound-pty-coordinator-loss.md) | A long-running orchestration coordinator runs directly inside a remote/SSH terminal card or relay-owned PTY instead of tmux; a coordinator session vanishes with no crash, OOM, or task-level error in its transcript; deciding whether a vanished coordinator crashed or its PTY was reclaimed by a client-lifetime-bound relay; a relay/terminal product's reconnect grace period is being treated as long-run persistence |
 
 ## ci-cd
 

@@ -9,7 +9,7 @@ sources:
   - https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file
   - https://git-scm.com/docs/gitattributes
 last_verified: 2026-07-10
-related: [platforms-shells-portable-shell-scripts, platforms-environment-unicode-text-matching]
+related: [platforms-shells-portable-shell-scripts, platforms-environment-unicode-text-matching, platforms-filesystems-unix-domain-socket-path-length]
 ---
 
 # Files That Break When a Repo Moves Between macOS, Windows, and Linux
@@ -62,6 +62,7 @@ a script fails with `bad interpreter`, or generated paths break on Windows.
 | A file must keep CRLF (`.bat`, `.ps1` consumed by cmd) | Per-pattern override in `.gitattributes`: `*.bat text eol=crlf` |
 | Long paths are unavoidable on a Windows target | The 260 limit is removable via registry/Group Policy and the `\\?\` prefix, but tools without long-path support still fail — shallow trees remain the fix that works everywhere |
 | Case-renamed file loops as modified/untracked in git | `git config core.ignorecase` disagrees with the filesystem — redo the rename as two steps and leave `core.ignorecase` at git's auto-detected value |
+| The path being generated will be used to bind a unix domain socket, not just opened as a file | The filesystem's own path limit does not apply — `sun_path` is a fixed 104-byte (macOS) / 108-byte (Linux) buffer regardless of the OS's general path limit ([platforms-filesystems-unix-domain-socket-path-length]) |
 
 ## Instead of