Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

daemon: T2 — launch-failure reason into fsm-trace (audit↔trace two-skins closure)

Gus9d638ee471f7
diff --git a/src/daemon/src/manager/managerPolicy.ts b/src/daemon/src/manager/managerPolicy.ts
index 1d6749d16..df5e15387 100644
--- a/src/daemon/src/manager/managerPolicy.ts
+++ b/src/daemon/src/manager/managerPolicy.ts
@@ -196,7 +196,26 @@ export type ManagerEvent =
* MEANS in FSM terms (deliberate kill vs crash) is a separate semantic layer
* left to T3, which may only LAYER fields on top, never overwrite these.
*/
- | { type: "exit"; agentId: string; exitCode?: number | null; exitSignal?: string | null; abnormal?: boolean }
+ | {
+ type: "exit";
+ agentId: string;
+ exitCode?: number | null;
+ exitSignal?: string | null;
+ abnormal?: boolean;
+ /**
+ * Present when this exit followed a LAUNCH failure (never established):
+ * the reason string reportSpawnFailure recorded — the SAME value the web
+ * audit gets (ENOENT / handshake_timeout / pre_handshake_exit /
+ * spawn_threw / a Node error code). T2 (audit↔trace two-skins closure,
+ * plans/daemon-trace-completeness-charter.md): without it, a
+ * failed-to-start exit is a bare exit in the trace, indistinguishable from
+ * a clean one. Orthogonal to exitCode/exitSignal (a launch failure often
+ * has no real code/signal) — consumers detect "was it a launch failure" by
+ * this field's presence, not by guessing code/signal combos. Observability
+ * only; `onExit` must not branch on it.
+ */
+ spawnFailureReason?: string | null;
+ }
| { type: "tick"; nowMs: number }
/**
* Owner-triggered "reset session". Nulls `AgentState.sessionId` so the next
diff --git a/src/daemon/src/manager/managerRuntime.test.ts b/src/daemon/src/manager/managerRuntime.test.ts
index 42bcb220d..d5da219cc 100644
--- a/src/daemon/src/manager/managerRuntime.test.ts
+++ b/src/daemon/src/manager/managerRuntime.test.ts
@@ -2206,6 +2206,84 @@ describe("AgentProcessManager — onFsmTransition trace (observability, zero beh
exitEffectsFor({ code: 0, reason: "runtime_exit" }, true),
);
});
+
+ // ---- T2: launch-failure reason into trace (audit↔trace two-skins closure) ----
+ // A spawn that never establishes (ENOENT / pre_handshake_exit / handshake_timeout
+ // / spawn_threw) previously reached the web audit but dispatched a BARE exit —
+ // in the trace it was indistinguishable from a clean exit. T2 carries the
+ // failure reason (same value as the audit) onto the exit event → trace.
+
+ it("T2 — a pre-handshake exit records spawnFailureReason on the trace exit row", () => {
+ const recs: Record<string, unknown>[] = [];
+ const { mgr, session } = makeWithTrace((r) => recs.push(r));
+ mgr.deliver("a1", { seq: 1, text: "hi" });
+ // Exit with NO prior runtime_event (never established) → pre_handshake_exit.
+ session.fire("exit");
+
+ const exitRec = recs.find((r) => r.event === "exit" && r.agentId === "a1");
+ expect(exitRec).toBeTruthy();
+ expect(exitRec!.spawnFailureReason).toBe("pre_handshake_exit");
+ });
+
+ it("T2 — an ENOENT spawn error carries that exact reason (same string as the web audit) into the trace", () => {
+ const recs: Record<string, unknown>[] = [];
+ const { mgr, session } = makeWithTrace((r) => recs.push(r));
+ mgr.deliver("a1", { seq: 1, text: "hi" });
+ session.fire("error", { code: "ENOENT" });
+ session.fire("exit");
+
+ const exitRec = recs.find((r) => r.event === "exit" && r.agentId === "a1");
+ expect(exitRec).toBeTruthy();
+ expect(exitRec!.spawnFailureReason).toBe("ENOENT");
+ });
+
+ it("T2 — a normal established exit carries NO spawnFailureReason", () => {
+ const recs: Record<string, unknown>[] = [];
+ const { mgr, session } = makeWithTrace((r) => recs.push(r));
+ mgr.deliver("a1", { seq: 1, text: "hi" });
+ session.fire("runtime_event", { kind: "session_init", sessionId: "s1" }); // established
+ session.fire("exit", { code: 0, reason: "runtime_exit" });
+
+ const exitRec = recs.find((r) => r.event === "exit" && r.agentId === "a1");
+ expect(exitRec).toBeTruthy();
+ expect(exitRec!.spawnFailureReason).toBeUndefined();
+ });
+
+ it("T2 no-leak (Claudette #398) — a spawn failure then a SUCCESSFUL spawn + clean exit: the clean exit carries NO stale spawnFailureReason", () => {
+ // Guards the per-spawn `state` isolation: the failure reason lives on the
+ // spawn's own `state` object (fresh each doSpawn), so a later spawn's exit
+ // can't inherit it. This assertion would also catch a regression to a
+ // per-agent map that forgot to clear (the B1 3a leak class).
+ const recs: Record<string, unknown>[] = [];
+ // Fresh session per spawn so the second (successful) launch is a real new
+ // session, exercising a real second doSpawn with its own `state`.
+ const sessions: FakeSession[] = [];
+ const mgr = new AgentProcessManager({
+ driverFor: () => fakeDriver("codex"),
+ baseContextFor: () => ({ workingDirectory: "/tmp", agentId: "a1", standingPrompt: "", config: {} as LaunchContext["config"], credentialProxy: {} as LaunchContext["credentialProxy"] }),
+ sessionFactory: () => {
+ const s = fakeSession();
+ sessions.push(s);
+ return s;
+ },
+ onFsmTransition: ((r: Record<string, unknown>) => recs.push(r)) as never,
+ });
+ mgr.register("a1");
+
+ // Spawn #1: fails pre-handshake.
+ mgr.deliver("a1", { seq: 1, text: "hi" });
+ sessions[0]!.fire("exit"); // → pre_handshake_exit, agent back to idle
+
+ // Spawn #2: succeeds (establishes), then exits cleanly.
+ recs.length = 0;
+ mgr.deliver("a1", { seq: 2, text: "again" });
+ sessions[1]!.fire("runtime_event", { kind: "session_init", sessionId: "s2" });
+ sessions[1]!.fire("exit", { code: 0, reason: "runtime_exit" });
+
+ const cleanExit = recs.find((r) => r.event === "exit" && r.agentId === "a1");
+ expect(cleanExit).toBeTruthy();
+ expect(cleanExit!.spawnFailureReason).toBeUndefined(); // no stale reason from spawn #1
+ });
});
describe("T1 — abnormal-exit user audit stays gated (no nap-noise on deliberate kill)", () => {
diff --git a/src/daemon/src/manager/managerRuntime.ts b/src/daemon/src/manager/managerRuntime.ts
index 5fd498950..ce747b0eb 100644
--- a/src/daemon/src/manager/managerRuntime.ts
+++ b/src/daemon/src/manager/managerRuntime.ts
@@ -208,6 +208,13 @@ export interface ManagerRuntimeOpts {
exitCode?: number | null;
exitSignal?: string | null;
abnormal?: boolean;
+ /**
+ * Present on an `exit` that followed a LAUNCH failure: the reason string
+ * (same value as the web audit — ENOENT/handshake_timeout/pre_handshake_exit/
+ * spawn_threw/Node code). T2: makes a failed-to-start distinguishable from a
+ * clean exit in the trace. Absent on a normal exit.
+ */
+ spawnFailureReason?: string | null;
}) => void;
/**
* Optional context-timeline recorder. When provided, the manager logs each
@@ -1099,6 +1106,11 @@ export class AgentProcessManager {
exitCode: (event as { exitCode?: number | null }).exitCode ?? null,
exitSignal: (event as { exitSignal?: string | null }).exitSignal ?? null,
abnormal: (event as { abnormal?: boolean }).abnormal ?? false,
+ // Launch-failure reason (T2). Included only when present so a
+ // normal exit row stays free of the key.
+ ...((event as { spawnFailureReason?: string | null }).spawnFailureReason != null
+ ? { spawnFailureReason: (event as { spawnFailureReason?: string | null }).spawnFailureReason }
+ : {}),
}
: {}),
});
@@ -1360,7 +1372,7 @@ export class AgentProcessManager {
// `terminate_stalled` from `applyEffect`) so the process's eventual
// `exit` event doesn't ALSO log a redundant/contradictory
// "session ended" line for the same termination.
- const state = { hasEstablished: false, hasReportedSpawnFailure: false, suppressExitLog: false, handshakeTimer: null as ReturnType<typeof setTimeout> | null, torndown: false, superseded: false, pid: null as number | null };
+ const state = { hasEstablished: false, hasReportedSpawnFailure: false, suppressExitLog: false, handshakeTimer: null as ReturnType<typeof setTimeout> | null, torndown: false, superseded: false, pid: null as number | null, spawnFailureReason: null as string | null };
this.activeSpawnState.set(agentId, state);
const clearHandshakeTimer = () => {
if (state.handshakeTimer) {
@@ -1374,6 +1386,14 @@ export class AgentProcessManager {
) => {
if (state.hasEstablished || state.hasReportedSpawnFailure) return;
state.hasReportedSpawnFailure = true;
+ // Record the launch-failure reason on THIS spawn's state so the exit
+ // dispatch that follows can carry it into the fsm-trace (T2 — same reason
+ // string the web audit below gets, so trace and audit "say the same word":
+ // ENOENT / handshake_timeout / pre_handshake_exit / spawn_threw / a Node
+ // error code). Lives on per-spawn `state` (fresh each doSpawn), so it can't
+ // leak into a later spawn's exit — no per-agent-map read-clear needed. See
+ // plans/daemon-trace-completeness-charter.md T2.
+ state.spawnFailureReason = reason;
this.log.warn("spawn failed", { agentId, runtime: driver.id, reason });
this.opts.onRuntimeSpawnFailed?.(driver.id, reason);
// Surface to the owner: a spawn that never handshakes is otherwise
@@ -1493,7 +1513,7 @@ export class AgentProcessManager {
// from a stale/superseded spawn must NOT drop a fresh session's marker.
this.nonCleanEndMarker.delete(agentId);
}
- this.dispatch({ type: "exit", agentId, exitCode, exitSignal, abnormal });
+ this.dispatch({ type: "exit", agentId, exitCode, exitSignal, abnormal, spawnFailureReason: state.spawnFailureReason });
});
// Stamp the wake-prompt timestamp AT the last mile — right before the
@@ -1544,7 +1564,10 @@ export class AgentProcessManager {
if (this.sessions.get(agentId) === session) this.sessions.delete(agentId);
this.liveSessions.delete(agentId);
if (this.activeSpawnState.get(agentId) === state) this.activeSpawnState.delete(agentId);
- this.dispatch({ type: "exit", agentId });
+ // T2: carry the launch-failure reason (just set by reportSpawnFailure)
+ // into the FSM/trace — a handshake_timeout exit is otherwise a bare
+ // exit in the trace, indistinguishable from a clean one.
+ this.dispatch({ type: "exit", agentId, spawnFailureReason: state.spawnFailureReason });
}, this.opts.handshakeTimeoutMs);
})
.catch((err: unknown) => {
@@ -1556,7 +1579,8 @@ export class AgentProcessManager {
"spawn_threw";
reportSpawnFailure(String(code));
if (this.sessions.get(agentId) === session) this.sessions.delete(agentId);
- this.dispatch({ type: "exit", agentId });
+ // T2: carry the launch-failure reason into the FSM/trace (same as above).
+ this.dispatch({ type: "exit", agentId, spawnFailureReason: state.spawnFailureReason });
});
}