# CLI See the packaged [complete command tree and invocation rules](cli-tree.md) for command ownership, read/write boundaries, and recommended sequences. The installed command is `aw`. Dynamic skill and step guidance returns compact `command_specs[]` rendered in-process from the compiled Clap tree; task workflows should trust those entries and use at most one exact-leaf `--help` fallback when a needed spec is absent or rejected, never broad or parent help. Manual users may still run an exact `aw --help` display command. In a source checkout, use `node bin/aw-debug.js` for current-source evidence. ## Project setup - Project-context commands require an initialized `.aw` directly under the current directory; they never search ancestors. Context-free commands remain available outside a project, and a legitimate local `.aw` worktree symlink retains its canonical owner. - `aw init "summary"` initializes or reconciles only the current directory and its own managed `AGENTS.md` binding. `--root` selects a local artifact path; `--project` is rejected. `--kind project` (the default) creates an ordinary root; `--kind workspace` creates a container root that owns member projects through its registry. An explicit `--kind` against an already-initialized root is refused rather than ignored. - New root IDs default to the normalized directory name: lowercase ASCII kebab-case, at most 32 characters, with `root` fallback and no hash suffix. Use `aw init --id ` at first initialization to choose a distinct ID when names would collide in a workspace. Reinitialization preserves existing IDs, including historical suffixes; an equal explicit ID is allowed, but a different ID fails before writes. - `aw convert --kind ` changes the recorded kind of an initialized artifact root, leaving its identity, repositories, and profiles untouched. Converting a workspace back to a project requires an empty member registry, and a root already registered as a member of a workspace cannot change kind. - `aw --project ` selects a registered member downward from the current workspace root, except for `init`. A member cannot route through its parent workspace. Without the selector, commands use the current directory's own artifact root. The selector redirects artifact root discovery only; explicit path arguments such as `--input-file` still resolve against the real working directory. - `aw project list|status|check` describes the member registry of a workspace root. `list` reports the recorded entries and touches no member root, `status` reports how each entry currently resolves, and `check` reports one typed finding per faulted entry, addressed as `::`, and exits non-zero when the registry is not healthy. All three describe every entry rather than stopping at the first fault, and none of them descends into a member root: an ordinary `aw check` stays scoped to the artifact root it is bound to. - `aw project add [--id ]` registers an already-initialized project root as a member, taking the entry id from that root's own recorded id. `aw project remove ` drops the entry. Both edit only the parent registry: the member directory, its `.aw` artifacts, its config, and any Git worktree are never created, moved, or deleted, so a removed member remains a usable standalone root. The recorded root is workspace-relative and uses `/` separators on every platform; legacy Windows separators remain readable. A literal `\` within a member path component name is rejected before the registry is written, with a hint to rename the file or directory. - A workspace root hosts one shared generated skill bundle for every project it registers. Which root holds the bundle is resolved at read time from the registry, so a member needs no bundle of its own and both `aw check` and the workflow mutation gate read the workspace bundle instead. Sharing changes where the bundle lives, not whether it is current: a stale or missing workspace bundle still refuses mutation inside every member. - `aw install` run inside a registered member installs no skill target. It writes only that member's `AGENTS.md` artifact-root binding and reports the workspace root that hosts the shared bundle. - A detached member keeps its artifacts and its binding and becomes a standalone project after one `aw install` in its own root; nothing else has to be restored. - `aw project summary` reports one row per registry entry with that member's own health counts, task counts by lifecycle, and roadmap item counts by status. The counts are read at call time from each member's own store and nothing is cached or written anywhere; an entry that does not resolve, or whose store cannot be read, reports its state with the counts absent rather than as zero. - `aw project service status|start|stop|restart` runs one lifecycle action across every registered member by invoking that member's own agent-server and index-server paths, so each keeps its own service state and process ownership and there is no shared supervisor. `--service agent-server|index-server` narrows the fan-out to one. A member that fails records its error and the walk continues; a faulted registry entry is skipped rather than turned into an error. - To supervise a single member, use the ordinary selector: `aw --project agent-server ` or `aw --project index-server `. `aw project service` exists for the all-members case only. - `aw install --target agents` installs project skills in `.agents/skills/`. - `aw install --target claude-code` installs Claude Code skills. - `aw install --target codex` installs the Codex integration target. - `aw check [task-id]` validates workflow structure. With no task id it runs the complete project-wide structural report. With an explicit task id it uses fixed lifecycle probes and validates only that task's durable directory, registered artifacts, and local consistency rules. `aw repair`, dashboard health, and TUI health remain project-wide. - Full checks use bounded parallel reads for independent inventory subtrees and task validation, followed by ordered cross-artifact checks and deterministic report sorting. `aw check --jobs 1` selects serial validation; `--jobs 2..16` sets the maximum parallelism, limited by available CPU parallelism, with a default maximum of 4. Pools never nest during recursive scanning. These controls do not change check scope or provide a filesystem snapshot. - Inventory still reads and validates every registered file. Within one check, later rules reuse the first successful reads of `task-status.json`, `task-config.json`, `plan.json`, and `execution.json`, up to 32 MiB of retained text; overflow falls back to ordinary reads. Runtime records and failed reads are not cached, and each check, including post-repair revalidation, starts with an empty cache. Retirement checks also reuse successful Git worktree-list queries per repository within that invocation; failed queries may be retried by later bindings. Mutation paths continue querying fresh Git state. These are bounded read reuse rules, not an atomic cross-file snapshot or a persistent cache. - `aw check --progress --json` writes phase transitions and throttled completed-work counts to stderr while stdout retains the final JSON envelope. Unknown totals remain unknown; progress is not a heartbeat. `--progress` and `--jobs` apply only to full checks, not `check `. Supervise long full checks in a retained background session without a fixed total deadline or silence-triggered termination; collect the exit status and final report, and investigate stalled progress before deciding to cancel rather than launching duplicate checks. ## Tasks and artifacts - `aw create --agent-runtime "intention"` creates a task record for lower-level automation. The caller obtains this exact runtime from its own Agent environment; creation rejects missing, malformed, guessed, or placeholder values. - `aw status --json` returns only `scope: "project"`, `todo_count`, `active_count`, `archive_count`, and `canceled_count`. It counts lifecycle directories without reading task artifacts or querying Git. Human output reports the same four counts. - `aw task list [--lifecycle todo|active|archive|canceled] --json` returns `tasks[]` containing only `id` and `lifecycle`, in lifecycle/id order. It lists `todo` and `active` by default; an explicit lifecycle selects only that group. It reads directory identities without task artifacts, Git queries, or a skill-install mutation gate. - This replaces the former project `status` task array: consumers needing identities must use `task list`, then request only necessary details with `aw status --json`. Task-level status retains `scope: "task"` and its normalized `task`, including worktree evidence. - `aw next [task-id]` reports the next recorded action. Its no-id form still builds the complete inventory for task selection; it is not a counts query. - Explicit task-id status and next forms use bounded probes of the fixed lifecycle paths and read only that task's direct artifacts. - `aw render --for ` renders task routing facts plus only the registered input artifacts for that step. It does not append unrelated Plan, Execute, action-log, verification, or task-status bodies. - `aw step enter ` is the replay-safe routine entry surface. It composes standalone step start, post-start render, and task-scoped guidance into one typed result containing `start`, `render`, `guidance`, and one non-duplicated `command_specs[]` array. Re-entering the same running step performs no start write. A later render or guidance failure retains the successful start and reports `failed_component` plus partial-result evidence so the same command can be retried safely. - `aw contract list|show|validate` exposes the current compiled artifact registry read-only. `list` returns every stable template id plus an aggregate SHA-256 fingerprint, `show ` returns its ownership, write command, shape, example, and fingerprint, and `validate --input ` or `--input-file ` validates caller content without persistence. JSONL failures retain physical line-aware paths. - `aw read` returns a complete registered task artifact. `aw write --input ''` or `--input-file ` is the full-document creation and strict repair boundary and is not the normal workflow path. For task JSON, AW validates the latest strict template, uses the registered task-session Agent runtime, overwrites `workflow_runtime` with the executing AW version, and persists atomically. The repair writer can locate one uniquely placed task without first parsing an invalid `task-status.json`. - Successful mutators return compact authoritative receipts for their exact target. Use explicit read commands for full state or when a receipt omits a fact needed for the next decision; do not reread only to confirm fields already returned by the mutator. - Normal structured artifacts use semantic commands instead of whole JSON payloads: - `aw artifact analysis init|file-set|function-set|question-add` - `aw artifact plan init|step-set`; Plan init accepts repeatable `--accepted-limit ` values - `aw artifact execution init|summary-set|step-set|deviation-add` - `aw artifact action-log add` - `aw artifact verify init|check-add`; Verify init accepts repeatable `--open-risk ` values - `aw artifact consolidate init|candidate-add|doc-add` - `aw artifact commit set` - Registered Markdown uses `aw artifact section read|set|append|replace|clear`. Heading lookup is exact, required-heading constrained, duplicate-sensitive, and ignores headings inside fenced code blocks. `aw artifact text set|append|replace` provides exact whole-text or chunk operations; replacement rejects zero or multiple matches. - `aw summary append` accepts repeatable `--item ` values. `aw step done` accepts repeatable `--summary-item ` values for distinct close-out evidence. - Roadmap phase/item add and update commands accept typed scalar and repeatable flags. Blueprint feedback uses `propose-blueprint` or `propose-roadmap`; knowledge add accepts exactly one opaque source through `--input` or `--input-file `. - Narrow roadmap item and phase mutations return the changed entity rather than the complete composed roadmap. `aw roadmap read` remains the full-roadmap retrieval surface. - `aw step todo add|update|remove ...` mutates one running-step DAG node with typed fields. Rows have a unique bounded `id`, bounded `title`, required bounded `abstract`, explicit `depends_on[]`, and `todo|doing|done` status. Add or replace edges with repeatable `--depends-on ` and clear them with `--clear-depends-on`. Missing references, self-edges, duplicate edges, cycles, and active nodes with incomplete predecessors are rejected. Multiple dependency-ready rows may be `doing`. Receipts and `step.todos_set` events include normalized rows, `doing_ids`, `ready_ids`, completed, and total. `aw step todo replace ... --input ''` or `--input-file ` is reserved for complete-list repair. A tracked step requires a non-empty all-done graph before completion. - `aw artifact execution step-set` writes explicit `depends_on[]`. Plan-backed rows must leave it empty because they inherit Plan edges; execution-only rows may repeat `--depends-on ` over the merged Plan and execution-only graph. Running, completed, or skipped rows are rejected until every predecessor is completed or skipped. - `aw step done verify`, `aw step done commit`, and `aw task move archive` require Verify `status=passed`, `open_risks=[]`, and every `checks[].result=passed`. `partial`, `failed`, and `blocked` artifacts remain evidence for repair routing but cannot close Verify. - `aw task config --agent-runtime ` registers the current semantic-author runtime. Runtime-only refresh remains allowed after execution settings freeze and cannot change worktree, retry, or reverse-feedback fields. - `aw task move|cancel|reactivate|rollback` owns lifecycle mutations. - `aw task migrate-worktree --reason [--worktree-dir ] [--acknowledge-head-only]` converts one already-frozen worktree-disabled task into a worktree-enabled task and creates its isolated checkout in the same invocation. See [Task worktree migration](#task-worktree-migration). - `aw task retire-worktree --reason --confirm` safely removes an archived task's recorded worktrees and branches. See [Archived task worktree retirement](#archived-task-worktree-retirement). For normal agent-driven work, prefer `$aw-task` and `$aw-resume`; the skills add roadmap association, step protocols, gates, and closure behavior around these CLI primitives. ## Workflow cost baseline Representative repository measurements for this minimization pass: | Surface | Before | After | Change | |---|---:|---:|---:| | Narrow roadmap mutation JSON | 227,397 B | 1,118 B | -99.5% | | Task-scoped Execute guidance JSON | 22,913 B | 13,990 B | -38.9% | | Execute render | 29,992 B | 20,488 B | -31.7% | | Commit render after step scoping | n/a | 1,409 B | current size | | Strict-schema JSON, current-only sample | 5,515,104 B | 4,695,013 B | -14.9% | | Concise prose simulation, 240/160 targets | 5,515,104 B | 4,199,266 B | -23.9% | | Concise prose simulation, 160/120 targets | 5,515,104 B | 3,849,786 B | -30.2% | | Minimal tracked-step mutation path | 9 AW calls | 6 AW calls | -33.3% | The current-only sample keeps independently meaningful fields required, writes explicit empty arrays, requires `abstract` within 256 display columns, replaces per-action runtime duplication with one required file-root `schema_version`/Agent/AW provenance set, removes Plan `notes[]`, and uses compact JSON serialization for comparison. The prose rows are historical simulations, not hard limits: one shared prompt rule asks for the shortest complete fact uniquely owned by each field, while exact commands, paths, identifiers, and errors remain unchanged. The command-count row covers start, one todo seed/completion cycle, artifact mutation, close-out, and next routing; health, render, and guidance entry calls are unchanged. Successful mutation receipts remove immediate confirmation rereads. Step completion uses repeatable `--summary-item` only when a distinct overview is needed. Retained rereads are intentional for warnings, ambiguity, missing routing facts, recovery, cross-owner results, and detected external changes. ## Repository VCS capability Each configured source repository has one of two fixed `vcs` values: `git` or `none`. This is a concrete capability choice, not a plugin surface. Reads, writes, indexing, and source-writable AGT-X execution remain available for `vcs = "none"`, and those paths do not discover, require, or launch Git. Git-only operations select the repository's configured capability before any process call. Commit-skip gates ignore repositories without Git commit capability. Task worktree creation and frozen-binding migration require a configured Git repository. `aw agent review` and `aw agent adjust` are explicitly Git-only because their diff and restore semantics come from Git; non-Git Agent execution remains valid, but review or adjustment returns an `artifact_validation` error with `reason=repository_vcs_unsupported`, `repository_id`, `vcs`, and `operation` details. No Mercurial/SVN adapter or non-Git snapshot and restore engine is inferred. ## Task worktree migration The first Execute entry freezes a task's `worktree` mode. A frozen config is otherwise immutable, so `aw task migrate-worktree` exists as its own narrow operation rather than as a relaxation of the frozen guard: it moves one task from `worktree = disabled` to `worktree = enabled` and creates the isolated checkout in the same invocation. The migration resolves the configured root repository first and requires `vcs = "git"`; a root configured with `vcs = "none"`, or no configured root repository, returns the structured unsupported outcome without launching Git. Eligibility is exact, and each refusal carries its own reason code: - the task is in `todo`, has no running step, and its next step is Brainstorm, Analyze, or Plan — Execute and later keep the binding they already froze; - its config is frozen, still `worktree = disabled`, and records no prior migration. The new worktree is created at the main checkout's committed HEAD, so uncommitted work stays in the main checkout. When the main checkout is dirty the command refuses until you either commit that work or pass `--acknowledge-head-only` to accept a HEAD-only binding; the acknowledgement is recorded as evidence. The direction is one-way by construction: there is no reverse mode, no unfreeze, and no force. `aw task rollback` restarts step work and never changes a task's recorded worktree binding. `frozen_at` keeps its original value, because the freeze itself is not re-performed; `updated_at` becomes the migration timestamp. Replay is idempotent but never repairing. Re-running with the same leaf against an intact binding reports no change. A recorded binding whose worktree, branch, or canonical `.aw` link no longer holds is an error naming what broke, and `aw check` reports the same state as a fatal `task_migration_binding_broken` issue — recreate the binding by hand at the recorded `source_head`. Migrating an already-migrated task, or the same task onto a different leaf, is also refused, because silently rebinding would invalidate work already done in the old checkout. While a migration runs it publishes a per-task fence under `.aw/.runtime/task-worktree-migrations//`, and Agent dispatch for that task fails closed until the fence is released. A fence whose owner process died is reclaimed by the next attempt; `aw check` surfaces live and stale fences, and any worktree an interrupted migration created but never bound, as warnings. Either the operation produces a complete binding — config metadata, a registered worktree at the recorded commit, the canonical artifact-root link, and the `task.worktree_migrated` event — or it produces nothing: a failure after publication restores the original config bytes and removes only what that invocation created, and the returned error carries the compensation outcome. Run the migration with the CLI that matches the installed package version, and never hand-edit `task-config.json` to change a binding. This worktree command is unrelated to historical JSON contract repair: old task JSON is manually rewritten by an Agent from current templates through existing validated writers. There is no artifact migration command, compatibility parser, or Runtime-selected fallback. ## Archived task worktree retirement `aw task retire-worktree --reason --confirm` is the archive-only cleanup path for an immutable enabled worktree binding. The explicit confirmation is required because the command removes Git resources. Before publishing any cleanup evidence, it requires the task to be archived, its config to be frozen with `worktree = enabled`, all task Agent sessions to be quiescent, every recorded checkout to be registered on the recorded branch with a canonical artifact-root link, every checkout to be clean, and every recorded branch to be merged into that repository's current branch. Cleanup is two-phase and never uses Git force flags. First, the command records `worktree_retirement.status = "in_progress"` with the ordered binding snapshot, start time, and operator reason. It then runs ordinary `git worktree remove` for each still-registered checkout and `git branch -d` for each remaining branch. Only after every recorded directory, registration, and branch is absent does it record `status = "completed"`, `completed_at`, and the `task.worktree_retired` event. An interrupted cleanup is recoverable by re-running the same command with the same reason and `--confirm`. The durable binding snapshot controls the retry, already-removed resources are accepted, and remaining resources must still pass the safe preflight. Repeating a completed retirement returns `updated = false` only while every recorded resource remains absent; recreated or leftover resources fail closed for manual inspection instead of being deleted implicitly. Once retirement starts, `aw task rollback` refuses to reopen the task because its frozen checkout is terminally retired; create a new task if more work is required. Canceled and trashed tasks retain their worktrees by design, and orphan worktrees without an owning archived task are outside this typed task command. ## Project guidance - `aw blueprint create --input ` or `--input-file ` creates one absent standalone top-level canonical document. The id has no path separator or `.md` suffix and follows the existing `blueprint`, `aw`, `spec-*`, `dev-*`, or `roadmap-*` role rules. Creation validates role headings, rejects source symlinks, existing targets, matching component families and outgoing Components edges, then publishes complete content atomically without overwriting. `aw` remains free-form without required headings or Components semantics. JSON returns `document_id`, `artifact_path`, `sha256`, and `created`. - `aw blueprint read --json` returns exact content and its fingerprint. `aw blueprint replace --expected-sha256 --match --input ` applies one unique exact match after validating the prospective document family. Replacement also supports `--input-file `. Read and review stale-source conflicts; do not force them. Create and read back a new document before separately replacing an ordinary reference to it. A failed reference edit leaves a valid unreferenced document, not an implicit rollback. Nested creation, deletion, renaming and multi-file graph edits are unsupported. - Domain CLIs retain their validation, provenance and transaction boundaries while reusing internal input, exact-text and filesystem mechanisms. There is no unified file CLI or arbitrary-path artifact writer. Advisory locks serialize cooperating writers only; external editors remain outside those transactions. - `aw guidance` is the read-only request surface for Core Action `guidance.compose`: Signal `guidance.requested` resolves exact Trigger `guidance.`, then the composer returns dynamic fields plus flat Action Outcome identity and status. JSON results also carry deterministic, deduplicated `command_specs[]` entries shaped as `path` plus compact Clap-rendered `usage`; no nested `aw --help` process or duplicated argument registry is involved. Task-scoped step guidance remains a compact delta: it reports core guidance as an available source without expanding it again, omits static product and host sections already loaded by the task router, and prefers exact step Agent Trigger bindings over the overlapping `complex.reasoning` wildcard. Human output remains only the generated Markdown. - `aw roadmap` composes `roadmap/phases.json` with authoritative flat `roadmap/items/.json` files. Use phase `update` with repeatable `--item-order` for explicit display-order changes and typed narrow item commands for item facts. Removal refuses a non-empty `task_refs[]` unless `--accept-unlinking` explicitly accepts losing those links. Item ids stay stable; correct an id through unlink, remove, add, and relink. There is no aggregate roadmap write command. - A successful changed `aw task move` emits Signal `task.lifecycle.changed` from Core Hook Point `task.lifecycle.after`. An archive target resolves Trigger `task.archive.roadmap-sync` to non-blocking Core Action `roadmap.progress-sync`; the lifecycle result remains authoritative while `action_outcomes[]` returns the Action's identity, status, typed warnings, `actions_required[]`, and evidence. Callers do not need a second `blueprint-update read` to discover follow-up work. - `aw blueprint-update propose-blueprint|propose-roadmap` records typed task feedback candidates. Blueprint proposals append an exact-id `blueprint-candidate-recorded` event. `aw blueprint-update apply ` changes only `proposed` to `applied` and appends one `blueprint-candidate-applied` event. `aw blueprint-update reject --reason [--replacement-candidate ]` changes only `proposed` to `rejected` and appends one `blueprint-candidate-rejected` event containing the required reason and optional distinct known replacement id. Both commands locate exact candidates in any task lifecycle and never edit Blueprint Markdown or candidate content. Repeating the same terminal decision returns `changed=false` without rewriting or duplicating evidence; an opposite terminal decision returns a typed lifecycle error. Unknown ids, invalid replacement ids, and empty reasons fail without writing. Historical proposed and applied candidates remain readable without migration, and decisions are never inferred from text matches. - `aw knowledge add ... --input ` or `--input-file ` adds retained knowledge; `load` reads it. - `aw docs` lists the version-matched Weyaw product manual shipped with the installed package, and `aw docs ` returns one topic as raw Markdown. The command is independent of the current directory, `.aw`, repository registration, task state, and background services. The npm wrappers default `WEYAW_PRODUCT_DOCS_DIR` to their own package's manual. An explicitly inherited `WEYAW_PRODUCT_DOCS_DIR` overrides that default for development and packaging tests; without an override, source builds fall back to the checkout's `docs/` directory. JSON reports this distinction as `source: package | override | source-checkout`, so callers can reject an override when strict package ownership is required. - `aw guidance` exposes `aw docs --json` as the version-matched product-manual handle; agents can list and read detailed CLI, skill, and artifact references without guessing npm layout. ## Services and inspection - Automatic provider probes require recent project activity. `agent_server.provider_probe_idle_timeout_ms` configures the activity window and defaults to `300000` (five minutes). Ordinary CLI queries and operations, including `status`, `read`, and `docs`, renew `.aw/.runtime/agent-server/project-activity.json` after project selection. This advisory local marker does not change durable workflow or lifecycle authority. Missing or unreadable activity or config evidence disables automatic probing; recording failure does not fail the ordinary command. - Background workers, signal handlers, dashboard serving, `observe`, Agent MCP/monitor/session/output polling, and Agent group status/join do not renew the activity window. Internal service and library reads, heartbeats, and probes never renew it. A custom script repeatedly calling an ordinary query such as `aw status` is indistinguishable from a manual invocation and does renew it. - The elected worker checks eligibility every 30 seconds and again before each stale profile request. Probe timing is project-configurable: `agent_server.provider_probe_success_ttl_ms` defaults to `18000000` (five hours), and `agent_server.provider_probe_failure_ttl_ms` defaults to `600000` (ten minutes). Renewed activity reuses any still-valid result. Idle expiry prevents scheduling and stops remaining automatic profile requests, but does not stop services, cancel running tasks, or interrupt a probe already issued under its unchanged 30-second timeout. Config changes are read dynamically and do not require recompilation. - `aw server` supervises enabled core background services. - `aw agent-server status|start|stop|restart` and `aw index-server` expose individual project-bound lifecycle control. Agent Server runtime state lives under `.aw/.runtime/agent-server`, and Project Index runtime state lives under `.aw/.runtime/index-server`. Main checkouts, linked task worktrees, and concurrent sessions resolving to one canonical artifact root share the same project-local service state. Separate projects own independent pools; there is no host-global registry, queue, supervisor, or capacity pool. - `agent_server.project_concurrency` configures fixed slots for one project and defaults to eight. Current config is strict, versionless, and complete. `aw config repair` restores missing or incorrectly typed current-template fields while preserving recognized current settings; it also deletes explicitly allowlisted retired roots, including the former `[docs]` table, but does not otherwise interpret historical formats. A current config structural failure is labeled `reason=cli_artifact_contract_skew` only when its complete issue batch contains both `missing_field` and `redundant_field`; the original `artifact_validation` kind remains, and details include the project-config contract fingerprint, resolved executable path, executable mtime, and config mtime with rebuild or reinstall guidance. - `aw agent-server status` reports `.aw/.runtime/agent-server`, lifecycle sequence, generation identity, draining state, queue state, fixed-slot heartbeats, and operational capacity. It is read-only and never refreshes authority or starts reconciliation. Only current-generation slots with a fresh owner heartbeat and matching launch, digest, nonce, and process-start identity count as live. - `aw agent-server restart` is the public recovery path after package upgrades, source rebuilds, executable deletion or replacement, worker-runtime config changes, stale heartbeats, or terminal reconciliation failure. It fences old claims and drains old in-flight sessions under their original timeout. Foreign-host ownership requires explicit `--confirm-host-takeover`. Do not invoke hidden worker commands or edit `.aw/.runtime` files. - Agent Server uses atomic create/replace, owner tokens, expiry, and generation fencing. Runtime locks live under `.aw/.runtime/locks`; durable Agent evidence lives under `.aw/agents`. - Installed projects execute the npm/system `aw` binary directly; source checkouts execute their own `target/debug/aw`. Agent Server records that original path and digest and creates no project-local binary copy. Provider profiles execute directly with the recorded normalized `PATH`; shell syntax must be explicit in the configured command, such as `["bash", "-lc", "..."]`. - `aw dashboard` is unmaintained: `start`, `restart`, and the internal `serve` entry all fail with a lifecycle error, and `aw server` never launches it. Current config has no `services.dashboard` setting. `aw dashboard status` and `aw dashboard stop` remain available for winding down a service record left by an earlier version. - `aw tui` launches the terminal inspector. Settings is its only writable tab; observation tabs, `--json`, and scripted fallback remain read-only. - `aw observe activity [task-id] [--goal-scope ]` is Weyaw's compact read-only activity contract for lightweight status consumers. Without a task id it returns only the local Weyaw project display name and never selects or lists repository tasks. An explicit project-bound task returns its roadmap title, lifecycle, effective step, and one normalized `current_step` detail containing `todo|doing|done` rows in AW-owned durable order plus `completed`, `total`, and optional derived `wave`. The wave contains one-based `current` and `total` logical Wave numbers plus the complete ordered `waves` array. Brainstorm, Analyze, Plan, Verify, and Review project their durable step todo DAGs; Execute projects the merged Plan and execution-only graph. Every logical Wave is the full stable-order dependency layer: node count, Action `fan_out`, group or project concurrency, worker availability, slots, and queue state do not split or narrow membership. The projection remains read-only and does not claim to reconstruct historical runtime launches. Consumers may derive presentation order without mutating this durable row order. A caller-supplied aw-goal stage or ordered item scope adds only one-based current/total position. Agent rows are task-scoped, bounded to 32, and returned in canonical display order: running, queued or pending, then terminal, with stable group, assignment, semantic id, and title tie-breakers inside each rank. Every row exposes bounded `id`, `title`, and objective-backed `abstract` plus AGT-R/AGT-X mode, optional submit-time `order_preset`, selected worker `profile`, provider `harness`, status, content-token usage/budget, turn and attempt counts, and optional group position. Current rows use durable group/session identity and derive task ownership by loading `group.json`; unavailable optional presentation fields remain null. Bounded terminal rows may be returned for presentation, but only queued/running agents drive activity polling. Prompts, unbounded objective records, outputs, events, paths, model identifiers, raw provider payloads, worker commands, mutable current configuration, health, service state, and mutation controls are omitted. AW TUI lists show `id · title` and expose the abstract in detail; Pi never renders the abstract and uses one 60-column responsive breakpoint. Detail presentation at 60 columns or above shows `P1 · Title` todo rows and `Step Wave(current/total) [P1] → [P2] → [P3,P4]`; compact presentation below 60 uses `1. Title` and `Step Wcurrent/total [1]→[2]→[3,4]` only when compact IDs stay one-to-one across the complete current workload and otherwise retains full IDs such as `S1. Title` and `[S1,X1,X2]`. Neither tier adds parentheses or `+N` compaction, and long headers wrap into terminal-safe rows. The Weyaw Pi extension publishes task status as ` · AGT` through `ctx.ui.setStatus("weyaw", ...)` and does not own or replace the footer. A footer owner such as Pi Choco Chips can combine that status with the `mcp` key as ` · AGT · MCP`, reserving the marker suffix and applying terminal-cell truncation only to the task id. Pi's Agent widget groups included rows by first appearance in canonical activity order: one GroupID heading supplies the only Group context, and child rows omit repeated Group id and assignment position. Compact Group headings show active/total plus aggregate used tokens; detail headings add the `active` label but keep the same aggregate used-token total rather than summing context limits. Group and Agent fields use two-space list columns instead of repeated middle-dot separators. Compact Agent rows use status marker, mode, `harness/profile`, authored title, used tokens, and the individual Action order preset. Detail rows add Agent id, full status, token budget, turns above one, and retries above the first attempt. HUD compact mode still includes only queued/running Agents and expanded mode includes all bounded rows independently of responsive presentation. Historical rows without identity use the label-first fallback, and every Group or Agent row is truncated by terminal display cells. - `aw index` reports or queries local project/workflow index state. - `aw index source-map` projects compact structural roles published with each active index generation. It never walks source corpora at query time. A corpus reports `available: false` with warnings while unbuilt, dirty, backlogged, refreshing, or migrating; `scanned_files` is the number of files classified in that published generation, not a query-time scan count. `explore-plan` continues with ready lexical search evidence and does not reconstruct the map in the foreground. - Manifest/source-map schema upgrades are performed by index-server background reconciliation or explicit index administration, not by normal task steps. ### TUI Settings The interactive Settings tab presents six semantic groups: Services, Index, Actions, Workers, Workflow, and Signals. Booleans use toggles, bounded choices use selectors, numbers and text use inline editors, optional values use enable/edit controls, ordered values use list editors, and profiles or order presets use grouped object operations. The editor never exposes a raw TOML tree or asks users to manage dotted keys. Settings edits the stored raw value. For interpolated path fields it shows the `${project_abs_path}` or `${artifact_abs_path}` expression alongside a resolved preview and never writes the preview back as an absolute path. Profiles and presets stay name-sorted. Renaming either updates all references transactionally; referenced deletion is blocked with dependency paths; only profile-member order inside a preset has explicit reorder semantics. Profiles and presets are deleted separately without cascading. Drafts remain memory-only until Save. `Ctrl+S`, leaving Settings, or quitting enters the same validated save path; dirty leave and quit offer Save, Discard, or Cancel. Every write takes the short config lock, compares the load-time digest inside the lock, validates, preserves representable TOML decoration, and atomically replaces the file. A stale external edit rejects the save and preserves the draft. Watcher events for the saved digest do not reset focus or modals; different bytes become a visible conflict instead of overwriting a dirty draft. After a successful save, one modal lists `Start`, `Stop`, `Restart`, or `None` for Agent Server and Index Server. The user may apply the consolidated list or skip all operations. Activation is a separate phase: failure never rolls back the valid config, successful operations are removed from the retry list, and the remaining failed operations can be retried without rewriting the file. Dashboard is not part of this workflow. Long-running lifecycle commands require a host environment that can retain processes; ordinary reads, status, guidance, roadmap, and artifact commands do not. ## Official Agent dispatch Weyaw ships immutable, version-matched official Agent Actions and Trigger bindings. Every parallel-safe official Action defaults to `fan_out=8`, including `agent.complex.reasoning`; the temporary broad-control Action `agent.control.aw-cli-chain` remains the sole exception at immutable default and maximum `1`. Task-step project config may choose any positive `u32` value rather than a dedicated 8, 12, or 64 ceiling. Effective Action `fan_out`, `agent_server.project_concurrency`, group concurrency, worker availability, readiness, sandbox, write-root, and resource gates remain finite running-capacity limits. Current versionless config stores every Agent Action at `actions.""`, selects a reusable worker `order_preset`, narrows turns, fan-out, and content-token limits within bundled ceilings, and names per-project Agent Server capacity as `agent_server.project_concurrency`. It stores official activation enablement at `triggers."".enabled` only where the Trigger permits project disablement. Fresh config creates empty `explorer`, `thinker`, `reviewer`, `executor`, `light-reviewer`, and `light-executor` presets; configuring the first real profile fills those empty bootstrap presets without guessing a provider. `extensions/actions.json` may add `local.*` Actions and Triggers only by extending the same official binding; it cannot override official ids or widen source, context, executor, capability, write-root, or resource authority. Fresh config also retains one disabled, empty-command `unconfigured` profile, so recommendations never become implicit activation. The version-matched starting points are `codex-gpt-5_6-sol` with `command=["codex","exec"]` and `model="gpt-5.6-sol"`, direct `claude-opus-5` with `command=["claude","--model","claude-opus-5"]`, and `ccr-claude-opus-5` with `command=["ccr","claude-opus-5"]`. Guidance and health may present these values, but the user must choose and apply one after checking launcher resolution, authentication, model access, and—before selecting CCR—that `claude-opus-5` is present in `ccr preset list`. Current config is never inferred from retired fields or layouts. Run `aw config repair` to restore the complete strict versionless template from recognized current settings. Repair removes unknown fields, fills current defaults, validates the full result, and never converts retired names, values, or extension files. Use `aw agent readiness --json` before dispatch. Every task or non-task readiness request names `--trigger`; task requests also name `--task` and may assert the recorded `--step`, while non-task requests name `--context` and may name an existing `--operation` or let readiness allocate one. Readiness resolves and reports both `trigger_id` and `action_id` together with context, owner, workdir, canonical write roots, recovery decision, and resource conflicts. Requests use `--trigger`; there is no definition alias or alternate selector. Every `aw agent readiness --json` result and each Agent-capable Dynamic Guidance result includes `mcp_host_recommendation`. The object contains `advisory=true`, `transport="stdio"`, `command=["aw","agent","mcp"]`, the initialized project path in `cwd`, `shared_methods=["tools/list","tools/call"]`, and `required_tools=["agent_monitor","agent_join"]`. These fields describe the complete currently verified useful cross-Harness intersection and therefore the maximal shared capability baseline; newly universal useful capabilities are promoted into it. The descriptor is advisory: it does not gate readiness, submit, or fallback and never changes Host-owned configuration. - Task writers are bound to the task's frozen worktree. Brainstorm, Analyze, and Execute official project contributors require explicit project-relative `--write-root` values outside the artifact root. Each write root is directory authority, not a file selector. Declare each existing or planned file separately with `--target-file`; every target file must be strictly contained by at least one validated root and never widens or narrows that authority. An existing file passed as a write root is rejected with a correction to pass its parent directory as the root and the file as the target. - Before either provider launches, the shared runtime creates missing directory roots and missing target-file parents only. It never creates the target file or a directory at that path. Empty, absolute, parent-escaping, root-equal, outside-root, directory-valued, or symlink-escaping target files fail before session publication; Codex and Claude transports do not implement separate target rules. - Every non-task read-only launch still creates durable project-owned group/session evidence under `.aw/agents`. Promote useful conclusions into task, action-log, or knowledge artifacts before treating advisory Agent output as workflow authority. - `control.aw-cli-chain` is the only official non-task writer. It matches `weyaw.operation.aw-cli` and may open one temporary broad `aw **` capability. The harness runs in the common sandbox with project and workflow files read-only; AW invocations are proxied, recorded, and followed by Host reread. - `aw agent submit` requires exactly one `--task` or `--operation` plus `--trigger`, `--id`, `--title`, and `--objective`, and repeats the resolved readiness and identity policy immediately before persistence. `aw agent start` requires the same semantic identity inputs plus `--trigger`. Agent ids use 1..48 ASCII characters from `[A-Za-z0-9._-]`; titles use 1..48 terminal display columns. Objective remains execution truth and the detailed abstract source. - `aw agent group start` accepts the same owner forms and reads its strict assignment document through `--input` or `--input-file `. Every assignment requires `id`, `title`, `objective`, `role`, `trigger`, `scope`, and `prompt`; assignment `id` becomes the persisted `agent_id`. Writable assignments may add `write_roots` as explicit directory grants and `target_files` as existing or planned files inside those grants; omitting `target_files` preserves a directory-only assignment. Target files become conflict evidence automatically, but do not make overlapping directory grants safe for parallel execution. For a task-step logical Wave, the Host publishes the complete set of Agent-safe assignments in one group when at least two exist and handles a singleton directly. Assignment count is not capped by task-step `fan_out`; the effective Action and AgentServer capacities are persisted as group running concurrency, so excess assignments remain queued and start as slots become available. While sessions are queued or running, the Host may continue dependency-, write-scope-, and resource-disjoint Host-owned or control work. If one writable member completes while peers remain live, group status recommends that member's `aw agent review` before another aggregate status read; once all latest turns finish, status continues to recommend cooperative group join for shell closure. Runtime-operation groups retain their bounded assignment-count enforcement. Missing identity, Trigger, or valid target authority fails before the group manifest or any member is written. Group retry and follow-up preserve the same logical node id and require current Trigger/Action identity, while history, output, interruption, cancellation, review, and adjustment remain available for inspection and safe cleanup. - Use `aw agent group status|join|cancel|retry --task ...` for task groups or the corresponding `--operation ` form for runtime-operation groups. - Interpret AGT-X evidence as three independent facts: session `status` is the runtime outcome, `observed_changes` records mutation evidence, and `review_decision` records the parent disposition. No field implies either of the others; a completed writable run is not accepted until the parent records its review decision. ## Agent progress monitoring - `aw agent monitor --session [--since-line ]` performs one bounded read of current session identity, adapter, token, timing, progress, latest-turn, output, and terminal evidence. Add `--wait` to block without mutation until unread progress exists, the latest durable turn is terminal, or the runtime session finishes. - `aw agent monitor --session --stream [--jsonl]` emits a low-noise current activity feed until one terminal result. Stream mode does not replay old activity and cannot be combined with wait, cursors, group mode, or global `--json`. - `aw agent monitor --group --task [--wait] [--assignment-since-line =]` projects current evidence for every latest assignment attempt. Group mode is single-shot or one-wake and does not stream. - A monitor cursor is a complete progress-log line position. Carry `next_line` into a later call to receive only unseen events. An out-of-range cursor is an error; reread without a cursor and compare the current attempt and progress evidence. - When a latest turn becomes terminal and output is durable, inspect AGT-R through `aw agent history` or `aw agent output`, and inspect AGT-X through `aw agent review` followed by `aw agent adjust`. Agent completion never accepts changes or advances workflow state. - `aw agent mcp` runs a foreground, project-bound MCP server over newline-delimited stdin/stdout. `agent_monitor` accepts `session_id`, optional `since_line`, and optional `wait`; `agent_join` accepts one ordered non-empty `session_ids` list of at most 64 entries. Session resources use `weyaw://agent/sessions/`. `agent_join` is the normal MCP all-of dependency barrier. It rereads current session state until every declared session is terminal, preserves input order, and owns no join artifact, inbox, delivery ledger, or copied result store. A successful response includes each session and group identity, normalized owner projection, terminal status, durable evidence paths, bounded final-message text, and caller-local `barrier_wait_ms`. Canceling the tool call stops only that wait; it never cancels Agent sessions. Hosts without MCP retain session ids and use `aw agent monitor --session --wait [--since-line ]` plus `aw agent output ` at dependency barriers. Cooperative groups use group monitor mode and `aw agent group join` only to close lingering shells after useful turns finish. Stream records contain bounded status and activity metadata only; they omit prompts, reasoning, provider payloads, tool inputs or results, commands, paths, stdout, stderr, and full evidence arrays. Closing a stream ends only the observer. Durable group/session/turn artifacts remain authoritative evidence, while monitor and join durations remain read-time projections. See [Getting Started](getting-started.md) and [Dashboard](dashboard.md).