@staix/agent-hub 0.12.15 → 0.12.17

package/src/hub/bus.ts

@@ -82,6 +82,8 @@ function resolveTo(to: PeerId[], originals: Envelope[] | undefined): PeerId[] {
 
 const SEEN_CAP = 2048;
 const MAX_ATTEMPTS = 3;
+// ponytail: one digest carries at most ten originals; larger supervision windows split into bounded deliveries.
+// Revisit this ceiling after measuring native supervision cost, rather than bypassing the delivery limit.
 const DIGEST_MAX = 10;
 const NOTES_KEPT = 10;
 
@@ -100,6 +102,8 @@ export class Bus {
   private readonly manualPaused = new Set<PeerId>();
   private readonly timers = new Map<PeerId, ReturnType<typeof setTimeout>>();
   private readonly draining = new Set<PeerId>();
+  /** Still pending while an asynchronous condensation runs; never includes native dispatches. */
+  private readonly preparing = new Map<PeerId, Envelope[]>();
   private readonly seen = new Map<string, Envelope>();
   private readonly taps = new Set<(e: BusEvent) => void>();
   private readonly withdrawn = new Set<string>();
@@ -119,6 +123,10 @@ export class Bus {
    * and is never corrected once the queue empties (measured: status.json kept `queued 4` on an empty queue).
    */
   onQueues?: () => void;
+  /** Actual transport admission, using originals even when a digest was condensed. Never an enqueue metric. */
+  onDelivered?: (peer: PeerId, originals: Envelope[]) => void;
+  /** Synchronous native failure observation, before queue callbacks can finish turn metrics. */
+  onDeliveryFailed?: (peer: PeerId) => void;
   private recoveryHeld = false;
   private steering = 0;
   private condensing = 0;
@@ -389,7 +397,9 @@ export class Bus {
     const id = receipt.id;
     const before = this.journal.get(id);
     const state: JournalDeliveryState = receipt.state === "accepted" ? "accepted" : receipt.state === "completed" ? "completed" : receipt.state === "failed_safe" ? "failed" : "needs_review";
+    if (state === "failed" || state === "needs_review") this.deliveryFailed(peer);
     this.journal.transition(id, state, receipt.reason);
+    if (before?.state === "dispatching" && (state === "accepted" || state === "completed")) this.delivered(peer, before.originals);
     if (state === "failed") {
       if (before) this.failed(peer, before.originals, before.originals.some((e) => e.private) ? "private delivery failed" : receipt.reason);
     }
@@ -525,7 +535,8 @@ export class Bus {
         this.activeDeliveries.set(deliveryId, id);
         if (this.journal) this.durableHandoff(id, deliveryId, [env], [env]);
         const steerResult = this.journal ? peer.steer([env], deliveryId) : peer.steer([env]);
-        steerResult.then(() => {}).catch(() => {
+        steerResult.then(() => { this.delivered(id, [env]); }).catch(() => {
+          this.deliveryFailed(id);
           if (this.journal) this.journal.transition(deliveryId, "needs_review", "adapter steering outcome is uncertain");
           this.activeDeliveries.delete(deliveryId);
           if (!this.journal) this.enqueue(id, env, true);
@@ -570,8 +581,7 @@ export class Bus {
    * dropped if the refused steer tries to queue it later.
    */
   withdraw(envelopeId: string): boolean {
-    this.withdrawn.add(envelopeId);
-    if (this.withdrawn.size > 256) this.withdrawn.delete(this.withdrawn.values().next().value as string);
+    this.markWithdrawn(envelopeId);
     let removed = false;
     for (const queue of this.queues.values()) {
       const i = queue.findIndex((e) => e.id === envelopeId);
@@ -582,6 +592,49 @@ export class Bus {
     return removed;
   }
 
+  /** Revoke pending feed copies only; accepted/dispatching journal records and native turns are untouched. */
+  revokeSupervision(peer: PeerId): number {
+    const queue = this.queues.get(peer);
+    if (!queue && !this.preparing.has(peer)) return 0;
+    let removed = 0;
+    const discarded = new Set<string>();
+    for (let i = (queue?.length ?? 0) - 1; i >= 0; i--) {
+      const env = queue![i]!;
+      if (env.from !== HUB || !env.refs?.supervision) continue;
+      queue!.splice(i, 1);
+      removed++;
+      discarded.add(env.id);
+      this.markWithdrawn(env.id);
+      this.discardQueued(peer, env, "supervision role or feed revoked");
+    }
+    for (const env of this.preparing.get(peer) ?? []) {
+      if (env.from !== HUB || !env.refs?.supervision || discarded.has(env.id)) continue;
+      this.markWithdrawn(env.id);
+      this.discardQueued(peer, env, "supervision role or feed revoked during preparation");
+      removed++;
+    }
+    if (removed) { this.persist(); this.onQueues?.(); }
+    return removed;
+  }
+
+  private discardQueued(peer: PeerId, env: Envelope, reason: string): void {
+    if (this.journal) this.pendingOutcomes.push({ id: crypto.randomUUID(), peer, state: "discarded", createdAt: Date.now(), originals: [env], out: [], reason });
+    this.emit({ t: "stale", env, peer, reason });
+  }
+
+  private delivered(peer: PeerId, originals: Envelope[]): void {
+    try { this.onDelivered?.(peer, originals); } catch { /* observation must never affect delivery settlement */ }
+  }
+
+  private deliveryFailed(peer: PeerId): void {
+    try { this.onDeliveryFailed?.(peer); } catch { /* observation must never affect delivery settlement */ }
+  }
+
+  private markWithdrawn(id: string): void {
+    this.withdrawn.add(id);
+    if (this.withdrawn.size > 256) this.withdrawn.delete(this.withdrawn.values().next().value as string);
+  }
+
   queued(id: PeerId): number {
     return this.queues.get(id)?.length ?? 0;
   }
@@ -599,8 +652,23 @@ export class Bus {
     if (this.withdrawn.has(env.id)) return;
     const queue = this.queues.get(id) ?? [];
     this.queues.set(id, queue);
-    if (front) queue.unshift(env);
-    else queue.push(env);
+    const key = env.from === HUB && env.refs?.supervision ? env.refs.supervisionKey : undefined;
+    const replace = !front && key ? queue.findIndex((old) => old.from === HUB && old.refs?.supervision && old.refs.supervisionKey === key && !this.attempts.has(`${id}:${old.id}`)) : -1;
+    const preparing = !front && key ? this.preparing.get(id)?.find((old) => old.from === HUB && old.refs?.supervision && old.refs.supervisionKey === key && !this.attempts.has(`${id}:${old.id}`) && !this.withdrawn.has(old.id)) : undefined;
+    let queuedEnv = preparing ? { ...env, ts: Math.min(preparing.ts, env.ts) } : env;
+    if (replace >= 0) {
+      const old = queue[replace]!;
+      // Keep the first milestone's deadline, so continuous updates cannot create another batching window.
+      queuedEnv = { ...queuedEnv, ts: Math.min(old.ts, queuedEnv.ts) };
+      queue[replace] = queuedEnv;
+      this.markWithdrawn(old.id);
+      this.discardQueued(id, old, "superseded supervision milestone");
+    } else if (front) queue.unshift(queuedEnv);
+    else queue.push(queuedEnv);
+    if (preparing && !this.withdrawn.has(preparing.id)) {
+      this.markWithdrawn(preparing.id);
+      this.discardQueued(id, preparing, "superseded supervision milestone during preparation");
+    }
     if (queue.length > this.opts.queueCap) {
       const victim = queue.findIndex((e) => e.priority !== "important");
       const [lost] = queue.splice(victim === -1 ? 0 : victim, 1);
@@ -614,7 +682,8 @@ export class Bus {
 
   /** 0 = deliver now; otherwise how long the oldest envelope still has to wait for company. */
   private wait(queue: Envelope[]): number {
-    if (queue.length >= this.opts.batchMax || queue.some((e) => e.priority === "important")) return 0;
+    const supervisionOnly = queue.every((e) => e.from === HUB && e.refs?.supervision && e.priority === "status");
+    if ((!supervisionOnly && queue.length >= this.opts.batchMax) || queue.some((e) => e.priority === "important")) return 0;
     return Math.max(0, queue[0]!.ts + this.opts.batchMs - Date.now());
   }
 
@@ -656,6 +725,7 @@ export class Bus {
         // may checkpoint during that wait; it must not checkpoint the batch out of existence.
         if (!this.journal) this.prefaces.delete(id);
         const batch = this.take(id, queue, !this.journal);
+        this.preparing.set(id, batch);
         const delivery = preface ? [preface, ...batch] : batch;
         const mayCondense = this.opts.condense && !delivery.some((e) => e.priority === "important");
         this.condensing += mayCondense ? 1 : 0;
@@ -679,11 +749,12 @@ export class Bus {
         for (const e of out) if (!this.seen.has(e.id)) this.seen.set(e.id, e);
         while (this.seen.size > SEEN_CAP) this.seen.delete(this.seen.keys().next().value as string);
         this.lastDelivery.set(id, { out, originals: delivery });
+        this.preparing.delete(id); // from here on the transport/journal owns settlement
         const deliveryId = crypto.randomUUID();
         if (this.journal) { this.durableHandoff(id, deliveryId, delivery, out); this.activeDeliveries.set(deliveryId, id); }
         try {
           if (this.journal) await peer.deliver(out, deliveryId);
-          else await peer.deliver(out);
+          else { await peer.deliver(out); this.delivered(id, delivery); }
         } catch {
           if (this.journal) this.uncertain(id, deliveryId, "adapter delivery outcome is uncertain");
           else this.failed(id, delivery);
@@ -691,11 +762,11 @@ export class Bus {
         }
       }
     } catch { this.storageError = "delivery journal unavailable"; }
-    finally { this.draining.delete(id); this.onQueues?.(); }
+    finally { this.preparing.delete(id); this.draining.delete(id); this.onQueues?.(); }
   }
 
   private isRelevant(id: PeerId, env: Envelope): boolean {
-    return this.opts.relevant?.(id, env) ?? true;
+    return !this.withdrawn.has(env.id) && (this.opts.relevant?.(id, env) ?? true);
   }
 
   /**
@@ -704,7 +775,7 @@ export class Bus {
    * this recipient's copy goes: the other queues keep theirs, and no other delivery record changes.
    */
   private dropIrrelevant(id: PeerId, queue: Envelope[]): boolean {
-    if (!this.opts.relevant) return false;
+    if (!this.opts.relevant && !this.withdrawn.size) return false;
     let dropped = false;
     for (let i = queue.length - 1; i >= 0; i--) {
       const env = queue[i]!;
@@ -757,6 +828,7 @@ export class Bus {
   }
 
   private failed(id: PeerId, envs: Envelope[], reason = "delivery failed without an error detail"): void {
+    if (!this.journal) this.deliveryFailed(id);
     this.lastFailure.set(id, reason.replace(/\s+/g, " ").slice(0, 300));
     if (envs.some((env) => !(env.from === HUB && env.kind === "presence") && (this.attempts.get(`${id}:${env.id}`) ?? 0) + 1 >= MAX_ATTEMPTS)) {
       this.failureStreak.set(id, (this.failureStreak.get(id) ?? 0) + 1);

package/src/hub/child-process.ts

@@ -11,6 +11,17 @@ export function childEnv(source: NodeJS.ProcessEnv = process.env): NodeJS.Proces
   return env;
 }
 
+/** Every native child owns its marker; caller vendor markers must not leak across peers (#193). */
+export function peerChildEnv(peer: string, source: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  const env = childEnv(source);
+  delete env.CLAUDECODE;
+  delete env.CLAUDE_CODE_SESSION_ID;
+  delete env.CODEX_THREAD_ID;
+  delete env.AGENTHUB_PEER_ID;
+  env.AGENTHUB_PEER_ID = peer;
+  return env;
+}
+
 /** One process: its identity is the pid with its start time (`lstart`, which exec keeps); group and command are evidence. */
 export interface ProcRow {
   pid: number;

package/src/hub/conductor.ts

@@ -0,0 +1,196 @@
+import { Database } from "bun:sqlite";
+import type { Task } from "./board.ts";
+import { CONDUCTOR_TOOL_NAMES } from "./hub-tools.ts";
+import type { HubEvent } from "./events.ts";
+import type { SupervisionFeed } from "./supervision.ts";
+import type { Budget } from "./budget.ts";
+
+/** The production ProgressObserver sink forwards structured verdicts, never its observations/reasoning. */
+export function conductorProgressSink(record: (event: HubEvent) => void, feed: Pick<SupervisionFeed, "milestone">): (event: HubEvent) => void {
+  return event => { record(event); if (event.type === "stuck") feed.milestone(event.task, "stuck", { reason: event.category }); };
+}
+
+export function publicPeerBudget(status: ReturnType<Budget["status"]>, nameable: (text: string) => boolean): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(status).map(([peer, value]) => [peer, {
+    windows: value.windows.map(window => ({ id: window.id, used: window.used, at: window.at, stale: window.stale,
+      ...(window.resetsAt === undefined ? {} : { resetsAt: window.resetsAt }),
+      ...(window.windowMins === undefined ? {} : { windowMins: window.windowMins }),
+      source: nameable(window.source) ? window.source : "[quota source withheld]",
+    })),
+    ...(value.paused ? { paused: { since: value.paused.since, resetsAt: value.paused.resetsAt, reason: "quota" } } : {}),
+  }]));
+}
+
+const PEER = /^[a-z][a-z0-9-]{0,31}$/;
+const peerId = (value: unknown): string => {
+  if (typeof value !== "string" || /\s/.test(value) || !PEER.test(value) || ["user", "hub", "digest"].includes(value)) throw new Error("peer must be a valid agent peer id");
+  return value;
+};
+
+/** Validate before listening; missing configuration grants nobody the conductor role. */
+export function conductorPeer(roles: unknown): string | null {
+  if (roles === undefined) return null;
+  if (!roles || typeof roles !== "object" || Array.isArray(roles)) throw new Error("roles must be an object of peer role lists");
+  let conductor: string | null = null;
+  for (const [peer, list] of Object.entries(roles)) {
+    peerId(peer);
+    if (!Array.isArray(list) || list.some((r) => typeof r !== "string")) throw new Error(`roles.${peer} must be a list of role names`);
+    if (!list.includes("conductor")) continue;
+    if (conductor !== null) throw new Error("roles may name at most one conductor peer");
+    conductor = peer;
+  }
+  return conductor;
+}
+
+/** The role check always comes first; default-allow capabilities cannot grant a role. */
+export function requireConductor(peer: string, roles: unknown, capabilities: Record<string, unknown> = {}, assign = false): void {
+  if (conductorPeer(roles) !== peer) throw new Error("this operation requires the explicit conductor role");
+  if (assign && Object.hasOwn(capabilities, peer)) {
+    const caps = capabilities[peer];
+    if (!Array.isArray(caps) || !caps.includes("assign")) throw new Error(`${peer} requires assign capability for this operation`);
+  }
+}
+
+export interface ConductorHold { peer: string; actor: string; since: number }
+
+/** Actor ownership survives restart. No titles, plans, summaries or memory writes. */
+export class ConductorHolds {
+  private readonly db: Database;
+  constructor(dbPath: string, private readonly now: () => number = Date.now) {
+    this.db = new Database(dbPath, { create: true });
+    this.db.run("CREATE TABLE IF NOT EXISTS conductor_holds (peer TEXT PRIMARY KEY, actor TEXT NOT NULL, since INTEGER NOT NULL)");
+    this.db.run("CREATE TABLE IF NOT EXISTS supervision_rounds (peer TEXT PRIMARY KEY, signature TEXT NOT NULL)");
+  }
+  get(peer: string): ConductorHold | null {
+    return this.db.query("SELECT peer, actor, since FROM conductor_holds WHERE peer = ?").get(peer) as ConductorHold | null;
+  }
+  has(peer: string): boolean { return this.get(peer) !== null; }
+  list(): ConductorHold[] { return this.db.query("SELECT peer, actor, since FROM conductor_holds ORDER BY peer").all() as ConductorHold[]; }
+  readRound(peer: string): string | undefined { return (this.db.query("SELECT signature FROM supervision_rounds WHERE peer = ?").get(peer) as { signature: string } | null)?.signature; }
+  writeRound(peer: string, signature: string): void { this.db.query("INSERT INTO supervision_rounds (peer, signature) VALUES (?, ?) ON CONFLICT(peer) DO UPDATE SET signature = excluded.signature").run(peer, signature); }
+  hold(peer: string, actor: string): ConductorHold {
+    peerId(peer); peerId(actor);
+    // INSERT OR IGNORE cannot take ownership of an earlier conductor's hold.
+    this.db.query("INSERT OR IGNORE INTO conductor_holds (peer, actor, since) VALUES (?, ?, ?)").run(peer, actor, this.now());
+    const hold = this.get(peer)!;
+    if (hold.actor !== actor) throw new Error(`peer ${peer} is held by another conductor`);
+    return hold;
+  }
+  release(peer: string, actor: string): ConductorHold {
+    peerId(peer); peerId(actor);
+    const hold = this.get(peer);
+    if (!hold || hold.actor !== actor) throw new Error("you may release only a conductor hold you placed");
+    this.db.query("DELETE FROM conductor_holds WHERE peer = ? AND actor = ?").run(peer, actor);
+    return hold;
+  }
+  /** The daemon must authenticate a human console and check budget/local constraints first. */
+  releaseByOperator(peer: string): ConductorHold | null {
+    peerId(peer);
+    const hold = this.get(peer);
+    if (hold) this.db.query("DELETE FROM conductor_holds WHERE peer = ?").run(peer);
+    return hold;
+  }
+  close(): void { this.db.close(); }
+}
+
+export type ConductorStart = { peer: "local" | "kimi" | "pi"; mode: "headless" } | { peer: "claude" | "codex" | "pi"; mode: "tui"; command: string };
+/** Preview commands come from the same launch planner the CLI uses, never caller-supplied shell text. */
+export function conductorStart(peer: unknown, mode: unknown, preview: (peer: "claude" | "codex" | "pi") => string): ConductorStart {
+  if (mode !== undefined && mode !== "headless" && mode !== "tui") throw new Error("mode must be headless or tui");
+  if (peer === "claude" || peer === "codex" || (peer === "pi" && mode === "tui")) return { peer, mode: "tui", command: preview(peer) };
+  if ((peer === "local" || peer === "kimi" || peer === "pi") && mode !== "tui") return { peer, mode: "headless" };
+  throw new Error("only local, kimi and headless pi may be started by the conductor");
+}
+
+const numberOrNull = (v: unknown): number | null => typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : null;
+export interface ConductorStatusInput {
+  peers: Array<{ peer: string; state?: string; attached?: boolean; queued?: number; needsReview?: number; manualHeld?: boolean; hold?: ConductorHold | null; budgetPause?: { since?: number; resetsAt?: number } | null; windows?: Array<{ id: string; used?: number; resetsAt?: number; at?: number; source?: string }> }>;
+  taskCounts: Record<string, number>;
+  approvals: Array<{ peer: string; tool?: string; at?: number }>;
+}
+/** Explicit projection, never spreads a queue, permission request or quota pause containing private text. */
+export function publicConductorStatus(input: ConductorStatusInput, now = Date.now()): Record<string, unknown> {
+  return {
+    peers: input.peers.map((p) => ({
+      peer: p.peer, state: p.state ?? "unknown", attached: p.attached ?? null,
+      queued: numberOrNull(p.queued), needsReview: numberOrNull(p.needsReview),
+      manualHold: p.manualHeld === undefined ? null : { held: p.manualHeld, actor: p.manualHeld ? "user" : null },
+      conductorHold: p.hold ? { actor: p.hold.actor, since: numberOrNull(p.hold.since) } : null,
+      budgetPause: p.budgetPause ? { since: numberOrNull(p.budgetPause.since), resetsAt: numberOrNull(p.budgetPause.resetsAt) } : null,
+      windows: p.windows === undefined ? null : p.windows.map((w) => ({ id: w.id, used: numberOrNull(w.used), resetsAt: numberOrNull(w.resetsAt), at: numberOrNull(w.at), source: w.source ?? null })),
+    })),
+    taskCounts: Object.fromEntries(Object.entries(input.taskCounts).map(([state, count]) => [state, numberOrNull(count)])),
+    approvals: input.approvals.map((a) => ({ peer: a.peer, tool: a.tool ?? null, ageMs: a.at === undefined || !Number.isFinite(a.at) ? null : Math.max(0, now - a.at) })),
+  };
+}
+
+/** publicView must use Tasks.publicView(task, true), including its screened history. */
+export function publicConductorTask(task: Task, publicView: (task: Task) => Record<string, unknown>): Record<string, unknown> {
+  const view = publicView(task);
+  if (view.title === "[pii]") return { id: task.id, title: "[pii]", detail: "[pii]", class: task.class, state: task.state, owner: task.owner, reviewer: task.reviewer, history: [] };
+  return { ...view, history: Array.isArray(view.history) ? view.history : [] };
+}
+
+export interface ConductEvent {
+  kind: "conduct"; actor: string; action: string; task?: number; peer?: string;
+}
+export interface ConductorHooks {
+  roles(): unknown;
+  capabilities(): Record<string, unknown>;
+  status(): ConductorStatusInput;
+  task(id: number): Task | undefined;
+  publicView(task: Task): Record<string, unknown>;
+  /** These callbacks must call Tasks, never Board.update. */
+  assign(actor: string, id: number, peer: string): Promise<unknown>;
+  escalate(actor: string, id: number): Promise<unknown>;
+  preview(peer: "claude" | "codex" | "pi"): string;
+  start(peer: "local" | "kimi" | "pi"): Promise<unknown>;
+  known(peer: string): boolean;
+  pause(peer: string): void;
+  validateRelease?(peer: string): Promise<void>;
+  /** Re-check manual, budget, recovery and remaining conductor holds before Bus.resume. */
+  release(peer: string): void;
+  /** Log and console notice plus events.jsonl, using this ids-only payload. Must not throw. */
+  audit(event: ConductEvent): void;
+}
+
+export class Conductor {
+  constructor(private readonly holds: ConductorHolds, private readonly hooks: ConductorHooks) {}
+  async execute(actor: string, tool: string, args: Record<string, unknown>): Promise<unknown> {
+    if (!CONDUCTOR_TOOL_NAMES.has(tool)) throw new Error("unknown conductor tool");
+    requireConductor(actor, this.hooks.roles(), this.hooks.capabilities(), tool === "hub_task_assign" || tool === "hub_task_escalate");
+    const action = tool.slice(4);
+    const emit = (extra: Pick<ConductEvent, "task" | "peer"> = {}) => {
+      try { this.hooks.audit({ kind: "conduct", actor, action, ...extra }); } catch { /* never throw after a task or hold write */ }
+    };
+    if (tool === "hub_status") { const result = publicConductorStatus(this.hooks.status()); emit(); return result; }
+    if (tool.startsWith("hub_task_")) {
+      if (typeof args.id !== "number" || !Number.isSafeInteger(args.id) || args.id <= 0) throw new Error("id must be a positive integer");
+      const task = this.hooks.task(args.id);
+      if (!task) throw new Error(`no task #${args.id}`);
+      if (tool === "hub_task_show") { const result = publicConductorTask(task, this.hooks.publicView); emit({ task: task.id }); return result; }
+      if (tool === "hub_task_assign") {
+        const peer = peerId(args.peer);
+        await this.hooks.assign(actor, task.id, peer); emit({ task: task.id, peer });
+      } else { await this.hooks.escalate(actor, task.id); emit({ task: task.id }); }
+      // Task callbacks may return raw objects; always re-read and apply the public view.
+      const updated = this.hooks.task(task.id);
+      return updated ? publicConductorTask(updated, this.hooks.publicView) : { id: task.id };
+    }
+    if (tool === "hub_peer_start") {
+      const start = conductorStart(args.peer, args.mode, this.hooks.preview);
+      if (start.mode === "headless") await this.hooks.start(start.peer);
+      emit({ peer: start.peer }); return start;
+    }
+    const peer = peerId(args.peer);
+    if (!this.hooks.known(peer)) throw new Error(`unknown peer: ${peer}`);
+    if (tool === "hub_peer_hold") { this.holds.hold(peer, actor); this.hooks.pause(peer); }
+    else {
+      if (this.holds.get(peer)?.actor !== actor) throw new Error("you may release only a conductor hold you placed");
+      await this.hooks.validateRelease?.(peer);
+      requireConductor(actor, this.hooks.roles(), this.hooks.capabilities());
+      this.holds.release(peer, actor); this.hooks.release(peer);
+    }
+    emit({ peer }); return { peer, held: this.holds.has(peer) };
+  }
+}

package/src/hub/context-window.ts

@@ -0,0 +1,72 @@
+/** Native active-context occupancy, separate from accumulated billable usage (#185). */
+export interface ContextReading {
+  source: "claude_statusline" | "codex_token_usage";
+  sessionId: string;
+  measuredAt: number;
+  tokens: number | null;
+  window: number | null;
+  used: number | null;
+}
+export interface ContextView {
+  source: string | null;
+  measuredAt: number | null;
+  tokens: number | null;
+  window: number | null;
+  used: number | null;
+  freshness: "fresh" | "stale" | "unknown";
+}
+export interface ContextConfig { gate: number; stale_min: number }
+export const DEFAULT_CONTEXT: ContextConfig = { gate: 0, stale_min: 30 };
+const nonnegative = (n: unknown): n is number => typeof n === "number" && Number.isFinite(n) && n >= 0;
+const positive = (n: unknown): n is number => nonnegative(n) && n > 0;
+const record = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === "object" && !Array.isArray(v);
+const object = (v: unknown): Record<string, unknown> => record(v) ? v : {};
+export function claudeContext(value: unknown, sessionId: string, measuredAt: number): ContextReading {
+  const c = object(value);
+  const current = object(c.current_usage);
+  const parts = [current.input_tokens, current.cache_creation_input_tokens, current.cache_read_input_tokens];
+  const window = positive(c.context_window_size) ? c.context_window_size : null;
+  const sum = c.current_usage != null && parts.every(nonnegative) ? parts.reduce<number>((sum, n) => sum + (n as number), 0) : null;
+  const tokens = nonnegative(sum) ? sum : null;
+  const used = record(c.current_usage) && tokens !== null && nonnegative(c.used_percentage) && c.used_percentage <= 100 && window !== null ? c.used_percentage / 100 : null;
+  return { source: "claude_statusline", sessionId, measuredAt, tokens, window, used };
+}
+export function codexContext(value: unknown, sessionId: string, measuredAt: number): ContextReading {
+  const c = object(value), last = object(c.last);
+  const window = positive(c.modelContextWindow) ? c.modelContextWindow : null;
+  const tokens = nonnegative(last.totalTokens) ? last.totalTokens : null;
+  return { source: "codex_token_usage", sessionId, measuredAt, tokens, window, used: tokens !== null && window !== null ? Math.min(1, tokens / window) : null };
+}
+export const unknownContext = (): ContextView => ({ source: null, measuredAt: null, tokens: null, window: null, used: null, freshness: "unknown" });
+/** Invalid/stale readings hide the value but never rearm a threshold already crossed. */
+export class ContextWindows {
+  private readings = new Map<string, ContextReading>();
+  private high = new Map<string, { sessionId: string; crossed: boolean }>();
+  constructor(private cfg: ContextConfig, private crossing: (peer: string, reading: ContextReading) => unknown, private now: () => number = Date.now) {
+    if (!Number.isFinite(cfg.gate) || cfg.gate < 0 || cfg.gate > 1 || !Number.isFinite(cfg.stale_min) || cfg.stale_min <= 0) throw new Error("context: gate must be 0..1 and stale_min positive");
+  }
+  report(peer: string, reading: ContextReading, currentSession: string | undefined): void {
+    if (!currentSession || reading.sessionId !== currentSession) return;
+    const previous = this.readings.get(peer);
+    if (previous?.sessionId === reading.sessionId && positive(previous.measuredAt) && previous.measuredAt <= this.now() && positive(reading.measuredAt) && reading.measuredAt <= this.now() && previous.measuredAt > reading.measuredAt) return;
+    this.readings.set(peer, reading);
+    if (!positive(reading.measuredAt) || reading.measuredAt > this.now() || reading.used === null || !nonnegative(reading.used) || reading.used > 1 || this.now() - reading.measuredAt > this.cfg.stale_min * 60_000 || !this.cfg.gate) return;
+    const state = this.high.get(peer);
+    const crossed = state?.sessionId === reading.sessionId && state.crossed;
+    const over = reading.used >= this.cfg.gate;
+    if (over && !crossed && this.crossing(peer, reading) === false) return;
+    this.high.set(peer, { sessionId: reading.sessionId, crossed: over });
+  }
+  /** Reconsider a held crossing after release, using only the still-fresh reading and current native session. */
+  retry(peer: string, currentSession: string | undefined): void {
+    const reading = this.readings.get(peer);
+    if (reading) this.report(peer, reading, currentSession);
+  }
+  view(peer: string, currentSession: string | undefined, attached: boolean): ContextView {
+    const r = this.readings.get(peer);
+    if (!r) return unknownContext();
+    const stale = this.now() - r.measuredAt > this.cfg.stale_min * 60_000;
+    const valid = positive(r.measuredAt) && r.measuredAt <= this.now() && attached && !!currentSession && r.sessionId === currentSession && !stale;
+    return { source: r.source, measuredAt: positive(r.measuredAt) ? r.measuredAt : null, tokens: valid ? r.tokens : null, window: r.window, used: valid ? r.used : null, freshness: !valid ? stale ? "stale" : "unknown" : r.used === null ? "unknown" : "fresh" };
+  }
+}

package/src/hub/control-client.ts

@@ -6,10 +6,10 @@ export function stateDirFor(cwd: string): string {
   return projectContext(cwd).stateDir;
 }
 
-/** Control WS wire version. 2 = `deliver` carries `envs` (digests); 3 = `tools` role and task messages; 4 = budget messages and `hub_checkpoint`; 5 = `ask`; 6 = console-only `ui` session bootstrap; 8 = controlled recovery; 9 = Pi bridge metadata; 10 = durable delivery receipts; 11 = queue hold diagnostics; 12 = generation-bound channel settlement and execution budgets; 13 = turn-free facts (`facts` with tool, session and transcript binding, `silenced`) and per-recipient send results (issue #108). The plugin is installed apart from the daemon, so they can drift. */
-export const PROTOCOL = 13;
+/** Control WS wire version. 2 = `deliver` carries `envs` (digests); 3 = `tools` role and task messages; 4 = budget messages and `hub_checkpoint`; 5 = `ask`; 6 = console-only `ui` session bootstrap; 8 = controlled recovery; 9 = Pi bridge metadata; 10 = durable delivery receipts; 11 = queue hold diagnostics; 12 = generation-bound channel settlement and execution budgets; 13 = turn-free facts (`facts` with tool, session and transcript binding, `silenced`) and per-recipient send results (issue #108). 14 = native context-window status and session-bound context checkpoint request ids (issue #185). 15 = conductor tools and permission deadlines/closed events (issues #190, #194). The plugin is installed apart from the daemon, so they can drift. */
+export const PROTOCOL = 15;
 /** Protocols a current coordinator may authenticate while upgrading a running source. */
-export const RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, 12, PROTOCOL] as const;
+export const RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, 12, 13, 14, PROTOCOL] as const;
 
 export interface Hello {
   /** `tools`: acts for `peer` (task tools, hub_send) without being a delivery target: the MCP server Kimi and Codex run. */