cli-jaw

# CLI-JAW Claude Guide

- The canonical desktop release workflow must Developer ID-sign macOS with Team `U9ATA49N28`, notarize, staple, verify the final app, and verify channel metadata plus the update ZIP SHA-512 before upload. `electron:dist:mac:signed` is the equivalent opt-in local path; ordinary `electron:dist:mac` remains ad-hoc. Windows remains unsigned. Keep README and `structure/infra.md` aligned; fixture tests do not prove a signed/notarized artifact, and the first signed release is a manual-DMG bootstrap before in-app updates can be trusted.

This repository is a Node.js ESM orchestration runtime for boss/employee dispatch, Web UI, browser/CDP automation, Telegram/Discord/Slack channels, memory, heartbeat, and PABCD orchestration.

The `/api/code` API owns isolated Codex/Claude/Cursor/Grok sessions through `src/code-mode/host.ts`. Use its dedicated store, native adapters and captured turn/resource ownership; keep full snapshots, compact replay and byte limits synchronized with the runtime and API architecture docs. Claude conversation rollback is the one replay carve-out: removed items and their events are deleted, replay below the replay floor answers `invalid_sequence`, and a higher `historyGeneration` requires a new snapshot.

Native Code interruption seals callbacks before persisting accepted buffered content under the captured store owner. Worker and Manager share the Code JSON body policy in `src/routes/code-body-parser.ts` (1MiB decoded prompt, 6MiB + 4KiB envelope); generic API limits stay separate. Settings navigation guards the drafts actually being discarded, including keyboard and desktop subscriptions.

## Documentation Map

- Start at `structure/INDEX.md` for the current architecture map.
- Architecture contract notes live in `structure/AGENTS.md` §Root contract notes.
- Workbench modernization uses a one-row Activity header with Codex-style expanded rows/groups; the Workbench Settings tab is replaced by a ZCode-style full settings page that swaps the workspace (header gear / Meta+,, `← Back to workspace`, grouped icon nav, card content), persisted as Manager registry `ui.instanceSettingsOpen`. A unified settings registry separates Instance/Manager scopes and the same page is served standalone from `dist/settings` behind the Classic header gear (the right-panel 설정 tab is gone); Classic uses the t3 token shell. Preserve per-page save owners, dirty guards, Preview iframe identity and independent live Requests; see `structure/frontend.md`.
- Keep `README.md`, `AGENTS.md`, this file, and `structure/AGENTS.md` aligned when command/API/orchestration behavior changes. Concurrent inbound gateway changes belong in `structure/INDEX.md`, `structure/infra.md`, `structure/telegram.md`, and the messaging runtime docs.
- `docs/` and `structure/` contain public product documentation only. Private plans, audits, evidence, and history belong only in a separate sibling clone of [cli-jaw-internal](https://github.com/lidge-jun/cli-jaw-internal); request access through an [issue](https://github.com/lidge-ai/cli-jaw/issues).
- Never create private records inside this checkout, including `devlog`, `_plan`, `_fin`, or `.jwc` aliases at any depth. This overrides generic skill defaults. Do not include private record paths in public docs or source.
- Before public pushes, check the index with `npm run check:private-boundary` and outgoing commit trees with `node scripts/check-private-boundary.mjs --range <remote-base> HEAD`; enable the checkout-local pre-push hook as described in [CONTRIBUTING.md](CONTRIBUTING.md#local-private-path-check). Review content separately. CI runs after upload and cannot prevent initial disclosure.

- Manager sidebar selection and Sessions/Stop/Open use separate interactive targets. Keep list navigation scoped to the focused row selector, stable session-disclosure links, and preferred width separate from viewport clamping. Pointer and keyboard resize completion persist the latest value; see `structure/frontend.md`.
- Manager terminal presentation preserves backend PTY ownership across hide/unmount. Keep hydration-first bounded creation, explicit recovery, stable tab identity and focus ownership separate from native Code API sessions; theme updates must not recreate shells. See `structure/frontend.md`.

## Build & Deploy Contract

- The running server executes compiled `dist/` (`jaw serve` → `dist/server.js`), never the TS sources. After changing `server.ts`/`src/**`/`bin/**`, run `npm run build` before telling anyone to restart; frontend changes additionally need `npm run build:frontend`. Full rules: `AGENTS.md` § Build & Deploy Contract.

## Current Runtime Notes

- Channel forwarders deliver to the destination captured when a run was admitted, never to a per-channel last-active slot. `src/messaging/run-pin.ts` builds the identity block (origin/requestId/scope/sessionId/remoteKey/target) that every `agent_done` carries, and `resolveForwarderTarget` refuses an event with no destination or one addressed to another channel. Slack, Discord and Telegram forwarders no longer accept a `getLastTarget`/`getLastChatId` option, so web and CLI turns are not mirrored into chat rooms. Heartbeat destinations are complete or held: a Slack destination needs a thread or an explicit `scope: "channel_root"`, an absent destination sends nothing, threaded jobs verify `conversations.replies` before runner work, a bound destination send carries `fullAccess` after binding (not an HTTP JSON voucher; mention-watch hit posts do not copy it), and a 25-minute server-owned `enforceDestination` grant is injected into print, native, employee and script runtimes before work so omitted targets pin and mismatches fail without process-global locking. Live hold reasons remain visible to GET/UI until recovery. `authorizeExplicitTarget` vouches for a send without rewriting its address. Slack progress cards end their live loop on `message_not_found`/`cant_update_message` or three consecutive failures rather than retrying a dead message. See `structure/telegram.md` and `structure/server_api.md`.

- File sends across Slack, Telegram and Discord share one confirmation vocabulary. A send the vendor will not name is refused rather than reported as delivered (Slack keeps its `files[]` echo requirement, Telegram requires `message_id` > 0, Discord requires a readable Create Message body): those are `ok:false` with `confirmation: 'unconfirmed'`, replacing the older `ok:true, ambiguous:true` no consumer read. Anything forwarding a file result must preserve `confirmation`, or the caption posts twice. See `structure/infra.md` and `structure/telegram.md`.

The Classic permission selector offers Auto (YOLO) / Safe choices, stored as literal `auto` / `safe`. Server startup preserves the saved policy; never reintroduce the obsolete safe-to-auto coercion. Existing runtime-specific policy support and settings invalidation still apply.

- Linux `/api/file/open` acknowledges asynchronous `xdg-open` launch, not desktop application success. Keep detached/ignored-stdio dispatch and launch-error handling; never wait synchronously for the opener. See `structure/server_api.md`.

- Classic history restoration uses bounded targeted replay and preserves recorded
  scope; unrelated live runs continue. Exact saved answers come from the run+chat
  MESSAGE lookup, not redacted journal finals. Resolved-session loading and captured
  cache namespaces keep browser/server IDs distinct. Raw Trace pages cap80 rows;
  denied/unverified actions stay inert. Fork MESSAGE visibility does not confer
  original Trace ownership. Keep frontend/API docs aligned.

- Presentation preference is activity(default on fresh/upgraded absence) or explicitlegacy; runtime transport/permissions are separate. Explicit known mode and/or eligible transport-only API patches preserve admitted-run ownership and skip fallback/singleton effects, not serialization or rollback. Legacy presentation-subtree skips remain separate; mixed execution-changing/unknown/empty leaves still invalidate. External-file transport edits still invalidate, while API self-write echoes are ignored. Classic's bounded4MiB/15s preference GET retains last mode on failure and ignores old generations. Manager Display singleflight and port/client epochs preserve drafts on failed or stale saves. Do not replace the native request bridge. Classic live and retained Activity use bounded native disclosures and one authoritative saved/public answer; TUI integration follows the separate controls and ownership notes below.

- Interactive TUI defaults Activity with reversible Legacy. Snapshot owns live admission; F6 reads history only (Enter journal record, A saved answer), never changes message/Stop target. Journal text is redacted; saved MESSAGE refines compatibility without duplicate cleanup. Preserve missing-journal receipts across live/replay, bounded GET/queue cancellation, absent-native diagnostics, newer-run lifecycle guards, draft-safe late line output and actual-flush-only payload release. Raw/simple have no new reads. Sync commands/frontend/stream/tui-scrollback docs; TUI proof is not broader visual/runtime/Electron certification.

- Print providers observe accepted text/thought/tool boundaries through `runtime/print-activity.ts`; they never create a native outcome or infer final from exit0/last text. Existing lifecycle selects the application-final; trace link/finalize failure cannot roll back its MESSAGE or block delivery. `merge-tool-log.ts` keeps run-scoped latest terminal tool detail. Snapshot reconstruction must retain known omission even with nonempty partial DB rows; default sanitizer semantics and messaging stay unchanged. Native terminal replacement remains opt-in for print only.

- Activity journal ownership is captured at trace admission, not inferred from provider IDs or copied messages. Immutable bounded runtime rows and private control metadata live in `src/trace/activity-{journal,control,retention}.ts`. Discovery/replay and owned raw routes require the original explicit session; internal append remains available but internal replay is denied. Retention removes whole canonical prefixes; late `onlyIfRunning` cleanup cannot rewrite completed control. Existing instance auth, finals and Slack ACK/queue behavior remain unchanged. See `structure/runtime-integration.md` and `server_api.md`.

- Native decision APIs are `GET /api/runtime/requests?sessionId=...` and `POST /api/runtime/requests/:id`. Existing instance auth, exact run/session/scope/turn and current-owner checks apply; this is not a tenant ACL or a new loopback credential policy. The registry sanitizes and preflights the32KiB event before insertion, keeps native option IDs in private mappings, and caps128 requests/120s; ACP callbacks cap32 and retain cancellation latches through reply completion. An unflushed selected reply forces connection retirement on cancellation. Provider activation and Activity controls remain separate; no messaging contract changes.

- New installations prefer Codex App when capability and auth are ready; existing saved runtimes change only through the one-time accept/keep Settings action. CLI status is served from a nullable stale-while-revalidate cache whose probes run in a bounded child. OpenCodex diagnostics compare the read-only Codex root URL with the live runtime fingerprint and never modify Codex config.
- PABCD entry is explicit: `jaw orchestrate`, `/orchestrate`, or `/pabcd`. Resume is explicit `/continue`; natural-language “continue/계속/이어서” remains a normal prompt.
- Workflow helper slash commands are `/plan`, `/interview`, `/deliberate`, `/planaudit`, `/review`, `/search`, `/goal`, `/goalplan`, `/team`, `/task`, `/fork`, and `/gd`. Dynamic `/skill:<id>` injects an active skill on CLI/Web. `/plan` is a compatibility guide for users expecting a plan command; it maps to PABCD P and does not create another planning mode. `/planaudit` is the canonical remote-safe spelling; `/plan-audit` is not registered. `/search <query>` forces the active search skill policy, rewrites focused queries, discovers candidate URLs, and uses browser commands only for evidence verification after candidates exist. Bounded automation is a `/goal run ...` subcommand family, not a separate top-level `/autopilot` command; current `/goal run` controls are tracking-oriented runtime gates.
- `/goal plan [hint]`, `/goalplan [hint]`, and `cli-jaw goal plan [hint]` create a pending plan-mode goal. The raw hint is stored separately as `planHint`, not as the durable objective. Agents must refine with `/goal refine <specific objective>`, `cli-jaw goal refine "<specific objective>"`, or `/api/goal` `refine-objective` before checkpoints are accepted.
- Agent pause is a two-tap audited gate. After the first `--agent --audit` attempt, the goal remains persisted as `active` but status/API surfaces expose derived `pauseGate: { armed: true, reason: "pause_gate_pending" }`; one audit/finalizer goal-continuation may run, and if that turn exits with the gate still armed it emits `goal_pause_gate_pending` without scheduling another kick. A second audited pause pauses the goal; a productive checkpoint clears the gate.
- PABCD forward transitions require `jaw orchestrate <phase> --attest '{"from","to","did",...}'` (C→D also `checkOutput`/`exitCode`). Goal mode self-advances but still uses attestation as proof-of-work. See `structure/prompt_flow.md`.
- Optimization/score-maximization goals follow the optimization-loop discipline (LOOP-PHASE-DEATH/CONTINUITY/CANDIDATE-ANCHOR/INSTANCE-CHECK + GATE-ORACLE-VALIDITY):
  classify candidate changes, ban a class after 3 consecutive discards, force evaluator-gate work on repeated D-phase deaths.
  Canonical: dev-pabcd §10, dev-testing §9.5; injected via orchestration template and goal continuation.
- Pre-prompt context hooks: optional `~/.cli-jaw/context-hooks.json`, scopes `main`/`heartbeat`, `cli-jaw hooks inspect`. See `docs/dev/pre-prompt-context-hooks.md`.
- **Telegram Hub** (P0–P4): forum-topic routing via Dashboard `/api/dashboard/telegram-hub`; hub commands `/setthread` `/threads` `/hubhelp`; per-topic `model`/`systemPrompt` overrides (P4). One bot token → one long-poller. See `structure/telegram.md`.
- Bounded local search (prompt-injected): Grep/Glob from one known file or narrow directory only; external/Korean search via `/search` / active search skill. See `structure/prompt_flow.md`.
- `npm test` runs `tests/run.mts` (programmatic driver, `isolation:'process'`, per-file `CLI_JAW_HOME`); `--scope`/`--shard i/N`/`--list` select and slice deterministically. CI is sharded: `test 1..4/4` + `integration` (integration/manager/bin with a live server) + `gates` + `windows-unit` (manifest `scripts/ci/windows-unit-manifest.txt`) → `ci-aggregate` (`scripts/ci/aggregate-check.sh`). See `structure/infra.md`.
- Standalone lifecycle is home-scoped: `jaw --home <path> service stop|restart [--port N]` verifies `<JAW_HOME>/jaw.pid.json` before signalling; registered launchd/systemd instances delegate to their native manager. Never recommend killing every Node process. See `structure/commands.md`.
- `/review` is a project-dir review workflow: it uses configured `projectDirs` or a validated recent-context git repo, never JAW_HOME/`process.cwd()` fallback, treats `/review [focus]` user text as the highest-priority scope signal, resolves the review scope from the current conversation focus plus recent goal/chat context and commit history/diffs/worktree/untracked files, saves a Markdown report with scope evidence, and scopes `--fix` to Critical/High findings as new working-tree patches on top of current `HEAD` without rewriting commits. Git ranges are evidence for the conversation-selected work item, not permission to include unrelated recent commits.
- Korean promotional/content writing (홍보 쓰레드, 인스타 카드뉴스, 링크드인, 웹/블로그 게시물, 윤문) is owned by the active private runtime `k-writing` skill, not free-form prose or the retired `k-thread-gen` label. Route by channel first, then run the mandatory workflow: pre-search, content-type detection, 3-candidate hook scoring, tone/module formatting, and anti-AI-tell plus 인간다움 checks before output.
- Pi (`pi`) is a top-level runtime, not a hosted-provider SDK inside cli-jaw. It runs through `pi --mode rpc` with owned profiles, isolated `PI_CODING_AGENT_DIR` and the existing command fallback. One asynchronous completed-close capability observation gates prompts per RPC instance; both pool wrappers expose its live getter. Direct cancellation and RPC exit trigger one paired cleanup owner, and persistent failure is claimed before cleanup. Worker deletion needs both physical evidence and captured unique-directory identity; uncertainty retains. `PiRuntimeSession` owns ACP-style claim/finalize, two-outcome cancel (pooled abort-and-reuse / oneshot abort-then-kill), and employee `openPiRpc` then `send`. Preserve typed finals and explicit resolver/opaque-wrapper/shutdown limits in `structure/runtime-integration.md`.
- AGY (`agy`) is a top-level runtime. It runs in print mode through `agy -p`; optional flags such as `--model` are capability-probed before emission (AGY 1.0.12 supports `--model`; probe failure falls back to legacy emit-all compatibility), captures print-mode session ids from a per-run `--log-file`, resumes exact saved sessions with `--conversation <id>`, exposes no per-run `--effort` flag, checks auth at run time, and uses plain-text stdout rather than NDJSON parsing. Native AGY context-file ingestion is separate from cli-jaw's wrapper-injected operational context, exact resume policy, transcript anchoring, quota UI, and post-compaction invariants.
- Grok (`grok`) quota uses native OIDC credentials and user identity for JSON weekly credits, with bounded Grok Build gRPC-web weekly and legacy monthly billing fallbacks.
- Cursor (`cursor`) is a top-level experimental runtime. It runs through `cursor-agent -p --trust --output-format stream-json`, resumes with `--resume <chatId>`, uses `--model <resolvedModelId>`, and encodes effort in the model id rather than passing a separate `--effort`/`--thinking` flag. Cursor quota reads the selected native credential store and current period/summary/legacy usage endpoints, with an explicitly configured dashboard cookie as a separate fallback.
- Native quota readers follow the OpenCodex source contract: Codex window duration/plan policy, Spark and reset-credit metadata; Claude model-scoped windows and credential-scoped cache. Missing measurements remain unknown, 429 alone never means 100%, and upstream bodies are bounded. See `docs/migration/quota-reader-parity.md`.
- Kiro (`kiro-code`) is a top-level runtime. It runs through `kiro-cli chat --no-interactive`, resumes with `--resume-id <sessionId>`, passes `--model` and optional `--trust-all-tools`, parses plain-text stdout (ANSI stripped), emits `agent_tool` steps from Kiro tool progress lines, shows AGY-style working indicators while busy, and captures session ids from the kiro-cli v2 session store (`conversations_v2` in the kiro-cli data sqlite, keyed by the canonical cwd) — the legacy `~/.kiro/sessions/cli/*.json` files are not used by `chat --no-interactive`. Fresh Kiro turns include cli-jaw operational context + bounded history; resumed Kiro turns send only the current prompt because the native session already owns prior context. Live models come from `kiro-cli chat --list-models --format json`; quota uses `AmazonCodeWhispererService.GetUsageLimits` on the validated regional Kiro management host with a read-only native social/OIDC token selection.
- Gemini full-access runs use `--skip-trust --approval-mode yolo` on both fresh and resume sessions.
- `/api/channel/send` is the canonical outbound Telegram/Discord/Slack delivery endpoint. Concurrent inbound gateway: settings v4 uses `messaging.enabledChannels` (array) and `messaging.homeChannel`; legacy `settings.channel` is a deprecated read-only alias for one major version. Outbound resolution prefers `target.channel`, then explicit `channel`, then `homeChannel`.
- Mid-run policy: `multiSession.midRunPolicy` defaults to `'steer'`. In-band same-turn steer works for codex-app while a steerable turn is in flight (`turn/steer`). Every other runtime takes the kill-steer path — the turn is killed and a new run starts with the interrupted partial output reinjected (`withSteerContext` + exit-settle barrier). Only in-band failures (turn-end race, review/compact rejection) degrade to the queue; queueing on busy is what `'followup'`/`'collect'` are for. See `structure/prompt_flow.md` §Mid-run 메시지 정책.
- Slack text sends preserve Markdown and explicit Block Kit `blocks`, splitting multiple tables into separate messages. `ok:true` means every chunk was posted, independently of rendering verification. Inspect `delivery.verification` (`verified`, `failed`, or `unavailable`) and `delivery.messages` for each posted chunk's timestamp, verification error, table-content status, and feature evidence. A persisted mismatch is `failed`; missing permission, unavailable/malformed readback, or a missing timestamp is `unavailable`. Neither stops remaining posts or triggers reposting. Actual validation/POST failures retain `ok:false`; partial receipts include `postedChunks`, `totalChunks`, and `sent:true, retryable:false`. Never blindly resend posted chunks. `tableContent` compares ordered text, numeric value/display, links and supported styles; ordinary Markdown character references decode once while code and escaped ampersands stay literal. `richContent` and `sourceAccuracy` remain `not_checked`, and readback stays bounded to 1 MiB.

- Slack progress uses one bounded native task plan for direct and queued requests, with exact request/run correlation and no raw tool details. Native elapsed time updates every second when the shared API budget permits; only changed cards are sent. Known file tools show bounded, sanitized project-relative filenames (outside the captured project: basename only). Cursor shell tool-call purposes and bounded English action/target summaries distinguish shell-based reads, searches, tests and scripts; raw command bodies and argument values remain excluded. Final delivery stays with the verified sender; known failure/cancellation cannot become a success ACK. Restore and shutdown use captured ownership and bounded cleanup. See `structure/telegram.md`.

- Slack connection environment variables own their matching fields at runtime: `GET /api/settings` reports `slackEnvironmentVariables` while redacting values, Settings and CLI setup conservatively refuse connection editing while any are present, generic `PUT`s reject only env-owned paths, and persistence strips only those fields so environment values never enter `settings.json` or erase unrelated file-backed credentials. Full `POST /api/settings/slack/reset` still returns `409` while any connection env variable exists. Telegram and Discord connections share the same model: `TELEGRAM_TOKEN`/`TELEGRAM_ALLOWED_CHAT_IDS` and `DISCORD_TOKEN`/`DISCORD_GUILD_ID`/`DISCORD_CHANNEL_IDS` own their matching fields, `GET /api/settings` reports `telegramEnvironmentVariables`/`discordEnvironmentVariables`, generic `PUT`s reject env-owned paths with `409 telegram_connection_managed_by_environment`/`discord_connection_managed_by_environment` naming the managed fields, the file watcher ignores env-owned fields, and Manager/Classic lock the connection controls showing only the variable names.
- Auto (`permissions:auto`) grants qualified direct-local Jaw API authority across supported runtimes, independently of per-turn secrets. Keep actual/effective loopback, exact browser origin, proxy provenance, explicit outbound destinations and server-only resource options. Safe/custom keep existing scoped/operator paths; full API authority is instance-wide, distinct from provider Safe and task scope. Preserve no-descendant/read-only assignments, captured worker context and honest capability/receipt evidence. See `docs/slack-tools.md` and `structure/server_api.md`.
- Slack group DMs use `message.mpim` and optional `mpim:history`; exact `channel_type: mpim` mentions retain channel allowlist and thread policy, never the one-to-one DM bypass. An install without `mpim:history` receives no group-DM traffic at all; that gap is reported in `missingCapabilities` and logged as a reception limitation rather than failing credential validation. An absent scope header is unknown and a present empty header is a known empty grant. Keep `structure/telegram.md` and the validation API docs synchronized.
- Slack-triggered Boss turns receive `channel_id` and parent `thread_ts` in the per-turn user prompt regardless of multi-session state; agents use that explicit context for Slack lookup/send APIs instead of parsing session labels.
- Heartbeat schedules support `{ kind: "every", minutes }` and `{ kind: "cron", cron, timeZone? }`.
- Slack mention watching is an opt-in `mentionWatch` mode of the existing `runHeartbeatJob`, not a daemon. It scans the configured non-empty `channelIds` subset with bot-token `conversations.history` because user-token-only `search.messages` cannot be used, walks newest history backward with completed frontiers and resume bounds, rotates channels between ticks, stops on 429, and reports overflow beyond 60 channels. Each hit re-checks PABCD/agent/message-queue/pending-replay work before the agent returns answer text only; the server sends that text to the source thread with `sendChannelOutput` and records seen only after success, giving at-least-once delivery. Keep watch jobs disabled until configured, and re-intersect their channels with the current Slack allowlist on every tick. Optional `userIds` and `conditions` (`mention`|`talk`) keep the default as mention-of-`userId`; talk is opt-in and inbound `mentionOnly` is a different gate.
- A mention-watch answer runs in the answered thread's `chatSessionId` so it shares that conversation's history, but in a separate `mention-watch:<remoteKey>` scope so no inbound message can steer the background turn. The per-item guard is therefore per conversation: the thread must be PABCD-`IDLE`, its session free of in-flight work, and its lane free (checked, never awaited, because a lane wait is unbounded while the whole heartbeat is held). Sessions are minted only on admission, since a remote-bound session row cannot be deleted later.
- The receipt/cursor ledger is keyed by (jobId, workspaceId, userId): Slack identifies a person as (team_id, id) and one runtime can re-authenticate against a different workspace, so a job-only key hands one person's cursor to another. The workspace id comes from a bot-token `auth.test` cached per token, never from mutable `settings.slack.teamId`, and a failed lookup skips the tick rather than guessing. Pre-v2 ledger rows carry no workspace or user, so a job holding them is HELD out of scheduling until an operator restarts it with a fresh `since` through `POST /api/heartbeat/:jobId/mention-watch-fresh-start`; the hold is durable in SQLite because `heartbeat.json` is operator intent while the hold is the system's judgement, and a downgrade that writes v1 rows again re-quarantines. A duplicate job id in one PUT is a 400, since two jobs under one id share one namespace.
- Tool logs are capped by `src/shared/tool-log-sanitize.ts` before SSE/WebSocket, `agent_done`, and orchestration snapshot delivery. Web UI delivery is SSE-first through `GET /api/events`, with WebSocket as the legacy fallback dispatcher.
- Canonical Codex/Pi events use `src/agent/runtime/*` and the shared runtime contract. Trace-first `agent_runtime` bypasses messaging listeners; a per-run `agent_runtime_gap` cannot suppress ordinary final delivery. Optional native outcomes preserve absent/empty finals and separate partial salvage; compatibility terminals expose finality/status and optional `stopCause`, never the full outcome. Pi resolved stderr remains private and bounded; caught diagnostics are redacted before bounding and only annotate error outcomes. Captured internal kill reasons retain generic stopped wording. Existing untagged behavior remains. See `structure/runtime-integration.md` before extending an adapter.
- Cursor/Grok/Claude transport choice is independent of Activity display. Existing homes migrate absent/print to native once per migration id (`nativeTransportMigration`, now v2, which re-runs over v1 stamps including a print chosen after v1) wherever permissions let native run; print chosen after the v2 stamp is operator intent, and a v2 `partial` retries only its skipped engines when permissions later allow. Keep native-v1 session keys and the print singleton isolated. Forward the captured mode/bucket through both saves and all compact paths, use exact scoped reset keys, and guard unsupported main/worker native modes before any print/fallback side effect. Status implementation flags are not binary/auth readiness; builtin Codex App/Pi identities remain unchanged.
- Claude native uses optional SDK/shared pool/host/lifecycle, sequential main reuse, fresh owned workers, deferred terminal claims and hard-close Stop. Keep kill-steer/resume salvage and interrupted MESSAGE before exit-settle; no in-band input claim. Auto (YOLO) / Safe approval/question callbacks use the live panel, images are bounded and SDK children are foreground-only; deny/unknown profiles (memory extractor included) stay print-only. Reconcile parent/child declarations to a bounded fixed point; retain declared ID history even after a child stops, without reviving permission eligibility. Fallback start precedes compatibility end; `onlyIfRunning` preserves finished headers.
- `/api/code` Claude sessions accept one in-band follow-up per streaming turn; jaw kill/resume unchanged.
- Claude unleased acquisition cleanup remains on the captured control after logical main/worker completion; rejection keeps the fence. Worker directory cleanup is worker-only. All three main-steer callers use the main-only wait and preserve exit-settle/salvage; existing scoped/global shutdown waits stay inclusive. A wait deadline is not physical-close proof. See `structure/runtime-integration.md`.
- Native request notices use a route-resolved presentation scope and bypass messaging. Live request entries/POST retain original run/session/execution-scope/turn. The Classic/Manager chat panel distinguishes SSE health from explicitly refreshed REST data, rejects stale identity/epochs and never auto-retries an unknown POST. Display defaults/history are separate work.
- Cursor main native ACP is explicit auto-only until restrictive policy is verified; reject other modes before prompt-file/session preparation. Native final/partial are independent of Activity previews and use claim-before-lifecycle/passive-finalize. Keep collector liveness private and text-free, preserve explicit server execution binding even when multi-session is off, fence old live/lease/barrier cleanup, and never rerun lifecycle or inference after partial failure.
- Grok main native ACP is also literal-auto-only with existing auth and advertised model/effort. Cancel/replacement reuses one native session and logical final after original response/drain. Input commit requires local dispatch plus current run and canonical ownership; busy no-start may queue, fatal errors never retry. Restrictive policies/workers remain guarded before preparation.
- Cursor cancel-reprompt uses the provider-neutral replacement controller and exact local-dispatch commit barrier, not `steerTurnInBand`. Restore bounded original/accepted/partial context separately from active operational rules. Recheck captured main and canonical ownership before input recording; no-start may queue, fatal never retries. `/steer` recognizes the hook; `/queue steer` remains forced interrupt/new-run. Post-B anonymous packet provenance relies on ACP v1 ordering, not local epochs.
- Employee worker progress is query-first via `jaw worker status [agent]`, watchable via `jaw worker watch [agent]` or `jaw dispatch --watch`, memory-only for current plus previous completed run, and safe-summary only with thinking detail hidden.
- `jaw employee list [--json]` lists DB and static employees, including Control. `jaw dispatch` reads response bodies defensively and reports stale/missing server routes when an old manager returns HTML instead of JSON.
- `npm run build` is a pure backend build/link operation and must not signal, kill, or restart live manager processes.
- Release path is `feature → preview → main`, then a `workflow_dispatch`-only npm publish from `main`; `dev` is the contributor integration base and is never in the release path. `scripts/promote-to-main.sh` promotes only an already-certified `preview` head, produces a **new** `main` SHA carrying the same tree, dispatches `publish.yml` and then exits without checking the publish outcome, and cannot be re-run after a successful promotion (its `git merge-base --is-ancestor` guard fails). Partial-release and rollback recovery — re-dispatching `publish.yml`, backfilling a missing GitHub release, moving the npm `latest` dist-tag back, reverting a red `main` commit — is documented in `structure/infra.md` § 릴리스 파이프라인과 부분 실패 복구. Do not describe a `dev`-based release flow.
- Web/CLI `jaw dashboard serve` defaults to manager port `24576`; Electron implicit spawn owns the separate `24577-24590` manager lane and does not reuse `24576`.
- Sidecar packaging owns a locked source snapshot/staging transaction; smoke runs the target Node from an isolated artifact copy, not checkout dependencies. Keep compiled-asset/prune/native/no-JWC gates, exact candidate/seal identity, retained failure roots and report-before-cleanup ordering. Skipped/timeout is not verification and local fingerprints are not signatures; see `structure/infra.md`.
- Explicit `CLI_JAW_ISOLATED_QA_ROOT` selects fixed task homes/strict worker-manager-preview ports through `src/shared/isolated-qa.ts`. Validate/scrub before imports, apply Electron paths before lock/session, preserve captured policy and forbid global registration/installer, foreign scan/peer and Manager lifecycle actions in QA. Normal mode stays unchanged. Controlled launch is not an arbitrary-command sandbox or packaged/native certification; see `structure/infra.md`.
- The Electron Manager right sidebar uses an open-tab model (2026-07-04): module tab kinds `files | diff | browser | design`, multi-instance except the Diff singleton, launcher row + equal-width tab strip + `+` menu, per-tab resource state persisted in tab metadata (`RightSidebarOpenTab.files/browser/design`), only the ACTIVE tab body mounts (hidden Electron webviews composite over the window), CEO hidden.
- Design workspace v1: `jaw design <list|create|show|path|rescan|edit|export|files|snapshots|catalog>` is FILE-FIRST over `src/manager/design/store.ts` (`~/.cli-jaw-dashboard/design/projects/<project-key>/pages/<page-id>/`, `page.json` source of truth, revision 409s, keep-last-20 snapshots). Manager routes live at `/api/dashboard/design` (mutators require the Electron desktop header; preview is CSP-locked, `script-src 'none'`). The Design module tab's Run button enqueues a pageDir-scoped generation prompt into the currently selected instance.
- Embedded Browser agent surface (030, v1–v5): agent-visible Manager Browser pages are relayed into the SELECTED instance's runtime-context by default. Agent endpoints via a renderer-relayed command queue: `POST …/<targetId>/screenshot` (PNG temp-file path), `POST …/<targetId>/snapshot` (bounded accessibility tree), and `POST …/<targetId>/act` (click/type/scroll/key). `act` is available for agent-visible targets by default (`actionsEnabled` remains a compatibility flag) and still validates payload bounds + re-checks the current URL policy in main. Element inspect/actions use Electron CDP attachment with ONLY DOM/Overlay/Input/Accessibility domains (native element-box highlight via `Overlay.setInspectMode`); the Runtime domain / page-side script evaluation is never enabled. Page titles/urls are sanitized + JSON-delimited before entering agent context.
- `jaw browser fetch <url>` is the adaptive URL-reader mirror from agbrowse: use it for a known URL/search-result URL, not as generic search. For raw search intent, use `/search <query>` so the search skill can choose search, browser verification, and model-gated parallel research policy.
- Platform classification has one source of truth: `src/core/platform-kind.ts` (`windows-native | wsl | linux | darwin | other`). `process.platform` decides first, so a `win32` process can never be classified as WSL, and the WSL branch is reachable only from `linux`. **`WSLENV` is never a WSL signal** — Microsoft shares it with the Windows host, so testing it made `doctor` and `postinstall` misfire on native Windows. `browser-open.ts`, `browser-open-default.ts`, `browser/connection.ts`, and `bin/commands/doctor.ts` delegate to it; `bin/postinstall.ts` answers the separate launch-origin question with `isWindowsNodeLaunchedFromWsl` + `resolveInvocationCwd` (npm lifecycle scripts run from the package root, so `INIT_CWD` is the user's directory). `jaw doctor --json` exposes the result as `platform`. Do not add another hand-rolled WSL check.

## Build

Backend and frontend are separate builds. **Both must run after source changes.**

```bash
npm run build            # backend only (tsc → dist/)
npm run build:frontend   # frontend only (vite → public/dist/)
```

- `public/js/**/*.ts` changes require `npm run build:frontend` — the browser loads Vite-bundled output from `public/dist/`, not raw TS.
- Backend `src/**/*.ts` changes require `npm run build`.
- After editing frontend code, ALWAYS run `npm run build:frontend` before reporting the change is applied.

## Local Gates

Prefer the existing gates only:

```bash
npm run gate:all
npm test
bash structure/check-doc-drift.sh
```

Doc-only changes should not modify `.mjs`, `.js`, or `.ts` source files unless explicitly requested.

JWC integration is retired. Keep stored `jwc` choices inert and readable; execution
returns `retired_runtime:jwc` before fallback. Unrelated settings saves preserve
user data. TUI uses local presentation without generated Jawcode/Bun bundles;
package guards must reject retired payloads without cleaning user installations.

Claude E and AI-E are retired. Keep stored `claude-e` and `ai-e` choices inert
and readable; execution returns `retired_runtime:claude-e` or
`retired_runtime:ai-e` before fallback. Unrelated settings saves preserve user
data. Do not restore `native/claude-e`, `claude-exec`, or `@bitkyc08/ai-e`.

- Boss user prompts include host-local civil dates and Monday–Sunday ranges via `src/agent/calendar-context.ts`; the timestamp and calendar share one clock sample. Explicit user timezone/week conventions take precedence; system-prompt caching and worker/internal prompts stay unchanged.

- Optional pinned local services use `scripts/service-artifact.mjs` with an externally anchored manifest digest and an immutable package tree. Activation and registration remain explicit; keep the prior registration for rollback. See `docs/pinned-service-artifacts.md`.

Slack file CLI uses an explicit conversation and completion-only upload receipts (`sent: boolean|unknown`, no auto retry or caption fallback); cancellation preserves known/unknown delivery. Sync commands/API/Slack docs.

Slack `trustedBotTriggers` lets one named bot start a turn here: a fully validated rule plus a self-mention opens exactly the `bot_message` subtype, `allowBots` and `mention_via_app_mention` refusals, and nothing else. One malformed rule voids the whole list, and `isSlackMention` stays narrow because it also decides thread ownership. See `structure/infra.md` §`src/slack/`.

Optional `workflowSkill` selects the operator-configured execution route only after the actual sender/channel/bot-user/marker match and self-mention. Load only the selected enabled skill, bounded to 64 KiB; unverified sender/request context or unavailable or ambiguous skill selection is visibly blocked with no model fallback. Four-key rules keep legacy behavior. Empty or standalone `SILENT` workflow results require an unconfirmed notice and failure ACK, with no automatic rerun because effects may already exist. Preserve normal approval, tool grants and source permissions; an AI reply is not business-completion proof. See `docs/slack-tools.md`.

Opted-in workflow requests use the `followup` queue when busy; never steer or collect them into an unrelated running turn. Read the selected skill at admission and preserve its captured content, hash and source metadata across queueing and restart. Silent outcomes settle the workflow request as unconfirmed/failed while preserving provider/native final text and status; never automatically rerun.