agent-relay-runner 0.129.11 → 0.129.13

package/src/native-memory-lever.ts

@@ -0,0 +1,308 @@
+// #1565 P5.7 (design §10.3) — the provider-NATIVE-memory lever.
+//
+// WHAT THIS IS FOR. Every agent today can carry two competing memory stores: relay memory (which
+// survives a respawn) and the provider's own (which, for 8 of 11 built-in profiles, is destroyed
+// at every spawn because the managed provider home is instanceId-keyed). This module renders one
+// profile field into the concrete per-provider switches that make relay memory THE store.
+//
+// TWO INVARIANTS, both load-bearing:
+//
+//  1. ABSENT ⇒ ON, and absent emits NOTHING. A profile without `nativeMemory` produces an empty
+//     application: no env, no args, no settings keys. The launch is byte-identical to today. This
+//     is what keeps P5.7 (the lever) separate from P5.8 (the rollout that flips profiles).
+//
+//  2. A DECLARED policy renders EXPLICITLY IN BOTH DIRECTIONS — never as "omit the flag"
+//     (§10.3.5). `policy:"on"` emits `CLAUDE_CODE_DISABLE_AUTO_MEMORY=0` / `-c
+//     features.memories=true`, not an absence. An absence cannot override an `autoMemoryEnabled:
+//     false` or `features.memories = false` written into a reused managed home on an earlier
+//     launch, so a K3 kill-switch pull would be silently defeated. An explicit value cannot be.
+//
+// REACH, per §10.3.1's table — and the reason the env/argv lever is the one that must always be
+// present: relay writes a managed `settings.json`/`config.toml` only into an ISOLATED home, and
+// must never clobber a host-base agent's real `~/.claude`/`~/.codex`. Claude's env var sits ABOVE
+// the settings read in the CLI's own predicate and Codex's `-c` sits above `config.toml`, so the
+// portable lever is also the authoritative one; the file channels are a belt, not the trousers.
+//
+// NEVER THROWS. Resolution is total: any unexpected input degrades to "nothing applied, reported
+// as suppressed" rather than propagating. A failure to apply this lever must not fail a spawn
+// (the #1612 discipline, applied to the switch instead of the preamble) — an agent that launches
+// with its native memory still on is a two-store agent, which is exactly today's state; an agent
+// that fails to launch is an outage.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { AgentProfileNativeMemoryPolicy, SpawnProvider } from "agent-relay-sdk";
+import { sanitizeFsName } from "agent-relay-sdk/fs-name";
+import type { RunnerSpawnConfig } from "./adapter";
+import { providerHomeRootFromEnv } from "./config";
+import { profileUsesProviderHostGlobals } from "./profile-home";
+import { upsertTomlTable } from "./relay-mcp";
+
+export const CLAUDE_DISABLE_AUTO_MEMORY_ENV = "CLAUDE_CODE_DISABLE_AUTO_MEMORY";
+export const CLAUDE_AUTO_MEMORY_ENABLED_SETTING = "autoMemoryEnabled";
+export const CLAUDE_AUTO_MEMORY_DIRECTORY_SETTING = "autoMemoryDirectory";
+export const CODEX_MEMORIES_FEATURE_KEY = "features.memories";
+
+/** `"default"` = the profile declared nothing, so no lever is emitted at all. */
+export type ResolvedNativeMemoryPolicy = AgentProfileNativeMemoryPolicy | "default";
+
+export interface NativeMemoryLever {
+  policy: ResolvedNativeMemoryPolicy;
+  /** Env additions for the launch. Empty for `"default"`. */
+  env: Record<string, string>;
+  /** Argv additions for the launch. Empty for `"default"`. */
+  args: string[];
+  /** Provider-settings keys relay folds into its OWN settings channel (Claude `--settings` and,
+   *  for an isolated home, the managed `settings.json`). Empty for `"default"` and for Codex. */
+  settings: Record<string, unknown>;
+  /** Codex only: `config.toml` keys for an ISOLATED `CODEX_HOME`. Empty otherwise. */
+  configToml: Record<string, string>;
+  /** The levers that actually reach this launch, as short stable ids for the projection report. */
+  applied: string[];
+  /** Levers that were resolved but could NOT be delivered on this base/provider. Reported LOUDLY
+   *  (the `hooksSuppressed` precedent, #1096) so a lever is never silently absent while the
+   *  report claims it applied. */
+  suppressed?: { reason: string; levers: string[] };
+}
+
+const NONE: NativeMemoryLever = { policy: "default", env: {}, args: [], settings: {}, configToml: {}, applied: [] };
+
+function none(): NativeMemoryLever {
+  return { ...NONE, env: {}, args: [], settings: {}, configToml: {}, applied: [] };
+}
+
+/**
+ * A STABLE, relay-owned, per-profile directory for `policy:"redirect"` (§10.3.4/F3). Deliberately
+ * NOT under the instanceId-keyed provider home: the entire point of the redirect is that a
+ * host-base profile's native store stops being destroyed every spawn and becomes durable and
+ * harvestable. Sibling to the per-instance homes, so one profile's native memory is one directory.
+ */
+export function defaultNativeMemoryDirectory(provider: SpawnProvider, config: RunnerSpawnConfig): string {
+  const profileName = sanitizeFsName(config.agentProfile?.name || config.profile || "profile", {
+    replacement: "-",
+    collapse: false,
+    maxLen: 120,
+    fallback: "profile",
+  });
+  return join(providerHomeRootFromEnv(), provider, profileName, "native-memory");
+}
+
+interface ClaudeDeliveryChannels {
+  /** An isolated managed home exists, so relay owns a `settings.json` it may write. */
+  managedSettings: boolean;
+  /** Relay's inline `--settings` reaches this launch (false when a caller `--settings` is a file
+   *  path or malformed JSON and therefore unmergeable — the same gate `claudeSettingsArgs` uses). */
+  inlineSettings: boolean;
+}
+
+function resolveClaudeLever(
+  policy: AgentProfileNativeMemoryPolicy,
+  directory: string | undefined,
+  channels: ClaudeDeliveryChannels,
+  resolveDefaultDirectory: () => string,
+): NativeMemoryLever {
+  // The env var is unconditional and authoritative — it works on EVERY base, host included, and
+  // outranks the settings read inside the CLI's own predicate.
+  const disable = policy === "off";
+  const env = { [CLAUDE_DISABLE_AUTO_MEMORY_ENV]: disable ? "1" : "0" };
+  const applied = [`env:${CLAUDE_DISABLE_AUTO_MEMORY_ENV}=${disable ? "1" : "0"}`];
+
+  const settings: Record<string, unknown> = { [CLAUDE_AUTO_MEMORY_ENABLED_SETTING]: !disable };
+  if (policy === "redirect") settings[CLAUDE_AUTO_MEMORY_DIRECTORY_SETTING] = directory ?? resolveDefaultDirectory();
+
+  const settingsLevers = Object.keys(settings).map((key) => `settings:${key}`);
+  const settingsReach = channels.managedSettings || channels.inlineSettings;
+  if (settingsReach) {
+    applied.push(...settingsLevers);
+    return { policy, env, args: [], settings, configToml: {}, applied };
+  }
+  // No settings channel: the env var still carries the on/off decision (and outranks settings
+  // anyway), so "off"/"on" lose nothing. A REDIRECT does lose something real — native memory
+  // stays on but writes wherever the provider defaults to — so say so instead of implying the
+  // redirect happened.
+  return {
+    policy,
+    env,
+    args: [],
+    settings: {},
+    configToml: {},
+    applied,
+    suppressed: {
+      reason: policy === "redirect"
+        ? `relay has no settings channel for this launch (no isolated managed home, and the caller's --settings could not be merged), so ${CLAUDE_AUTO_MEMORY_DIRECTORY_SETTING} was NOT applied: native memory stays ON at the provider's default location`
+        : `relay has no settings channel for this launch (no isolated managed home, and the caller's --settings could not be merged), so the ${CLAUDE_AUTO_MEMORY_ENABLED_SETTING} belt was not applied; the ${CLAUDE_DISABLE_AUTO_MEMORY_ENV} env lever still applies and outranks settings`,
+      levers: settingsLevers,
+    },
+  };
+}
+
+function resolveCodexLever(policy: AgentProfileNativeMemoryPolicy, isolatedHome: boolean): NativeMemoryLever {
+  // §10.3.4: Codex memories live in a fixed `CODEX_HOME` sqlite with no redirect knob, so
+  // `redirect` degrades to an EXPLICIT "on" — never to "off". Losing a redirect must not be a
+  // path that silently deletes a store.
+  const enable = policy !== "off";
+  const value = enable ? "true" : "false";
+  const args = ["-c", `${CODEX_MEMORIES_FEATURE_KEY}=${value}`];
+  const applied = [`arg:${CODEX_MEMORIES_FEATURE_KEY}=${value}`];
+  const configToml: Record<string, string> = isolatedHome ? { [CODEX_MEMORIES_FEATURE_KEY]: value } : {};
+  if (isolatedHome) applied.push(`config.toml:${CODEX_MEMORIES_FEATURE_KEY}=${value}`);
+
+  const suppressedLevers: string[] = [];
+  const reasons: string[] = [];
+  if (policy === "redirect") {
+    suppressedLevers.push("redirect");
+    reasons.push("Codex has no autoMemoryDirectory equivalent (memories live in a fixed CODEX_HOME sqlite), so the redirect could not be applied; native memory was left EXPLICITLY ON instead");
+  }
+  if (!isolatedHome) {
+    suppressedLevers.push(`config.toml:${CODEX_MEMORIES_FEATURE_KEY}`);
+    reasons.push(`this host-base launch reuses the real ~/.codex, which relay must not write, so the config.toml belt was not applied; the ${CODEX_MEMORIES_FEATURE_KEY} argv lever still applies and outranks config.toml`);
+  }
+  return {
+    policy,
+    env: {},
+    args,
+    settings: {},
+    configToml,
+    applied,
+    ...(suppressedLevers.length ? { suppressed: { reason: reasons.join("; "), levers: suppressedLevers } } : {}),
+  };
+}
+
+// Per-provider lever renderers, dispatched by NAME rather than by an identity branch — the same
+// registry shape `launch-assembly`'s ASSEMBLERS/MATERIALIZERS use, so adding a provider is a table
+// entry (and an unregistered provider degrades to "no lever, reported", never to a throw).
+type NativeMemoryLeverRenderer = (
+  policy: AgentProfileNativeMemoryPolicy,
+  input: ResolveNativeMemoryLeverInput,
+) => NativeMemoryLever;
+
+const LEVER_RENDERERS: Record<string, NativeMemoryLeverRenderer> = {
+  claude: (policy, input) => resolveClaudeLever(
+    policy,
+    input.config.agentProfile?.nativeMemory?.directory,
+    { managedSettings: Boolean(input.channels?.managedSettings), inlineSettings: Boolean(input.channels?.inlineSettings) },
+    () => defaultNativeMemoryDirectory(input.provider, input.config),
+  ),
+  codex: (policy, input) => resolveCodexLever(policy, Boolean(input.isolatedHome)),
+};
+
+export interface ResolveNativeMemoryLeverInput {
+  provider: SpawnProvider;
+  config: RunnerSpawnConfig;
+  /** Claude only — see {@link ClaudeDeliveryChannels}. Ignored for Codex. */
+  channels?: Partial<ClaudeDeliveryChannels>;
+  /** Codex only — true when this launch has an isolated `CODEX_HOME` relay may write. */
+  isolatedHome?: boolean;
+}
+
+/**
+ * Render the profile's `nativeMemory` field into concrete launch levers. Total: returns the
+ * empty application (policy `"default"`) when the profile declares nothing, and converts ANY
+ * unexpected failure into a reported suppression rather than a throw.
+ */
+export function resolveNativeMemoryLever(input: ResolveNativeMemoryLeverInput): NativeMemoryLever {
+  try {
+    const declared = input.config.agentProfile?.nativeMemory;
+    if (!declared) return none();
+    const policy = declared.policy ?? (declared.directory ? "redirect" : "on");
+    if (policy !== "on" && policy !== "off" && policy !== "redirect") {
+      return {
+        ...none(),
+        suppressed: { reason: `unrecognized nativeMemory.policy ${JSON.stringify(policy)}; no lever was applied and the provider default (native memory ON) stands`, levers: ["nativeMemory"] },
+      };
+    }
+    const render = LEVER_RENDERERS[input.provider];
+    if (render) return render(policy, input);
+    return {
+      ...none(),
+      policy,
+      suppressed: { reason: `provider ${input.provider} has no known native-memory lever; nothing was applied`, levers: ["nativeMemory"] },
+    };
+  } catch (err) {
+    // The fail-safe (#1612's discipline applied to the switch). A lever we could not compute must
+    // degrade to "not applied, loudly reported" — never to a failed spawn.
+    return {
+      ...none(),
+      suppressed: { reason: `native-memory lever could not be resolved: ${(err as Error)?.message ?? String(err)}; no lever was applied and the provider default (native memory ON) stands`, levers: ["nativeMemory"] },
+    };
+  }
+}
+
+// ── Launch-seam adapters ───────────────────────────────────────────────────────
+//
+// The two entry points `launch-assembly` calls, kept here so the lever's whole surface — what it
+// emits, where each half is delivered, and what happens when a delivery fails — reads as one file.
+
+/**
+ * Resolve the Claude lever with its REAL delivery channels. The `inlineSettings` reach uses the
+ * same caller-`--settings` mergeability gate `claudeSettingsArgs` applies, so the lever's
+ * applied/suppressed report cannot claim a settings key the merge then drops. Both `assembleClaude`
+ * (for the launch) and `materializeClaudeAssets` (for the managed settings.json) call this, so the
+ * launch and the disk agree — the `claudeManagedHookSettings` pattern.
+ */
+export function resolveClaudeNativeMemoryLever(
+  config: RunnerSpawnConfig,
+  configHome: string | undefined,
+  hostDefaultArgs: string[],
+  callerSettingsMergeable: (argLists: string[][]) => boolean,
+): NativeMemoryLever {
+  return resolveNativeMemoryLever({
+    provider: "claude",
+    config,
+    channels: {
+      managedSettings: Boolean(configHome),
+      inlineSettings: callerSettingsMergeable([hostDefaultArgs, config.providerArgs]),
+    },
+  });
+}
+
+/**
+ * The native-memory keys `materializeClaudeAssets` writes into an ISOLATED managed home's
+ * settings.json. Returns `{}` for host base (which reuses the real `~/.claude` — relay must not
+ * write it); that base is covered by the env lever plus the inline `--settings`.
+ */
+export function claudeManagedNativeMemorySettings(
+  config: RunnerSpawnConfig,
+  configHome: string | undefined,
+  callerSettingsMergeable: (argLists: string[][]) => boolean,
+): Record<string, unknown> {
+  if (!configHome) return {};
+  const hostDefaultArgs = profileUsesProviderHostGlobals(config) ? config.providerConfig.defaultArgs : [];
+  return resolveClaudeNativeMemoryLever(config, configHome, hostDefaultArgs, callerSettingsMergeable).settings;
+}
+
+/**
+ * The fail-safe at the APPLY seam (#1612's discipline, moved from the preamble to the switch). The
+ * file-channel belt is best-effort by construction: the authoritative lever is the env var / `-c`
+ * arg, computed into the launch and touching no disk, so a failed belt write costs nothing an
+ * operator can observe — while a THROW here would fail the whole spawn. So: never propagate, and
+ * never swallow either. Returns the reason on failure (also logged), `undefined` on success.
+ */
+export function applyNativeMemoryBelt(label: string, apply: () => void): string | undefined {
+  try {
+    apply();
+    return undefined;
+  } catch (err) {
+    const reason = `native-memory lever: ${label} could not be written: ${(err as Error)?.message ?? String(err)}. `
+      + "The authoritative env/argv lever still applies (it outranks the file channel), and the spawn continues — design #1565 §10.3.";
+    console.warn(reason);
+    return reason;
+  }
+}
+
+/**
+ * Idempotently upsert the `[features]` table into an ISOLATED `CODEX_HOME/config.toml`. Values are
+ * already rendered TOML literals (`"true"`/`"false"`) and are emitted BARE, not quoted:
+ * `features.memories` is a boolean, and a quoted string would not parse as one.
+ */
+export function writeCodexFeaturesToml(codexHome: string, features: Record<string, string>): void {
+  const bodyLines = Object.entries(features)
+    .map(([key, value]) => [key.startsWith("features.") ? key.slice("features.".length) : key, value] as const)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([key, value]) => `${key} = ${value}`);
+  if (!bodyLines.length) return;
+  mkdirSync(codexHome, { recursive: true });
+  const configPath = join(codexHome, "config.toml");
+  const existing = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+  writeFileSync(configPath, upsertTomlTable(existing, "features", bodyLines), { mode: 0o600 });
+}

package/src/outbox.ts

@@ -163,7 +163,7 @@ export class Outbox {
     this.enforceBound();
     // Defer the drain to a microtask so a synchronous burst of enqueues (e.g. several
     // coalesce updates) all land — and coalesce — before the pump pulls the head.
-    queueMicrotask(() => { void this.drain(); });
+    queueMicrotask(() => this.pump());
     return seq;
   }
 
@@ -187,11 +187,29 @@ export class Outbox {
   // Begin the background pump: an initial drain plus a poll timer as a backstop.
   start(): void {
     if (this.pollTimer || this.stopped) return;
-    void this.drain();
-    this.pollTimer = setInterval(() => { void this.drain(); }, this.pollMs);
+    this.pump();
+    this.pollTimer = setInterval(() => this.pump(), this.pollMs);
     this.pollTimer.unref?.();
   }
 
+  // (#1617) — the ONE way a background caller starts a drain. `drain()` is a bare try/finally with
+  // no catch, and drainOnce() touches SQLite outside the send() try/catch (the head SELECT, and the
+  // attempt/poison UPDATEs in the failure path), so a closed or erroring database rejects it. Every
+  // pump site is fire-and-forget — an enqueue microtask, start()'s initial pump and poll timer, the
+  // scheduleDue wake-up — with nobody to await the promise, and Bun exits(1) on an unhandled
+  // rejection with no handler installed anywhere in the runner (#1614). That crashed the whole
+  // agent over a queue error, on a runner nothing respawns (#1618).
+  //
+  // Reported through this module's own existing channel (logger, same as the bound-exceeded warn
+  // and the poison fatal) rather than swallowed: a pump that stops pumping is its own bug, and
+  // it's the only reason the durable queue exists. `drain()` itself keeps its rejecting contract
+  // for flush(), which awaits it directly and is bounded by its own deadline.
+  private pump(): void {
+    void this.drain().catch((error) => {
+      logger.error("outbox", `drain failed: ${errMessage(error)}`);
+    });
+  }
+
   // Drain everything we can before the process exits, ignoring per-row backoff. Used on
   // shutdown/kill/crash (#183): the capture seam durably enqueues the end-of-session
   // Insights datapoint, but the per-agent outbox is never reopened once the agent is gone,
@@ -289,7 +307,7 @@ export class Outbox {
     if (this.stopped || this.dueTimer) return;
     this.dueTimer = setTimeout(() => {
       this.dueTimer = undefined;
-      void this.drain();
+      this.pump();
     }, Math.max(0, delayMs));
     this.dueTimer.unref?.();
   }

package/src/profile-projection.ts

@@ -1,6 +1,7 @@
 import type { AgentProfile, AgentProfileProjectionEntry, AgentProfileProjectionReport, SpawnProvider } from "agent-relay-sdk";
 import { getManifest } from "agent-relay-providers";
 import type { AssembledLaunch } from "./launch-assembly";
+import { SHARED_MCP_METAONLY_CONFIG_FILENAME } from "./relay-mcp";
 
 // #557 — the projection report DESCRIBES an AssembledLaunch, the same object the adapters
 // turn into launch args. It is no longer a separate re-derivation from the profile, so the
@@ -41,6 +42,7 @@ export function agentProfileProjectionReport(input: AgentProfileProjectionInput)
   add(projectMcpEntry(assembled));
   add(projectSkillsEntry(assembled));
   add(projectSettingsEntry(assembled));
+  add(nativeMemoryEntry(assembled));
   add(sharedMcpEntry(assembled));
   if (profile) add(filesystemEntry(profile));
   add(configHomeEntry(assembled));
@@ -255,6 +257,36 @@ function projectSettingsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
   return applied("projectSettings", a.projectSettings.keys.length ? `${a.projectSettings.keys.length} keys` : "none", `Project .claude/settings.json was sanitized and injected through --settings; Relay approvalMode/permission gates remain authoritative${ignored}.`);
 }
 
+// #1565 P5.7 — the provider-NATIVE-memory lever (design §10.3). Names which levers actually
+// reached the launch and which were resolved but SUPPRESSED, following the `hooksSuppressed`
+// anti-lie rule (#1096): a lever that could not be delivered is reported as `partial` (so it
+// lands in `warnings`), never as an "applied" that silently didn't happen.
+function nativeMemoryEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
+  const lever = a.nativeMemory;
+  if (lever.policy === "default") {
+    return notApplicable(
+      "nativeMemory",
+      "absent",
+      `The profile declares no nativeMemory policy, so no lever is emitted and ${a.provider}'s own memory keeps its default (ON). `
+      + "Relay memory and provider-native memory are both in play for this agent.",
+    );
+  }
+  const what = lever.policy === "off"
+    ? `${a.provider}'s OWN memory store is switched OFF, so relay memory is this agent's single store`
+    : lever.policy === "redirect"
+      ? `${a.provider}'s own memory store stays ON but is redirected to a stable relay-owned directory, so it survives a respawn and stays harvestable`
+      : `${a.provider}'s own memory store is EXPLICITLY re-enabled (an explicit value, not an absence — so it outranks any stale setting left in a reused managed home)`;
+  const applieds = lever.applied.length ? ` Levers applied: ${lever.applied.join(", ")}.` : "";
+  if (lever.suppressed) {
+    return partial(
+      "nativeMemory",
+      lever.policy,
+      `${what}.${applieds} SUPPRESSED (${lever.suppressed.levers.join(", ")}): ${lever.suppressed.reason}.`,
+    );
+  }
+  return applied("nativeMemory", lever.policy, `${what}.${applieds}`);
+}
+
 // #672/#689 — shared host-listener MCP provenance. `applied` reports the per-agent `callmux
 // bridge` route. `not-applicable` means the resolved profile kept shared MCP off (for example a
 // zero-host profile, explicit false, or global kill-switch normalization before launch).
@@ -262,7 +294,19 @@ function sharedMcpEntry(a: AssembledLaunch): AgentProfileProjectionEntry {
   const optedIn = Boolean(a.profile?.sharedMcp);
   const listener = a.mcp.sharedListener;
   if (!optedIn || !listener) return notApplicable("sharedMcp", "off", "Shared host-listener MCP is off for this resolved profile; non-identity MCP is injected per-agent.");
-  return applied("sharedMcp", "on", `Non-identity MCP (e.g. tokenlean, github) routed through the shared callmux listener (${listener.url}) via a per-agent 'callmux bridge --cwd "$WORKTREE"'; session survives a listener restart, session-cwd isolated. Relay endpoint stays per-agent.`);
+  // #1575 — a Codex worker fronts the shared listener with a per-agent metaOnly callmux (~11
+  // meta-tools; the ~40 downstream schemas load on demand via callmux_call) instead of the flat
+  // bridge; every other profile keeps the flat bridge.
+  const route = listener.metaOnly
+    ? `a per-agent metaOnly 'callmux --config <home>/${SHARED_MCP_METAONLY_CONFIG_FILENAME}' (meta-tools only; downstream schemas reached on demand)`
+    : `a per-agent 'callmux bridge --cwd "$WORKTREE"'`;
+  // #1450 — a metaOnly callmux may ALSO front the relay endpoint on-demand (via the runner proxy),
+  // so the on-demand relay set (memory/blackboard/artifacts/timers/find_agents) loads through
+  // callmux_call instead of eager-booting; the eager hot-path relay set stays on the direct client.
+  const relayNote = listener.relayFronted
+    ? " The identity-bearing relay endpoint is ALSO fronted here on-demand (via the runner proxy — live token, never on disk): the on-demand relay tools load through callmux_call, the eager hot-path set stays on the per-agent relay client."
+    : " Relay endpoint stays per-agent.";
+  return applied("sharedMcp", "on", `Non-identity MCP (e.g. tokenlean, github) routed through the shared callmux listener (${listener.url}) via ${route}; session survives a listener restart, session-cwd isolated.${relayNote}`);
 }
 
 function globalInstructionsEntry(a: AssembledLaunch): AgentProfileProjectionEntry {

package/src/provider-input-queue.ts

@@ -0,0 +1,100 @@
+// One agent, ONE provider input stream (#1565 F1).
+//
+// Every payload the runner hands to a provider — a relay message batch, an injected prompt, a
+// self-resume continuation, a memory preamble — ends up in the same place: the provider's single
+// input channel. None of the transports are atomic:
+//
+//   • Claude tmux is paste → sleep → Enter (adapters/claude-tmux.ts). Two concurrent delivers
+//     paste BOTH buffers before either Enter fires, so two payloads are submitted as ONE prompt
+//     plus a stray Enter — the continuity envelope and the memory block merged into each other.
+//   • Codex issues `turn/start` per payload, and a second turn/start on a live turn is dropped by
+//     the app-server. Concurrent delivers both pass the adapter's in-turn guard and one payload is
+//     silently lost — while its command still reports `succeeded`, disarming the relay backstop
+//     that would otherwise re-send it.
+//
+// Nothing upstream serializes this: the relay creates the boundary payloads in one synchronous
+// block, broadcasts them without a queue, and the runner dispatches commands fire-and-forget
+// (`void this.handleCommand(...)`). So the gate belongs here, at the one seam every payload
+// crosses — which fixes the general hazard rather than one pair of payloads.
+//
+// FIFO, AND THE ORDER IS TAKEN SYNCHRONOUSLY. `reserve()` claims a place in the queue with no
+// `await` in between, so a caller that reserves first is served first. That is what makes the
+// ordering guarantee meaningful for the boundary pair: the relay creates the continuation BEFORE
+// the memory block, the bus delivers commands in that order, and the runner reserves in dispatch
+// order — so if only one payload can survive (Codex, one turn), the survivor is the continuation.
+//
+// A ticket that is never released would wedge the stream forever, which is worse than the race it
+// prevents. So every ticket is watchdogged: after `stuckAfterMs` it auto-releases and reports,
+// rather than silently stopping all delivery to the agent.
+
+const DEFAULT_STUCK_AFTER_MS = 120_000;
+
+export interface ProviderInputTicket {
+  /** Resolves when it is this ticket's turn. Never rejects. */
+  readonly turn: Promise<void>;
+  /** Hand the stream to the next ticket. Idempotent. */
+  release(): void;
+}
+
+export interface ProviderInputQueueOptions {
+  /** How long a held ticket may block the stream before it is force-released. */
+  stuckAfterMs?: number;
+  /** Reported (never thrown) when a ticket is force-released. */
+  onStuck?: (heldMs: number) => void;
+}
+
+export class ProviderInputQueue {
+  private tail: Promise<void> = Promise.resolve();
+  private readonly stuckAfterMs: number;
+  private readonly onStuck?: (heldMs: number) => void;
+
+  constructor(options: ProviderInputQueueOptions = {}) {
+    this.stuckAfterMs = options.stuckAfterMs ?? DEFAULT_STUCK_AFTER_MS;
+    if (options.onStuck) this.onStuck = options.onStuck;
+  }
+
+  /**
+   * Take a place in the queue NOW, without awaiting. The caller may do other async work before
+   * awaiting `turn` — its position is already fixed, so arrival order is preserved even when the
+   * work before the delivery takes different amounts of time per payload.
+   */
+  reserve(): ProviderInputTicket {
+    const previous = this.tail;
+    let handOff!: () => void;
+    const held = new Promise<void>((resolve) => { handOff = resolve; });
+    // `previous` is built from settled-on-both-paths handlers below, so it never rejects.
+    this.tail = previous.then(() => held);
+    let released = false;
+    let watchdog: ReturnType<typeof setTimeout> | undefined;
+    const release = (stuck?: number) => {
+      if (released) return;
+      released = true;
+      if (watchdog) clearTimeout(watchdog);
+      if (stuck !== undefined) this.onStuck?.(stuck);
+      handOff();
+    };
+    const turn = previous.then(() => {
+      if (released) return;
+      watchdog = setTimeout(() => release(this.stuckAfterMs), this.stuckAfterMs);
+      watchdog.unref?.();
+    }, () => {});
+    return { turn, release: () => release() };
+  }
+
+  /**
+   * Run `fn` with exclusive use of the provider's input stream. Pass a `ticket` reserved earlier to
+   * keep that reservation's place in the queue; otherwise a fresh one is taken here.
+   *
+   * Only the delivery itself belongs inside — never the bookkeeping around it — so a slow relay
+   * round-trip cannot hold the stream shut.
+   */
+  async run<T>(fn: () => Promise<T>, ticket?: ProviderInputTicket): Promise<T> {
+    const slot = ticket ?? this.reserve();
+    await slot.turn;
+    try {
+      return await fn();
+    } finally {
+      slot.release();
+    }
+  }
+}