@os-eco/overstory-cli 0.10.3 → 0.11.0

package/src/sessions/store.test.ts

@@ -133,11 +133,17 @@ describe("upsert", () => {
 		expect(result?.stalledSince).toBeNull();
 	});
 
-	test("rejects invalid state values via CHECK constraint", () => {
+	test("accepts arbitrary state strings (CHECK relaxed in overstory-3087)", () => {
+		// The inline CHECK on `state` was dropped (overstory-3087): the
+		// TypeScript `AgentState` union enforces values at the writer
+		// boundary, so the SQL constraint became a maintenance tax that had
+		// to be rebuilt on every union extension. Verify the schema no
+		// longer throws when an out-of-union value reaches it. Real callers
+		// type their writes through the union and cannot land here.
 		const session = makeSession();
-		// Force an invalid state to test the CHECK constraint
 		const badSession = { ...session, state: "invalid" as AgentState };
-		expect(() => store.upsert(badSession)).toThrow();
+		expect(() => store.upsert(badSession)).not.toThrow();
+		expect(store.getByName("test-agent")?.state).toBe("invalid" as AgentState);
 	});
 
 	test("handles null transcriptPath", () => {
@@ -376,9 +382,13 @@ describe("updateState", () => {
 		store.updateState("nonexistent", "completed");
 	});
 
-	test("rejects invalid state via CHECK constraint", () => {
+	test("accepts arbitrary state strings (CHECK relaxed in overstory-3087)", () => {
+		// Same rationale as the upsert test: the TypeScript `AgentState`
+		// union is the authoritative gate; the SQL CHECK was dropped to
+		// avoid the rebuild tax on every union extension.
 		store.upsert(makeSession());
-		expect(() => store.updateState("test-agent", "invalid" as AgentState)).toThrow();
+		expect(() => store.updateState("test-agent", "invalid" as AgentState)).not.toThrow();
+		expect(store.getByName("test-agent")?.state).toBe("invalid" as AgentState);
 	});
 });
 
@@ -572,6 +582,258 @@ describe("tryTransitionState", () => {
 	});
 });
 
+// === in_turn / between_turns spawn-per-turn substates (overstory-3087) ===
+//
+// The spawn-per-turn engine splits the legacy `working` state into two:
+// `in_turn` (claude is mid-execution, parser events streaming) and
+// `between_turns` (claude exited cleanly, agent waiting for the next mail
+// batch). The matrix must allow the cycle in both directions and forward
+// progression to terminal/error states from either substate. The CHECK
+// constraint and `getActive` query must accept the new values so the
+// watchdog and dashboards see these workers as alive.
+
+describe("in_turn / between_turns substates", () => {
+	test("upsert accepts in_turn via CHECK constraint", () => {
+		store.upsert(makeSession({ state: "in_turn" }));
+		expect(store.getByName("test-agent")?.state).toBe("in_turn");
+	});
+
+	test("upsert accepts between_turns via CHECK constraint", () => {
+		store.upsert(makeSession({ state: "between_turns" }));
+		expect(store.getByName("test-agent")?.state).toBe("between_turns");
+	});
+
+	test("getActive includes in_turn and between_turns alongside working/booting/stalled", () => {
+		store.upsert(makeSession({ agentName: "a-it", id: "s-it", state: "in_turn" }));
+		store.upsert(makeSession({ agentName: "a-bt", id: "s-bt", state: "between_turns" }));
+		store.upsert(makeSession({ agentName: "a-w", id: "s-w", state: "working" }));
+		store.upsert(makeSession({ agentName: "a-c", id: "s-c", state: "completed" }));
+		store.upsert(makeSession({ agentName: "a-z", id: "s-z", state: "zombie" }));
+
+		const activeNames = store
+			.getActive()
+			.map((s) => s.agentName)
+			.sort();
+		expect(activeNames).toEqual(["a-bt", "a-it", "a-w"]);
+	});
+
+	test("booting → in_turn lands (turn-runner first-event transition)", () => {
+		store.upsert(makeSession({ state: "booting" }));
+		const outcome = store.tryTransitionState("test-agent", "in_turn");
+		expect(outcome.ok).toBe(true);
+		expect(store.getByName("test-agent")?.state).toBe("in_turn");
+	});
+
+	test("in_turn → between_turns lands (turn-runner end-of-turn settle)", () => {
+		store.upsert(makeSession({ state: "in_turn" }));
+		const outcome = store.tryTransitionState("test-agent", "between_turns");
+		expect(outcome.ok).toBe(true);
+		expect(store.getByName("test-agent")?.state).toBe("between_turns");
+	});
+
+	test("between_turns → in_turn lands (next mail batch starts a turn)", () => {
+		store.upsert(makeSession({ state: "between_turns" }));
+		const outcome = store.tryTransitionState("test-agent", "in_turn");
+		expect(outcome.ok).toBe(true);
+		expect(store.getByName("test-agent")?.state).toBe("in_turn");
+	});
+
+	test("legacy working → in_turn is rejected (spawn-per-turn keeps separate path)", () => {
+		// A row in the legacy `working` state predates the spawn-per-turn
+		// substate split. The matrix intentionally does not list `working` as
+		// a predecessor of `in_turn` — turn-runner.ts handles legacy `working`
+		// rows by writing in_turn directly via updateState() / unconditional
+		// override on the first parser event of a fresh batch. A
+		// CAS-guarded transition is rejected to keep the two paths disjoint.
+		store.upsert(makeSession({ state: "working" }));
+		const outcome = store.tryTransitionState("test-agent", "in_turn");
+		expect(outcome.ok).toBe(false);
+		if (!outcome.ok && outcome.reason === "illegal_transition") {
+			expect(outcome.prev).toBe("working");
+		}
+		expect(store.getByName("test-agent")?.state).toBe("working");
+	});
+
+	test("legacy working → between_turns is rejected", () => {
+		store.upsert(makeSession({ state: "working" }));
+		const outcome = store.tryTransitionState("test-agent", "between_turns");
+		expect(outcome.ok).toBe(false);
+		if (!outcome.ok && outcome.reason === "illegal_transition") {
+			expect(outcome.prev).toBe("working");
+		}
+	});
+
+	test("booting → between_turns is rejected (must pass through in_turn)", () => {
+		// Spec: between_turns predecessors are in_turn / between_turns /
+		// stalled. The agent only reaches between_turns after a turn produced
+		// events — which means the turn-runner must have transitioned to
+		// in_turn first.
+		store.upsert(makeSession({ state: "booting" }));
+		const outcome = store.tryTransitionState("test-agent", "between_turns");
+		expect(outcome.ok).toBe(false);
+		if (!outcome.ok && outcome.reason === "illegal_transition") {
+			expect(outcome.prev).toBe("booting");
+		}
+	});
+
+	test("in_turn → completed lands (clean exit + terminal mail)", () => {
+		store.upsert(makeSession({ state: "in_turn" }));
+		const outcome = store.tryTransitionState("test-agent", "completed");
+		expect(outcome.ok).toBe(true);
+		expect(store.getByName("test-agent")?.state).toBe("completed");
+	});
+
+	test("between_turns → completed lands (operator stops an idle worker)", () => {
+		store.upsert(makeSession({ state: "between_turns" }));
+		const outcome = store.tryTransitionState("test-agent", "completed");
+		expect(outcome.ok).toBe(true);
+		expect(store.getByName("test-agent")?.state).toBe("completed");
+	});
+
+	test("in_turn → zombie lands (parser stall / abort)", () => {
+		store.upsert(makeSession({ state: "in_turn" }));
+		const outcome = store.tryTransitionState("test-agent", "zombie");
+		expect(outcome.ok).toBe(true);
+		expect(store.getByName("test-agent")?.state).toBe("zombie");
+	});
+
+	test("between_turns → zombie lands (watchdog terminate after long idle)", () => {
+		store.upsert(makeSession({ state: "between_turns" }));
+		const outcome = store.tryTransitionState("test-agent", "zombie");
+		expect(outcome.ok).toBe(true);
+		expect(store.getByName("test-agent")?.state).toBe("zombie");
+	});
+
+	test("in_turn → stalled lands (watchdog escalate)", () => {
+		store.upsert(makeSession({ state: "in_turn" }));
+		const outcome = store.tryTransitionState("test-agent", "stalled");
+		expect(outcome.ok).toBe(true);
+		expect(store.getByName("test-agent")?.state).toBe("stalled");
+	});
+
+	test("idempotent in_turn → in_turn is allowed (re-entering on same batch)", () => {
+		store.upsert(makeSession({ state: "in_turn" }));
+		const outcome = store.tryTransitionState("test-agent", "in_turn");
+		expect(outcome.ok).toBe(true);
+	});
+
+	test("idempotent between_turns → between_turns is allowed", () => {
+		store.upsert(makeSession({ state: "between_turns" }));
+		const outcome = store.tryTransitionState("test-agent", "between_turns");
+		expect(outcome.ok).toBe(true);
+	});
+
+	test("completed → in_turn is rejected (sticky completed)", () => {
+		store.upsert(makeSession({ state: "completed" }));
+		const outcome = store.tryTransitionState("test-agent", "in_turn");
+		expect(outcome.ok).toBe(false);
+		expect(store.getByName("test-agent")?.state).toBe("completed");
+	});
+
+	test("zombie → in_turn is rejected (turn-runner cannot revive zombie)", () => {
+		store.upsert(makeSession({ state: "zombie" }));
+		const outcome = store.tryTransitionState("test-agent", "in_turn");
+		expect(outcome.ok).toBe(false);
+		expect(store.getByName("test-agent")?.state).toBe("zombie");
+	});
+
+	test("zombie → between_turns is rejected", () => {
+		store.upsert(makeSession({ state: "zombie" }));
+		const outcome = store.tryTransitionState("test-agent", "between_turns");
+		expect(outcome.ok).toBe(false);
+		expect(store.getByName("test-agent")?.state).toBe("zombie");
+	});
+
+	test("nothing transitions into booting from in_turn or between_turns", () => {
+		store.upsert(makeSession({ state: "in_turn" }));
+		const outcome = store.tryTransitionState("test-agent", "booting");
+		expect(outcome.ok).toBe(false);
+		if (!outcome.ok && outcome.reason === "illegal_transition") {
+			expect(outcome.prev).toBe("in_turn");
+		}
+	});
+});
+
+// === migration: pre-3087 CHECK constraint relaxation ===
+//
+// SQLite cannot DROP a CHECK constraint in place, so the old inline CHECK on
+// the `state` column must be removed by rebuilding the table. The migration
+// must preserve every existing row verbatim and let inserts of the new
+// values (and any future state extensions) land without a schema bump.
+
+describe("migration: drop legacy state CHECK constraint", () => {
+	test("rebuilds the table when the recorded CHECK predates 3087", async () => {
+		store.close();
+
+		const { Database: Db } = await import("bun:sqlite");
+		const legacyDb = new Db(dbPath);
+		legacyDb.exec("DROP TABLE IF EXISTS sessions");
+		// Recreate using the pre-3087 CHECK so the migration has something
+		// to detect and rebuild.
+		legacyDb.exec(`
+			CREATE TABLE sessions (
+				id TEXT PRIMARY KEY,
+				agent_name TEXT NOT NULL UNIQUE,
+				capability TEXT NOT NULL,
+				worktree_path TEXT NOT NULL,
+				branch_name TEXT NOT NULL,
+				task_id TEXT NOT NULL,
+				tmux_session TEXT NOT NULL,
+				state TEXT NOT NULL DEFAULT 'booting'
+					CHECK(state IN ('booting','working','completed','stalled','zombie')),
+				pid INTEGER,
+				parent_agent TEXT,
+				depth INTEGER NOT NULL DEFAULT 0,
+				run_id TEXT,
+				started_at TEXT NOT NULL,
+				last_activity TEXT NOT NULL,
+				escalation_level INTEGER NOT NULL DEFAULT 0,
+				stalled_since TEXT,
+				transcript_path TEXT,
+				prompt_version TEXT,
+				claude_session_id TEXT
+			)
+		`);
+		legacyDb.exec(`
+			INSERT INTO sessions
+				(id, agent_name, capability, worktree_path, branch_name, task_id,
+				 tmux_session, state, started_at, last_activity)
+			VALUES
+				('legacy-1','legacy-agent','builder','/tmp/wt','branch','task',
+				 '','working','2026-01-01T00:00:00.000Z','2026-01-01T00:00:00.000Z')
+		`);
+		legacyDb.close();
+
+		// Opening a new SessionStore must run the migration and accept new states.
+		const migrated = createSessionStore(dbPath);
+		try {
+			expect(migrated.getByName("legacy-agent")?.state).toBe("working");
+			migrated.upsert(makeSession({ agentName: "fresh-it", id: "s-it", state: "in_turn" }));
+			migrated.upsert(makeSession({ agentName: "fresh-bt", id: "s-bt", state: "between_turns" }));
+			expect(migrated.getByName("fresh-it")?.state).toBe("in_turn");
+			expect(migrated.getByName("fresh-bt")?.state).toBe("between_turns");
+		} finally {
+			migrated.close();
+		}
+
+		store = createSessionStore(join(tempDir, "unused.db"));
+	});
+
+	test("is a no-op when the CHECK has already been dropped (idempotent)", () => {
+		// `store` was created by beforeEach against a fresh DB whose CREATE
+		// TABLE no longer carries a CHECK on `state`. Reopen on the same path
+		// and verify it does not throw or rebuild gratuitously.
+		store.upsert(makeSession({ state: "in_turn" }));
+
+		const reopened = createSessionStore(dbPath);
+		try {
+			expect(reopened.getByName("test-agent")?.state).toBe("in_turn");
+		} finally {
+			reopened.close();
+		}
+	});
+});
+
 // === tmux_session clearing on terminal transitions (overstory-14c0) ===
 //
 // The tmux session is torn down by ov stop / watchdog / coordinator cleanup

package/src/sessions/store.ts

@@ -29,15 +29,25 @@ import type {
  *     wrote zombie is rejected — last writer no longer wins.
  *   - Idempotent self-transitions (e.g. `working → working`) are allowed.
  *   - `booting` is set only by the initial `upsert` and never re-entered.
+ *   - `in_turn` and `between_turns` cycle while a spawn-per-turn worker is
+ *     alive (overstory-3087): turn-runner advances `between_turns → in_turn`
+ *     when the next batch produces its first parser event and settles back
+ *     `in_turn → between_turns` when the turn ends without a terminal mail.
+ *     Both can advance forward to `stalled`/`zombie`/`completed`. The two
+ *     paths are kept separate from the tmux/long-lived `working` rank — a
+ *     spawn-per-turn worker should not flow through `working` during normal
+ *     operation — so neither lists `working` as a predecessor.
  *
  * See overstory-a993 for the race symptoms this guard prevents.
  */
 const TRANSITION_ALLOWED_FROM: Record<AgentState, readonly AgentState[]> = {
 	booting: [],
 	working: ["booting", "working", "stalled"],
-	stalled: ["booting", "working", "stalled"],
-	completed: ["booting", "working", "stalled", "zombie", "completed"],
-	zombie: ["booting", "working", "stalled", "zombie"],
+	in_turn: ["booting", "in_turn", "between_turns", "stalled"],
+	between_turns: ["in_turn", "between_turns", "stalled"],
+	stalled: ["booting", "working", "in_turn", "between_turns", "stalled"],
+	completed: ["booting", "working", "in_turn", "between_turns", "stalled", "zombie", "completed"],
+	zombie: ["booting", "working", "in_turn", "between_turns", "stalled", "zombie"],
 };
 
 /**
@@ -57,7 +67,14 @@ export interface SessionStore {
 	upsert(session: AgentSession): void;
 	/** Get a session by agent name, or null if not found. */
 	getByName(agentName: string): AgentSession | null;
-	/** Get all active sessions (state IN ('booting', 'working', 'stalled')). */
+	/**
+	 * Get all active sessions (state IN ('booting', 'working', 'in_turn',
+	 * 'between_turns', 'stalled')).
+	 *
+	 * `in_turn` and `between_turns` are spawn-per-turn equivalents of `working`
+	 * and must be returned by `getActive` so the watchdog and dashboards see
+	 * spawn-per-turn workers as alive (overstory-3087).
+	 */
 	getActive(): AgentSession[];
 	/** Get all sessions regardless of state. */
 	getAll(): AgentSession[];
@@ -142,8 +159,7 @@ CREATE TABLE IF NOT EXISTS sessions (
   branch_name TEXT NOT NULL,
   task_id TEXT NOT NULL,
   tmux_session TEXT NOT NULL,
-  state TEXT NOT NULL DEFAULT 'booting'
-    CHECK(state IN ('booting','working','completed','stalled','zombie')),
+  state TEXT NOT NULL DEFAULT 'booting',
   pid INTEGER,
   parent_agent TEXT,
   depth INTEGER NOT NULL DEFAULT 0,
@@ -251,6 +267,83 @@ function migrateAddClaudeSessionId(db: Database): void {
 	}
 }
 
+/**
+ * Drop the inline CHECK(state IN (...)) constraint from the sessions table
+ * (overstory-3087).
+ *
+ * The CHECK was defensive — the TypeScript `AgentState` union enforces values
+ * at the writer boundary. With the spawn-per-turn substate split (`in_turn` /
+ * `between_turns`) and likely future state extensions, keeping the constraint
+ * in sync with the union via inline-CHECK rebuilds becomes a recurring tax.
+ * Drop it and rely on the type system.
+ *
+ * SQLite has no `ALTER TABLE DROP CONSTRAINT`, so we detect the old constraint
+ * via `sqlite_master.sql` (the recorded CREATE TABLE DDL), then rebuild the
+ * table inside a transaction: copy rows verbatim into a new constraint-free
+ * schema, drop the original, and rename. Indexes are dropped by the swap and
+ * re-created by the caller via CREATE_INDEXES, which is idempotent.
+ *
+ * Safe to call multiple times — short-circuits when the recorded DDL no
+ * longer contains a CHECK on `state`. Must run BEFORE indexes are created
+ * (the swap drops them) and BEFORE the column-add migrations that read
+ * `PRAGMA table_info` on the legacy table (the new table inherits any added
+ * columns via the rebuild, so the column-add migrations become idempotent).
+ */
+function migrateRelaxStateCheck(db: Database): void {
+	const row = db
+		.prepare<{ sql: string | null }, []>(
+			"SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'sessions'",
+		)
+		.get();
+	if (!row || row.sql === null) return;
+	// Detect the inline CHECK on the `state` column. Match conservatively on
+	// the literal "CHECK(state IN" — any whitespace variant SQLite stores
+	// will still contain this substring.
+	if (!row.sql.includes("CHECK(state IN")) return;
+
+	// Discover the columns that exist on the LIVE table so the rebuild copies
+	// every column the column-add migrations have layered on. Hard-coding the
+	// column list would silently drop newer columns when this migration runs
+	// against a DB that earlier migrations have already extended.
+	const colInfo = db.prepare("PRAGMA table_info(sessions)").all() as Array<{
+		name: string;
+		type: string;
+		notnull: number;
+		dflt_value: string | null;
+		pk: number;
+	}>;
+
+	// Render each column for the new CREATE TABLE. PRIMARY KEY and UNIQUE are
+	// preserved on `id` and `agent_name` respectively to match the original
+	// schema; everything else is straight type + nullability + default.
+	const colDefs = colInfo
+		.map((c) => {
+			const parts: string[] = [c.name, c.type || "TEXT"];
+			if (c.pk === 1) parts.push("PRIMARY KEY");
+			if (c.notnull === 1) parts.push("NOT NULL");
+			if (c.dflt_value !== null) parts.push(`DEFAULT ${c.dflt_value}`);
+			if (c.name === "agent_name") parts.push("UNIQUE");
+			return `\t\t\t\t${parts.join(" ")}`;
+		})
+		.join(",\n");
+	const colNames = colInfo.map((c) => c.name).join(", ");
+
+	db.exec("BEGIN");
+	try {
+		db.exec(`CREATE TABLE sessions__new_3087 (\n${colDefs}\n\t\t\t)`);
+		db.exec(`
+			INSERT INTO sessions__new_3087 (${colNames})
+			SELECT ${colNames} FROM sessions
+		`);
+		db.exec("DROP TABLE sessions");
+		db.exec("ALTER TABLE sessions__new_3087 RENAME TO sessions");
+		db.exec("COMMIT");
+	} catch (err) {
+		db.exec("ROLLBACK");
+		throw err;
+	}
+}
+
 /**
  * Migrate an existing sessions table from bead_id to task_id column.
  * Safe to call multiple times — only renames if bead_id exists and task_id does not.
@@ -282,6 +375,10 @@ export function createSessionStore(dbPath: string): SessionStore {
 	db.exec(CREATE_RUNS_TABLE);
 
 	// Migrate existing tables BEFORE creating indexes that reference new columns.
+	// `migrateRelaxStateCheck` runs FIRST so the column-add migrations that
+	// follow operate on the rebuilt table — they read PRAGMA table_info and
+	// ADD COLUMN, both of which work on the new constraint-free schema.
+	migrateRelaxStateCheck(db);
 	migrateBeadIdToTaskId(db);
 	migrateAddTranscriptPath(db);
 	migrateAddPromptVersion(db);
@@ -353,7 +450,8 @@ export function createSessionStore(dbPath: string): SessionStore {
 	`);
 
 	const getActiveStmt = db.prepare<SessionRow, Record<string, never>>(`
-		SELECT * FROM sessions WHERE state IN ('booting', 'working', 'stalled')
+		SELECT * FROM sessions
+		WHERE state IN ('booting', 'working', 'in_turn', 'between_turns', 'stalled')
 		ORDER BY started_at ASC
 	`);
 

package/src/types.ts

@@ -187,7 +187,33 @@ export type Capability = (typeof SUPPORTED_CAPABILITIES)[number];
 
 // === Agent Session ===
 
-export type AgentState = "booting" | "working" | "completed" | "stalled" | "zombie";
+/**
+ * Agent lifecycle states.
+ *
+ * `in_turn` and `between_turns` are spawn-per-turn-specific substates that
+ * split the legacy `working` state so the UI can distinguish a worker actively
+ * executing a turn from one idling between mail batches (overstory-3087):
+ *
+ *   - `in_turn`: the turn-runner has observed at least one parser event from
+ *     a live claude subprocess. The agent is mid-execution.
+ *   - `between_turns`: the turn-runner finished a turn without a terminal
+ *     mail; the agent is alive (process gone, session pinned) and waiting
+ *     for the next mail batch to spawn a fresh turn.
+ *
+ * `working` remains the active state for tmux/long-lived headless agents
+ * (coordinator, orchestrator, monitor, sapling) which have no per-turn
+ * boundary. Spawn-per-turn workers (builder/scout/reviewer/lead/merger
+ * under the headless default) transition through in_turn ↔ between_turns
+ * instead.
+ */
+export type AgentState =
+	| "booting"
+	| "working"
+	| "in_turn"
+	| "between_turns"
+	| "completed"
+	| "stalled"
+	| "zombie";
 
 /**
  * Result of a guarded state transition attempt (`SessionStore.tryTransitionState`).
@@ -446,6 +472,13 @@ export interface OverlayConfig {
 	qualityGates?: QualityGate[];
 	/** Relative path to the instruction file within the worktree (runtime-specific). Defaults to .claude/CLAUDE.md. */
 	instructionPath?: string;
+	/**
+	 * Names of sibling agents dispatched in parallel that may share file scope
+	 * with this agent. When set, the overlay renders a "Parallel Siblings"
+	 * section with rebase-before-merge_ready guidance (overstory-f76a). Empty
+	 * or unset → no overlay section.
+	 */
+	siblings?: string[];
 }
 
 // === Merge Queue ===
@@ -491,6 +524,23 @@ export interface ConflictHistory {
 	predictedConflictFiles: string[];
 }
 
+/**
+ * Side-effect-free prediction of how `ov merge` would resolve a branch.
+ * Produced by `predictConflicts` (src/merge/predict.ts) without touching HEAD,
+ * the working tree, or the merge lock — surfaced via `ov merge --dry-run` so a
+ * lead/operator/greenhouse can branch on `wouldRequireAgent`.
+ */
+export interface ConflictPrediction {
+	/** The tier `ov merge` would land in if invoked now. */
+	predictedTier: ResolutionTier;
+	/** Files that would conflict — empty for clean-merge. */
+	conflictFiles: string[];
+	/** True iff predictedTier is "ai-resolve" or "reimagine" (Tier 3+). */
+	wouldRequireAgent: boolean;
+	/** Short, operator-readable explanation for the predicted tier. */
+	reason: string;
+}
+
 // === Watchdog ===
 
 export interface HealthCheck {

package/src/watchdog/daemon.test.ts

@@ -531,6 +531,123 @@ describe("daemon tick", () => {
 		expect(reloaded[0]?.stalledSince).toBeNull();
 	});
 
+	// Regression tests for overstory-74ce: killAgent() must never call
+	// tmux.killSession("") for headless agents — an empty `-t` argument is
+	// prefix-matched and would wildcard-kill the entire overstory tmux server.
+
+	test("spawn-per-turn agent at level 3 termination does NOT call tmux.killSession", async () => {
+		const nudgeIntervalMs = 60_000;
+		const stalledSince = new Date(Date.now() - 4 * nudgeIntervalMs).toISOString();
+		const staleActivity = new Date(Date.now() - THRESHOLDS.staleThresholdMs * 2).toISOString();
+
+		// Spawn-per-turn worker between turns: tmuxSession === "" AND pid === null.
+		// Before the fix, killAgent fell through to tmux.killSession("") which
+		// prefix-matches every session in the overstory tmux server.
+		const session = makeSession({
+			agentName: "spawn-per-turn-doomed",
+			tmuxSession: "",
+			pid: null,
+			state: "stalled",
+			lastActivity: staleActivity,
+			escalationLevel: 2,
+			stalledSince,
+		});
+
+		writeSessionsToStore(tempRoot, [session]);
+
+		// No tmux sessions registered — emulates production where the spawn-per-turn
+		// agent has no named session.
+		const tmuxMock = tmuxWithLiveness({});
+
+		await runDaemonTick({
+			root: tempRoot,
+			...THRESHOLDS,
+			nudgeIntervalMs,
+			tier1Enabled: false,
+			_tmux: tmuxMock,
+			_triage: triageAlways("extend"),
+			_nudge: nudgeTracker().nudge,
+			_eventStore: null,
+			_recordFailure: async () => {},
+			_getConnection: () => undefined,
+			_removeConnection: () => {},
+			_tailerRegistry: new Map(),
+			_findLatestStdoutLog: async () => null,
+		});
+
+		// Critical assertion: no wildcard kill attempt. tmuxMock.killed must be empty.
+		expect(tmuxMock.killed).toHaveLength(0);
+
+		// The session is still transitioned to zombie — termination semantics are preserved,
+		// just without the wildcard tmux kill.
+		const reloaded = readSessionsFromStore(tempRoot);
+		expect(reloaded[0]?.state).toBe("zombie");
+		expect(reloaded[0]?.escalationLevel).toBe(0);
+		expect(reloaded[0]?.stalledSince).toBeNull();
+	});
+
+	test("long-lived headless agent at level 3 termination kills pid tree, not tmux", async () => {
+		const nudgeIntervalMs = 60_000;
+		const stalledSince = new Date(Date.now() - 4 * nudgeIntervalMs).toISOString();
+		const staleActivity = new Date(Date.now() - THRESHOLDS.staleThresholdMs * 2).toISOString();
+
+		// Long-lived headless capability (e.g. coordinator/orchestrator/monitor):
+		// tmuxSession === "" AND pid !== null. The PID tree should be killed; tmux
+		// must not be touched.
+		const session = makeSession({
+			agentName: "headless-long-lived-doomed",
+			tmuxSession: "",
+			pid: process.pid, // alive PID — health eval won't short-circuit to direct terminate
+			state: "stalled",
+			lastActivity: staleActivity,
+			escalationLevel: 2,
+			stalledSince,
+		});
+
+		writeSessionsToStore(tempRoot, [session]);
+
+		const killedPids: number[] = [];
+		const procMock = {
+			isAlive: (pid: number) => {
+				try {
+					process.kill(pid, 0);
+					return true;
+				} catch {
+					return false;
+				}
+			},
+			killTree: async (pid: number) => {
+				killedPids.push(pid);
+			},
+		};
+
+		const tmuxMock = tmuxWithLiveness({});
+
+		await runDaemonTick({
+			root: tempRoot,
+			...THRESHOLDS,
+			nudgeIntervalMs,
+			tier1Enabled: false,
+			_tmux: tmuxMock,
+			_triage: triageAlways("extend"),
+			_nudge: nudgeTracker().nudge,
+			_process: procMock,
+			_eventStore: null,
+			_recordFailure: async () => {},
+			_getConnection: () => undefined,
+			_removeConnection: () => {},
+			_tailerRegistry: new Map(),
+			_findLatestStdoutLog: async () => null,
+		});
+
+		// PID tree was killed; tmux.killSession was never called.
+		expect(killedPids).toContain(process.pid);
+		expect(tmuxMock.killed).toHaveLength(0);
+
+		const reloaded = readSessionsFromStore(tempRoot);
+		expect(reloaded[0]?.state).toBe("zombie");
+	});
+
 	test("triage retry sends nudge with recovery message", async () => {
 		const staleActivity = new Date(Date.now() - 60_000).toISOString();
 		const stalledSince = new Date(Date.now() - 130_000).toISOString();
@@ -2765,10 +2882,15 @@ describe("headless agent stale detection via events.db (Bug 2)", () => {
 			});
 
 			// lastActivity refreshed from events.db → spawn-per-turn evaluation
-			// path keeps the agent in working, NOT zombie.
+			// path keeps the agent active (action=none), NOT zombie. The
+			// healthy classification reports `between_turns` (overstory-3087)
+			// for spawn-per-turn workers; the legacy `working` row stays at
+			// `working` on disk because the matrix does not list `working` as
+			// a predecessor of `between_turns` and the CAS rejects the write
+			// (the substate cycle is reserved for the turn-runner).
 			expect(checks).toHaveLength(1);
 			expect(checks[0]?.action).toBe("none");
-			expect(checks[0]?.state).toBe("working");
+			expect(checks[0]?.state).toBe("between_turns");
 
 			const reloaded = readSessionsFromStore(tempRoot);
 			expect(reloaded[0]?.state).toBe("working");