@animalabs/connectome-host 0.7.4 → 0.8.0

package/scripts/release-changelog.ts

@@ -1,32 +1,221 @@
 // Runs as npm's `version` lifecycle hook (see package.json): at that point
 // package.json already carries the new version, and files staged here are
 // included in the release commit that `npm version` then creates and tags.
-import { readFileSync, writeFileSync } from "node:fs";
+//
+// Folds the pending fragments in changelog.d/ (one file per change,
+// `<slug>.<breaking|added|changed|fixed>.md`) together with anything filed
+// directly under the standing `## Unreleased` section into a new
+// `## X.Y.Z — YYYY-MM-DD` section, deletes the consumed fragments, and
+// leaves a fresh empty `## Unreleased` above it. Refuses to release when
+// there is nothing to release, or when the input's shape is ambiguous.
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
 
-const { version } = JSON.parse(readFileSync("package.json", "utf8"));
-const path = "CHANGELOG.md";
-const text = readFileSync(path, "utf8");
+const CHANGELOG = "CHANGELOG.md";
+const FRAGMENT_DIR = "changelog.d";
+// Canonical subsection order; a fragment's category must be one of these.
+const CATEGORIES = ["breaking", "added", "changed", "fixed"] as const;
+type Category = (typeof CATEGORIES)[number];
+const HEADINGS: Record<Category, string> = {
+  breaking: "Breaking",
+  added: "Added",
+  changed: "Changed",
+  fixed: "Fixed",
+};
 
-const header = text.match(/^## Unreleased[ \t]*$/m);
-if (!header || header.index === undefined) {
-  console.error("CHANGELOG.md: no '## Unreleased' section — add one before releasing.");
-  process.exit(1);
+// Refusals throw and are reported at the entry point, which then lets the
+// process end on its own with exitCode 1. process.exit() would race the
+// stderr write when stderr is a pipe (asynchronous on macOS), leaving the
+// caller a bare failure status with no reason attached.
+class ReleaseError extends Error {}
+const fail = (msg: string): never => {
+  throw new ReleaseError(msg);
+};
+
+interface Fragment {
+  name: string;
+  category: Category;
+  body: string;
 }
 
-const escaped = version.replace(/[.]/g, "\\.");
-if (new RegExp(`^## ${escaped}([^0-9]|$)`, "m").test(text)) {
-  console.error(`CHANGELOG.md: a '## ${version}' section already exists.`);
-  process.exit(1);
+// Fragment grammar: every non-blank line starts a bullet or continues one
+// (indented two or more spaces; nested bullets included). Headings and
+// thematic breaks are refused wherever they appear — at top level a '## '
+// line would splice a fake section boundary into the released changelog,
+// and as item content ('- ## x', '  ## x') they still render as headings.
+const isBulletStart = (l: string): boolean => /^[-*] /.test(l);
+const isContinuation = (l: string): boolean => /^ {2,}\S/.test(l);
+const itemContent = (l: string): string => l.replace(/^\s*(?:[-*]\s+)?/, "");
+const isHeading = (s: string): boolean => /^#{1,6}(\s|$)/.test(s);
+// Thematic breaks may carry interior whitespace ('- - -', '* * *').
+const isRule = (s: string): boolean => /^([-*_=])(\s*\1){2,}\s*$/.test(s);
+const isBlockConstruct = (l: string): boolean =>
+  isRule(l.trim()) || isHeading(itemContent(l));
+
+// The directory is scanned fail-closed: anything that is not README.md or
+// a well-formed fragment file aborts the release, so an entry can never be
+// silently left out (e.g. a fragment created under a 'fix/' subdirectory
+// because the slug was taken verbatim from a branch name).
+function collectFragments(): Fragment[] {
+  const fragments: Fragment[] = [];
+  if (!existsSync(FRAGMENT_DIR)) return fragments;
+  const entries = readdirSync(FRAGMENT_DIR, { withFileTypes: true }).sort(
+    (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0),
+  );
+  for (const entry of entries) {
+    const { name } = entry;
+    if (name === "README.md") continue;
+    if (!entry.isFile()) {
+      fail(
+        `${FRAGMENT_DIR}/${name}: not a file. Fragments are flat files directly ` +
+          `in ${FRAGMENT_DIR}/ — a slug cannot contain '/'; use the PR number, ` +
+          "or the branch name with '/' replaced by '-'.",
+      );
+    }
+    const m = name.match(/\.(breaking|added|changed|fixed)\.md$/);
+    if (!m) {
+      fail(
+        `${FRAGMENT_DIR}/${name}: unrecognized file — name fragments ` +
+          `'<slug>.<${CATEGORIES.join("|")}>.md' so the entry is not silently stranded.`,
+      );
+    }
+    const body = readFileSync(join(FRAGMENT_DIR, name), "utf8").trim();
+    if (!body) fail(`${FRAGMENT_DIR}/${name}: empty fragment.`);
+    const offending = body
+      .split("\n")
+      .find(
+        (l) =>
+          l.trim() !== "" &&
+          (!(isBulletStart(l) || isContinuation(l)) || isBlockConstruct(l)),
+      );
+    if (offending !== undefined) {
+      fail(
+        `${FRAGMENT_DIR}/${name}: a fragment is one or more markdown bullets ` +
+          "('- …'; continuation lines indented two spaces; no headings or " +
+          `rules) — offending line: '${offending}'.`,
+      );
+    }
+    fragments.push({ name, category: m[1] as Category, body });
+  }
+  return fragments;
 }
 
-const afterHeader = text.slice(header.index + header[0].length);
-const nextSection = afterHeader.search(/^## /m);
-const unreleasedBody = nextSection === -1 ? afterHeader : afterHeader.slice(0, nextSection);
-if (!/^\s*[-*] /m.test(unreleasedBody)) {
-  console.error(`CHANGELOG.md: '## Unreleased' has no entries — nothing to release as ${version}.`);
-  process.exit(1);
+// Merge fragment bullets into the Unreleased body's subsection structure.
+// Directly-filed entries are kept; a fragment joins the first subsection
+// whose title starts with its category (so audience-qualified headings like
+// '### Breaking (recipe authors only)' still attract 'breaking' fragments),
+// or a new canonical subsection. Output is emitted in canonical order.
+function mergeFragments(body: string, frags: Fragment[]): string {
+  interface Part {
+    title: string;
+    lines: string[];
+  }
+  const preamble: string[] = [];
+  const parts: Part[] = [];
+  let current: Part | null = null;
+  for (const line of body.split("\n")) {
+    const h = line.match(/^###\s+(.*)$/);
+    if (h) {
+      current = { title: (h[1] ?? "").trim(), lines: [] };
+      parts.push(current);
+    } else if (current) {
+      current.lines.push(line);
+    } else {
+      preamble.push(line);
+    }
+  }
+  for (const f of frags) {
+    let part = parts.find((p) => p.title.toLowerCase().startsWith(f.category));
+    if (!part) {
+      part = { title: HEADINGS[f.category], lines: [] };
+      parts.push(part);
+    }
+    part.lines.push("", ...f.body.split("\n"));
+  }
+  const rank = (t: string): number => {
+    const i = CATEGORIES.findIndex((c) => t.toLowerCase().startsWith(c));
+    return i === -1 ? CATEGORIES.length : i;
+  };
+  const chunks: string[] = [];
+  const pre = preamble.join("\n").trim();
+  if (pre) chunks.push(pre);
+  for (const p of [...parts].sort((a, b) => rank(a.title) - rank(b.title))) {
+    const content = p.lines.join("\n").replace(/\n{3,}/g, "\n\n").trim();
+    chunks.push(content ? `### ${p.title}\n\n${content}` : `### ${p.title}`);
+  }
+  return chunks.join("\n\n");
+}
+
+function main(): void {
+  const { version } = JSON.parse(readFileSync("package.json", "utf8")) as {
+    version: string;
+  };
+  const text = readFileSync(CHANGELOG, "utf8");
+  const fragments = collectFragments();
+
+  // Exactly one Unreleased heading. A second one silently strands entries:
+  // only the first is ever cut, so anything filed under a later heading is
+  // never released and never reaches the GitHub release notes.
+  const headings = [...text.matchAll(/^## Unreleased[ \t]*$/gm)];
+  if (headings.length === 0) {
+    fail(`no '## Unreleased' section in ${CHANGELOG} — add one before releasing.`);
+  }
+  if (headings.length > 1) {
+    const lines = headings.map((m) => text.slice(0, m.index ?? 0).split("\n").length);
+    fail(
+      `${headings.length} '## Unreleased' headings (lines ${lines.join(", ")}). ` +
+        "Only the first is released; fold them into one before releasing.",
+    );
+  }
+  const header = headings[0]!;
+  const headerIndex = header.index ?? 0;
+
+  const escaped = version.replace(/[.]/g, "\\.");
+  if (new RegExp(`^## ${escaped}([^0-9]|$)`, "m").test(text)) {
+    fail(`a '## ${version}' section already exists.`);
+  }
+
+  const afterHeader = text.slice(headerIndex + header[0].length);
+  const nextSection = afterHeader.search(/^## /m);
+  const oldBody = nextSection === -1 ? afterHeader : afterHeader.slice(0, nextSection);
+  const rest = nextSection === -1 ? "" : afterHeader.slice(nextSection);
+
+  const merged = mergeFragments(oldBody, fragments);
+  if (!/^[ \t]*[-*] /m.test(merged)) {
+    fail(
+      `nothing to release as ${version} — no fragments in ${FRAGMENT_DIR}/ ` +
+        "and no entries under '## Unreleased'.",
+    );
+  }
+
+  // Spliced by index rather than string-replaced: `text.replace("## Unreleased", …)`
+  // would hit the first *substring* occurrence, which is not necessarily the
+  // heading the regex matched (an inline mention of `## Unreleased` in prose
+  // comes first) and would inject the version heading into the wrong place.
+  const date = new Date().toISOString().slice(0, 10);
+  writeFileSync(
+    CHANGELOG,
+    text.slice(0, headerIndex) +
+      `## Unreleased\n\n## ${version} — ${date}\n\n${merged}\n\n` +
+      rest,
+  );
+  for (const f of fragments) unlinkSync(join(FRAGMENT_DIR, f.name));
+  console.log(
+    `${CHANGELOG}: released '## ${version} — ${date}' from ${fragments.length} ` +
+      "fragment(s) plus the Unreleased section.",
+  );
 }
 
-const date = new Date().toISOString().slice(0, 10);
-writeFileSync(path, text.replace(header[0], `## Unreleased\n\n## ${version} — ${date}`));
-console.log(`CHANGELOG.md: cut Unreleased into '## ${version} — ${date}'.`);
+try {
+  main();
+} catch (e) {
+  if (!(e instanceof ReleaseError)) throw e;
+  console.error(`release-changelog: ${e.message}`);
+  process.exitCode = 1;
+}

package/src/cache-keepalive-log.ts

@@ -0,0 +1,41 @@
+// Where prompt-cache keepalive events get written.
+//
+// Every event goes to STDERR, deliberately and without exception.
+//
+// The host's systemd unit routes `StandardError` to
+// `<data>/service-stderr.log` and leaves stdout on the journal. That file is
+// where an operator actually looks — it is where `[inference-refusal]` and the
+// `[autobiographical]` lines live. Splitting keepalive events across two sinks
+// by severity means the routine ones land somewhere nobody greps.
+//
+// This is not hypothetical. On 2026-08-23 the keepalive ran correctly on
+// fable-cm for three hours — three clean refreshes, 523,102 tokens read each,
+// zero writes — while a monitor tailing service-stderr.log reported
+// `keepalive=0` the entire time, because `refreshed` was going to stdout. An
+// operator would have concluded the feature was dead. A background spender
+// that cannot be found in the log an operator reads is indistinguishable from
+// one that never ran.
+//
+// Volume does not justify splitting them: one refresh per lineage per ~50
+// minutes is nothing next to the compression chatter already in that file.
+
+import type { KeepaliveEvent } from '@animalabs/membrane';
+
+export const KEEPALIVE_LOG_PREFIX = '[cache-keepalive]';
+
+/** Render one event as a single log line. */
+export function formatKeepaliveEvent(event: KeepaliveEvent): string {
+  return `${KEEPALIVE_LOG_PREFIX} ${JSON.stringify(event)}`;
+}
+
+/**
+ * Write one keepalive event to the operator-visible log.
+ *
+ * `sink` exists for tests; production always uses stderr via the default.
+ */
+export function logKeepaliveEvent(
+  event: KeepaliveEvent,
+  sink: (line: string) => void = (line) => console.error(line),
+): void {
+  sink(formatKeepaliveEvent(event));
+}

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;
@@ -147,6 +152,8 @@ export function handleCommand(command: string, app: AppContext): CommandResult {
           { 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: '  /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', style: 'system' },
           { text: '  /restore <name>        Restore to checkpoint', style: 'system' },
           { text: '  /branches              List Chronicle branches', style: 'system' },
@@ -189,6 +196,12 @@ export function handleCommand(command: string, app: AppContext): CommandResult {
     case 'undo':
       return handleUndo(app);
 
+    case 'nudge':
+      return handleNudge(app, args[0]);
+
+    case 'puppet':
+      return handlePuppet(app, args);
+
     case 'redo':
       return handleRedo(app);
 
@@ -651,6 +664,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);

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,17 @@ const PASSTHROUGH_KEYS: ReadonlyArray<keyof RecipeStrategy> = [
   'maxSpeculativeL1s',
   'compressionRefusalCurveFallbacks',
   'compressionContextBudgetTokens',
+  'compressionSourceOnly',
+  'compressionSourceOnlyFallback',
+  'compressionMergeSourceOnly',
+  'compressionMergeSourceOnlyFallback',
+  'compressionRecallBudgetTokens',
   'positionedRecallPairs',
   'recallHeaderTemplate',
   'targetChunkTokens',
   'mergeThreshold',
   'summaryTargetTokens',
+  'productionBudgetTokens',
   'l1BudgetTokens',
   'l2BudgetTokens',
   'l3BudgetTokens',
@@ -28,6 +35,7 @@ const PASSTHROUGH_KEYS: ReadonlyArray<keyof RecipeStrategy> = [
   'compressionSlackRatio',
   'overBudgetGraceRatio',
   'foldingStrategy',
+  'kvUnified',
   'speculativeProduction',
   'l1HoldbackChunks',
   'summaryParticipant',
@@ -124,3 +132,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,106 @@
+/**
+ * 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;
+  channelId?: 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';
+  if (r === 'mcpl:channel-incoming' || r === 'mcpl:push-event' || r.startsWith('discord')) 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);
+}
+
+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);
+    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' });