CALL FIRST: mandatory repository manager contract and callback workflow.

The identity block -- role, verified route, repository and storage readiness, task health, the last hygiene pass and the Claude-route dispatcher state -- is on every reply, so repository_current and task_health need no call of their own. The contract prose is delivered once per verified session and then suppressed with its sha; pass include_contract=true to re-read it, or known_contract_sha256 to prove you already hold it.

A reply that suppresses the contract (contract_delivered=false) is the steady-state one, and it was measured at up to 11 KB -- most of it the last hygiene pass's per-task detail and the reconciler's own internals, which no caller gates on (NF-2026-01447). Those bodies are dropped from task_hygiene/task_health and replaced by the names omitted plus the block's sha256/bytes, so nothing silently disappears; the verdicts and counts beside them stay exact. include_diagnostics=true keeps them.

MANAGER EDIT: bind one verified file range before changing it.

MANAGER EDIT: replace exactly one prepared, hash-bound range.

new replaces the WHOLE prepared range; re-emit every line you keep. allow_escape_level_change: true only for an intentional regex/escape fix.

MANAGER CODE DISCOVERY: use first and continuously before built-in file search.

MANAGER READ: bounded canonical Session Manager current state.

MANAGER READ: bounded canonical AI Memory search.

MANAGER READ: exact active canonical AI Memory lookup.

MANAGER READ: bounded related canonical AI Memory lookup.

MANAGER READ: bounded canonical KB search.

MANAGER READ: exact canonical KB entry lookup.

MANAGER READ: bounded canonical KB relation lookup.

MANAGER READ: search exact transcript-backed Context Graph evidence.

MANAGER READ: retrieve an exact bounded transcript range around one event.

MANAGER READ: retrieve bounded deterministic relations for one graph node.

MANAGER WRITE: append one exact current-thread conversation event.

MANAGER WRITE: rebuild derived graph state from the immutable ledger.

MANAGER READ: configured models joined to observed canonical outcomes.

full=True returns the complete payload exactly as before: every worker field plus outcome history. The default keeps every top-level key that is not the worker list verbatim (summary, revision, manager envelope, ...) and folds the per-worker list to one compact row per worker -- worker_id, adapter_id, model, enabled, launch_eligible (build_routing_catalog's launchability key) and the row's outcomes sample_count and accepted_rate (read only from worker["outcomes"], omitted when absent, never invented) -- beside detail_omitted (bytes/sha256 of the canonical JSON of the full worker list) and a detail_request naming the full call (NF-2026-01566). An error result passes through untouched.

MANAGER READ: explainable cheapest-capable routing from current evidence.

detail="summary" (default) keeps every top-level selection field (selected_*, economic_advisory, etc.) exact; the selected compatible candidate and the next two keep their full row, every other compatible candidate is reduced to worker_id/adapter_id/model/score; excluded candidates are reduced to a count per exclusion reason plus the first 10 as worker_id/adapter_id/model. detail="evidence" behaves like "full": both return today's payload exactly.

MANAGER READ: validate a Source Graph-grounded child-DAG proposal.

This operation never creates or launches tasks. The returned digest is an advisory proposal that requires a separate explicit manager decision.

MANAGER WRITE: append one audited canonical Session Manager event, or edit one existing event.

Append actions: start, event, checkpoint, state, handoff, close (no document_id). Edit actions: amend rewrites the content of one exact existing document (FTS rebuilt, audit row recorded, context-graph mirror rewritten); redact deletes that document, its FTS row and its graph mirror (audit keeps the fact of the redaction, never the content). Both require document_id and leave the document count/id audit trail truthful.

MANAGER WRITE: remember, update, supersede, or archive canonical memory.

MANAGER WRITE: upsert, ingest, supersede, or archive canonical KB data.

MANAGER WRITE: persist and project one verified Learning Commit.

SHORT FORM -- the one to use: task_id, request_id and the lesson. Everything mechanical is resolved server-side from the card's OWN decision event: outcome is read from the adjudication (never asserted), repo_area from the paths that decision was taken over, evidence_ids from the sealed FIXED_AND_VERIFIED acceptance reference, and idempotency_key/provenance are the deterministic strings the learning_commit_owed payload in your accept/reject reply already carried. failure_category is always derived server-side from the card's structured terminal evidence and is never caller-suppliable. repo_area omitted is derived from the decision's paths; any explicitly supplied value is normalized and honored, while an empty or whitespace value is refused with learning_commit_repo_area_invalid:empty.

Add your own references with extra_evidence_ids. An evidence id must carry an allowed scheme -- file:, http: or https:. A sha256: receipt id is refused, and any refusal here returns allowed_evidence_id_schemes.

outcome is accepted, rejected or inconclusive; only the first two may promote, and each promotion needs what its store demands (a lesson for AI Memory, an invariant for KB, an edge plus an acceptance for Context Graph).

LONG FORM (compatibility): supply repo_area, outcome, evidence_ids, idempotency_key and provenance yourself and nothing is resolved. The lesson text is always the caller's; nothing is written without this call.

MANAGER READ: preview bounded captured NeedFix candidates from Markdown.

MANAGER WRITE: commit an exact Markdown preview as captured items only.

MANAGER WRITE: audited bounded upsert of one repository worker model.

MANAGER: dry-run, apply or rollback one explicit repo-local legacy context store.

MANAGER READ: inspect authenticated worker context-write proposals.

MANAGER WRITE: explicitly accept or reject one worker proposal.

MANAGER WRITE: register and persist one proposed skill.

Give candidate_id from aiworkhub_manager_skill_mine and the MECHANICAL dimensions are copied server-side from that candidate's measured draft -- identity, version, scope, path_or_symbol, risk, stage. You then supply only the judgement: task_family, triggers, applicability, confidence, procedure_steps, avoid_rules. Passing a mechanical field that disagrees with the candidate is refused, never silently overridden. Without a candidate_id every field is required from the caller.

CLOSED VOCABULARIES -- a value outside these is refused before any write: scope repository | global risk low | medium | high | critical stage orientation | implementation | validation | review | rework task_family analysis | bugfix | data_ml | docs | implementation | performance | refactor | replay | security | test triggers authority_boundary | code_change | combined_change | concurrency | destructive_change | missing_validation | public_api | release | schema_migration | security_sensitive | clean_verdict_without_input_check | silently_bounded_population | single_bucket_aggregate | swallowed_exception_default | unknown_or_empty_result applicability aggregation_reader | observability_surface | quality_gate | readiness_preflight | authority_boundary_surface | concurrency_surface | public_api_surface | release_surface | security_surface | storage_schema_surface version semver MAJOR.MINOR.PATCH with optional -prerelease/+build identity ^[a-z][a-z0-9_.-]{0,127}$ confidence a finite float in [0, 1] path_or_symbol a repository-RELATIVE path or symbol; absolute paths and .. are refused

The proposal is evidence-free and a duplicate identity/version is refused without overwriting the stored record. It is never ACTIVE on creation: activation needs accepted evidence from two DISTINCT actor identities and stays a separate manager decision.

MANAGER WRITE: append one MANAGER evidence entry to a skill version.

CLOSED VOCABULARIES -- a guess is refused before a turn is spent: outcome accepted | negative actor_id ^[a-z][a-z0-9_.-]{0,127}$, and it may NOT contain the reserved role tokens worker, reviewer, coordinator, agent or owner. Those name a DERIVED identity read off a task card's own runner and can never be typed here.

Two spellings of one manager are ONE actor: identities are compared in their canonical form, so manager.claude.7e and claude_manager_7e do not make an activation independent. Genuinely independent evidence comes from a card: it is appended automatically when a decision is recorded on a card the skill was injected into, and can be filed for one card at a time through the task-derived path.

When resolve_negative_source is set, no row is appended: the one unresolved negative row with that source is marked resolved instead, with note as the REQUIRED reason (source and outcome are ignored).

MANAGER READ: per-skill usage statistics, measured from the stored record.

For every stored skill version: how many versions of that identity are proposed, its evidence rows split by outcome (accepted/negative), the number of CANONICAL independent actor identities its accepted evidence rests on (not the raw strings -- two spellings of one manager count once), the cards it was injected into according to the persisted selection receipts, whether it is injectable at all, and when it is not, the exact named reason:

lifecycle_state_is_retired unresolved_negative_evidence activation_evidence_below_two_distinct_actors lifecycle_state_is_proposed_not_active

Read-only. It never activates, retires or evidences anything.

MANAGER WRITE: activate a proposed skill, evidence-gated and fail-closed.

The registry's activation threshold is enforced unchanged; when it is unmet the registry's own reason is returned and the stored record is left as it was.

MANAGER READ: mine the correction record into gated skill PROPOSALS.

Clusters every stored rejection instruction and adjudicated invariant by the RULE it asserts -- instance vocabulary (paths, identifiers, ids, digits) is deleted before anything is compared -- then promotes only families that recurred across at least min_cards distinct cards in min_files distinct files. Each candidate carries the exact card ids and request ids where the rule was violated, plus a proposal draft whose closed-vocabulary selection dimensions are left blank for the manager to fill in.

Read-only. It produces proposals, never activations: the returned draft reaches the store only if a manager passes it to aiworkhub_manager_skill_propose, and activation remains gated on evidence from two distinct actor identities.

MANAGER READ: measure every stored skill against its own failure class.

Reports, per skill, whether it is injectable at all, the cards its evidence anchors to, and the adjudicated outcome of those cards. It also reports whether the injection denominator exists in this repository -- and when it does not, says so with both counts instead of computing a rate against a zero denominator. Verdicts are recommendations; retirement stays manager-gated and this never writes.

Summary mode (default) folds each skill's evidence_anchors list to {count, sha256} (digest of its canonical JSON); full=true returns the anchor-card lists unchanged.

MANAGER WRITE: backfill learning-commit evidence for every recorded commit.

Bounded and resumable like every other sweep here: pass back next_cursor to continue past a ledger larger than limit. Reports skipped_by_reason (why a window's commit produced no row -- rejected, no selection vocabulary, and so on) and activated (every identity/version this window's evidence pushed across the registry's own two-actor activation gate). A second sweep over an unchanged window records nothing new and activates nothing twice.

MANAGER WRITE: open the repository's one manager agent loop session.

MANAGER WRITE: attach to the repository's one passive manager conversation.

Synchronous and provider-free: no backend is built and no model is called. Takes the launching gate like start because it persists the conversation record. The panel calls this on open instead of Start; the first send then pins the policy route and runs the turn.

MANAGER WRITE: load the last manager conversation. Does not create one.

Synchronous and provider-free. The panel calls this on open. The first send on a selected model opens the first session when none exists.

MANAGER WRITE: rename one saved manager conversation.

MANAGER WRITE: delete one saved manager conversation.

MANAGER WRITE: continue one saved manager conversation.

Synchronous and provider-free. The chosen record becomes the active session and the persisted selection. A picked backend_id/model is authorized and pinned on it without starting it; the pick renews the manager seat. Refused while a turn is running.

MANAGER WRITE: close the current conversation and open a fresh passive one.

Synchronous and provider-free. The displaced record gets a mechanical handoff. Refused while a turn is running.

MANAGER WRITE: run one manager turn in the background.

Returns at once with state: "running". A call while a turn is already running is queued (queued: true with its position; at most 8, in memory only) and runs before the next callback wake; an unrunnable route is refused at once. Poll aiworkhub_manager_loop_status (its send_queue) or aiworkhub_manager_loop_events for the outcome.

backend_id/model carry the panel picker selection: the turn binds to that exact route (same route is a no-op, a switch re-opens with a mechanical handoff). Blank means "no selection" and keeps the legacy policy-default pin behavior. reasoning is the owner's depth choice. images attaches up to 4 png/jpeg/gif/webp images, each {"name": ..., "data": <base64>} within 5 MiB; claude_cli and codex_cli read them, other backends refuse them as the turn's error.

MANAGER WRITE: close the session with a handoff, in the background.

Returns at once with state: "running"; a call while a turn is already running is refused with manager_turn_in_progress and nothing is queued. The next aiworkhub_manager_loop_start opens a successor rehydrated from the handoff.

MANAGER READ: the active session, whether a turn is running, queued owner sends, and the last turn's outcome.

MANAGER READ: bounded session events, for incremental client polling.

Events with seq greater than after_seq, bounded to limit, and partial: the running turn's streamed, unfinished text for this session, or null. The partial is display only; it is never persisted or sent to a model.

MANAGER WRITE: release the backend and lock at shutdown, without a model turn.

MANAGER WRITE: end a running turn's CLI process now, without waiting for it.

MANAGER WRITE: register and persist one caller-defined tool recipe.

manifest is the caller's complete recipe payload -- the exact shape aiworkhub_manager_recipe_show returns -- and no field of it is inferred or generated. An invalid manifest is refused with the tool_recipes module's own stable reason_code before any write, and a (id, version) that is already stored is refused without touching the stored row: a recipe version is immutable.

This registers a DESCRIPTION of an invocation. It never runs one.

MANAGER WRITE: install the catalogue of this repository's own invocations.

Each entry of manager_recipe_tools.CANONICAL_RECIPES describes an argv vector AIWorkHub genuinely builds (the card validation commands, the worker worktree provisioning sequence, the finalization Git probes), naming its call site in its purpose. Idempotent: an entry already stored is reported as already_registered and its row is left untouched.

Per-project, not a fixed list. The universal entries -- the git workspace/finalization/diff probes and the packaged aiworkhub.recipes.* operator modules -- install everywhere. The entries that depend on a toolchain or on paths that must exist in THIS project install only when toolchain_authority measures them present, so a project without Node never receives validation.node_test. withheld names every skipped entry with its measured reason.

MANAGER READ: which catalogue entries THIS project would be seeded.

The same per-project decision aiworkhub_manager_recipe_seed_canonical makes, measured without making it: every eligible entry, every withheld one with the reason it was withheld, and the toolchain evidence behind both. Use it when onboarding a repository to see what it will get before anything is written.

MANAGER READ: bounded identity/contract listing of persisted recipes.

Returns each manifest's identity, digest, purpose, risk, capabilities and parameter signature -- never its argv template. An empty store is a legitimate repository state and returns registry_count zero.

MANAGER READ: which registered recipes are actually used, and by whom.

aiworkhub_manager_recipe_list answers how many recipes EXIST. This answers whether anything uses them: every registered recipe appears with its run count, how many DISTINCT verified actors ran it, its first and last run, its exit-code distribution and the bytes those runs returned -- and a recipe with no runs appears with used false rather than being omitted, because "registered and never run" is the actionable state.

The actor on every receipt is derived by the server from the verified route, never from a caller-supplied string, so distinct_actors cannot be inflated by typing a new name. Runs recorded before actors existed are reported as unattributed_runs rather than credited to anyone.

since is an ISO-8601 UTC timestamp bounding the evidence window; registered_count still covers every stored manifest, and window_only marks the asymmetry.

MANAGER READ: one persisted recipe in its exact canonical manifest form.

With version omitted the highest stored version wins, ordered by the registry's own version key. The returned manifest is exactly the payload the recipe digest hashes, so the reported digest is independently checkable.

MANAGER EXECUTE: run one PERSISTED recipe and return a bounded digest.

What runs is the immutable stored manifest resolved from the registry, not a mapping typed at call time: argv[0] is a manifest literal, the vector is built from typed slots, and it is spawned as an execve list with no shell. Read-only by default -- tool_recipes.validate_invocation refuses a recipe whose declared capabilities grant_capabilities does not name, and a write/network recipe additionally requires the repository write gate to be open.

A non-zero exit is a RESULT, not an error: the digest carries the return code, the duration, stdout/stderr tails capped at 4096 characters with explicit truncation flags, and the path plus SHA-256 of the full output file, so the whole stream stays retrievable without being carried here. Every run persists a tool_recipes invocation receipt.

PRIVATE BRIDGE: execute one active GLM call with worker-scoped audit authority.

READ-ONLY: bounded shared registry of live AIWorkHub repository routes.

This is discovery only. Task storage and task mutation remain scoped to the current repository's own .aiworkhub MCP child.

READ-ONLY: bounded live repository identities available to this manager.

READ-ONLY: exact current repository, binding source, and manager route.

MANAGER OPERATION: atomically switch to one live manager-owned repo_id.

MANAGER WRITE: create one new canonical repo-local task card.

Creation choices (also exposed as field hints): difficulty: bounded, standard, complex (optional; never inferred). work_kind: generic, bugfix, refactor, performance, security, data_ml. validation_roles: generic, reproduction, regression, parity, baseline, delta, negative_fixture, schema, distribution; one per validation command. Required roles: bugfix=reproduction+regression; refactor=parity; performance=baseline+delta; security=negative_fixture; data_ml=schema+distribution. validation: shell-free executable commands; no environment assignments, pipes, redirects or chaining. Set environment outside validation argv. custom_template_escape: audited_custom_unclassified, explicitly audited unclassified cards only, not an automatic bypass; writable escaped cards require non-empty required_outputs covered by allowed_writes.

Replies with a creation receipt (aiworkhub.task_create_receipt.v1): task_id, created/reconciled/receipt_state, scope_warnings, the server-derived validation_roles, risk_tier/origin/signals, difficulty/origin, validation_exemption, template_provenance, the project_context Source Graph query, and card_sha256/card_bytes -- never the card the caller just typed. echo_card=True returns the full CLI envelope with the persisted card in stdout instead. A refusal names every violation at once (violations) with field, length and limit. The live manager session supplies callback provider/origin identity; callers cannot route a task into another chat, disable the mandatory review callback, or overwrite an existing id. depends_on (optional) names other task_ids in this repo that must finish before this card is Plan-DAG ready; omit it for the pre-DAG behavior. Tasks are uncapped by default. Never infer, estimate, or auto-assign max_live_tokens from task complexity, model, historical usage, or cost. Supply it only when the owner explicitly requests an exact cap or a repository policy pre-registers one. Process efficiency must come from focused context, bounded reads, minimal edits, fewer retries, and useful validation rather than from truncating work. An authorized cap is enforced only when the selected provider exposes structured usage while running; terminal-only usage remains posthoc evidence, never a false live- enforcement claim. A writable task's required_outputs may be empty ONLY when template classification matches a contract that declares that default itself (e.g. implementation_with_tests/cross_boundary_bugfix, whose combined production+test scope keeps a deliberate empty default per NF-2026-00456) or an explicit, in-scope mandatory list resolves that way. Every other writable outcome -- including the audited custom-escape path, which has no template contract of its own to fall back on -- requires a non-empty required_outputs (NF-2026-00772); it contains only repo-relative file paths or glob patterns covered by allowed_writes. Human-readable outcome descriptions belong in acceptance; mixing prose into required_outputs is rejected before a provider run is launched. allow_unchanged_required_outputs explicitly names required files that are evidence inputs/outputs permitted to remain byte-identical to both launch baselines; they are verified and hashed but never promoted. allow_empty_required_outputs is the equivalent explicit exception for deliberately zero-byte outputs. Neither exception is inferred. read_only=True is required for a task that intentionally declares both allowed_writes=[] and required_outputs=[]. Read-only intent is never inferred from missing output authority. runner is the worker execution identity returned by aiworkhub_manager_workforce_rank.launch_contract.runner. The exact value codex is reserved for the verified manager and is rejected for worker cards. work_kind is an explicit behavioral contract, never inferred from the title or worker prose. Specialized values require one validation_roles entry per validation command: bugfix=reproduction+regression, refactor=parity, performance=baseline+delta, security=negative_fixture, and data_ml=schema+distribution. Missing roles are rejected before launch. risk_tier is optional explicit routing/economic evidence. It is never inferred from priority or prose; omitted historical cards remain unknown. It is a FLOOR: the observed write scope may escalate it, never lower it. The skill_* fields are the card's skill selection vocabulary, drawn from closed sets (aiworkhub_manager_skill_mine and skill_registry.SELECTION_VOCABULARIES name them). An unknown token is refused at create rather than silently matching nothing. skill_task_family and skill_path_scope are derivable from the template and the write set and may be omitted; skill_stage, skill_triggers and skill_applicability are not derivable, and a card that omits them selects no skill at all. Default creation is template-first: generic Python production-plus-test cards classify against the frozen registry, and unclassified raw cards fail closed unless custom_template_escape is the audited token. wave_goal_binding (optional) is exactly {roadmap_id, goal_id, predecessor_task_id} and makes this card that active wave goal's current task in place of the predecessor. It is never inferred from a title, topic, version suffix or prose; the receipt names its state.

MANAGER WRITE: create one task from an authenticated template.

Replies with the same creation receipt as aiworkhub_task_create (template_provenance once, from the persisted card); echo_card=True returns the full CLI envelope with the card in stdout. Callers supply routing fields, task text/acceptance, a template ID, and explicit production/test paths. Generated allowed_writes, required_outputs, read_first, read_only, task_type, work_kind are taken from template expansion. Validation commands and their one-to-one roles may be overridden together; when both are omitted, the generated defaults are preserved. Malformed, stale, or forged template IDs, unsafe paths, and incomplete validation overrides fail closed before create_task. Provenance authenticates the final expanded contract. The skill_* fields are the card's skill selection vocabulary, drawn from the same closed sets core.create_task validates against (skill_registry.SELECTION_VOCABULARIES); an unknown token is refused at create rather than silently matching nothing. They are card fields, not path fields: they never enter allowed_writes or required_outputs, so declaring one can never make an output mandatory. skill_task_family defaults to the family the template itself declares (task_templates.skill_task_family of its declared work kind), and an explicit value overrides that default; skill_stage, skill_triggers and skill_applicability describe the occasion rather than the template genre, so no template can supply them and a card that omits them selects no skill at all. wave_goal_binding (optional) is exactly {roadmap_id, goal_id, predecessor_task_id} and is forwarded to core.create_task unchanged, exactly as aiworkhub_task_create does; it is never inferred from the template, title or prose, and core refuses a malformed binding. difficulty (optional) is bounded, standard or complex and is forwarded to core.create_task unchanged; core alone validates it. It only selects the worker's reasoning effort and is never inferred from the template, title or prose: omitted means undeclared.

MANAGER READ: list the bounded repository-bound template registry.

MANAGER READ: show one exact short or full template ID, fail closed.

READ-ONLY: bounded Plan-DAG summary, or the complete DAG with full.

Default mode reports actionable lifecycle, ready work, blockers, write-scope overlaps, orphaned processing and DAG validity without repeating every finished card's dependency history. Use full=true for exact historical dependency/layer inspection. This tool never claims work; aiworkhub_task_auto_pickup/_dryrun remain the claim surfaces.

Check parent AIWorkHub task queue health and write-gate state.

List tasks waiting for Codex review.

List task cards by status and optional topic.

Show a single task card by task_id.

Summary-first by default: retained baseline hash maps (tree, workspace and parent baselines) are folded to entry count plus sha256, and the evidence blobs (terminal_review.evidence.{validation, quality_gate, quality_review, quality_review_receipt, worker_mcp_gate, workspace} and accept_evidence.{validation, quality_gate}) are folded to {summarized, bytes, sha256, verdict/status, failed_count, first_failure}. terminal_failure and rework_predecessor are folded to the facts a reviewer reads (substatus/reason/category/first_error and task_id/request_id/outcome/reason); template_provenance.expanded_contract is folded to identity only. detail="evidence" keeps all of the above exact (baselines still folded); detail="full" or full=True returns the exact stored card. Summary/evidence renders are compact JSON; full keeps the indented one.

The manager-authored bodies (review_feedback, recovery_feedback, history) fold to identity plus their counts in the summary render, and every summary/evidence reply carries card_sha256/card_bytes plus review_findings_count when the card records reviewer reports: measured avg 11.5 KB/call over 31 calls (NF-2026-01447).

Return pending cards for a specific runner as raw output plus parsed JSONL rows.

READ-ONLY: preview which task auto_pickup WOULD claim for a runner/topic.

Reports the candidate task_id, a compact card, and runner/topic filtering counts WITHOUT mutating the parent queue and WITHOUT touching the write gate. Never invokes the write-gated auto-pickup command; uses only the read-only export path. The real claim path (aiworkhub_task_auto_pickup) stays behind AIWORKHUB_ALLOW_WRITES; this preview provides no alternate write path and cannot bypass that gate.

MANAGER WRITE: bounded startup reconciliation for dependency-ready children.

Write-gated Codex action: reject a reviewed task with exact feedback and an explicit disposition. to = pending (rework, default) | blocked | archived | superseded -- so a task whose real next step is a dependency- gated replacement is not silently requeued to pending.

predecessor_request_id selects an exact retained review request as the rework workspace authority. Omitted (None) defaults to the current review request. An empty string fails closed.

failure_category is a verified-manager escape hatch for a mechanical review failure. It is accepted only with to=blocked and only from the closed infrastructure taxonomy, so it cannot relabel candidate code.

reason is capped at 8000 UTF-8 bytes after strip; over it the call is refused with reject_reason_too_large:<bytes>><cap> and nothing changes.

Replies with a receipt (aiworkhub.reject_review_receipt.v1): task_id, to, status, request_id, claim_epoch, prior_episode, failure_category, reason_identity (sha256 + bytes, never the text), predecessor changed-path and residual counts, rework_delta_recovery, reviewer_finalization, learning_commit_owed, card_sha256/card_bytes. The reason and the argv are never echoed; include_card = none (default) | summary | full.

Recover one exact blocked task through the canonical transaction.

scope_rejection_resolved is the manager's explicit, audited clean-root resolution of a scope_rejected card; it requires feedback_reason. A feedback_reason over 8000 UTF-8 bytes is refused with feedback_reason_too_large:<bytes>><cap>; it is never truncated.

When the core result's stdout parses to a card dict the reply is the shared _lifecycle_receipt projection (aiworkhub.recover_blocked_rework_receipt.v1, include_card="none"): task_id/status/worker_status plus card_sha256/card_bytes from the canonical _card_identity (the same basis as aiworkhub_task_show), the card's runner/recovery_epoch/recovery_predecessor when present, a detail_request for aiworkhub_task_show, and every extra top-level key the core call attached -- never the whole recovered card (NF-2026-01566). command is never echoed: its argv carries feedback_reason (up to 8000 bytes). A not-ok or card-less result is returned unchanged minus the argv echo, so error text is never hidden.

COORDINATOR WRITE: retry one exact operational terminal episode.

Only blocked cancelled/timed-out/launch/worker/process/liveness failures are eligible. The exact prior request id and substatus are mandatory; semantic validation/review failures remain on their established review workflow. The same task ID is requeued and its append-only audit history is preserved.

Replies with a receipt (aiworkhub.retry_terminal_receipt.v1): task_id, status, worker_status, card_sha256/card_bytes, and every server-derived key the transition attached -- retried_request_id, terminal_substatus, request_linkage, workspace_retention, idempotent. One measured call echoed the whole requeued card at 67,395 chars, review_feedback and rework_predecessor included (NF-2026-01447); include_card = none (default) | summary | full brings it back.

COORDINATOR WRITE: explicitly reroute one pending retry launch identity.

COORDINATOR WRITE: archive stale non-processing tasks atomically (archived_at + card_json + an archived task_events row each). Runs the full coordinator-capability write gate per item -- use this instead of patching SQLite. For an active/orphaned card use supersede.

Targets: one task_id, task_ids (<= 200), or a selector (status/topic/older_than_hours/task_id_prefix, conjunctive). dry_run=True previews the exact ids (and the processing cards that would be refused) without writing. Replies with per-id receipts {task_id, ok, status_after, error?}; one refusal never hides the rest.

MANAGER WRITE: reconcile one exact authenticated dead blocked claim.

COORDINATOR WRITE: supersede a stale/active task with a replacement.

Archives the card as superseded (allowed even from processing) and records the optional replacement task id via by. Full coordinator- capability gate; atomic; no direct SQLite patching.

Replies with a receipt (aiworkhub.task_supersede_receipt.v1): task_id, status, card_sha256/card_bytes plus any server-derived keys the core call attached. include_card = none (default) | summary (baselines and evidence folded) | full (the exact post-transition card).

MANAGER WRITE: archive non-processing cards without deleting audit history.

Targets: one task_id, task_ids (<= 200), or a selector (status/topic/older_than_hours/task_id_prefix, conjunctive). dry_run=True previews the exact ids (and the processing cards that would be refused) without writing. Same write gate and verified manager actor per item, one audit event per task, per-id receipts {task_id, ok, status_after, error?}.

MANAGER WRITE: supersede an orphaned active card while preserving audit history.

Run the task collision guard for active cards.

Return task usage report, optionally filtered.

Read-only: inspect write-gate audit log summaries.

Returns counts by tool/action and the last N audit entries. Never writes, never enables writes, never launches processes. All authority flags are preserved false.

READ-ONLY: Inspect review queue, group tasks by topic/runner, return Codex review checklist.

Calls the B110 review_summarizer core (read-only contract). Returns grouped tasks, validation commands, allowed_writes counts, and a Codex-ready review checklist shape.

FROZEN INPUT SCHEMA — no write-gate toggle, no mutation parameters. Never calls taskctl done/review/start/auto-pickup/add-card. Never mutates queue or audit state. Never launches agents or model processes. Writes remain default-off regardless of input values.

READ-ONLY: Codex-ready HANDOFF report for review-queue tasks.

For each task waiting on Codex review, summarizes task_id, runner, topic, allowed_writes, validation commands, derived risks, commit-hygiene status, and a scoped stage/finalize command list — WITHOUT mutating the parent task queue.

FROZEN READ-ONLY CONTRACT — no write-gate toggle, no mutation parameters. Never calls taskctl done/review/start/auto-pickup/add-card. Never mutates queue or audit state. Never launches agents or processes. Writes remain default-off regardless of input values.

READ-ONLY: Codex-ready HANDOFF report rendered as compact Markdown.

Builds the same B116 handoff report as aiworkhub_task_codex_handoff (via the identical read-only review-queue + show calls, never a write command) and adds a deterministic markdown field — a compact review packet Codex can read directly instead of manually parsing the JSON.

FROZEN READ-ONLY CONTRACT — no write-gate toggle, no mutation parameters. Never calls taskctl done/review/start/auto-pickup/add-card. Never mutates queue or audit state. Never launches agents or processes. Writes remain default-off regardless of input values.

READ-ONLY: derive supervisor_state + error taxonomy for a task_id.

Implements the B08 contract's 7-step derivation over the LIVE queue (task_mcp_supervisor_loop_status_tool_b08_v1.json): fetch_status via core.show_task, then runner_topic_mismatch / missing_artifact / collision / stale_task / failed_validation checks, falling through to a read-only lifecycle_state -> supervisor_state mapping when none trip.

FROZEN READ-ONLY CONTRACT -- no write-gate toggle, no mutation parameters. Never calls taskctl done/review/start/auto-pickup/add-card. Never mutates queue or audit state. Never launches agents or processes. Writes remain default-off regardless of input values.

Return a validated launch PLAN without writing anything.

Wraps plan_dryrun(audit=False): validates argv against the static allowlist and returns the would-run plan. Writes NO audit entry, mutates NO task-queue state, and launches NOTHING. Any provided env is redacted (values, incl. secrets, are never emitted). Read-only holds regardless of the write gate. Also runs the B107 collision preflight (would_collide / collision_preflight): a plain read of the task-card JSONL, no lock, no claim, no mutation.

Return a read-only summary of the write-gate audit log.

Delegates to core.read_audit_log (which never writes, never enables writes, never launches). Adds the read-only authority flags for a consistent contract shape. Env values are absent from audit entries by construction, so this output is safe to log.

One read-only call returning BOTH a validated plan and an audit summary.

READ-ONLY: build the canonical dashboard queue, health, and storage snapshot for the active repository.

Use the default compact mode for manager queue summaries and status counts, or full=True for the native Webview payload; use aiworkhub_dashboard_health for a cheap connection check or aiworkhub_dashboard_task_detail for one task card. Reads canonical SQLite state and cached storage telemetry without mutating tasks or launching processes.

READ-ONLY: return the canonical detail, events, and validation evidence for one task card.

Use this to inspect a specific task's contract, history, and attempt receipts; use aiworkhub_dashboard_snapshot for queue-wide status counts or aiworkhub_dashboard_task_live_output for live process stdout and stderr. Validates task_id format before querying read-only task storage and never mutates state.

READ-ONLY: perform a fast storage readiness, manager identity, and dispatcher health check for the active repository.

Use this for lightweight connection-banner polling or pre-initialization checks; use aiworkhub_dashboard_snapshot when you need task queue counts, process rows, or cost summaries, or aiworkhub_dashboard_initialize when storage reports not_initialized. Probes storage readiness and cached observability without building the full queue snapshot or mutating repository state.

READ-ONLY: read a bounded page of live stdout and stderr output for one task's active or latest worker run.

Use this to stream or page incremental worker process output from a byte cursor; use aiworkhub_dashboard_task_detail for the task contract and attempt history, or aiworkhub_dashboard_snapshot for queue-wide status. Validates task_id format and reads only that task's log files without mutating state.

READ-ONLY: list the newest canonical AI Memory entries for the active repository.

Use this to browse stored AI Memory rows and lifecycle statuses in the dashboard; use aiworkhub_dashboard_sessions or aiworkhub_dashboard_kb to browse session transcripts or Knowledge Base entries. Opens the repository memory SQLite database in read-only mode and never increments access counters or mutates rows.

READ-ONLY: list the newest Session Manager transcript documents for the active repository.

Use this to inspect recent session continuity documents in the dashboard; use aiworkhub_dashboard_memory for durable AI Memory keys or aiworkhub_dashboard_kb for Knowledge Base articles. Opens the canonical transcript SQLite database read-only and never modifies session checkpoints or access state.

READ-ONLY: list the newest canonical Knowledge Base entries for the active repository.

Use this to browse repository Knowledge Base articles, categories, and tags in the dashboard; use aiworkhub_dashboard_memory for key-value AI Memory rows or aiworkhub_dashboard_sessions for session transcripts. Opens the KB SQLite store in read-only mode without mutating entries or usage counters.

READ-ONLY: return measured skill lifecycle counts and selection or injection coverage for the active repository.

Use this to audit active skill reachability, selection receipts, and consecutive empty-injection streaks; use aiworkhub_dashboard_settings for feature switches or aiworkhub_dashboard_snapshot for task queue state. Reads the skill registry and receipt store without mutating state, and reports measured=False with an explicit reason when the store is absent or unreadable.

READ-ONLY: list bounded NeedFix inbox items with optional status, kind, severity, and archive filters.

Use this to browse or page through NeedFix summaries; use aiworkhub_dashboard_needfix_detail to fetch full description, scope, provenance, and audit events for one item, or aiworkhub_dashboard_roadmap_list for Roadmap items. Reads the NeedFix SQLite store without mutating state.

READ-ONLY: return one NeedFix item with full detail fields and its bounded audit event history.

Use this to inspect a single NeedFix item's description, scope, evidence, and lifecycle events; use aiworkhub_dashboard_needfix_list to browse summary rows or aiworkhub_dashboard_needfix_convert_preview to preview task conversion. Validates needfix_id format and reads the NeedFix store without mutating state.

READ-ONLY: preview the normalized task card and plan_digest for converting a NeedFix item into a task.

Call this before aiworkhub_dashboard_needfix_convert_commit to inspect the normalized card, validation role requirements, and the plan_digest required to commit; use aiworkhub_dashboard_needfix_detail to inspect the NeedFix item itself. Normalizes the task plan and caches the signed preview in memory without creating a task or mutating durable store state.

USER WRITE: capture a new NeedFix item or deduplicate against an existing live row.

Use this to record a new bug or proposal in the NeedFix inbox; use aiworkhub_dashboard_needfix_update to edit an existing item or aiworkhub_dashboard_needfix_transition to change status. Requires an open write gate, normalizes kind synonyms, persists the new or deduplicated row in the NeedFix store, and returns a capture receipt.

USER WRITE: update mutable content and classification fields on an existing NeedFix item.

Use this to edit title, description, scope, kind, severity, tags, or readiness_score; use aiworkhub_dashboard_needfix_transition to change lifecycle status or aiworkhub_dashboard_needfix_capture to create a new item. Requires an open write gate, persists field changes and an audit event in the NeedFix store, and returns a delta receipt.

USER WRITE: apply one confirmed lifecycle status transition to a NeedFix item.

Use this to triage, accept, reject, defer, mark duplicate, mark task_planned, resolve, or recover a conversion claim; use aiworkhub_dashboard_needfix_archive, aiworkhub_dashboard_needfix_restore, or aiworkhub_dashboard_needfix_convert_commit for archive, restore, or task creation. Requires confirm=True, persists the state transition and audit event in the NeedFix store, and returns a transition receipt.

USER WRITE: archive one non-converting NeedFix item without deleting its stored record.

Use this to move an inactive or obsolete NeedFix row out of the active inbox; use aiworkhub_dashboard_needfix_restore to return an archived row to an active status, or aiworkhub_dashboard_needfix_purge to permanently delete an archived row. Requires confirm=True, refuses rows currently in converting status, sets status to archived with an audit event in the NeedFix store, and returns the updated item.

USER WRITE: restore an archived NeedFix item to an active non-terminal lifecycle status.

Use this to unarchive a NeedFix row previously archived with aiworkhub_dashboard_needfix_archive; use aiworkhub_dashboard_needfix_transition to advance the lifecycle of an already-active item. Requires confirm=True and a row currently in archived status, clears archived_at, sets status to target_status, records a restored audit event, and returns the updated item.

DESTRUCTIVE: permanently delete one archived NeedFix row from the NeedFix table while retaining an audit snapshot.

Use aiworkhub_dashboard_needfix_archive first to archive the item safely, or aiworkhub_dashboard_needfix_restore to recover an archived item instead of deleting it. Requires confirm=True, a non-empty audit_reason, and an already-archived row; records a purged audit event with the row snapshot and permanently deletes the row from the needfix table.

USER WRITE: convert an accepted NeedFix item into a canonical task card without launching a worker.

Call aiworkhub_dashboard_needfix_convert_preview first to obtain the required plan_digest; use aiworkhub_dashboard_needfix_link_existing_task instead when a finished accepted task already resolves the item. Requires confirm=True and a matching plan_digest, creates the task card in the task store, transitions the NeedFix item to task_created, and never spawns a worker process.

USER WRITE: link a NeedFix item to an existing finished, manager-accepted task in the same repository.

Use this when an already-completed canonical task resolves the NeedFix item; use aiworkhub_dashboard_needfix_convert_commit instead to create a new task card from the NeedFix. Requires confirm=True, verifies the target task exists and is finished and accepted (plus integrated_commit when supplied), and persists the task link and audit event in the NeedFix store.

USER WRITE: reopen a NeedFix item whose linked converted task was archived or superseded.

Use this when a converted task was superseded or archived without resolving the NeedFix so a new conversion can mint a successor -rN task; use aiworkhub_dashboard_needfix_transition for normal lifecycle changes. Requires confirm=True and a verified archived or superseded linked task, increments reopen_generation, restores the NeedFix to accepted status, and records an audit event.

READ-ONLY: list bounded Roadmap outcomes joined with task-DAG progress and wave projection.

Use this to browse Roadmap items, status counts, and wave readiness; use aiworkhub_dashboard_roadmap_detail for one Roadmap item's full detail and audit events, or aiworkhub_dashboard_needfix_list for NeedFix items. Reads the Roadmap and task stores without mutating state.

READ-ONLY: return one Roadmap outcome with linked task progress, wave projection, and audit events.

Use this to inspect a specific Roadmap item's dependencies, linked tasks, and event log; use aiworkhub_dashboard_roadmap_list to browse all Roadmap items. Validates roadmap_id format and reads the Roadmap and task stores without mutating state.

READ-ONLY: return repository feature switches, Source Graph policy, retention policy, and model routing policy.

Use this to inspect current settings and their revision numbers before calling aiworkhub_dashboard_settings_update, aiworkhub_dashboard_model_settings_update, or aiworkhub_dashboard_source_graph_settings_update. For queue state or task counts use aiworkhub_dashboard_snapshot instead. Reads repository configuration files and status views without mutating durable state or starting background services.

USER WRITE: atomically update repository-local feature switches with optimistic revision locking.

Use this to toggle top-level repository features such as source_graph or context_graph; use aiworkhub_dashboard_settings to inspect current switches and revision first, or aiworkhub_dashboard_source_graph_settings_update and aiworkhub_dashboard_model_settings_update for language or model routing switches. Atomically persists feature settings when expected_revision matches, starts or stops Source Graph when toggled, and initializes the context graph schema when enabled.

USER WRITE: update one provider, adapter, or model routing switch for the active repository.

Use this to enable or disable a provider, transport adapter, or specific model leaf; call aiworkhub_dashboard_settings first to read model_policy and its current revision, or use aiworkhub_dashboard_settings_update for repository feature flags. Acquires the model-settings lock, verifies expected_revision, and atomically persists the updated routing configuration.

USER WRITE: atomically update per-language Source Graph indexing switches for the active repository.

Use this to enable or disable individual languages in the Source Graph ignore policy; use aiworkhub_dashboard_settings to read the current policy and revision first, or aiworkhub_dashboard_settings_update to toggle the top-level source_graph feature switch. Enforces optimistic locking against expected_revision, atomically rewrites the ignore policy file, and triggers an immediate Source Graph refresh when the feature is enabled.

READ-ONLY: preview reclaimable worker worktrees, stale Git registrations, and storage quarantine batches.

Use this first to obtain a fresh preview_digest before calling aiworkhub_dashboard_storage_quarantine or aiworkhub_dashboard_storage_registration_prune; use aiworkhub_dashboard_terminal_log_retention_preview or aiworkhub_dashboard_task_retention_preview for terminal logs or archived tasks. Scans worktree storage read-only without moving or deleting files.

USER WRITE: move reclaimable worker worktrees matching a current preview into a reversible quarantine batch.

Call aiworkhub_dashboard_storage_retention_preview first to obtain preview_digest; use aiworkhub_dashboard_storage_restore to undo a batch or aiworkhub_dashboard_storage_purge to delete an expired batch. Requires confirm=True and an unchanged preview_digest, moves eligible worktree directories into a signed quarantine batch with an undo deadline, writes an audit entry, and invalidates cached storage telemetry.

USER WRITE: prune stale AIWorkHub Git worktree registrations verified against a current preview digest.

Call aiworkhub_dashboard_storage_retention_preview first to obtain the registration preview_digest; use aiworkhub_dashboard_storage_quarantine to move physical worktree directories instead. Requires confirm=True, refuses when foreign stale registrations exist or the digest drifted, runs git worktree prune, records an audit entry, and invalidates storage telemetry.

USER WRITE: restore a quarantined worker-worktree batch back to the repository worktree root.

Use this to roll back a quarantine batch listed by aiworkhub_dashboard_storage_retention_preview; use aiworkhub_dashboard_storage_purge to permanently delete an expired batch instead. Requires confirm=True, moves quarantined directories back without overwriting existing paths, reinstates Git worktree registrations when applicable, updates the batch manifest and audit log, and invalidates storage telemetry.

DESTRUCTIVE: permanently delete one expired worker-worktree quarantine batch from disk.

Inspect batches with aiworkhub_dashboard_storage_retention_preview first, or use aiworkhub_dashboard_storage_restore to recover a batch while its undo window is still active. Requires confirm=True and an authenticated batch whose restore deadline has passed, permanently removes the batch directory, records an audit event, and invalidates storage telemetry.

READ-ONLY: preview reclaimable terminal process log files, protected logs, and terminal-log quarantine batches.

Call this before aiworkhub_dashboard_terminal_log_quarantine to inspect candidates and obtain preview_digest, or call aiworkhub_dashboard_terminal_log_usage_backfill when runs lack usage receipts; use aiworkhub_dashboard_storage_retention_preview for worktrees. Scans process logs read-only while excluding the canonical request ledger.

USER WRITE: idempotently backfill missing provider usage receipts from retained terminal stdout logs.

Use this before aiworkhub_dashboard_terminal_log_quarantine when terminal runs remain protected due to missing usage capture receipts; use aiworkhub_dashboard_terminal_log_retention_preview to inspect protected runs first. Requires confirm=True, parses retained worker stdout logs without estimating tokens or cost, appends canonical usage capture events to the task store, and leaves already-captured runs unchanged.

USER WRITE: move eligible terminal process log files matching a current preview into repo-local quarantine.

Call aiworkhub_dashboard_terminal_log_retention_preview first to obtain preview_digest, and run aiworkhub_dashboard_terminal_log_usage_backfill first if uncaptured usage receipts protect logs; use aiworkhub_dashboard_terminal_log_restore to undo. Requires confirm=True and a matching preview_digest, moves eligible log files into a quarantine batch with an undo window, records an audit event, and invalidates storage telemetry.

USER WRITE: restore one terminal-log quarantine batch back into the repository process log directory.

Use this to recover quarantined log files from a batch listed in aiworkhub_dashboard_terminal_log_retention_preview; use aiworkhub_dashboard_terminal_log_purge to permanently delete an expired batch instead. Requires confirm=True, moves quarantined files back without overwriting existing files, updates the batch manifest and audit trail, and invalidates storage telemetry.

DESTRUCTIVE: permanently delete one expired terminal-log quarantine batch from disk.

Inspect quarantine batches with aiworkhub_dashboard_terminal_log_retention_preview first, or use aiworkhub_dashboard_terminal_log_restore to recover files while the undo window is active. Requires confirm=True and an expired restore deadline on manual batches, permanently removes the batch directory, appends an audit record, and invalidates storage telemetry.

READ-ONLY: preview archived task rows eligible for retention quarantine and list existing undo batches.

Call this before aiworkhub_dashboard_task_quarantine to inspect candidate counts and obtain preview_digest; use aiworkhub_dashboard_task_archive to archive a single live task first. Opens the task database read-only, excludes archived tasks with pending or inflight callbacks, and never mutates task rows.

USER WRITE: archive one non-active task card in the canonical task store without deleting its evidence.

Use this to hide a finished, blocked, pending, or superseded task from the active queue; use aiworkhub_dashboard_task_restore to unarchive it or aiworkhub_dashboard_task_quarantine to move aged archived tasks into a retention batch. Requires confirm=True, refuses processing or review tasks, sets archived_at with an audit event, and invalidates storage telemetry.

USER WRITE: restore one archived task card in the canonical task store back to its prior status.

Use this to unarchive a single task archived via aiworkhub_dashboard_task_archive; use aiworkhub_dashboard_task_quarantine_restore instead if the task was already moved into a task-retention quarantine batch. Requires confirm=True, clears the archived overlay on the task row, records an audit event, and invalidates storage telemetry.

USER WRITE: recover one restartable task through its canonical state transition path and launch a worker.

Use this for operator-initiated retry and launch of a pending, blocked, or dead-processing task; use aiworkhub_dashboard_task_detail to inspect the card first. Requires confirm=True, refuses live processing or review/finished/archived/superseded tasks, reconciles dead claims or blocked state in the task store, spawns a worker via process_launcher, and invalidates storage telemetry.

USER WRITE: move aged archived task rows matching a current preview into a reversible retention batch.

Call aiworkhub_dashboard_task_retention_preview first with the same older_than_days cutoff to obtain preview_digest; use aiworkhub_dashboard_task_quarantine_restore to undo a batch or aiworkhub_dashboard_task_archive to archive one live task. Requires confirm=True and a matching preview_digest, records retired task outcomes in the roadmap store, moves task and event rows into task_retention_batches, and invalidates storage telemetry.

USER WRITE: restore one archived-task retention batch back into the canonical task tables.

Use this to roll back a task retention batch listed by aiworkhub_dashboard_task_retention_preview; use aiworkhub_dashboard_task_restore instead to unarchive a single task that is still in the live tasks table. Requires confirm=True, checks for task_id collisions, reinserts tasks, task_events, and callback rows in one transaction, marks the batch restored, and invalidates storage telemetry.

DESTRUCTIVE: permanently delete one expired or already-restored archived-task quarantine batch.

Inspect batches with aiworkhub_dashboard_task_retention_preview first, or use aiworkhub_dashboard_task_quarantine_restore to recover tasks while the undo deadline is active. Requires confirm=True and an expired restore_deadline (unless already restored), deletes the batch payload from task_retention_batches, records a purged audit row, and invalidates storage telemetry.

USER WRITE: initialize or repair the active repository's canonical .aiworkhub stores and Source Graph directory.

Use this when aiworkhub_dashboard_health reports storage not_initialized; use aiworkhub_dashboard_health or aiworkhub_dashboard_snapshot for read-only status checks. Bound to AIWORKHUB_REPO_ROOT, verifies repo_id against any existing manifest, idempotently provisions the project manifest, storage registry, SQLite stores, and Source Graph directory without deleting legacy files, and invalidates storage telemetry.

MCP-bound: preview using the server's active repository root.

Never accepts a caller-selected repo_root; always binds to core.repo_root(). The CLI may still target an owner-selected repository via --repo, but the MCP surface is pinned to the server's active repository. provider is an instruction-file target, not a model provider; its schema enumerates all valid filenames.

MCP-bound: inspect using the server's active repository root.

MCP-bound: apply using the server's active repository root.

READ-ONLY: describe a launch INTENT via the disabled B119 launch_queue_contract.

Builds a pure LaunchRequest (enqueue_intent) and returns describe_intent's dry-run intent + gate evaluation as data. describe_intent is always invoked with audit=False here (the only other value the contract accepts, True, raises LaunchDisabledError rather than writing anything -- this tool never passes it). launch_enabled() stays hardcoded False and LAUNCH_IMPLEMENTED stays False regardless of any env flag; no launcher exists in the code path this tool reaches, so it can never start a process.

FROZEN READ-ONLY CONTRACT -- no write-gate toggle, no audit parameter. Never mutates queue or audit state. Never launches agents or processes.

READ-ONLY: evaluate a launch request via the disabled B119 launch_queue_contract.

Builds a pure LaunchRequest (enqueue_intent) and returns evaluate_launch's gate-evaluation decision. permitted is always False: this contract has no implemented launcher, so the request stays blocked_launch_disabled regardless of env gate state. Writes nothing: no persistence call is made and no process is launched.

FROZEN READ-ONLY CONTRACT -- no write-gate toggle, no mutation parameters. Never mutates queue or audit state. Never launches agents or processes.

READ-ONLY: summarize the append-only B119 launch-queue audit JSONL log.

Delegates to launch_queue_persist.read_persisted_log, which only reads the log file (plain open(..., "r"), and reports log_exists=False without creating it when absent) and never writes, never enables writes, never launches a process. Same shape as aiworkhub_task_audit_log_read: counts by decision/to_state plus the last N entries, and reports whether every persisted entry so far is blocked_launch_disabled -- the expected state while AIWORKHUB_ALLOW_LAUNCH / _ALLOW_WRITES stay unset (the default).

FROZEN READ-ONLY CONTRACT -- no write-gate toggle, no mutation parameters. Never mutates queue or audit state. Never launches agents or processes.

WRITE-GATED: append a disabled launch-queue request.

This is the B286 MVP queue-request tool. It never launches a process: LAUNCH_IMPLEMENTED remains False in launch_queue_contract. With AIWORKHUB_ALLOW_WRITES unset, it appends nothing. With the write gate open, it appends one existing launch-queue audit record unless the request is idempotent or a different runner already owns an open request for the same task_id.

READ-ONLY: recommend recovery actions for stale processing tasks or blocked cards.

scope="processing" (default) covers stale processing tasks. scope="blocked" triages the blocked-card queue: one recommendation per card, limit bounds the cards read (see bounds.truncated) and sample the rows listed per group. Produces recommendations only. It never calls taskctl write commands and never kills a process.

READ-ONLY: bounded cost summary, with opt-in detailed dimensions.

Default mode retains cost/cache truth plus provider, model and day aggregates, and stays bounded as usage history grows. by_model, cost_per_accepted_outcome.routes and model_outcomes.models each return at most _COST_LEDGER_SUMMARY_TOP_N rows. by_day is bounded as two independent groups -- up to _COST_LEDGER_SUMMARY_TOP_N most-recent dated buckets beside up to _COST_LEDGER_SUMMARY_TOP_N undated ones -- so its exact ceiling is 2 * _COST_LEDGER_SUMMARY_TOP_N rows, not N; undated spend is retained rather than made to compete with real days for one shared bound. Every bounded dimension carries explicit total_count/ returned_count/truncated/ranked_by metadata under summary_row_bounds, so no row is dropped silently. The two model-keyed dimensions rank by observed dollars rather than tokens; a bucket whose provider reported no price ranks on its activity instead of being cut as though it were free, and a partially priced bucket ranks in both orders so one cheap priced record cannot hide the magnitude whose dollars are still unknown. Per-runner and per-topic maps are available with full=true; task rows remain independently opt-in through include_tasks.

Kept rows are also narrower than full=true. Each kept model's cost_per_accepted_outcome.routes adapter folds its family/risk partitions into one total row, re-derived from summed counters so an UNKNOWN partition keeps it UNKNOWN; the fold is receipted under summary_row_bounds. by_day rows keep records, total_tokens, cost_usd, cost_unknown_records and cache_hit_ratio. full=true returns both exactly as built.

The repository binding is what makes those aggregates answerable. build_cost_ledger reads canonical usage events only when it is given a root; without one it parses the human-readable usage report, whose lines carry no model, provider or timestamp, so every dimension this docstring promises collapsed to unknown. Measured 2026-09-02 on this repository: unbound 590 rows / 1 model / 1 provider / 1 day / 0 usage-observed / 0 cache-observed / 0 routes; bound 3,509 rows / 28 models / 8 providers / 36 days / 2,267 usage-observed / 1,869 cache-observed / 13 routes. Every other caller (dashboard, manager tools, evidence instruments) already passed a root; this tool -- the manager's own cost surface -- did not, so routing by cost and difficulty had no measurement to steer by (NF-2026-00542).

READ-ONLY: combined completion-inbox facts for Codex orchestration.

Returns five facets in one call: review_queue (tasks awaiting Codex review), operational_failures (legacy finalizer failures eligible for retained retry), stale_processing (claimed tasks with no recent artifact/validation activity, default threshold 24h), runner_mismatch_warnings (batch-token mismatches between a runner name and the task_id it claimed -- a local pure replica of AITools/taskctl.py::_runner_task_batch_mismatch), and latest_validation_facts (the most recently recorded validation_status/ validation_error/blocker_reason per task).

FROZEN READ-ONLY CONTRACT -- no write-gate toggle, no mutation parameters. Only issues taskctl list/taskctl show (both read-only). Never calls taskctl done/review/start/auto-pickup/add-card/export-jsonl. Never mutates queue or audit state. Never launches agents or processes beyond the existing taskctl.py read-only child-process calls.

READ-ONLY: ONE bounded review packet for a review_ready candidate.

Every fact a manager needs to decide a candidate is already persisted -- validation rows with their declared commands and output tails, the quality gate's checks and blockers, the worker MCP gate and its receipt-conformance verdict, required outputs, destructive-diff checks, the effective tier and its per-lens status, the deduped reviewer findings, the reachability observation -- spread across six nested objects on one card. This returns them together, under a measured byte bound.

Measured over all 419 real cards carrying a quality gate: min 1,662 B, p50 6,387 B, p90 8,813 B, max 13,799 B, 0 needing truncation. It replaces per candidate 10 task-scoped calls at p50 (p90 21) and, session-wide, 1,688 hand-written Bash re-derivations (pytest 611, attempt-artifact reads 242, task_queue.sqlite scripts 250, log tails 113, git diff 155) totalling 1.45 MB.

Nothing here is a verdict: every status was decided by the gate that recorded it, and accepting still runs the whole fold in accept_review. The one live computation is accept_preview -- itself read-only -- which completion_inbox cannot call because it holds no launch authority, so it is computed here and passed in.

DUAL-GATED: launch one exact local Claude/Codex worker process.

Requires both AIWORKHUB_ALLOW_LAUNCH=1 and AIWORKHUB_ALLOW_WRITES=1. The task card, runner, topic, pending state, allowed-write scope, collision guard, adapter, and process limit are all validated before a shell-free child process can start. timeout_seconds is retained only as non-enforcing compatibility metadata; this API never installs a provider wall-clock deadline.

runner, topic and adapter_id are optional because the server already owns them: the card carries runner and topic (the launcher refused any value that differed, so typing them asserted rather than decided), and the adapter is a pure function of the runner narrowed to the first pinnable, policy-allowed entry in canonical tuple order. Omit them and the reply's launch_identity_derivation records exactly what was derived; pass them and the explicit value wins and is validated as before. The manager identity codex is never a worker runner.

DUAL-GATED: launch one independent anti-anchored quality reviewer.

timeout_seconds is retained only as non-enforcing compatibility metadata; this API never installs a reviewer wall-clock deadline.

READ-ONLY: inspect one launched process and its authoritative task card.

detail="summary" (default) folds the card's baseline hash maps and evidence blobs, its terminal_failure/rework_predecessor/ template_provenance.expanded_contract, and its static contract text (objective/acceptance/validation/read_first/template_provenance/ project_context/forbidden/required_outputs/mandatory_changed_outputs) to {summarized, bytes, sha256} -- identity and lifecycle fields (task_id, title, status, substatus, runner, topic, request ids, allowed_writes count) stay exact. The latest event's validation/quality_gate/ worker_mcp_gate/token_budget/project_context fold the same way, without redundant field-name inventories. Repeated retry/reroute reasons and the minimality contract fold to identity; named artifact/delivery/review receipts retain status, errors and explicit observed/unknown flags alongside identity. Failure/liveness fields and usage metrics stay exact. The manager-authored bodies (review_feedback, recovery_feedback, history) fold the same way, and the reply carries card_sha256/card_bytes plus review_findings_count when the card records reviewer reports: measured avg 11 KB/call over 48 calls, max 33 KB (NF-2026-01447). "evidence" keeps all of the above exact (baselines still folded); "full" returns the raw status payload.

READ-ONLY: collect bounded worker output and review-readiness evidence.

DUAL-GATED: terminate one exact process group recorded by this server.

COORDINATOR/WRITE-GATED: retry one retained finalization request.

The provider/model is never launched again. The exact successful worker request, retained workspace, task identity and supervisor exit receipt are revalidated before deterministic validation/finalization is re-entered. A validation failure is eligible only when its durable reason is the operational validation_exec_scratch_unavailable condition; ordinary product/test failures remain non-retryable. A scope_rejected request is eligible: the re-run repeats the scope check and reaches review_ready only if the retained delta is now in scope (NF-2026-01345).

validation_lane="manager_host" is the manager's explicit opt-in for a candidate whose declared validations failed only because the sandbox validation lane cannot execute them (NF-2026-01030). It makes any validation_failed/finalize_failed request whose retained candidate seal still verifies retryable, and re-runs the SAME declared commands with the validation route forced to the host backend. All pass -> the normal finalize path to review_ready; any failure -> validation_failed again, now with host receipts. The lane is never derived from candidate output. manager_host applies only to VS Code LM adapters: its forced backend is the editor-hosted one, which never runs a native CLI route outside its OS sandbox, so a request from a CLI adapter (e.g. claude_cli) is refused up front with validation_lane_forbidden_for_adapter:<adapter> before any event write or card transition, leaving the request and card unchanged (NF-2026-01645).

MANAGER WRITE: resolve one exact durable reviewer-route hold.

Every chain, candidate and retired-attempt identity is mandatory. The action can only expose an already-recorded callback, authorize the one bounded distinct-route successor, or re-arm the exact pre-provider reviewer attempt after its operational blocker was repaired. It never accepts the target and never relaunches its implementation worker.

MANAGER WRITE: record one audited disposition of one reviewer finding.

dismissed needs non-empty counter_evidence and lifts only that LOW/MEDIUM finding's refinement_required blocker at accept; a high/critical finding cannot be disposed. The receipt is append-only and bound server-side to the verified reviewer receipt and the candidate digest. It never edits the reviewer report and never accepts the target.

READ-ONLY: what would block accept_review right now, before any work.

Measured 2026-09-08: 49 of 159 accept attempts (31%) failed on a blocker that was knowable in advance -- a required lens still running, a target not yet review_ready, an approval not given -- but only after the combined tree had been materialized and two validation runs paid for. This folds exactly those cheap blockers and writes nothing.

A clear preview is NOT an acceptance and NOT a promise of one. The expensive half -- combined tree, declared validations, mechanical gate, reviewer receipt verification by request id -- runs only in accept_review and can still refuse. blocked False means only that nothing cheap is refusing yet. Leave requested_risk_tier unset to read the tier the finalizer measured; an explicit value can only raise it.

COORDINATOR/WRITE-GATED: accept one review_ready request, phase 2.

Re-runs scope, required-output, and validation gates against the retained isolated worktree, compares every changed path's hash against the ones recorded when the request first reached review, and only then promotes into the canonical repo and finalizes the task as done. Any precondition or revalidation failure leaves the canonical repo untouched and the task in review. Idempotent: accepting the same already-finished request again returns already_accepted instead of re-promoting. Medium-and-higher risk profiles also validate a fresh canonical+candidate combined tree and require strict reviewer findings; high/critical review requires an explicit confirm_high_risk decision.

manager_correction -- unset by default, and every other behaviour is then exactly as before -- accepts the sealed candidate PLUS a manager patch instead of rejecting it: {"patch": <unified diff>, "finding_ids": ["reviewer:<lens>:<id>", ...], "reason": str}. It lifts the refinement_required blocker of each named finding that a selected reviewer reported and aiworkhub_agent_dispose_review_finding already recorded as confirmed, provided its severity is not blocking. The patch is validated before any promotion or state change and refuses with manager_correction_invalid:<reason> when the manager is unverified, the patch does not apply to the sealed candidate bytes, a touched path is outside the card's allowed_writes or not part of the candidate, no finding is named, or a named finding is unconfirmed or blocking. The declared validations and the mechanical gate then run on the CORRECTED bytes, those are the bytes promoted, and the accepted-outcome receipt binds the patch digest with the candidate and corrected hashes.

A successful reply is the receipt (aiworkhub.accept_review_receipt.v1): promoted_paths, reviewer_finalization, acceptance_evidence_record, accepted_outcome_receipt, needfix_closure, learning_commit_owed, plus the finalized card's status and card_sha256/card_bytes. include_card = none (default) | summary | full adds the card view. Errors are unchanged.

READ-ONLY: summarize latest processes; use detail='full' for legacy records.

Idempotently ensure exactly one callback dispatcher is running for the active repository, bound to the currently-selected coordinator target (B857). Called by the VS Code extension after every MCP handshake (activation, tab-deserialization, reload) and after an explicit coordinator-target switch -- never starts a second thread and never marks an uninitialized repository as degraded.

READ-ONLY: dispatcher running/stopped, selected coordinator target, repository identity, pending callback count, and last delivery/error.

Stop and unregister the active repository's callback dispatcher, if any. Called on workspace/repository switch and extension deactivation so no cross-repository read or delivery can happen afterward.

Detect and auto-recover a down-but-expected callback dispatcher.

Intended for the VS Code extension's periodic refresh: when dispatch is expected for this process (extension-owned coordinator or verified Claude manager) but the dispatcher is unregistered/stopped, lost its repo_id, or reports a start error, this re-ensures it in place. A healthy dispatcher, a manager-inbox session, or a process where dispatch is not expected is left untouched. Accumulated durable-outbox callbacks replay automatically once the dispatcher is back.

Idempotently ensure exactly one Source Graph indexing daemon is running for the active repository. Safe to call repeatedly (InitRepo, activation, tab-deserialization, reload) -- never starts a second thread and never fabricates a running daemon for an uninitialized repository.

READ-ONLY: Source Graph indexing daemon health for the active repository -- indexing/ready/degraded status, last report/error/time.

Force one bounded incremental (or first-ever full) Source Graph build now, non-overlapping with the periodic background refresh.

Stop and unregister the active repository's Source Graph indexing daemon, if any. Called on workspace/repository switch and extension deactivation so no cross-repository indexing thread survives.

BLOCKING READ/CLAIM: wait for a callback for this verified Claude Code manager session. Acknowledge the previous batch by passing its batch_id/lease_id as ack_batch_id/ack_lease_id here, or call aiworkhub_claude_callback_ack; an unacknowledged lease is retried, never lost.

WRITE: acknowledge one exact callback batch returned to this same verified Claude manager session.

READ-ONLY: zero-config detected languages/declared/installed tools.

READ-ONLY: scan bounded changed paths for known bug patterns.

Native and SARIF outputs preserve the same truth boundary: a static candidate is not reported as runtime-reproduced evidence.

READ-ONLY: recompute registered eval verdicts from retained rows.

A PASS over zero eligible rows or a summary/count/aggregate divergence is returned as blocking evidence. The tool never rewrites an artifact.

READ-ONLY: detect managed provider/worker instruction drift.

READ-ONLY: run registered precision@k/MRR cases through manager MCP wrapper.

Threads a real, repository-bound external_qualification.canonical_acceptance_authority per declared case attempt, so accepted_outcome_coverage is measured from canonical task evidence instead of staying permanently pending.

READ-ONLY: observed provider tokens plus separately-labelled prompt bytes.

READ-ONLY: per-mode/language precision from adjudicated registered rows.

READ-ONLY: report new quality identities and no-net-growth overflow.

READ-ONLY: evaluate preregistered matched A/B provider-usage rows.

Execute one repo-declared quality check repeatedly; shell is never used.

READ-ONLY: parse a repo-local coverage.py JSON artifact.

WRITE-GATED: atomically project repo-local coverage into Source Graph.

Run repo-declared .aiworkhub/quality.json build/test/lint/typecheck commands (argv arrays only, shell=False). Fails closed on malformed config. Diff/new-code-first: pass changed_paths to scope evidence.

READ-ONLY: full canonical evidence packet -- profile, declared checks, risk-based optional-gate policy metadata (not_available != passed), and the cross-provider read-only quality_reviewer contract.

READ-ONLY: run the deterministic positive/negative gate matrix.

READ-ONLY: unified repository/policy/Source Graph/provider readiness.

Provider access is reported as observed only when an adapter-specific bridge or credential readiness source proves it; installed CLI binaries alone remain installed_unverified_access.

detail="summary" (default) folds Source Graph's refresh-job report to identity plus state, providers to a flat {adapter_id: status} map, provider_route_contracts.route_families to one {family, status, count} row each, policy to its verdict fields, worker_finalization to its state fields, and each of provider_summary's route/capability lists and its route_status_questions block to a count plus a short id preview (or identity); with adapter_id given, providers and provider_observability.adapters/providers are filtered to that adapter. detail="evidence" behaves like "full": both return repo_policy.build_preflight exactly.

Recover retained worktrees stranded outside every reclamation path.

NF-2026-00279: the storage observability surface recommends this recovery, but it had no tool/MCP/CLI entry point, so an operator was told to run something they could not. This exposes it as a real action.

READ-ONLY first: confirm=False (the default) returns a report of the worktrees that would be re-registered and those that are orphaned-but- reclaimable, mutating nothing. confirm=True requires a non-empty reason, reinstates the provably-owned registrations, and records the reason in the audit log.

List repo-scoped NeedFix entries (bounded).

Show one NeedFix by id; a body over 1 KB folds to its own identity.

Measured 2026-10-09: 51 calls, avg 4 KB, max 12 KB, almost all of it the description and evidence bodies the filer wrote (NF-2026-01447). Each body whose own canonical bytes exceed core.NEEDFIX_BODY_MAX_BYTES is replaced by {summarized, bytes, length, sha256} so it stays addressable; a smaller body is returned verbatim and full=true returns every byte.

READ-ONLY: draft the NeedFixes one request's own review evidence justifies.

A NeedFix could not be drafted from the evidence that justifies it, so it was retyped. Measured 2026-09-08: of 204 manual filings, 76 had an accept/ reject/status/collect result within the previous 15 calls, 43 carried a 32-hex request id, and 355 of 540 typed identifiers (66%) appeared verbatim in the previous 15 tool results; 453 of 557 stored rows carry a hand-typed evidence dict at p50 549 B. Meanwhile 589 accepted-shape reviewer findings and 1,623 failed-gate payloads became a NeedFix only if someone retyped them, and reviewer cards are archived (1,796 so far), taking every unconverted finding with them.

Everything returned is mechanical: title from the failing check id or the finding summary, kind and severity from the finding category through a fixed map, scope_files from the card's changed paths, evidence from terminal_review.evidence (error, returncode, declared command) plus the finding's own path/line/check_id, evidence_refs from the attempt -artifact manifest reference and this request id, and provenance {origin: server_draft, request_id, verified: false}.

The DESCRIPTION is deliberately empty -- it is your judgement about what to do, not a fact on the card, and this never invents one. Writes nothing: file a candidate with needfix_add once you have written that description. finding_id / check_id narrow the draft to exactly one finding or one failing check.

Manager-authority add of a NeedFix (dedupe-aware).

kind must be one of: bug, feature, improvement, idea, technical_debt, optimization, benchmark_gap, documentation_drift, security_risk, investigation, roadmap_candidate, refactor, security, docs, other. Common synonyms are normalised server-side and reported as kind_normalized: gap->improvement, defect->bug, performance->optimization, design->refactor, dead_code->technical_debt, test_coverage->improvement. severity must be one of: critical, high, medium, low, info. status defaults to captured; its authoritative choices are published in the field hint. Store lifecycle and manager authority still govern it.

Replies with a receipt (aiworkhub.needfix_add_receipt.v1): id, dedupe_key, status, kind, severity, created_at, provenance.origin, deduped with existing_id when the dedupe key matched a live row (the existing row is returned, nothing new is written), kind_normalized. The row itself is one needfix_show away.

Manager update of mutable NeedFix fields.

None keeps a field. evidence is an explicit FULL REPLACE of the evidence object; evidence_patch is a JSON merge patch (keys merged, nested objects merged, null deletes a key) applied server-side to the stored object, so one measurement can be added without re-sending the rest. The two are mutually exclusive. evidence_refs_add/remove, tags_add/remove, scope_files_add and scope_symbols_add edit the lists in place (add appends missing values, remove filters). expected_updated_at is optimistic concurrency: the update is refused (needfix_update_stale) when the stored updated_at differs. kind vocabulary and synonym normalisation are as in needfix_add.

Replies with a delta receipt (aiworkhub.needfix_update_receipt.v1): id, status, fields_changed, updated_at, evidence_keys_after, event_id, kind_normalized. The updated audit event records the same fields_changed plus the evidence sha256 before and after.

Explicitly archive (soft, audited, restorable) a NeedFix.

Explicitly restore an archived NeedFix.

Audited hard delete of an already-archived NeedFix.

Bounded count of NeedFix entries.

List events for a NeedFix entry.

READ-ONLY: bounded outcome metrics from canonical task/review events.

Create one repository-bound SDLC case under verified manager authority.

Append one bounded stage receipt under verified manager authority.

READ-ONLY: bounded repository-bound case packet.

READ-ONLY: one bounded repository-bound stage packet.

Create the SDLC case bound to one canonical task under verified manager authority.

READ-ONLY: bounded case packet bound to one canonical task, or a typed unknown.

Preview an explicit workforce-bound task conversion.

The reply keeps plan_digest, plan_digest_accepted_alone and validation_roles_requirement -- the three facts the commit decision actually turns on -- and folds the signed plan body to its identity plus title/runner/topic/work_kind and the allowed_writes and required_outputs counts. include_plan=true returns the plan verbatim. Measured 2026-10-09 on NF-2026-01452: ~6 KB of plan echoed three times, because convert then refused plan_digest alone (NF-2026-01447). It no longer does, so the previewed plan never has to be resent.

Commit the exact previewed workforce-bound task conversion.

plan_digest alone is enough: the matching preview remembered the exact plan it signed and this commits that plan, so the body never has to be resent. The digest re-check is unchanged, so NeedFix drift between preview and commit still fails closed, and a digest this server no longer holds is refused with previewed_plan_unavailable rather than reconstructed.

Manager-only: atomically link a NeedFix to an existing, finished, accepted task.

Manager-only: reopen a NeedFix whose exact linked task was superseded.

List bounded repository Roadmap outcomes.

Show one Roadmap outcome.

List bounded audit events for one Roadmap outcome.

Join bounded Roadmap outcomes to canonical Task-DAG lifecycle.

Manager-only Roadmap proposal; does not create or launch a task.

Manager-only guarded Roadmap lifecycle transition.

Link one existing canonical task to a Roadmap outcome.