@staix/agent-hub 0.12.16 → 0.12.18

package/docs/specs/2026-09-19-agent-hub-design.md

@@ -1343,6 +1343,181 @@ whether to continue the native session or restart; this change provides no
 automatic session replacement. Status, tail and dashboard expose readings with
 source, measurement time and freshness beside quota information.
 
-The control contract is protocol 14. Recovery sources 9 through 13 remain
+Release 0.12.16 uses control protocol 14. Recovery sources 9 through 13 remain
 supported; protocol 13 identifies releases 0.12.4 through 0.12.15, while
 0.12.16 uses protocol 14.
+
+## Operator console and conductor (issues #190, #191, #193, #194, #195)
+
+`ahub console` owns one authenticated console connection. It shares tail's
+renderer, renders a DECSTBM stream and footer, and provides optional alternate
+screen panels. `up` opens it only with terminal input and output, unless
+`--no-console` is given. Tail remains a plain stream. Console commands use an
+allowlisted argv with stdin closed; lifecycle and native launches are excluded.
+Allow options require confirmation and never interpret nonempty input as an
+approval. Deny is direct. Pending requests include expiry and are withdrawn by
+`permission_closed` on any answer or cancellation. Answer audits have no title.
+Panels expose Peers, Approvals, Tasks, Queue and Events with bounded polling and
+Unicode cell widths, fall back below 80x24, and restore terminal state on exit.
+
+Console semantic colors (issue #201) use spans with a fixed terminal-native
+palette: cyan information, bold cyan active/selected labels, green availability
+and success, yellow attention/waiting, red failure/intervention, and restrained
+bright-black metadata. Offline peers, ordinary titles, action details and body
+lines use the default foreground. Existing labels, selection markers and
+confirmation prompts remain sufficient without color. Stream headers use event
+structure for their tone; body text is never parsed for meaning or passed
+through as terminal styling. Denial requests and observed expiry/cancellation
+are red; an answered remote closure lacks option-kind metadata and is not
+guessed to be a denial.
+
+`--color=auto|always|never` affects styling only. Auto requires terminal input
+and output, a non-dumb TERM, and absent/empty NO_COLOR. Always overrides those
+checks even for redirected stream output, without enabling panels or raw mode;
+never disables styling. Invalid values fail with usage text before connection.
+Plain `renderConsole` remains available, while `renderConsoleLines` exposes
+semantic spans. Geometry is computed from sanitized plain Unicode text before
+painting. `paint` sanitizes every span, inserts only fixed palette SGR sequences
+and resets each styled span. Interactive exits, signals, disconnect and errors
+retain the console restoration sequence. No new dependencies, protocol changes,
+polling or redraw triggers are added. Tail, logs and machine-readable output
+remain unchanged. Native light/dark readability and idle-CPU observations are
+separate smoke evidence, not inferred from fake-terminal tests.
+
+Agent shell CLI calls connect as the detected peer in tools mode. Hub launches
+set `AGENTHUB_PEER_ID`; the pinned installed Codex shell injects
+`CODEX_THREAD_ID` after environment filtering, and Claude uses `CLAUDECODE`.
+Malformed or conflicting markers fail closed. Console-only commands are denied
+before connecting, with no as-user escape. Refusals enter a bounded ids-only
+local audit spool which a running daemon consumes; this preserves the no-connect
+rule while making refusals visible on the console and in the log. A stopped
+daemon cannot show a live notice; it consumes remaining records on startup.
+This does not establish a security boundary against an unrestricted shell
+which can read the token. Native source evidence and live probe results remain
+separate in the smoke ledger.
+
+Exactly one explicit conductor role may be configured. Default-allow
+capabilities do not grant it; role authority is checked on each operation and
+refreshed on a subsequent connection. Shared MCP tools provide public status,
+public task history, actor-preserving assign/escalate, headless local/Kimi/Pi
+start, and conductor-owned persistent holds. TUI starts return launch commands.
+Assign/escalate need `assign` if the peer has a capabilities entry. Approval
+answers, durable queue resolution, budget overrides and lifecycle remain human
+operations. A conductor cannot release human or budget holds. Audit events are
+ids-only and report counts their actions.
+
+The conductor feed defaults to own tasks, also supports all and off, and uses
+the existing bus digest window. Repeated queued task/kind milestones replace
+the earlier pending notice; accepted or in-flight deliveries are preserved.
+Structured milestones carry public titles or PII stubs, never raw history
+notes or check output. Only aged approval summaries and needs-review delivery
+ids are important. Role/feed revocation withdraws pending feed notices. A
+completed task set produces one round notice until a new task joins; subsequent
+rounds count only newly joined tasks. Pure status supervision queues wait for
+the existing digest deadline rather than flushing at the ordinary batch-count
+threshold. Mixed traffic retains the ordinary admission behavior. The existing
+10-original digest ceiling and 200-entry queue ceiling still bound admission;
+larger windows may require multiple bounded deliveries.
+
+Supervision cost counts completed native turns that received feed notices,
+with whole-turn token readings when available. Other work may share a turn;
+these readings are not per-notice token attribution. Missing measurements are
+unknown. Native TUI conductor, sandbox and feed-on smoke results must be recorded
+as observed outcomes, separately from unit/fake protocol tests.
+
+Managed Claude launches with turn-free facts, task-idle sweeps or a conductor
+role install native observation hooks. A conductor receives them even when facts
+injection and task-idle sweeps are disabled; ordinary non-opt-in launches remain
+unchanged. SessionStart registers the native
+session and UserPromptSubmit starts observation; PreToolUse keeps a tool turn
+active and Stop closes it. Explicit caller settings remain authoritative and
+produce a warning when they replace these hooks. An ordinary terminal records a
+private launcher identity without creating an Orca terminal-recovery record.
+The facts control request accepts session/start/pre/post/stop phases and carries
+nativeInstanceId and nativeLaunchId alongside sessionId and transcriptPath.
+The command hook forwards launcher identity only for its matching state directory
+and peer; library calls targeting another hub do not inherit that identity.
+The daemon fences observations to its current instance and launcher, validates
+the session transcript, and rejects stale stop/post observations. Native prompt
+text is never included in those requests or events.
+
+A genuine native Stop requires the current daemon/launcher binding and an actual
+assistant end_turn transcript message at or after the native turn's first start,
+distinct from the completed-message baseline recorded at that start. Later tool
+activity does not move this turn-start boundary. Missing start evidence or a
+start from another session, launch or channel claim leaves completion unknown.
+Accepted completion consumes that start before the peer becomes idle, so another
+message cannot reuse it. A valid bound Stop request receives one prompt
+acknowledgement with pending=true, within the existing two-second hook deadline.
+The acknowledgement records observation only, never completion. After the hook
+can return, a deferred observer waits up to 1200 monotonic milliseconds for its
+transcript append to become visible. Each read and final consumption revalidate
+the captured start, session,
+launch, peer and claim. A seen previous-turn baseline still waits while a new
+current start exists; a consumed duplicate remains a no-op. Timeout, malformed or
+oversized evidence and superseded context leave completion unknown. This wait
+does not retry a user action or relax authority.
+The observer sends no second request reply and never changes global hook settings.
+The live harness also binds its final receipt to the current private launch id.
+Its opaque
+deduplication id binds session, launch and message; transport replacement or new
+activity cannot turn a replay into another completion. Unbound or idless legacy
+Stop events cannot certify completion or finish supervision. A current private
+launcher marker takes precedence over an older terminal-recovery launch id for
+native observation, while preserving the recovery records and their authority.
+Claude turn reports
+prefer unique native Stop events; historical logical-state counts are labelled
+as such, and an unobserved completion remains unknown. Channel idle, watchdog
+expiry, board approval and a tool reply do not independently establish native
+completion. The live harness waits for the current fixture/instance/session's
+final transcript end_turn and turn_duration after its last review before
+reporting a completed case or terminating its native TUI. It also requires the
+matching opaque native completion event, an idle peer and settled delivery rows.
+
+These additions use control protocol 15. Supported recovery sources include
+protocol 14 (0.12.16) alongside the previous source protocols.
+
+For release 0.12.17 only, the user explicitly accepted deferral of real Kimi ACP
+new-tool invocation and ordinary-role refusal T0 evidence on 2026-10-09. The
+managed OAuth account rejected its prompt with HTTP 403 for the weekly quota
+before any tool event; reset time is unknown and no configured native alternative
+was found. This prerequisite remains unverified. Actual Claude/Codex conductor
+workflows, Claude shell/channel observations, shared MCP/fake-adapter authority
+checks, real Kimi ACP initialization/session creation and full source gates are
+separately qualified. The deferral authorizes no purchase, credentials,
+provider/configuration change, account retry or authority relaxation. Once quota
+is available under an authorized account, the same isolated read-only status-tool
+and ordinary-role refusal probe must record a native tool event and daemon result
+before this Kimi prerequisite can be marked verified.
+
+## Amendment: per-task usage attribution (issue #200)
+
+Task usage is attributed by a rule at write time, never by a proportional guess:
+
+- A turn whose original delivery names exactly one distinct positive `refs.task` uses that id and `attribution: "delivery"`, even when the peer does not own the task. Two distinct delivery task ids fall through to the next rule.
+- Otherwise a peer with exactly one owned `in_progress` task uses that id and `attribution: "single_open"`.
+- Otherwise the record carries `attribution: "unattributed"` and no task id.
+
+The bus calls `onDeliver(peer, originals)` immediately before `peer.deliver`,
+after retaining the original delivery. The daemon consumes pending delivery
+identity during the synchronous busy/turn-start transition and clears it on
+delivery admission/failure. A user-started native turn cannot inherit an older
+delivery. Tokens and usage use the rule at write time; turn ends preserve the
+start-time attribution. Local worker usage carries its request-bound route
+policy task when one exists. Relay usage would use a route decision's task when
+present; the current daemon has no such relay usage writer, so collection is
+unchanged. Attributed PII records carry only a task id and `pii: true`.
+
+`ahub report --by task` and `--by task --json` use only events, never the board or
+task text. They report latest task class/outcome, attributed turn ends, first
+accept-to-first-approval wall time (unknown while not approved or without both
+boundaries), per-peer token increments and provider counters, and class rollups.
+Usage deduplication uses peer/source/id. Missing counters stay unknown, distinct
+from reported zero, and known-record counts identify measured subsets.
+
+Unattributed token and usage-record shares always appear. Older records without
+`attribution` stay in a distinct `before attribution` bucket, never redistributed
+to a task; both buckets appear even when empty. A zero denominator has unknown
+share. Export carries the new fields without task text. No prices or savings
+counterfactuals are derived. These additive fields retain events schema 1 and
+the existing control protocol. Plain `ahub report` remains unchanged.

package/docs/verification/2026-10-09-agent-shell-t0.md

@@ -0,0 +1,123 @@
+# Agent shell identity T0, issues #193 and #194
+
+## Evidence collected
+
+- Installed CLI reports `codex-cli 0.146.0` (`codex --version`, 2026-10-09). `codex app-server --help` supports configuration overrides and WebSocket listeners; its example names `shell_environment_policy.inherit=all`.
+- The [version-pinned native environment implementation](https://github.com/openai/codex/blob/rust-v0.146.0/codex-rs/protocol/src/shell_environment.rs) applies inheritance, default exclusions, custom exclusions, explicit values, and `include_only` in that order. It then injects `CODEX_THREAD_ID`. `AGENTHUB_PEER_ID` is an ordinary inherited variable and can be removed by filtering. The native thread marker is injected after filtering, which supplies a fallback without widening the user's environment policy.
+- The [version-pinned core wrapper](https://github.com/openai/codex/blob/rust-v0.146.0/codex-rs/core/src/exec_env.rs) explicitly documents thread-marker injection even with `include_only`.
+- The [current configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference) describes inheritance and filtering, and now describes a `filters` map alongside legacy `exclude` and `include_only`. Current documentation is not evidence that every new option exists in installed 0.146.0.
+- The hub's Codex adapter passes a child environment even without optional launch values. It now sets its own marker and removes stale vendor markers inherited from the caller. Recovery authority remains scrubbed by `childEnv`.
+
+## Native Codex observations (2026-10-09)
+
+- Real installed `codex exec --json --model gpt-5.5 --sandbox workspace-write`
+  completed a single fixed Python shell probe in an isolated git fixture.
+  With explicit `inherit=all`, the hub marker, native thread marker and harmless
+  canary were present; a Claude marker was absent. The disposable loopback
+  responder was reachable by the harness, while the native shell request failed
+  with `URLError`, errno 1. No sandbox or network exception was requested.
+- A second real run used `inherit=none`, an explicit PATH and
+  `include_only=["PATH"]`. The hub marker, native marker and canary still appeared
+  in the observed shell. This does not establish that filtering removed them;
+  the difference from the pinned environment construction is unresolved in this
+  installed host environment. The fallback is supported by source and marker
+  presence, without widening the caller's configured policy.
+- A real native MCP call under `workspace-write` completed `agent-hub.hub_status`
+  against the candidate bundle and an isolated conductor daemon. Native JSONL
+  recorded the MCP call completing, and the daemon independently recorded a
+  codex `conduct/status` event. Only this exact hub tool was approved through the
+  existing per-tool `approval_mode=approve` configuration; its daemon role check
+  still applied. This proves MCP access separately from the blocked shell path.
+- The first run with the user's configured `gpt-6.1-sol` failed before tools:
+  that slug was rejected by the installed ChatGPT-account endpoint. The probe's
+  explicit model selection did not change the user's configuration.
+
+## Native Claude observations (2026-10-09)
+
+- The final observer proof used source `20ad5e6`. Its read-only feed-off
+  continuation verified one completed native turn, 263,413 cached-inclusive
+  tokens, a matching opaque daemon Stop receipt, native idle and no pending
+  deliveries. The fresh feed-own run verified two actual owner completions and
+  independent file reviews, nine native finals matched by nine daemon Stops,
+  27 unique usage records and 1,888,242 tokens. Eight completed turns contained
+  supervision, totalling 1,292,922 tokens. The receipt matched the final native
+  message, session, launcher and instance; earlier incomplete captures below
+  were not retroactively marked complete.
+
+- In the original captures, Claude Code 2.1.295, Opus 5.5, ran the candidate MCP tools in real PTYs
+  after its five-hour quota reset. Both feed-off and feed-own fixtures started
+  local and headless Pi, proposed two tasks, reassigned Beta to Pi, held and
+  released both peers, and independently read the exact ALPHA/BETA files before
+  approving their tasks. The console independently audited four allow-once
+  answers in each fixture, covering the two writes and bounded file checks.
+- The real feed-off TUI displayed inbound review requests; the feed-own TUI
+  displayed actual supervision and review pushes. MCP success and channel
+  delivery were observed separately. A transient startup warning about the
+  server name did not prevent the later observed channel deliveries.
+- In the feed-own native TUI, the operator submitted the fixed Python probe
+  through `!`. Its actual command output was `AGENTHUB_PEER_ID=true`,
+  `CLAUDECODE=true`, `CLAUDE_CODE_SESSION_ID=true`, `CODEX_THREAD_ID=false`.
+  This is shell output captured before Claude's interpretation of it.
+- A subsequent feed-off run pinned to `da2ebbc` executed the same fixed probe
+  through the model's actual native Bash tool and separately through `!`.
+  Both actual command outputs showed the same three Claude/hub markers present
+  and `CODEX_THREAD_ID` absent. This closes the separate model-shell observation;
+  neither command printed environment values.
+- The original harness accepted hub idle too early and stopped both last
+  review turns before a native final answer. Native transcripts independently
+  show two completed turns in feed-off and five in feed-own, with the last
+  assistant message still `tool_use` in each case. The board approvals are real;
+  complete final-turn verification and production supervision accounting were
+  incomplete for those captures. The harness now requires the current daemon instance, its session,
+  the fixture-specific transcript, a final `end_turn` and `turn_duration` after
+  the last actual review. Missing measurements remain unknown.
+- The `da2ebbc` run verified the final native message UUID, message id,
+  `end_turn`, subsequent `turn_duration`, daemon instance, session and launcher.
+  Its complete transcript contains five completed turns and 21 unique usage
+  records, totalling 1,451,782 tokens including cached input. The daemon certified
+  only one native Stop, however. Its log refused the other completions as an
+  unavailable completed transcript message or completion predating the current
+  turn; the final refusal occurred before cleanup. A normal review receipt
+  remained queued. Actual task/file/final-answer evidence is valid, while full
+  runtime accounting and delivery settlement remain incomplete.
+- The `6034dd9` read-only continuation preserved both approved tasks and exact
+  files. It completed one native turn with four unique usage records and 261,483
+  cached-inclusive tokens, but the matching daemon Stop remained absent. After
+  a bounded retry, the Stop handler logged unavailable completion at
+  01:39:04.087 UTC; the native stop summary/duration appeared at 01:39:04.095 UTC.
+  With no overlapping operator prompt, this strongly supports a transcript
+  visibility barrier while the native hook waits. The strict harness timed out
+  incomplete and stopped its owned processes. The final message's thinking/text
+  rows carried identical usage counters in these observed transcripts; this
+  observation does not replace the final text/duration requirement.
+
+## Plain Claude and Kimi observations (2026-10-09)
+
+- Plain Claude 2.1.295, launched with the candidate MCP configuration but no
+  development-channel flag, completed one native `hub_status` call with an
+  independent daemon Claude status audit. Its only native tool calls were
+  ToolSearch and that status call. A unique operator push was bridge-accepted,
+  but no native pushed user row or response appeared in the observed
+  20.075-second window. This bounded negative observation is not a universal
+  claim about channel support. Actual channel-enabled review/supervision pushes
+  were observed separately in the conductor cases. The plain probe and cleanup
+  took 56.724 seconds and made no model file, shell, task or settings changes.
+- Real Kimi Code CLI 2.1.1 answered ACP `initialize` and created native session
+  `session_17eeb9dc-38d3-4685-b1aa-3db6a89b465c`. Its single prompt failed with
+  protocol error `-32000`, HTTP 403, for the managed account's weekly usage
+  limit before any requested tool event. No task-list/status result or ordinary
+  peer's conductor refusal was obtained. The owning CLI's safe provider list
+  showed only `managed:kimi-code`, type `kimi`, four models, OAuth, default
+  `kimi-code/k3`. No distinct configured provider was found. The reset time
+  remains unknown; no purchase, credential/configuration change or model retry
+  was attempted. Owned native processes and the fixture daemon were stopped.
+
+## Release disposition and remaining bounded live probe
+
+- On 2026-10-09 the user explicitly approved release 0.12.17 with only the Kimi native new-tool and ordinary-role refusal T0 evidence deferred. Kimi coverage remains unverified. This decision defers no other source/native gate and authorizes no purchase, credentials, provider/configuration change, account retry or authority relaxation.
+- Kimi ACP MCP: after native provider access is available under an authorized account, request the same read-only task list/status and ordinary-role refusal probes in isolated sessions. Verify actual native tool events/results and the daemon reply before marking this prerequisite verified. The existing quota failure proves neither new-tool access nor refusal behavior.
+
+## Verification limits
+
+- Codex shell and MCP probes used the root agent's serial resource slot. Claude `!`, model shell, enabled-channel pushes and the bounded plain-session comparison were observed in subsequent serial native cases. Kimi new-tool access remains unverified because its real account rejected the prompt before tools.
+- New unit and fake-adapter tests are prepared but have not been run by this worker. The root agent owns the final immutable-head checks.

package/docs/verified.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "documents": {
     "README.md": {
-      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
       "paths": [
         "package.json",
         "src/",
@@ -11,14 +11,14 @@
       ]
     },
     "docs/security.md": {
-      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
       "paths": [
         "src/",
         "templates/"
       ]
     },
     "docs/operations.md": {
-      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
       "paths": [
         "package.json",
         "src/",
@@ -30,11 +30,12 @@
         ".github/workflows/check.yml",
         "scripts/ci-gates.mjs",
         "scripts/ci-reuse.mjs",
-        ".github/workflows/release.yml"
+        ".github/workflows/release.yml",
+        "scripts/smoke-conductor.ts"
       ]
     },
     "docs/quickstart.md": {
-      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
       "paths": [
         "package.json",
         "src/",
@@ -42,7 +43,7 @@
       ]
     },
     "docs/agent-notes/adapters.md": {
-      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
       "paths": [
         "src/adapters/",
         "src/pi/",
@@ -55,7 +56,7 @@
       ]
     },
     "docs/agent-notes/benchmarks.md": {
-      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "verifiedAgainst": "8b7d7254f1bb5602ec5d658e7814e236f8fb43e7",
       "paths": [
         "scripts/benchmarks/",
         "test/benchmarks/",
@@ -67,7 +68,7 @@
       ]
     },
     "docs/agent-notes/budget.md": {
-      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
       "paths": [
         "src/hub/budget.ts",
         "src/cli/statusline-tee.ts",
@@ -79,18 +80,19 @@
       ]
     },
     "docs/agent-notes/bus.md": {
-      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
       "paths": [
         "src/hub/bus.ts",
         "src/hub/envelope.ts",
         "src/hub/limits.ts",
         "src/hub/delivery-journal.ts",
         "src/hub/inference.ts",
-        "src/hub/daemon.ts"
+        "src/hub/daemon.ts",
+        "src/hub/supervision.ts"
       ]
     },
     "docs/agent-notes/daemon.md": {
-      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
       "paths": [
         "src/hub/daemon.ts",
         "src/hub/control-client.ts",
@@ -107,11 +109,16 @@
         "src/cli/recovery-package.ts",
         "src/cli/facts-hook.ts",
         "src/pi/process-signature.ts",
-        "src/hub/context-window.ts"
+        "src/hub/context-window.ts",
+        "src/hub/conductor.ts",
+        "src/cli/console.ts",
+        "src/cli/console-state.ts",
+        "src/cli/identity.ts",
+        "src/cli/identity-audit.ts"
       ]
     },
     "docs/agent-notes/local-worker.md": {
-      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
       "paths": [
         "src/adapters/local-worker.ts",
         "src/local/",
@@ -120,7 +127,7 @@
       ]
     },
     "docs/agent-notes/models.md": {
-      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "verifiedAgainst": "8b7d7254f1bb5602ec5d658e7814e236f8fb43e7",
       "paths": [
         "src/models/",
         "src/hub/inference.ts",
@@ -129,7 +136,7 @@
       ]
     },
     "docs/agent-notes/tasks.md": {
-      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
       "paths": [
         "src/hub/tasks.ts",
         "src/hub/board.ts",
@@ -138,11 +145,13 @@
         "src/hub/task-sweep.ts",
         "src/cli/launch.ts",
         "src/cli/main.ts",
-        "src/cli/preview.ts"
+        "src/cli/preview.ts",
+        "src/hub/conductor.ts",
+        "src/hub/supervision.ts"
       ]
     },
     "docs/agent-notes/tests.md": {
-      "verifiedAgainst": "2f6274d007d47aa3db0976c4989021520c03a3ef",
+      "verifiedAgainst": "4b44b92dd2dc4b5515b6e87627fe4bdfcd6742c3",
       "paths": [
         "test/",
         "scripts/check.sh",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-hub",
-  "version": "0.12.16",
+  "version": "0.12.18",
   "description": "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   "license": "MIT",
   "type": "module",

package/plugins/agent-hub/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-hub",
-  "version": "0.12.16",
+  "version": "0.12.18",
   "description": "Channel between Claude Code and the agent-hub daemon: peer messages from Codex, Kimi and the local worker arrive as channel events; hub_send replies.",
   "author": {
     "name": "Young Joon Lee",

package/plugins/agent-hub/server.js

@@ -15291,8 +15291,8 @@ function projectContext(cwd, env = process.env) {
 function stateDirFor(cwd) {
   return projectContext(cwd).stateDir;
 }
-var PROTOCOL = 14;
-var RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, 12, 13, PROTOCOL];
+var PROTOCOL = 15;
+var RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, 12, 13, 14, PROTOCOL];
 function readControl(stateDir) {
   try {
     const status = JSON.parse(readFileSync2(join2(stateDir, "status.json"), "utf8"));
@@ -15403,7 +15403,7 @@ class ControlClient {
 // package.json
 var package_default = {
   name: "@staix/agent-hub",
-  version: "0.12.16",
+  version: "0.12.18",
   description: "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   license: "MIT",
   type: "module",
@@ -15503,7 +15503,18 @@ var TASK_TOOLS = [
   tool("hub_remember", "Save a decision, finding, contract or fail to the memory all agents share (claude-mem); the other agents also get it with their next message. A fail is an approach you tried that does not work, and why: the most useful note, it stops the others spending their quota on it. Do not retry what a fail note rules out without new evidence. Conclusions worth recalling, not chatter.", { text: str, title: str, kind: { type: "string", enum: [...NOTE_KINDS] }, task: id }, ["text"])
 ];
 var TASK_TOOL_NAMES = new Set(TASK_TOOLS.map((t) => t.name));
+var CONDUCTOR_TOOLS = [
+  tool("hub_status", "Inspect public team state, holds, quota windows, task counts and pending approval peer/tool/age. Only the configured conductor may use this tool.", {}),
+  tool("hub_task_show", "Read a task's public view and history. PII tasks remain stubs. Only the conductor may use this tool.", { id }, ["id"]),
+  tool("hub_task_assign", "Move a task to another peer, as the conductor. Requires assign capability when the conductor has an explicit capabilities list.", { id, peer: str }, ["id", "peer"]),
+  tool("hub_task_escalate", "Escalate a task through the normal task flow, as the conductor. Requires assign capability when explicitly listed.", { id }, ["id"]),
+  tool("hub_peer_start", "Start local, kimi or headless pi. Claude, Codex and Pi TUI requests return a command for the person to run, without launching a terminal.", { peer: { type: "string", enum: ["local", "kimi", "pi", "claude", "codex"] }, mode: { type: "string", enum: ["headless", "tui"] } }, ["peer"]),
+  tool("hub_peer_hold", "Hold a peer's deliveries as the conductor. This hold is separate from the person's hold and budget pauses.", { peer: str }, ["peer"]),
+  tool("hub_peer_release", "Release only the conductor hold you placed. Never lifts a person's hold or a budget pause.", { peer: str }, ["peer"])
+];
+var CONDUCTOR_TOOL_NAMES = new Set(CONDUCTOR_TOOLS.map((t) => t.name));
 var ROLE_TEXT = {
+  conductor: "conductor: plan and split work into tasks with owners, watch the team with hub_status, move stalled work, and ensure every task is reviewed (review it yourself only if you also hold reviewer). Report results and open decisions to the person. Do not implement tasks you handed out. Never ask a peer to answer an approval; ask the person for human-only actions. You may release only holds you placed, never human holds or budget pauses.",
   planner: "planner: break work into tasks with hub_task_propose (one outcome each, the right class, paths in refs, and after: [ids] for work that must wait for other tasks) instead of doing everything yourself.",
   implementer: "implementer: accept tasks assigned to you, do them, and finish with hub_task_done (summary: what changed, why, and the check you ran with its result; refs). Decline what you cannot do. Before starting work nobody assigned you, claim it with hub_task_propose naming yourself as owner, with the paths in refs. With a claim or an accept, give a plan: the files, symbols and signatures you will change and where new code goes.",
   verifier: "verifier: run the checks a task names and report what passed and what did not in hub_task_done.",
@@ -15690,7 +15701,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         inputSchema: { type: "object", properties: { delivery_id: { type: "string" }, delivery_generation: { type: "string" } }, required: ["delivery_id", "delivery_generation"], additionalProperties: false }
       }
     ],
-    ...TASK_TOOLS
+    ...TASK_TOOLS,
+    ...CONDUCTOR_TOOLS
   ]
 }));
 server.setRequestHandler(CallToolRequestSchema, async (req) => {
@@ -15720,7 +15732,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
     const sent = `sent to: ${res.targets.join(", ") || "(no other peers attached)"}`;
     return text(typeof res.notice === "string" ? `${sent}; ${res.notice}` : sent);
   }
-  if (TASK_TOOL_NAMES.has(name)) {
+  if (TASK_TOOL_NAMES.has(name) || CONDUCTOR_TOOL_NAMES.has(name)) {
     if (!hub)
       return text(offline());
     const res = await hub.request({ t: "task", op: name, args: args ?? {} });

package/src/adapters/acp.ts

@@ -2,7 +2,7 @@ import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
 import { createInterface } from "node:readline";
 import { renderDigest, replyAudience, replyParent, type Envelope, type PeerId } from "../hub/envelope.ts";
 import { BasePeer } from "../hub/peers.ts";
-import { childEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
+import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 
 export interface PermissionOption {
   optionId: string;
@@ -135,7 +135,7 @@ export class AcpPeer extends BasePeer {
   async start(): Promise<void> {
     const [bin, ...args] = this.opts.cmd;
     // Its own process group, stopped as a whole (#115, as Codex's in #113): an agent CLI may be a launcher with a native child.
-    const proc = spawn(bin!, args, { cwd: this.opts.cwd, env: childEnv({ ...process.env, ...(this.opts.env ?? {}) }), stdio: ["pipe", "pipe", "pipe"], detached: true });
+    const proc = spawn(bin!, args, { cwd: this.opts.cwd, env: peerChildEnv(this.id, { ...process.env, ...(this.opts.env ?? {}) }), stdio: ["pipe", "pipe", "pipe"], detached: true });
     this.proc = proc;
     trackGroup(proc);
     proc.on("error", (e) => this.down(`spawn failed: ${e.message}`));

package/src/adapters/claude-channel.ts

@@ -8,7 +8,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { ControlClient, stateDirFor } from "../hub/control-client.ts";
 import { VERSION } from "../version.ts";
-import { DEFAULT_ROLES, roleContract, TASK_TOOL_NAMES, TASK_TOOLS } from "../hub/hub-tools.ts";
+import { CONDUCTOR_TOOLS, CONDUCTOR_TOOL_NAMES, DEFAULT_ROLES, roleContract, TASK_TOOL_NAMES, TASK_TOOLS } from "../hub/hub-tools.ts";
 import { frame, replyParent, sanitize, HUB_MESSAGE_INSTRUCTION, type Envelope } from "../hub/envelope.ts";
 
 // A native session is pinned at launch. Unlike a new CLI invocation after `cd`,
@@ -201,6 +201,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           },
         ]),
     ...TASK_TOOLS,
+    ...CONDUCTOR_TOOLS,
   ],
 }));
 
@@ -225,7 +226,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
     const sent = `sent to: ${res.targets.join(", ") || "(no other peers attached)"}`;
     return text(typeof res.notice === "string" ? `${sent}; ${res.notice}` : sent);
   }
-  if (TASK_TOOL_NAMES.has(name)) {
+  if (TASK_TOOL_NAMES.has(name) || CONDUCTOR_TOOL_NAMES.has(name)) {
     if (!hub) return text(offline());
     const res = await hub.request({ t: "task", op: name, args: args ?? {} });
     return text(res.ok ? res.text : `error: ${res.error}`);

package/src/adapters/codex-appserver.ts

@@ -3,7 +3,7 @@ import type { Server, ServerWebSocket } from "bun";
 import { renderDigest, replyAudience, replyParent, type Envelope, type PeerId } from "../hub/envelope.ts";
 import { BasePeer } from "../hub/peers.ts";
 import { codexContext, type ContextReading } from "../hub/context-window.ts";
-import { childEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
+import { peerChildEnv, stopOwnedProcess, trackGroup } from "../hub/child-process.ts";
 
 export interface CodexOptions {
   /** Port the TUI attaches to: `codex --enable tui_app_server --remote ws://127.0.0.1:<proxyPort>`. */
@@ -305,9 +305,10 @@ export class CodexPeer extends BasePeer {
       throw new Error(`port ${port} already answers /healthz: an app-server the hub does not own is running (orphan from a crashed hub?)`);
     }
     let gone = "";
+    const env = peerChildEnv("codex", { ...process.env, ...(this.opts.env ?? {}) });
     this.proc = spawn(this.opts.bin ?? "codex", ["app-server", "--listen", `ws://127.0.0.1:${port}`, ...(this.opts.extraArgs ?? [])], {
       cwd: this.opts.cwd,
-      env: childEnv({ ...process.env, ...(this.opts.env ?? {}) }),
+      env,
       stdio: ["ignore", "ignore", "pipe"],
       detached: true, // its own process group, stopped as a whole (#113): `codex` is a launcher with a native child
     });