@animalabs/connectome-host 0.7.4 → 0.8.1

package/src/commands.ts

@@ -4,6 +4,7 @@
  * Commands:
  *   /undo          — Revert to state before last agent turn
  *   /redo          — Re-apply last undone action
+ *   /nudge [agent] — Run inference on current context (no new events)
  *   /checkpoint N  — Save current state as named checkpoint
  *   /restore N     — Branch from checkpoint, switch to it
  *   /branches      — List all Chronicle branches
@@ -35,6 +36,10 @@ import { type FleetModule, formatChildRow } from './modules/fleet-module.js';
 /** Imported lazily to avoid circular deps — index.ts re-exports the type. */
 interface AppContext {
   framework: AgentFramework;
+  /** Resolved main-agent name (see index.ts resolveAgentName). Optional
+   *  because some callers (tui/webui refs) don't thread it; /puppet falls
+   *  back to the first registered agent, same as getAgentCM. */
+  agentName?: string;
   sessionManager: import('./session-manager.js').SessionManager;
   recipe: Recipe;
   branchState: BranchState;
@@ -116,6 +121,35 @@ function getAgentCM(framework: AgentFramework, agentName?: string): ContextManag
   return all[0]?.getContextManager() ?? null;
 }
 
+/**
+ * Refuse head-moving commands while the main agent's turn is in flight.
+ *
+ * Moving the Chronicle head (undo/redo/checkout/restore/branchto/newtopic)
+ * is not atomic with respect to a streaming generation: the in-flight reply
+ * commits onto whatever branch is current WHEN IT COMPLETES, so a head move
+ * mid-stream detaches the reply from its request — it lands on the new
+ * branch attached to the wrong parent (orphaned node), including when the
+ * move is issued from a second client on the same session. The supported
+ * sequence is: stop the generation, then move the head.
+ *
+ * Returns null when the command may proceed. Agents without a state field
+ * (stubs, minimal harnesses) are treated as idle.
+ */
+function inFlightGuard(app: AppContext, cmd: string): CommandResult | null {
+  const framework = app.framework;
+  const agent = (app.agentName ? framework.getAgent(app.agentName) : undefined)
+    ?? framework.getAllAgents()[0];
+  const status = (agent as { state?: { status?: string } } | undefined)?.state?.status;
+  if (status === undefined || status === 'idle') return null;
+  return {
+    lines: [
+      { text: `/${cmd} refused: a turn is in flight (${(agent as { name?: string }).name ?? 'agent'}: ${status}).`, style: 'system' },
+      { text: '  Moving the head mid-generation would attach the streaming reply to the wrong', style: 'system' },
+      { text: '  branch/request. Stop the generation first, then retry.', style: 'system' },
+    ],
+  };
+}
+
 export function handleCommand(command: string, app: AppContext): CommandResult {
   const parts = command.slice(1).split(/\s+/);
   const cmd = parts[0]!;
@@ -142,14 +176,16 @@ export function handleCommand(command: string, app: AppContext): CommandResult {
           { text: '--- Commands ---', style: 'system' },
           { text: '  /quit, /q              Exit the app', style: 'system' },
           { text: '  /status                Show agent status', style: 'system' },
-          { text: '  /clear                 Clear conversation', style: 'system' },
+          { text: '  /clear                 Clear this client\'s display (history/context are kept)', style: 'system' },
           { text: '  /lessons               Show lesson library', style: 'system' },
           { text: '  /export                Export lessons to ./output/ (JSON + markdown)', style: 'system' },
           { text: '  /undo                  Revert last agent turn', style: 'system' },
           { text: '  /redo                  Re-apply undone action', style: 'system' },
-          { text: '  /checkpoint <name>     Save current state', style: 'system' },
-          { text: '  /restore <name>        Restore to checkpoint', style: 'system' },
-          { text: '  /branches              List Chronicle branches', style: 'system' },
+          { text: '  /nudge [agent]         Run inference on current context (no new events)', style: 'system' },
+          { text: '  /puppet <tool> [json]  Admin: execute a tool AS the agent, store the pair', style: 'system' },
+          { text: '  /checkpoint [name]     Save current state (no name: list checkpoints)', style: 'system' },
+          { text: '  /restore [name]        Restore to checkpoint (no name: list checkpoints)', style: 'system' },
+          { text: '  /branches              List Chronicle branches and checkpoints', style: 'system' },
           { text: '  /checkout <name>       Switch to branch', style: 'system' },
           { text: '  /history [n]           Show state transitions (last n)', style: 'system' },
           { text: '  /find <text>           Search messages for text', style: 'system' },
@@ -163,9 +199,9 @@ export function handleCommand(command: string, app: AppContext): CommandResult {
           { text: '  /session               Show current session', style: 'system' },
           { text: '  /session list          List all sessions', style: 'system' },
           { text: '  /session new [name]    Create new session', style: 'system' },
-          { text: '  /session switch <name> Switch to session', style: 'system' },
+          { text: '  /session switch <name or id> Switch to session', style: 'system' },
           { text: '  /session rename <name> Rename current session', style: 'system' },
-          { text: '  /session delete <name> Delete a session', style: 'system' },
+          { text: '  /session delete <name or id> --confirm  Delete a session (irreversible)', style: 'system' },
           { text: '  /recipe                Show current recipe info', style: 'system' },
           { text: '  /newtopic [context]    Reset head window (auto-summarize if empty)', style: 'system' },
           { text: '  /usage                 Show session token usage and costs', style: 'system' },
@@ -175,7 +211,12 @@ export function handleCommand(command: string, app: AppContext): CommandResult {
       };
 
     case 'clear':
-      return { lines: [{ text: '(cleared)', style: 'system' }] };
+      // Display-clearing is client-side: the TUI wipes its scrollback and
+      // the SPA wipes its transcript view before this handler is ever
+      // reached. This line is only seen by surfaces with no display to
+      // clear (headless), where it honestly reports that nothing else —
+      // Chronicle, context — was touched.
+      return { lines: [{ text: '(display cleared on clients; history and context are kept)', style: 'system' }] };
 
     case 'status':
       return handleStatus(framework);
@@ -187,28 +228,38 @@ export function handleCommand(command: string, app: AppContext): CommandResult {
       return handleExport(app);
 
     case 'undo':
-      return handleUndo(app);
+      return inFlightGuard(app, cmd) ?? handleUndo(app);
+
+    case 'nudge':
+      return handleNudge(app, args[0]);
+
+    case 'puppet':
+      return handlePuppet(app, args);
 
     case 'redo':
-      return handleRedo(app);
+      return inFlightGuard(app, cmd) ?? handleRedo(app);
 
+    // Name-taking commands join the REST of the line, not just the first
+    // token: names may contain spaces (/checkpoint my test point), and
+    // /session rename already accepts multi-word names — parsing them
+    // differently made multi-word names silently truncate here.
     case 'checkpoint':
-      return handleCheckpoint(app, args[0]);
+      return handleCheckpoint(app, args.join(' ') || undefined);
 
     case 'restore':
-      return handleRestore(app, args[0]);
+      return inFlightGuard(app, cmd) ?? handleRestore(app, args.join(' ') || undefined);
 
     case 'branches':
-      return handleBranches(framework);
+      return handleBranches(app);
 
     case 'checkout':
-      return handleCheckout(framework, args[0]);
+      return inFlightGuard(app, cmd) ?? handleCheckout(framework, args.join(' ') || undefined);
 
     case 'history':
       return handleHistory(framework, args[0]);
 
     case 'branchto':
-      return handleBranchTo(app, args[0]);
+      return inFlightGuard(app, cmd) ?? handleBranchTo(app, args[0]);
 
     case 'find':
       return handleFind(framework, args.join(' '));
@@ -229,7 +280,7 @@ export function handleCommand(command: string, app: AppContext): CommandResult {
       return handleRecipe(app);
 
     case 'newtopic':
-      return handleNewTopic(app, args);
+      return inFlightGuard(app, cmd) ?? handleNewTopic(app, args);
 
     case 'usage':
       return handleUsage(app);
@@ -297,12 +348,14 @@ function handleSession(app: AppContext, args: string[]): CommandResult {
       return handleSessionNew(app, args.slice(1).join(' ') || undefined);
     case 'switch':
     case 'sw':
-      return handleSessionSwitch(app, args[1]);
+      // Rest-of-line, matching rename: session names may contain spaces, and
+      // a session renamed to a multi-word name must stay reachable by name.
+      return handleSessionSwitch(app, args.slice(1).join(' ') || undefined);
     case 'rename':
       return handleSessionRename(app, args.slice(1).join(' ') || undefined);
     case 'delete':
     case 'rm':
-      return handleSessionDelete(app, args[1]);
+      return handleSessionDelete(app, args.slice(1));
     default:
       return { lines: [{ text: `Unknown /session subcommand: ${sub}. Try /session list.`, style: 'system' }] };
   }
@@ -398,9 +451,17 @@ function handleSessionRename(app: AppContext, name?: string): CommandResult {
   return { lines: [{ text: `Session renamed to "${name}".`, style: 'system' }] };
 }
 
-function handleSessionDelete(app: AppContext, nameOrId?: string): CommandResult {
+function handleSessionDelete(app: AppContext, args: string[]): CommandResult {
+  // Deletion is irreversible, so it takes an explicit second step: the bare
+  // command shows exactly what matched (name + id + message count) and asks
+  // for --confirm. This also defuses the truncated-name amplifier: a typo'd
+  // or partial name can match a DIFFERENT session, and without the echo the
+  // wrong one died silently.
+  const confirmed = args[args.length - 1] === '--confirm';
+  const nameOrId = (confirmed ? args.slice(0, -1) : args).join(' ') || undefined;
+
   if (!nameOrId) {
-    return { lines: [{ text: 'Usage: /session delete <name or id>', style: 'system' }] };
+    return { lines: [{ text: 'Usage: /session delete <name or id> [--confirm]', style: 'system' }] };
   }
 
   const session = app.sessionManager.findSession(nameOrId);
@@ -408,6 +469,16 @@ function handleSessionDelete(app: AppContext, nameOrId?: string): CommandResult
     return { lines: [{ text: `Session "${nameOrId}" not found.`, style: 'system' }] };
   }
 
+  if (!confirmed) {
+    const msgs = session.messageCount !== undefined ? `, ${session.messageCount} msgs` : '';
+    return {
+      lines: [
+        { text: `Will delete session "${session.name}" [${session.id}]${msgs} — irreversible.`, style: 'system' },
+        { text: `To proceed: /session delete ${session.id} --confirm`, style: 'system' },
+      ],
+    };
+  }
+
   try {
     app.sessionManager.deleteSession(session.id);
     return { lines: [{ text: `Deleted session "${session.name}" [${session.id}].`, style: 'system' }] };
@@ -513,14 +584,16 @@ function handleBudget(framework: AgentFramework, arg?: string): CommandResult {
   }
 
   if (!arg) {
-    // Show current budgets
+    // Show current budgets. fmtTokens is exact below 1000 — flooring to "0k"
+    // hid real small values and made the display contradict the validator
+    // (which rejects 0 but accepts 50).
     const lines: Line[] = [{ text: '--- Stream Token Budgets ---', style: 'system' }];
     for (const agent of agents) {
       const budget = agent.maxStreamTokens;
       const last = agent.lastStreamInputTokens;
       const pct = budget > 0 ? ((last / budget) * 100).toFixed(0) : '—';
       lines.push({
-        text: `  ${agent.name}: ${(budget / 1000).toFixed(0)}k (last: ${(last / 1000).toFixed(0)}k, ${pct}%)`,
+        text: `  ${agent.name}: ${fmtTokens(budget)} (last: ${fmtTokens(last)}, ${pct}%)`,
         style: 'system',
       });
     }
@@ -546,12 +619,8 @@ function handleBudget(framework: AgentFramework, arg?: string): CommandResult {
     agent.maxStreamTokens = tokens;
   }
 
-  const display = tokens >= 1_000_000
-    ? `${(tokens / 1_000_000).toFixed(1)}m`
-    : `${(tokens / 1_000).toFixed(0)}k`;
-
   return {
-    lines: [{ text: `Stream budget set to ${display} tokens for all agents.`, style: 'system' }],
+    lines: [{ text: `Stream budget set to ${fmtTokens(tokens)} tokens for all agents.`, style: 'system' }],
   };
 }
 
@@ -651,6 +720,89 @@ export function handleExport(app: AppContext): CommandResult {
   };
 }
 
+/**
+ * /nudge [agent] — admin-level: queue an inference turn on the agent's
+ * CURRENT context without adding any message or event (framework
+ * `nudgeAgent`). The zero-pollution complement to /undo: rewind, then nudge,
+ * and the agent takes another swing at exactly what it already sees.
+ */
+/**
+ * /puppet <toolName> [json-input] — admin: execute one tool AS the main
+ * agent and store the tool_use + tool_result pair in its window, exactly as
+ * a model-initiated call (Framework.puppetToolCall). The call runs for real.
+ * Refused unless the agent is idle and the tool is on its surface. Does not
+ * wake the agent. Born from the princess exemplar surgery (2026-08-23):
+ * one first-person pair restores a capacity the model can't find on its own
+ * — older models especially. Disclosure to the resident is the operator's
+ * call; the precedent was disclosed first.
+ */
+function handlePuppet(app: AppContext, args: string[]): CommandResult {
+  const toolName = args[0];
+  if (!toolName) {
+    return {
+      lines: [
+        { text: 'Usage: /puppet <toolName> [json-input]', style: 'system' },
+        { text: '  Executes the tool AS the agent (for real) and stores the', style: 'system' },
+        { text: '  tool_use + tool_result pair in its window. Requires idle.', style: 'system' },
+      ],
+    };
+  }
+  const rawInput = args.slice(1).join(' ').trim();
+  let input: Record<string, unknown> = {};
+  if (rawInput) {
+    try {
+      const parsed = JSON.parse(rawInput);
+      if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return { lines: [{ text: 'puppet: input must be a JSON object', style: 'system' }] };
+      }
+      input = parsed;
+    } catch (e) {
+      return { lines: [{ text: `puppet: bad JSON input: ${e instanceof Error ? e.message : e}`, style: 'system' }] };
+    }
+  }
+  const agentName = app.agentName ?? app.framework.getAllAgents()[0]?.name;
+  if (!agentName) {
+    return { lines: [{ text: 'puppet: no registered agent', style: 'system' }] };
+  }
+  const asyncWork = (async (): Promise<CommandResult> => {
+    try {
+      const { toolUseId, result } = await app.framework.puppetToolCall(agentName, toolName, input);
+      const preview = result.isError
+        ? `ERROR: ${result.error ?? 'unknown'}`
+        : String(typeof result.data === 'string' ? result.data : JSON.stringify(result.data) ?? '').slice(0, 300);
+      return {
+        lines: [
+          { text: `puppet ${agentName}: ${toolName} → ${result.isError ? 'error' : 'ok'} (${toolUseId})`, style: 'system' },
+          { text: `  stored tool_use + tool_result in ${agentName}'s window (no wake).`, style: 'system' },
+          { text: `  result: ${preview.replace(/\n/g, ' ')}`, style: 'system' },
+        ],
+      };
+    } catch (e) {
+      return { lines: [{ text: `puppet failed: ${e instanceof Error ? e.message : e}`, style: 'system' }] };
+    }
+  })();
+  return {
+    lines: [{ text: `puppet: executing ${toolName} as ${agentName}...`, style: 'system' }],
+    asyncWork,
+  };
+}
+
+function handleNudge(app: AppContext, agentName?: string): CommandResult {
+  const r = app.framework.nudgeAgent(agentName, 'host-console');
+  if (!r.ok) {
+    return { lines: [{ text: `Nudge failed: ${r.error}`, style: 'system' }] };
+  }
+  const when = r.agentStatus === 'idle'
+    ? 'running now'
+    : `queued — runs when current turn settles (agent is ${r.agentStatus})`;
+  return {
+    lines: [{
+      text: `Nudged ${r.agentName}: inference on current context, no new events (${when}).`,
+      style: 'system',
+    }],
+  };
+}
+
 function handleUndo(app: AppContext): CommandResult {
   const { framework, branchState: bs } = app;
   const cm = getAgentCM(framework);
@@ -742,7 +894,17 @@ function handleRedo(app: AppContext): CommandResult {
 
 function handleCheckpoint(app: AppContext, name?: string): CommandResult {
   if (!name) {
-    return { lines: [{ text: 'Usage: /checkpoint <name>', style: 'system' }] };
+    // Bare /checkpoint lists what exists — same affordance as bare /restore —
+    // so the lifecycle is discoverable from either end.
+    const names = [...app.branchState.checkpoints.keys()];
+    return {
+      lines: [
+        { text: 'Usage: /checkpoint <name>', style: 'system' },
+        ...(names.length > 0
+          ? [{ text: `Saved checkpoints: ${names.join(', ')}`, style: 'system' as const }]
+          : []),
+      ],
+    };
   }
 
   const cm = getAgentCM(app.framework);
@@ -838,8 +1000,8 @@ function handleRestore(app: AppContext, name?: string): CommandResult {
   };
 }
 
-function handleBranches(framework: AgentFramework): CommandResult {
-  const cm = getAgentCM(framework);
+function handleBranches(app: AppContext): CommandResult {
+  const cm = getAgentCM(app.framework);
   if (!cm) return { lines: [{ text: 'No agent context manager.', style: 'system' }] };
 
   const branches = cm.listBranches();
@@ -854,6 +1016,19 @@ function handleBranches(framework: AgentFramework): CommandResult {
     });
   }
 
+  // Checkpoints are positions (branch + message), not branches — but they're
+  // part of the same mental model, and being invisible here made the whole
+  // checkpoint lifecycle run blind: created → not listed anywhere → restored
+  // on faith. Session-scoped, in-memory (cleared on session switch/restart).
+  const cps = [...app.branchState.checkpoints.entries()];
+  if (cps.length > 0) {
+    lines.push({ text: `--- Checkpoints (${cps.length}, this session) ---`, style: 'system' });
+    for (const [name, point] of cps) {
+      const at = point.messageId ? ` @ [${point.messageId}]` : '';
+      lines.push({ text: `  ${name} → ${point.branchName}${at}`, style: 'system' });
+    }
+  }
+
   return { lines };
 }
 
@@ -1041,13 +1216,27 @@ function handleMcpAdd(args: string[]): CommandResult {
 
   const [id, command, ...cmdArgs] = args;
   const servers = readMcplServersFile(DEFAULT_CONFIG_PATH);
-  const isOverwrite = id! in servers;
-  servers[id!] = { command: command!, ...(cmdArgs.length > 0 ? { args: cmdArgs } : {}) };
+  const prev = servers[id!];
+  // Overwrite replaces the command line (command + args, which travel as one
+  // unit) but PRESERVES env and other settings: env is edited via /mcp env
+  // and the panel editor, whose contract is "cleared only by explicit empty
+  // save" — a command update silently dropping tokens/settings broke working
+  // servers in a way that only surfaced at next start.
+  servers[id!] = {
+    ...prev,
+    command: command!,
+    ...(cmdArgs.length > 0 ? { args: cmdArgs } : {}),
+  };
+  if (cmdArgs.length === 0) delete servers[id!]!.args;
   saveMcplServers(DEFAULT_CONFIG_PATH, servers);
 
+  const keptEnv = prev?.env ? Object.keys(prev.env) : [];
   return {
     lines: [
-      { text: `${isOverwrite ? 'Updated' : 'Added'} server "${id}". Restart to apply.`, style: 'system' },
+      { text: `${prev ? 'Updated' : 'Added'} server "${id}". Restart to apply.`, style: 'system' },
+      ...(keptEnv.length > 0
+        ? [{ text: `  (kept env: ${keptEnv.join(', ')})`, style: 'system' as const }]
+        : []),
     ],
   };
 }

package/src/framework-agent-config.ts

@@ -113,5 +113,8 @@ export function buildFrameworkAgentConfig(
     ...(recipe.agent.proseRouting !== undefined
       ? { proseRouting: recipe.agent.proseRouting }
       : {}),
+    ...(recipe.agent.toolWrapperProseGuard !== undefined
+      ? { toolWrapperProseGuard: recipe.agent.toolWrapperProseGuard }
+      : {}),
   };
 }

package/src/framework-strategy.ts

@@ -2,6 +2,7 @@ import {
   AutobiographicalStrategy,
   PassthroughStrategy,
   type ContextStrategy,
+  type ConversationRouterConfig,
 } from '@animalabs/agent-framework';
 import type { Recipe, RecipeStrategy } from './recipe.js';
 import { FrontdeskStrategy } from './strategies/frontdesk-strategy.js';
@@ -12,11 +13,22 @@ const PASSTHROUGH_KEYS: ReadonlyArray<keyof RecipeStrategy> = [
   'maxSpeculativeL1s',
   'compressionRefusalCurveFallbacks',
   'compressionContextBudgetTokens',
+  'compressionSourceOnly',
+  'compressionSourceOnlyFallback',
+  'compressionMergeSourceOnly',
+  'compressionMergeSourceOnlyFallback',
+  'compressionSplitFallback',
+  'compressionSplitPlaceholder',
+  'compressionSplitMaxCallsPerChunk',
+  'compressionSplitMaxCallsPer10Min',
+  'compressionRecallBudgetTokens',
   'positionedRecallPairs',
   'recallHeaderTemplate',
   'targetChunkTokens',
   'mergeThreshold',
+  'mergeMaxSourceSpanMessages',
   'summaryTargetTokens',
+  'productionBudgetTokens',
   'l1BudgetTokens',
   'l2BudgetTokens',
   'l3BudgetTokens',
@@ -28,6 +40,7 @@ const PASSTHROUGH_KEYS: ReadonlyArray<keyof RecipeStrategy> = [
   'compressionSlackRatio',
   'overBudgetGraceRatio',
   'foldingStrategy',
+  'kvUnified',
   'speculativeProduction',
   'l1HoldbackChunks',
   'summaryParticipant',
@@ -124,3 +137,32 @@ export function buildFrameworkStrategy(
       ? new FrontdeskStrategy(autobiographicalOpts)
       : new AutobiographicalStrategy(autobiographicalOpts);
 }
+
+/**
+ * Map a recipe's `conversations` block to the framework's
+ * ConversationRouterConfig. The host supplies the two fields a recipe
+ * cannot: `templateAgent` is the recipe's own (sole) agent, and
+ * `strategyFactory` builds a FRESH instance of the recipe's configured
+ * strategy per fork — strategy instances are stateful and must never be
+ * shared between ContextManagers (without a factory the framework would
+ * silently give forks passthrough, i.e. no compression).
+ */
+export function buildConversationsConfig(
+  recipe: Recipe,
+  agentName: string,
+  model: string,
+  timeZone: string,
+  extensions?: ExtensionRegistry,
+): ConversationRouterConfig | undefined {
+  const conv = recipe.conversations;
+  if (!conv) return undefined;
+  return {
+    templateAgent: agentName,
+    ...(conv.bind !== undefined ? { bind: conv.bind } : {}),
+    ...(conv.trigger !== undefined ? { trigger: conv.trigger } : {}),
+    ...(conv.idleTtlMs !== undefined ? { idleTtlMs: conv.idleTtlMs } : {}),
+    ...(conv.closurePrompt !== undefined ? { closurePrompt: conv.closurePrompt } : {}),
+    ...(conv.agentPrefix !== undefined ? { agentPrefix: conv.agentPrefix } : {}),
+    strategyFactory: () => buildFrameworkStrategy(recipe, model, timeZone, extensions),
+  };
+}

package/src/gate-telemetry.ts

@@ -0,0 +1,134 @@
+/**
+ * Household-gateway telemetry headers (x-gate-* stamps).
+ *
+ * The data boundary these headers exist under: a household inference gateway
+ * records them into its ledger and STRIPS them before the vendor — the vendor
+ * must never see them. That boundary is only real if the host refuses to
+ * attach the stamps anywhere else, so attachment is double-gated:
+ *
+ *   1. `GATE_TELEMETRY=1` — the operator's explicit declaration that the
+ *      configured base URL is such a gateway. Absent/false ⇒ never attach.
+ *   2. `ANTHROPIC_BASE_URL` actually set — the flag alone must not stamp
+ *      traffic that would go to the vendor's default endpoint.
+ *
+ * Fail-closed on both (review finding on the first wiring: the stamp was
+ * attached unconditionally, so with no base URL configured the value went
+ * straight to the vendor).
+ *
+ * Two stamps ride the same hook:
+ *
+ *   x-gate-debt-chunks   compression debt at request build (every lane — the
+ *                        aux lane is where the debt series is most telling)
+ *   x-gate-origin        WHY the turn fired: heartbeat | event | mail |
+ *                        operator | <raw reason>  — stream lane ONLY
+ *   x-gate-channel       where (adapter-namespaced id)     — stream lane ONLY
+ *   x-gate-counterparty  who woke the agent (namespaced id) — stream lane ONLY
+ *
+ * The origin trio describes the agent's turn; a compression call running in
+ * the background is not the turn, so on the 'complete' lane those three are
+ * withheld (an older membrane that passes no lane gets them on every call —
+ * documented, and the ledger's `streamed` flag lets a reader tell the lanes
+ * apart regardless). Values are ids and short class words: never content,
+ * never display names.
+ */
+
+/** Truthy env-flag parse: unset/''/'0'/'false' (any case) are off. */
+function envFlag(value: string | undefined): boolean {
+  return value !== undefined && value !== '' && value !== '0' && value.toLowerCase() !== 'false';
+}
+
+/** What the framework knows about the turn in progress (agent-framework InferenceRequest). */
+export interface TurnTrigger {
+  reason: string;
+  source: string;
+  /** Routing locus of the turn (direct channel wakes set it). */
+  channelId?: string;
+  /** Telemetry-only channel of a gate-batched wake (agent-framework ≥0.14:
+   *  InferenceRequest.wakeChannelId) — never a locus. */
+  wakeChannelId?: string;
+  counterparty?: string;
+}
+
+export interface DynamicHeadersContext {
+  lane?: 'stream' | 'complete';
+}
+
+/**
+ * Collapse the framework's free-form reason/source pair into the ledger's
+ * origin classes. The raw reason survives when no class fits, clipped and
+ * sanitized (ids and words only), so a new event kind shows up as itself
+ * instead of vanishing into 'event'.
+ */
+export function originClass(trigger: TurnTrigger): string {
+  const r = trigger.reason.toLowerCase();
+  const s = trigger.source.toLowerCase();
+  if (r.includes('heartbeat') || s.includes('heartbeat')) return 'heartbeat';
+  if (r.includes('mail') || s.includes('mail')) return 'mail';
+  // channel/push events, directly or batched through the framework's EventGate
+  if (r === 'mcpl:channel-incoming' || r === 'mcpl:push-event' || r.startsWith('discord') || r.startsWith('gate:') || s === 'gate') return 'event';
+  // a person typing at the host itself: headless IPC, CLI, TUI, web UI, API
+  if (r === 'external-message' || ['headless', 'cli', 'tui', 'webui', 'api'].includes(s)) return 'operator';
+  if (r.includes('admin') || r.includes('nudge') || r.includes('unstick') || r.includes('operator')) return 'operator';
+  return r.replace(/[^a-z0-9:_-]/g, '').slice(0, 40) || 'event';
+}
+
+/**
+ * Header-safe attribute. HTTP header values are ByteStrings: a single
+ * non-ASCII code point (an emoji in a channel name, say) makes Fetch throw
+ * and would turn telemetry into a failed model request. So the rule is
+ * fail-closed on the WHOLE value — visible ASCII (0x20..0x7e) only, clipped
+ * to 120 — never character-stripping, which would mint a different id and
+ * collide provenance. An unsendable id is simply not sent (null → dropped).
+ */
+function attr(v: string | undefined): string | null {
+  if (typeof v !== 'string') return null;
+  const t = v.trim();
+  if (!t) return null;
+  for (let i = 0; i < t.length; i++) {
+    const code = t.charCodeAt(i);
+    if (code < 0x20 || code > 0x7e) return null;
+  }
+  return t.slice(0, 120);
+}
+
+/**
+ * Which agent's turn may be stamped onto a request, given that ONE provider
+ * adapter — and therefore one header hook — serves every agent in the
+ * process (primary, subconscious, forks, ephemerals) and the hook cannot
+ * tell whose request it is decorating. Rule: stamp the primary's trigger
+ * only while the primary is the ONLY agent with a turn in flight; any other
+ * agent mid-turn → withhold (null), never guess. Debt is per agent, not per
+ * request, so it may always be read from the primary.
+ */
+export function stampedTrigger(view: {
+  agents: string[];
+  primary?: string | null;
+  triggerOf: (agent: string) => TurnTrigger | null | undefined;
+}): TurnTrigger | null {
+  const primary = view.primary ?? (view.agents.length === 1 ? view.agents[0] : undefined);
+  if (!primary) return null;
+  for (const a of view.agents) {
+    if (a !== primary && view.triggerOf(a)) return null;
+  }
+  const t = view.triggerOf(primary);
+  return t ?? null;
+}
+
+export function gateTelemetryHeaders(
+  env: Record<string, string | undefined>,
+  pendingDebtChunks: () => number | null,
+  activeTrigger: () => TurnTrigger | null = () => null,
+): ((ctx?: DynamicHeadersContext) => Record<string, string | number | null>) | undefined {
+  if (!envFlag(env.GATE_TELEMETRY)) return undefined;
+  if (!env.ANTHROPIC_BASE_URL) return undefined;
+  return (ctx?: DynamicHeadersContext) => {
+    const out: Record<string, string | number | null> = { 'x-gate-debt-chunks': pendingDebtChunks() };
+    if (ctx?.lane === 'complete') return out;
+    const t = activeTrigger();
+    if (!t) return out;
+    out['x-gate-origin'] = originClass(t);
+    out['x-gate-channel'] = attr(t.channelId ?? t.wakeChannelId);
+    out['x-gate-counterparty'] = attr(t.counterparty);
+    return out;
+  };
+}

package/src/headless.ts

@@ -205,6 +205,16 @@ export async function runHeadless(app: AppContext, argv: string[] = []): Promise
         for (const line of result.lines) {
           emit({ type: 'command-output', text: line.text, style: line.style ?? null });
         }
+        // Commands with async follow-up (fleet kill/restart, puppet) put
+        // their real outcome in asyncWork; without this await the IPC
+        // caller only ever saw the "...starting" line and the result was
+        // silently dropped.
+        if (result.asyncWork) {
+          const followUp = await result.asyncWork;
+          for (const line of followUp.lines) {
+            emit({ type: 'command-output', text: line.text, style: line.style ?? null });
+          }
+        }
         if (result.switchToSessionId) {
           await app.switchSession(result.switchToSessionId);
           emit({ type: 'command-output', text: 'Session switched.', style: 'system' });