structure

Imported from lidge-ai/cli-jaw (structure/AGENTS.md). Install upstream with npx skills add lidge-ai/cli-jaw --skill structure. Copyright stays with the author.

📚 INDEX · Sync Checklist · Commands · Server API · Stream Events · str_func

structure/ — Sync 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 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.

Electron Builder 26 copies sidecar node_modules through an explicit extraResources FileSet with the sidecar exclusions preserved; local default/signed macOS commands and every desktop release matrix leg must smoke the packaged server tree after packaging and before upload.

• 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 server_api.md.

• Slack group DMs use message.mpim, which requires mpim:history — without it group DMs do not arrive at all; existing IM/channel installs keep working and merely report the optional capability gap. Exact channel_type: mpim mentions retain channel allowlist and thread policy, never the one-to-one DM bypass. an absent scope header is unknown and a present empty header is a known empty grant. Keep telegram.md and the validation API docs synchronized.

• Native Code: synchronize runtime-integration.md, server_api.md, INDEX.md and root guides for src/code-mode/ and /api/code. Code uses separate per-backend storage and direct native adapters; preserve append/status replay, complete active snapshots, byte budgets, early resource registration and physical-exit proof. Interruption must seal callbacks before owner-checked accepted-buffer persistence; both hosts use src/routes/code-body-parser.ts for Code envelope/decoded limits. Compact replay has one carve-out: a Claude rollback deletes the removed items and their events, so replay from below its replay_floor_sequence answers invalid_sequence and a higher historyGeneration means a new snapshot. Private prompt boundaries never reach the wire, the fork is verified before one CAS commit, and the source native session is never changed.

• 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 server_api.md.

• Sidecar build/smoke: sync infra.md and root notes for transactional source/stage/lock ownership, runtime-candidate/seal matching, outside-checkout target-Node execution, preserved asset/prune/native/no-JWC gates and explicit retained evidence/cleanup. Ordinary import, live server readiness and final packaged native UI are separate proofs; no timeout or skipped green.

• Isolated desktop QA: src/shared/isolated-qa.ts owns opt-in role paths/strict ports/child env; Electron, dashboard CLI and Manager enforce the captured launch policy before their owned side effects. Keep the supervisor-before-import boundary, no global registration/installer or foreign scan/peer/lifecycle actions, normal-mode compatibility and lifetime-safe QA cleanup explicit in infra.md and root docs. Do not conflate mocked/compiled launch checks with final packaged native UI proof.

• Keep this folder aligned with the live cli-jaw tree; INDEX.md lists the public architecture docs and support tools.

• Private plans, audits, evidence, and history belong only in a separate sibling clone of cli-jaw-internal; request access through an issue. Never create private records inside this checkout, including devlog, _plan, _fin, or .jwc aliases at any depth, even when generic skill defaults suggest them. docs/ and structure/ are for public product documentation; omit private record paths from public docs and source. Agent harness state under the gitignored .codexclaw/ (sessions, goalplans, ledgers) is local tool state, not a record store: plans, audits and reviews never go there either.

• Update INDEX.md whenever a doc is added, removed, renamed, or re-scoped. Keep the doc map, tier list, and quick links in sync.

• Update str_func.md file-tree entries when files are added, removed or renamed in server.ts, src/routes/*, src/cli/handlers*.ts, src/cli/api-auth.ts, src/manager/* (multi-instance dashboard), bin/commands/*, bin/star-prompt.ts, tests/, public/, or generated-dist exclusions change. verify-counts.sh checks that every file-tree entry in str_func.md points at a real file (it records no line counts).

• stream-events.md is the SSE/WS/event-trace companion for frontend.md, server_api.md, and the ProcessBlock pipeline. Keep GET /api/events, replay behavior, and fallback WS current.

• When a command, API, UI, memory, or orchestration surface changes, sync the relevant doc(s) in this directory in the same change.

• Route refactors belong in INDEX.md, server_api.md, infra.md, and str_func.md. CLI handler splits and auth helper changes belong in commands.md, memory_architecture.md, telegram.md, and str_func.md.

• 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 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 frontend.md.

Current sync hotspots (2026-06)

• Recent non-strict hotspots: Workbench modernization uses a one-row Activity header with Codex-style expanded rows/groups; the Workbench Settings tab and the command-bar gear are both removed, leaving the sidebar rail as the only settings entry point; it renders manager scope only and Meta+, opens it. A unified settings registry separates Instance/Manager scopes and shares the standalone dist/settings entry with the Classic header-gear settings page; Classic uses the t3 token shell. Preserve per-page save owners, dirty guards, Preview iframe identity and independent live Requests; see frontend.md.

• Classic retained Activity: keep activity-history.ts (discovery disclosure removed 260908), the one-row activity-view.ts summary header, shared fixed-through reads, MESSAGE withSession=1 and exact saved-answer lookup in sync. TUI retains its discovery reader. Preserve stored scope, unrelated live progress, namespace/ID separation, bounded queue/eviction and80-row raw paging. Old metadata-free cache is not chat authority; fork answers never acquire original Trace access. See frontend/API/runtime docs.

• Classic live Activity: activity-state.ts/activity-replay.ts own bounded preview state; activity-view.ts owns disclosure, activity-live.ts uses injected host actions to avoid the legacy renderer SCC. Preserve original snapshot/request bridge ownership, shared bounded pre-admission event/gap queue, native-absent diagnostic separation, late canonical/public final reconciliation and captured-scope cache correction. Additive VS hooks must not replace existing lazy/post callbacks. Cold transcript history has a separate bounded reader owner; live remounting alone does not restore it. Keep frontend/stream/root notes aligned.

• presentation.mode defaults/activity and Legacy opt-in share src/shared/presentation.ts with the existing identity parser. Explicit known mode and/or eligible transport-only API patches preserve admitted ownership and captured completion buckets; mixed execution changes and external-file transport edits retain invalidation. Keep legacy presentation-subtree side-effect skips separate from this strict exception. Keep config/ingress/runtime-settings side-effect boundaries, Classic preference generation/bounded reads, Manager Display draft/instance guards and Classic, retained history, Manager and TUI ownership synchronized in frontend/API/runtime docs. No transport-default migration or messaging restart is implied.

• Print Activity observer/accepted parser hooks, exact-pointer terminal recovery and latest run-scoped tool merge are documented in runtime/stream/spawn/API docs. Preserve lifecycle-selected final, native terminal defaults, trace-failure containment and current channel sends. Snapshot known-omission is a conservative retained loss signal, never a sum of overlapping source counts or a claim of complete reconstruction.

• Interactive TUI Activity is now connected: Ctrl+O disclosure, read-only F6 journal/Enter and saved-answer/A views, snapshot-owned admission, exact MESSAGE over compatibility, missing-journal receipt binding and old-run cleanup isolation. Keep GET/queue bounds, original history scope, paste-drain lifetime, terminal sanitation/shared cell geometry and draft-safe late line output. Commit queue acceptance is not flush; release payload only after actual native commit. Raw/simple unchanged. Sync commands/frontend/stream/tui-scrollback/root notes; final integrated Electron QA remains separate.

• Durable Activity journal: synchronize trace owner columns/original-message backfill, six native/print admission headers, internal append/public replay separation, explicit-session raw drawer reads, immutable event/first-loss control and whole-prefix retention in runtime/API/stream/infra docs. Current finality and messaging contracts remain independent; no Activity display/default rollout is implied by journal availability.

When refreshing docs from recent non-strict commits, check these first:

• src/orchestrator/parser.ts / pipeline.ts: /continue is slash-only; do not document natural-language continue as resume.

• src/cli/commands.ts / src/cli/handlers/session-handlers.ts / src/core/chat-sessions.ts: slash registry currently includes 55 commands total / 54 non-hidden (only /file hidden), with /queue CLI-only and hidden from cmdline. Keep quoted-argument tokenizeArgs(), Levenshtein unknown-command recovery, /goalplan, /gd, /review, /search, /queue, /task, and /fork reflected in commands.md.

• src/prompt/templates/a1-system.md / src/prompt/templates/skills.md / skills_ref/jaw-search/SKILL.md / skills_ref/jaw-browser/SKILL.md: Korean/source-sensitive search defaults to native cli-jaw search with focused query rewrite + original-page verification; agbrowse research plan is optional planning help only. Private runtime skills such as k-writing (Korean promotional/content writing; retired label: k-thread-gen) and lecture-stt are active-skill deployments, not skills_ref public entries. Route Korean promotional/content writing through active k-writing, not free-form prose or the retired label.

• src/agent/lifecycle-handler.ts / src/trace/redact.ts: retry docs should mention exponential backoff attempt metadata and trace redaction should include AWS, Anthropic, JWT, and expanded secret key patterns.

• src/cli/commands.ts / src/cli/handlers-workflows.ts / src/cli/handlers-search.ts / src/command-contract/catalog.ts / src/workflows/*: workflow helper commands are /plan, /interview, /deliberate, /planaudit, /review, /search, and /goal; /plan is a PABCD P compatibility guide, not a second planning mode; /search is search-skill routing that discovers candidate URLs before browser commands; bounded automation belongs under /goal run ..., not a top-level /autopilot; keep /planaudit remote-safe and do not document /plan-audit as registered unless an interface-aware alias layer exists.

• src/agent/args.ts + src/agent/spawn.ts: Gemini full-access must keep auto-approval and pass OS home roots through --include-directories so cwd-external folders do not fail with Path not in workspace; WSL should include both Linux home and the Windows user home when discoverable.

• src/shared/tool-log-sanitize.ts: bounded tool-log storage/delivery protects Web UI and Manager ProcessBlock hydration.

• src/core/platform-kind.ts: canonical platform classification (windows-native | wsl | linux | darwin | other). process.platform decides first, so a win32 process is never wsl, and WSLENV must never be treated as a WSL signal — Microsoft shares it with the Windows host, which is what made doctor/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 asks the separate launch-origin question via isWindowsNodeLaunchedFromWsl + resolveInvocationCwd. src/lib/tui/terminal.ts is excluded on purpose (vendored, outside the root tsconfig). Do not add a new hand-rolled WSL check.

• 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.

• src/messaging/send.ts + src/routes/messaging.ts: /api/channel/send is canonical outbound channel delivery. Concurrent inbound gateway: messaging.enabledChannels (array) + messaging.homeChannel; legacy settings.channel is a deprecated read-only alias for one major version; restart only affects changed channels. Heartbeat destination send after resolveHeartbeatBinding may set in-process fullAccess; HTTP JSON cannot. Slack Socket reconnect defaults to unlimited (src/slack/socket.ts); a finite ceiling is caller opt-in and link_disabled stays terminal.

• Mid-run steer defaults to 'steer': Codex App uses in-band input; native Cursor uses original-cancelled-response/drain/idle followed by same-session cancel-reprompt. Its separate replaceTurn hook and local-dispatch commit barrier keep one logical final and never queue fatal failures. Preserve the remaining runtimes' existing kill/salvage behavior and explicit followup/collect queues; /queue steer remains a separate forced interrupt. Sync prompt_flow.md and commands.md.

• src/prompt/conversation-context.ts + src/agent/spawn.ts: Slack Boss turns get explicit channel_id and parent thread_ts in the per-turn user prompt regardless of multi-session state; keep this separate from the cache-stable system prompt and internal session labels.

• src/slack/mention-watch.ts + src/slack/mention-watch-match.ts + src/memory/heartbeat-mention-watch.ts + src/memory/heartbeat.ts + src/messaging/forwarder-origin.ts: Slack mention watching is an opt-in mentionWatch mode inside runHeartbeatJob, not a daemon. Optional userIds + conditions (mention|talk) keep the default as mention-of-userId; talk is opt-in and inbound mentionOnly stays a different gate. It uses bot-token conversations.history because search.messages is user-token-only, keeps per-channel frontier/resume state, rotates channels, stops a tick on 429, reports overflow beyond 60 channels, and re-intersects the configured non-empty channel subset with the live allowlist. Each hit yields to PABCD/agent/message-queue/pending-replay work; the agent returns answer text only, the server sends it to the source thread and records seen after success, and producer-owned heartbeat output bypasses channel forwarders. Delivery is at-least-once. The answer turn runs with the answered thread's own chatSessionId but in a dedicated mention-watch:<remoteKey> execution scope, never the thread's inbound scope: sharing it would make the background turn visible as busy to the next human message, which is then steered into it instead of starting its own run. That per-thread placement also replaces the global-only yield with getState(remoteKey) === 'IDLE' + hasChatSessionWork(chatSessionId) + a non-blocking sessionLanes.hasPending check, and the session is minted only once a hit is actually being answered because a remote-bound session row cannot be deleted afterwards.

• src/memory/mention-watch-ledger.ts + src/memory/legacy-mention-watch-quarantine.ts + src/slack/verified-workspace.ts: 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.

• src/core/config.ts + src/routes/settings.ts + bin/commands/init.ts / slack.ts + Slack Settings UIs: configured SLACK_* variables own their matching fields at runtime. API snapshots expose variable names only; Settings/reset and CLI setup stay conservatively locked while any are present, generic mutation rejects only env-owned paths, and persistence strips only those paths so effective env values never enter settings.json or delete unrelated file-backed credentials.

• src/core/event-bus.ts + src/routes/events.ts + public/js/event-channel.ts: Web event delivery is SSE-first through GET /api/events with WebSocket fallback for legacy servers.

• Pi capability/cleanup: one per-instance async version observation gates actual prompt writes, feeds both live pool getters and preserves typed finality. Direct child cancellation and RPC exit start the same paired owner; persistent failure claims before drain. Pi-only temporary-directory allocation/identity plus the immutable physical receipt controls deletion, not mutable settings. Keep explicit unknown-close retention and resolver/opaque-wrapper/shutdown limits synchronized in runtime-integration.md and root notes; no new process registry or numeric tree signalling.

• src/agent/runtime/requests.ts + acp/callbacks.ts + src/routes/runtime-requests.ts: exact-session native decision GET/POST, opaque handles, canonical pre-insertion sanitization/32KiB event budget,128-entry/120s registry and32-callback limits. Preserve currentness/cancellation; retire an unflushed ACP selected write on cancel. Route-owned notices map captured chat to presentation delivery scope without changing execution IDs or messaging. public/js/features/native-request-bridge.ts and native-requests.ts own the live response panel, SSE health/epoch and manual freshness. Instance auth is not a tenant ACL. Keep runtime/server API and root docs synchronized; Activity layout/default/history remain independent.

• src/shared/runtime-contract.ts + src/agent/runtime/*: canonical Codex/Pi projection bypasses internal messaging listeners; explicit native outcome is optional and preserves null/empty finality and partial MESSAGE salvage. Keep terminal finality/status/optional stopCause/trace correlation aligned across lifecycle, pipeline/collector and web/TUI. Native formatter-empty guards must not alter untagged delivery/ACK/queue behavior. Sync runtime-integration.md and stream-events.md before adapter activation.

• Pi private diagnostics retain bounded resolved stderr and redacted caught errors under captured-turn ownership; they do not expand public outcomes or annotate stopped turns. Captured internal kill reasons must not become user Stop through legacy flags.

• src/agent/runtime/selection.ts: Cursor/Grok/Claude native/print selection, independent main/worker implementation flags and isolated native-v1 buckets. Keep boot/init/watch validation, captured spawn/lifecycle identity, exact reset/compact semantics and additive CLI-status diagnostics synchronized in runtime-integration.md. Existing absence or print migrates to native once per migration id (nativeTransportMigration v2 re-runs over v1 stamps) where permissions let native run; print chosen after the v2 stamp is operator intent, not a fresh-default opt-in. Codex App/Pi retain legacy keys.

• Claude integration uses claude-runtime-pool.ts, the type-only runtime-pool-contract.ts, claude-runtime-run.ts and the existing shared host/lifecycle. Keep logical settlement separate from captured main/worker physical cleanup; rejected unleased cleanup retains its control and only workers own instruction-directory removal. All three main-steer callers use main-only waits while scoped/global shutdown stays inclusive, with the existing exit-settle/salvage barrier. Document deferred claim/finalization and hard Stop separately from supported worker/approval/image/foreground-child paths. No-start fallback precedes compatibility completion; conditional trace finalization preserves completed headers. Sync runtime-integration/prompt_flow and root notes.

• Native Cursor main uses runtime/acp/runtime-session.ts plus native-runtime-run.ts; explicit auto only, no worker activation. Early guard precedes all preparation, private I/O liveness never carries text to messaging, and explicit execution bindings survive the global multi-session toggle. Claims/finalizers, live trace ownership, retirement fences and exact exit-settler cleanup are separate from provider wire completion.

• Native Grok main reuses the same host/facade/pool with an optional provider-neutral replacement strategy. acp/replacement-turn.ts owns one logical result across cancelled attempts and a synchronous input-commit barrier; runtime/replace-turn.ts maps typed receipts. Literal auto only; restrictive/worker activation remains blocked before preparation. grok-session.ts owns existing auth/model setup and grok-events.ts maps only observed result usage.

• runtime/acp/replacement*.ts owns private prompt-attempt epochs and one logical result; runtime/replace-turn.ts maps local-dispatch/no-start/fatal receipts. Cursor's captured prompt closure restores bounded original/accepted/partial context and active rules. Main object and canonical generation must still match at input commit; trace/log observer failure must not cause inference retry. Anonymous same-session frames after B admission depend on provider ordering and cannot be identified by a local epoch alone.

• src/browser/runtime-*, src/browser/tab-lifecycle.ts, src/browser/web-ai/session*.ts: browser docs should mention runtime diagnostics, orphan cleanup, tab lifecycle, and web-ai session reattach.

• src/browser/adaptive-fetch/*, src/routes/browser.ts, bin/commands/browser.ts: browser docs should keep browser fetch <url> scoped as an adaptive URL/search-result reader, not generic search, with browser escalation and third-party reader opt-in boundaries explicit.

• src/routes/traces.ts / src/trace/*: server docs should include public trace read routes and related WebSocket/event surfaces such as alert_escalation.

• src/notes/search.ts / src/manager/notes/routes.ts / public/manager/src/notes/NotesSearchSidebar.tsx: Manager notes docs should include ripgrep-backed search, /api/dashboard/notes/search, typed errors, abortable sidebar search, and search CSS.

• src/manager/reminders/* / public/manager/src/dashboard-reminders/*: Manager docs should include dashboard reminders API, notification scheduler, matrix buckets, top-priority strip, detail popover, and drag/drop bucket moves.

• src/orchestrator/pipeline.ts / src/orchestrator/state-machine.ts / skills_ref/dev*/SKILL.md: PABCD docs should keep the Project root: <absolute path> dispatch contract and strict TypeScript + existing source-of-truth discovery guidance aligned. Repository-specific private record boundaries override generic planning locations.

• src/orchestrator/worker-registry.ts / src/routes/orchestrate.ts / bin/commands/dispatch.ts / bin/commands/worker.ts: worker progress query/watch is memory-only, keyed by stable employee agentId plus per-dispatch runId for recent history, safe-summary only, and must not expose employee thinking detail. Human dispatch follows safe progress by default; --quiet and --json must remain quiet.

• src/agent/agy-capabilities.ts + src/agent/args.ts + src/agent/spawn.ts + src/agent/spawn-env.ts + src/cli/registry.ts + src/cli/readiness.ts: AGY is a top-level agy runtime. It uses agy -p print mode with capability-probed optional flags (--model observed in AGY 1.0.12; probe failure logs and falls back to legacy emit-all compatibility), exact resume via --conversation <sessionId>, plain-text stdout, NO_COLOR=1, run-time auth checking. No per-run --effort flag. Native AGY context-file ingestion is separate from cli-jaw wrapper contracts such as injected operational context, transcript anchoring, quota UI, and post-compaction retention.

• src/cli/cli-status.ts + src/cli/cli-status-worker.ts + src/cli/readiness.ts: clean installs prefer capability/auth-ready Codex App, while existing settings use the authenticated accept/keep migration route. Status requests return nullable checking/stale snapshots immediately; raw detection, auth, and capability probes run in a bounded child. src/cli/opencodex-runtime.ts and src/core/codex-config.ts provide read-only config/live-health diagnostics and never write the Codex endpoint.

• src/routes/quota.ts: Grok quota reads ~/.grok/auth.json OIDC credentials and prefers JSON weekly credits before bounded Grok Build gRPC-web and legacy monthly billing fallbacks.

• src/agent/cursor-runtime.ts + src/agent/events/cursor.ts + src/agent/args.ts + src/cli/registry.ts + src/cli/readiness.ts: Cursor is a top-level cursor runtime. It uses cursor-agent -p --trust --output-format stream-json, exact resume via --resume <chatId>, model ids resolved from model+effort before spawn, auth via CURSOR_API_KEY or cursor-agent status, and native quota from its selected credential store with explicit dashboard-cookie fallback.

• src/manager/telegram-hub/* / src/manager/routes/telegram-hub.ts / src/telegram/hub-callback.ts / src/messaging/thread-target.ts: Telegram Hub P0–P4 — sync telegram.md + server_api.md Manager surface (per-topic model/systemPrompt overrides).

• public/js/features/process-block.ts: hydrated expand (reconstructStepsFromBlock), data-had-detail release placeholder — frontend.md + stream-events.md §12.

• src/goal/pause-gate.ts / src/agent/lifecycle-handler.ts: goal_pause_gate_pending continuation suppression — stream-events.md, INDEX.md delta.

• src/agent/events/claude.ts: plain claude text_delta live streaming — stream-events.md §3.

• tests/run.mts / package.json test scripts: programmatic test driver (--scope/--shard i/N/--list, per-file test home) — infra.md scripts table; CI job graph, aggregate truth table and quarantine list — infra.md § CI job graph.

• scripts/release-preview.sh / scripts/promote-to-main.sh / .github/workflows/publish.yml: release path is feature → preview → main then a workflow_dispatch-only npm publish; dev is never in the release path. Promotion requires an already-certified preview SHA, the promoted main commit is a new SHA with the same tree, and the promote script exits without checking the publish outcome and cannot be re-run afterwards. Keep the flow, the publish.yml input names, and the partial-release recovery steps in infra.md § 릴리스 파이프라인과 부분 실패 복구 aligned with the actual scripts, and mirror the precondition in root README.md.

• bin/commands/service.ts / src/core/instance-lifecycle.ts: home-scoped service stop|restart, ownership pidfile, and native-service delegation — commands.md, root README/AGENTS/CLAUDE.

• src/orchestrator/attestation.ts: PABCD --attest evidence gate — prompt_flow.md, INDEX.md.

• src/cli/handlers-skill-invoke.ts: dynamic /skill:<id> — commands.md, INDEX.md.

• src/browser/adaptive-fetch/scheduler.ts / src/browser/web-ai/session-artifacts.ts: adaptive-fetch P0 + web-ai parity wave — infra.md, str_func.md entries.

• Keep root AGENTS.md, CLAUDE.md, README.md, and public docs/dev/ pages aligned with this folder when the architecture map changes.

• 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.

Retirement changes must synchronize the saved-selection diagnostic and executable key split in runtime-integration.md, CLI tombstone behavior in commands.md, and local TUI/package absence contracts in infra.md. Preserve stored user data.

Quota reader contract

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.

• 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 progress uses a one-second native heartbeat under a shared append budget, delta-only cards and dispatch-time snapshots. Known file tools expose only validated project-relative filenames or outside basenames under captured workingDir; preserve request identity, final/ACK ownership and raw-content exclusion. See telegram.md.

• Slack semantic activity uses progress-detail.ts and progress-files.ts: explicit Cursor shell tool purposes, finite literal command summaries and validated targets, never raw script bodies or credential arguments. Description-only same-ID updates do not reset accepted Cursor answer text; sparse terminal details retain the same observed purpose. See telegram.md and stream-events.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.

Root contract notes (moved from AGENTS.md, 2026-09-25)

Architecture Docs Sync

• 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.

• 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.

• 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 Socket Mode app-token ownership is coordinated across homes by a connected, fresh, live-PID claim; uncertainty fails open, conflicts disable inbound only, and the runtime notice/activation epoch must remain generation-bound. A long-running server keeps retrying Socket reconnects until Slack answers (finite maxReconnectAttempts is caller opt-in; link_disabled stays terminal). A bound heartbeat destination send uses fullAccess after resolveHeartbeatBinding and never last-active retarget; /api/channel/send does not accept fullAccess from JSON. See structure/telegram.md and structure/server_api.md.

• 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.

• 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.

• Sidecar builds use exclusive owned staging/source snapshots and retained failure evidence; preserve the existing compiled-asset/prune/native/no-JWC gates. Smoke executes a byte-matched copy outside checkout dependency ancestors with the target Node, strict process/IPC/listener/HTTP/close checks and evidence before cleanup. Never equate timeout/skipped with pass, relabel retained roots as deleted, adopt unknown output, or force-remove locks. Input relative contained symlinks are preserved verbatim; output fingerprinting is local provenance, not a signature. Final builder-filtered native UI remains separate. See structure/infra.md.

• Isolated desktop QA is explicit via CLI_JAW_ISOLATED_QA_ROOT; src/shared/isolated-qa.ts owns fixed role homes, strict W/M/P ports and fresh child environment. The supervisor validates before imports; Electron applies paths before lock/session and suppresses global registration/installer actions. QA Manager rejects foreign scans/peers and lifecycle actions before side effects; ordinary mode is unchanged. Preserve captured policy and lifetime-safe QA cleanup. This is controlled launch containment, not an arbitrary-command sandbox or packaged/native QA certification. Sync structure/infra.md, README and root/structure notes.

• Native event foundation: src/shared/runtime-contract.ts + src/agent/runtime/* own canonical Codex/Pi projections and optional explicit outcomes. agent_runtime/agent_runtime_gap publish directly to SSE, bypassing messaging listeners. Native compatibility terminals carry finality/status, optional stopCause on stopped orchestrate_done, and existing trace identity; no public partial/outcome object. Preserve legacy final selection when outcome is absent, and interrupted MESSAGE salvage before exit settlement. See structure/runtime-integration.md and structure/stream-events.md; Classic live Activity and its default preference are implemented separately from this event foundation; Classic history has its own bounded restoration owner; Interactive TUI has its own scoped consumer described in root AGENTS.md (Interactive TUI Activity).

• Runtime selection: only Cursor/Grok/Claude accept perCli.<cli>.transport; existing homes migrate absent/print to native once per migration id (nativeTransportMigration v2, re-run over v1 stamps; permission-blocked engines are skipped and retried only from a v2 partial) and print chosen after the v2 stamp is operator intent. Native switchable keys prefix the whole legacy bucket with native-v1: and never overwrite the print singleton. Capture transport/bucket once, forward through lifecycle persistence/compact, and keep scoped resets exact. Unsupported main/worker native adapters fail before print/fallback work; compiled support in /api/cli-status is separate from cached auth/binary readiness. Codex App/Pi keys remain unchanged.

• Claude native: the optional SDK, shared pool/host and existing lifecycle own sequential main turns, fresh worker assignments, immutable terminal claims, hard Stop and interrupted MESSAGE before exit-settle. Default jaw steer remains kill/resume, never advertised as in-band; the one exception is Code-only: an /api/code Claude session (inBandSteer, set by src/code-mode/providers/claude.ts alone) accepts one in-band follow-up per streaming turn, settled on the result that consumes it (runtime-integration.md#native-code-sessions). Auto (YOLO) / Safe decisions use live requests; deny/unknown profiles fail before preparation, including the memory extractor. Images are bounded and child activity is foreground-only. Child declarations reconcile from both parent/child frames; their ID ownership survives child completion and is not the same as live permission eligibility. Pre-start failure/Stop use one cached fallback before compatibility output; onlyIfRunning preserves finished trace headers. Background tasks are unavailable: the pool seeds CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 when the caller left it unset, because the PreToolUse hook refuses only an explicit run_in_background:true while Claude backgrounds a long foreground Bash command on its own, which ended the turn. A mid-turn session failure now fills ctx.runtimeDiagnostic from facade.lastError, and lifecycle prefers that sentence over the stderr classification so a failed turn with no text reports a cause instead of tg.noResponse.

• Cursor native main: explicit native/auto only; restrictive permissions and unsupported workers fail before regenerateB, bucket/bootstrap/snapshot, detection or pool work. AcpRuntimeSession keeps raw final/partial independent of bounded Activity and claims an immutable logical result before lifecycle; passive finalization survives main-map removal. Native run cleanup holds the exact lease through application settlement and uses captured exit-barrier identity. Server-explicit scope/chat bindings survive multi-session off; private identity-only I/O liveness keeps the owning collector alive without messaging content. Preserve legacy/manual compact while excluding print-era automatic compact/count heuristics from explicit native outcomes.

• structure/ is the current public architecture-doc hub.

• Keep README.md, root AGENTS.md, root CLAUDE.md, and structure/AGENTS.md synchronized when command/API/orchestration surfaces change.

• Recent non-strict hotspots: explicit /continue, workflow helper slash commands (/plan as PABCD P compatibility guide, /interview, /deliberate, /planaudit, /review, /search, /goal, /goalplan, /team, /task, /fork, /gd; forward PABCD transitions require cli-jaw orchestrate <phase> --attest '{"from","to","did",...}'), pre-prompt context hooks (context-hooks.json, cli-jaw hooks), bounded local search contract (narrow-path Grep/rg; external search via active search skill), Telegram Hub P0–P4 (structure/telegram.md, /api/dashboard/telegram-hub), goal pause gate continuation suppression (goal_pause_gate_pending), tests/run.mts programmatic test driver, /goal plan and /goalplan store user direction as planHint and require /goal refine before checkpoints; agent pause first-tap state is exposed as derived pauseGate on status/API surfaces while persisted status remains active; bounded automation is /goal run ..., not top-level /autopilot), Codex App clean-install default with opt-in migration for existing settings, bounded child-backed nullable CLI status, read-only OpenCodex root-URL/live-health diagnostics, Pi top-level pi --mode rpc runtime with isolated PI_CODING_AGENT_DIR profiles, AGY -p print-mode runtime with capability-probed optional --model (observed in AGY 1.0.12), Grok weekly quota via native credentials and JSON credits, then bounded Grok Build gRPC-web and legacy monthly fallbacks, SSE-first GET /api/events event channel with WebSocket fallback, bounded tool-log sanitizer, worker progress query/watch, canonical /api/channel/send, heartbeat every/cron schedules, heartbeat Slack mention watch inside runHeartbeatJob (mentionWatch, optional userIds/conditions for mention|talk while default remains mention-of-userId and inbound mentionOnly stays separate, bot-token conversations.history scan instead of user-token-only search.messages, frontier/resume/round-robin/429 stop/60-channel cap, per-item busy yield, server-owned thread send then seen receipt, at-least-once delivery; the ledger is keyed by (jobId, workspaceId, userId) with the workspace id taken from a per-token auth.test rather than settings.slack.teamId, pre-v2 rows hold a job in a durable SQLite quarantine cleared only by POST /api/heartbeat/:jobId/mention-watch-fresh-start with a new since, and a duplicate job id in one PUT is a 400; the answer turn carries the answered thread's chatSessionId but runs in a dedicated mention-watch:<remoteKey> scope so inbound Slack cannot steer it, with a per-conversation guard of getState(remoteKey) === 'IDLE' + hasChatSessionWork + non-blocking sessionLanes.hasPending, and the thread session is minted only on admission) , browser runtime diagnostics/session lifecycle, Electron Node sidecar packaging, private active k-writing routing for Korean promotional/content writing, inbound ACK reactions and queue-notice lifecycle owned by src/messaging/ack-reaction.ts + src/messaging/queue-notice.ts (channels supply transport factories only; the notice is deleted only AFTER a successful answer and rewritten on timeout/shutdown; QueueNoticeRegistry.drain bounds shutdown and actually aborts; ACK settles immediately after successful text delivery and BEFORE the optional image relay, because uploads are uncancellable and would otherwise strand the reaction on running after the answer is already visible), canonical platform classification via src/core/platform-kind.ts (windows-native|wsl|linux|darwin|other; process.platform decides first and WSLENV is never a WSL signal), and npm run gate:all. 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.

• 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.

• Slack connection environment variables own their matching fields at runtime. Settings exposes only variable names and conservatively locks connection editing/reset while any are present; CLI setup refuses mixed input. Generic settings writes reject only env-owned paths, and persistence strips only those fields so env values never enter settings.json or erase unrelated file-backed credentials.

• 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.

• File sends across Slack, Telegram and Discord share one confirmation vocabulary. A send the vendor will not name is refused, not reported as delivered: Slack keeps its files[] echo requirement, Telegram requires a message_id greater than zero, and Discord requires a readable Create Message body. Those cases are ok:false with confirmation: 'unconfirmed', replacing the older ok:true, ambiguous:true that no consumer read. Callers that forward a file result must preserve confirmation; dropping it makes a caption post twice. See structure/infra.md and structure/telegram.md.

• 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-triggered Boss turns receive channel_id and parent thread_ts in the per-turn user prompt regardless of multi-session state; agents must use that explicit context for Slack lookup/send APIs instead of parsing session labels.

• 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.

• structure/ reading map: start at structure/INDEX.md; depth — telegram.md (Hub), prompt_flow.md (attest/hooks/bounded search), stream-events.md (pause gate/SSE), infra.md (test scripts), commands.md + server_api.md (slash/API surfaces). Concurrent inbound gateway docs: structure/INDEX.md §gateway, structure/infra.md §src/messaging/, structure/telegram.md §common messaging layer; legacy settings.channel is a deprecated read-only alias for one major version.

• Grok main native ACP requires literal auto, existing advertised authentication/model/effort, and no leader. Its optional common replacement strategy waits for original cancellation and drain, preserves one logical final, commits input only after local dispatch with current ownership, and never queues fatal failures. Restrictive policies and workers fail before preparation. Sync structure/runtime-integration.md.