@excitedjs/dreamux 0.13.0 → 0.14.0

package/dist/dispatcher-service/teammate/service.js

@@ -1,18 +1,22 @@
 import { Buffer } from 'node:buffer';
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { BUILTIN_CLAUDE_CODE_PROVIDER_REF, } from '../../config/config.js';
 import { teammateClaudeCodeStreamLogPath } from '../../agent-runtime/builtin/claude-code/paths.js';
 import { teammateCodexAppServerErrorLogPath, teammateCodexAppServerLogPath, } from '../../agent-runtime/builtin/codex/paths.js';
-import { dispatcherTeamMateRuntimeDir } from '../../platform/paths.js';
+import { dispatcherCompletionSpillDir, dispatcherTeamMateRuntimeDir, } from '../../platform/paths.js';
 import { validateDispatcherId } from '../../state/dispatcher-id.js';
+import { ensureDispatcherWorkspace } from '../dispatcher-workspace.js';
 import { TeamMateIdentityStore } from './identity-store.js';
 import { TeamMateRuntimeStateStore } from './runtime-state.js';
+import { TeamMateSessionLedger } from './session-ledger.js';
+import { allocateConcreteName } from './name-allocator.js';
 import { WorktreeManager } from './worktree-manager.js';
-import { validateTeamMateName, dispatcherPrincipal, principalDispatcherId, } from './types.js';
+import { requireLifecycleText, validateTeamMateName, dispatcherPrincipal, principalDispatcherId, } from './types.js';
 const TURN_ORIGIN_CACHE_LIMIT = 256;
 export class TeamMateAgentService {
     opts;
     identities;
+    sessionLedger;
     worktrees = new WorktreeManager();
     live = new Map();
     submissionSeq = 0;
@@ -21,24 +25,69 @@ export class TeamMateAgentService {
         this.identities = new TeamMateIdentityStore({
             warn: (message, fields) => opts.log.warn(fields ?? {}, message),
         });
+        this.sessionLedger = new TeamMateSessionLedger({
+            warn: (message, fields) => opts.log.warn(fields ?? {}, message),
+        });
+    }
+    /**
+     * Read-only access to the durable session ledger (issue #182 PR-5). The
+     * public, filterable read surface is built on this in PR-6; exposed now so
+     * tests and future read tools can materialize recovery rows.
+     */
+    sessions() {
+        return this.sessionLedger;
+    }
+    /**
+     * Allocate a concrete, never-reused TeamLeader name for a team (issue #188).
+     * The Team service calls this once at create time and persists the result as
+     * the team's durable `leader_name`; routing reads that stored name rather
+     * than reconstructing `${teamId}-leader`.
+     */
+    async allocateLeaderName(dispatcherId, teamId) {
+        return this.allocateName(dispatcherId, 'team_leader', teamId, teamId);
+    }
+    /**
+     * Allocate a concrete name from an agent-supplied base slug (issue #188).
+     * Uniqueness is checked against ALL persisted identities (closed included),
+     * so a concrete name is never reused; the suffix is regenerated on collision
+     * and the allocation fails loudly if the attempt budget is exhausted.
+     */
+    async allocateName(dispatcherId, role, base, teamSlug) {
+        const identities = await this.identities.list(dispatcherId);
+        const taken = new Set(identities.map((identity) => identity.name));
+        return allocateConcreteName({
+            role,
+            base,
+            ...(teamSlug !== undefined ? { teamSlug } : {}),
+            exists: (candidate) => taken.has(candidate),
+            ...(this.opts.suffixGenerator !== undefined
+                ? { generateSuffix: this.opts.suffixGenerator }
+                : {}),
+        });
     }
     async spawn(input) {
         return this.spawnScoped({
             principal: dispatcherPrincipal(input.dispatcherId),
             name: input.name,
             prompt: input.prompt,
+            intent: input.intent,
             ...(input.agentRuntime !== undefined ? { agentRuntime: input.agentRuntime } : {}),
             cwd: input.cwd,
             ...(input.worktree !== undefined ? { worktree: input.worktree } : {}),
-            ...(input.intent !== undefined ? { intent: input.intent } : {}),
         });
     }
     async spawnScoped(input) {
         const dispatcherId = principalDispatcherId(input.principal);
-        const name = validateTeamMateName(input.name);
         if (input.principal.kind === 'teammate') {
             throw new Error('ordinary TeamMates cannot spawn TeamMates');
         }
+        // The agent-supplied `name` is a base slug / display hint, not the final
+        // address (issue #188): require it non-empty, then allocate a concrete,
+        // never-reused name below and return it in the spawn result.
+        const displayName = requireLifecycleText(input.name, 'TeamMate spawn name');
+        // Required recovery subject — enforced here too for in-process callers that
+        // bypass the MCP shim / admin layer (issue #182 PR-3).
+        requireLifecycleText(input.intent, 'TeamMate spawn intent');
         const cwd = input.sharedWorkspace?.sourceCwd ?? input.cwd;
         if (input.principal.kind === 'team_leader' && input.sharedWorkspace === undefined) {
             throw new Error('TeamLeader member spawn requires a shared team workspace');
@@ -46,64 +95,64 @@ export class TeamMateAgentService {
         if (typeof cwd !== 'string' || cwd.trim() === '') {
             throw new Error('TeamMate spawn requires cwd');
         }
-        const existing = await this.identities.get(dispatcherId, name);
-        if (existing !== null && existing.status !== 'closed') {
-            throw new Error(`TeamMate ${JSON.stringify(name)} already exists; use send`);
-        }
+        const owner = ownerForPrincipal(input.principal);
+        const role = input.principal.kind === 'team_leader' ? 'team_member' : 'teammate';
+        // Allocate the concrete address from the requested slug (Team members get
+        // the `tm-` rule). Checked against all persisted identities, never reused.
+        const name = await this.allocateName(dispatcherId, role, displayName);
         const agentRuntimeId = input.agentRuntime ?? this.defaultAgentRuntime(dispatcherId);
         const agent = this.resolveAgent(dispatcherId, agentRuntimeId);
         const provider = this.opts.agentRuntimeProviders.resolve(agent.provider);
+        // Only a managed worktree is placed under the dispatcher workspace, so only
+        // managed mode resolves (and thus enforces) the dispatcher cwd contract;
+        // reuse-cwd never forces it (issue #182 PR-4).
+        const managedMode = (input.worktree?.mode ?? 'reuse-cwd') === 'managed';
         const workspace = input.sharedWorkspace ??
             (await this.worktrees.prepare({
                 dispatcherId,
                 teammateName: name,
                 cwd,
+                ...(managedMode
+                    ? { dispatcherWorkspace: await this.dispatcherWorkspace(dispatcherId) }
+                    : {}),
                 request: input.worktree,
             }));
         if (input.sharedWorkspace === undefined) {
             await this.assertManagedWorktreeAvailable(dispatcherId, name, workspace.worktree);
         }
-        const owner = ownerForPrincipal(input.principal);
-        const role = input.principal.kind === 'team_leader' ? 'team_member' : 'teammate';
-        let identity = existing ??
-            (await this.identities.create({
-                dispatcherId,
-                name,
-                owner,
-                role,
-                teamId: owner.kind === 'team' ? owner.team_id : null,
-                agentRuntime: agentRuntimeId,
-                sourceCwd: workspace.sourceCwd,
-                sourceRepo: workspace.sourceRepo,
-                cwd: workspace.runtimeCwd,
-                runtimeCwd: workspace.runtimeCwd,
-                worktree: workspace.worktree,
-                intent: input.intent ?? null,
-            }));
-        this.assertPrincipalCanAccess(input.principal, identity);
-        identity = await this.identities.update(identity, {
+        // A spawn always starts a fresh runtime session, so it mints a new session
+        // id (issue #182 PR-5). The concrete name is fresh, so this is always a
+        // create — there is no closed-identity reuse path (issue #188).
+        const sessionId = randomUUID();
+        let identity = await this.identities.create({
+            dispatcherId,
+            name,
+            displayName,
+            owner,
+            role,
+            teamId: owner.kind === 'team' ? owner.team_id : null,
             agentRuntime: agentRuntimeId,
+            sessionId,
             sourceCwd: workspace.sourceCwd,
             sourceRepo: workspace.sourceRepo,
             cwd: workspace.runtimeCwd,
             runtimeCwd: workspace.runtimeCwd,
             worktree: workspace.worktree,
-            intent: input.intent ?? null,
+            intent: input.intent,
             status: 'starting',
-            closedAt: null,
-            closeNote: null,
-            lastError: null,
-            checkpoint: null,
         });
+        this.assertPrincipalCanAccess(input.principal, identity);
         const live = await this.startRuntime(dispatcherId, identity, provider, agent);
         identity = live.state.current();
         const turn = await this.submitPrompt(dispatcherId, name, input.prompt, {
             principal: input.principal,
         });
-        await this.identities.appendHistory(live.state.current(), {
+        await this.sessionLedger.append({
+            identity: live.state.current(),
             type: 'spawn',
             prompt: input.prompt,
             turnId: turn.turn_id ?? null,
+            turnOrigin: principalTurnOrigin(input.principal),
         });
         return { teammate: this.toStatus(live.state.current(), live.runtime), turn };
     }
@@ -112,6 +161,7 @@ export class TeamMateAgentService {
             principal: dispatcherPrincipal(input.dispatcherId),
             name: input.name,
             prompt: input.prompt,
+            ...(input.intent !== undefined ? { intent: input.intent } : {}),
         });
     }
     async sendScoped(input) {
@@ -119,19 +169,33 @@ export class TeamMateAgentService {
         // not live — including one previously `close`d — is reopened from its
         // persisted checkpoint and the turn is submitted, so send always works as
         // long as the identity exists. reopenClosed scopes this revival to send;
-        // read-only verbs (last/ctx/status) never silently reopen a closed teammate.
+        // read-only verbs (last/status) never silently reopen a closed teammate.
         const dispatcherId = principalDispatcherId(input.principal);
         const live = await this.ensureRuntime(dispatcherId, input.name, {
             principal: input.principal,
             reopenClosed: true,
         });
+        // Optional intent update is applied BEFORE the turn so the recorded recovery
+        // subject reflects the work this turn is about (issue #182 PR-3). An empty
+        // string is ignored so a stray send never wipes a meaningful subject.
+        if (input.intent !== undefined && input.intent !== '') {
+            await live.state.updateIntent(input.intent);
+        }
         const turn = await this.submitPrompt(dispatcherId, input.name, input.prompt, {
             principal: input.principal,
         });
-        await this.identities.appendHistory(live.state.current(), {
+        // The send may have reopened a closed teammate from its checkpoint, so the
+        // session ledger continues the SAME session id carried on the identity
+        // (issue #182 PR-5); the optional intent update above is already reflected.
+        // A pre-PR-5 identity has no session id yet — mint one lazily so the event
+        // is captured rather than skipped (PR #187 review P3).
+        await live.state.ensureSessionId();
+        await this.sessionLedger.append({
+            identity: live.state.current(),
             type: 'send',
             prompt: input.prompt,
             turnId: turn.turn_id ?? null,
+            turnOrigin: principalTurnOrigin(input.principal),
         });
         return { teammate: this.toStatus(live.state.current(), live.runtime), turn };
     }
@@ -139,13 +203,17 @@ export class TeamMateAgentService {
         return this.closeScoped({
             principal: dispatcherPrincipal(input.dispatcherId),
             name: input.name,
-            ...(input.note !== undefined ? { note: input.note } : {}),
+            note: input.note,
         });
     }
     async closeScoped(input) {
         const dispatcherId = principalDispatcherId(input.principal);
         const name = validateTeamMateName(input.name);
         const identity = await this.mustIdentity(dispatcherId, name, input.principal);
+        // Required close reason — enforced for in-process callers too (issue #182
+        // PR-3); the Team dissolve path supplies an explicit note. Checked after the
+        // existence/access lookup so an inaccessible teammate reports that first.
+        requireLifecycleText(input.note, 'TeamMate close note');
         const key = liveKey(dispatcherId, name);
         const live = this.live.get(key);
         if (live !== undefined) {
@@ -155,12 +223,17 @@ export class TeamMateAgentService {
         const closed = await this.identities.update(identity, {
             status: 'closed',
             closedAt: Date.now(),
-            closeNote: input.note ?? null,
+            closeNote: input.note,
             worktree: await this.worktrees.cleanup(identity),
+            // A pre-PR-5 identity has no session id; mint a fresh, stable one in the
+            // same close write so the close event is captured rather than skipped
+            // (PR #187 review P3). Never re-keyed to the runtime thread id.
+            ...(identity.session_id === null ? { sessionId: randomUUID() } : {}),
         });
-        await this.identities.appendHistory(closed, {
+        await this.sessionLedger.append({
+            identity: closed,
             type: 'close',
-            note: input.note ?? null,
+            note: input.note,
         });
         return { teammate: this.toStatus(closed, null) };
     }
@@ -190,10 +263,28 @@ export class TeamMateAgentService {
     }
     async historyScoped(input) {
         const dispatcherId = principalDispatcherId(input.principal);
+        // `history` is the durable session-ledger recovery surface (issue #188): the
+        // session ledger is the source of every recovery fact (prompts, assistant
+        // output, intent, turn count, last-seen). The per-name forward-only history
+        // index is no longer read here. We still enumerate one row per teammate
+        // identity — joining each to its session row — so the surface also covers a
+        // legacy/never-captured teammate that has no ledger session yet, and can
+        // surface live-only facts the ledger does not hold (runtime status, the
+        // resume checkpoint, worktree cleanup state).
         const identities = await this.identities.list(dispatcherId);
+        const sessions = await this.sessionLedger.materializeSessions(dispatcherId);
+        // One session per teammate name (concrete names are never reused, so this is
+        // 1:1); if a name somehow carries more than one session id, keep the latest.
+        const sessionByName = new Map();
+        for (const session of sessions) {
+            const prev = sessionByName.get(session.name);
+            if (prev === undefined || session.last_seen_at >= prev.last_seen_at) {
+                sessionByName.set(session.name, session);
+            }
+        }
         const rows = [];
         for (const identity of identities) {
-            const row = await this.toLedgerRow(identity);
+            const row = this.toLedgerRow(identity, sessionByName.get(identity.name) ?? null);
             if (principalCanAccess(input.principal, identity) &&
                 this.matchesLedgerQuery(row, input)) {
                 rows.push(row);
@@ -211,46 +302,128 @@ export class TeamMateAgentService {
             next_cursor: next < rows.length ? encodeCursor(next) : null,
         };
     }
-    async historyEvents(dispatcherId, name) {
-        return this.historyEventsScoped(dispatcherPrincipal(dispatcherId), name);
+    async last(dispatcherId, name, turns) {
+        return this.lastScoped(dispatcherPrincipal(dispatcherId), name, turns);
     }
-    async historyEventsScoped(principal, name) {
-        const dispatcherId = principalDispatcherId(principal);
-        const teammateName = validateTeamMateName(name);
-        const identity = await this.identities.get(dispatcherId, teammateName);
-        if (identity !== null)
-            this.assertPrincipalCanAccess(principal, identity);
-        return {
-            teammate: identity === null
-                ? null
-                : this.toStatus(identity, this.live.get(liveKey(dispatcherId, teammateName))?.runtime ?? null),
-            events: await this.identities.history(dispatcherId, teammateName),
-        };
-    }
-    async last(dispatcherId, name) {
-        return this.lastScoped(dispatcherPrincipal(dispatcherId), name);
-    }
-    async lastScoped(principal, name) {
+    /**
+     * Read a closed-or-live teammate's most recent settled turn(s) from the
+     * durable session ledger (issue #188). This is a pure read: it resolves the
+     * concrete name to exactly one identity/session and folds `sessions.jsonl`
+     * filtered by that session id — it NEVER starts, resumes, or requires a live
+     * runtime, so it works after a teammate is closed or stopped. `turns` defaults
+     * to 1 and is clamped-by-rejection to 1..5; the newest turn is `turns.at(-1)`.
+     * This is the failed-completion-delivery fallback, so it returns the assistant
+     * output as completely as it was durably captured (truncation is flagged).
+     */
+    async lastScoped(principal, name, turns) {
+        const requestedTurns = validateLastTurns(turns);
         const dispatcherId = principalDispatcherId(principal);
-        const live = await this.ensureRuntime(dispatcherId, name, {
-            principal,
-        });
-        return {
-            teammate: this.toStatus(live.state.current(), live.runtime),
-            last: await live.runtime.getLast(),
+        const identity = await this.mustIdentity(dispatcherId, validateTeamMateName(name), principal);
+        const teammate = this.toStatus(identity, this.live.get(liveKey(dispatcherId, identity.name))?.runtime ?? null);
+        const sessionId = identity.session_id;
+        if (sessionId === null) {
+            // A pre-#182-PR-5 identity that never settled under a session id has no
+            // durable turns to read; report an empty, well-formed result.
+            return {
+                teammate,
+                session_id: null,
+                requested_turns: requestedTurns,
+                returned_turns: 0,
+                turns: [],
+            };
+        }
+        // Fold the ledger by streaming it in file APPEND ORDER — the only correct
+        // turn ordering, since `event_id`/`timestamp` are both `Date.now()` (a wall
+        // clock that can collide within a millisecond or move backwards on an NTP
+        // step) and must NOT be used to order or pick the latest turn. The fold is
+        // BOUNDED: only the most recent `requestedTurns` settled turns retain their
+        // (possibly 160k-char) assistant text, so memory does not grow with session
+        // length. `firstSeq` records each turn's first-seen (submit) order so a turn
+        // is ranked by when it STARTED, not by when a (possibly duplicate) settle was
+        // written; it holds only short turn ids, never assistant text.
+        let nextSeq = 0;
+        const firstSeq = new Map();
+        const seqOf = (turnId) => {
+            const existing = firstSeq.get(turnId);
+            if (existing !== undefined)
+                return existing;
+            const seq = nextSeq;
+            nextSeq += 1;
+            firstSeq.set(turnId, seq);
+            return seq;
         };
-    }
-    async context(dispatcherId, name) {
-        return this.contextScoped(dispatcherPrincipal(dispatcherId), name);
-    }
-    async contextScoped(principal, name) {
-        const dispatcherId = principalDispatcherId(principal);
-        const live = await this.ensureRuntime(dispatcherId, name, {
-            principal,
-        });
+        // Submit metadata (prompt/intent/origin) for turns not yet paired with a
+        // settle; dropped once paired, so it stays small.
+        const submitMeta = new Map();
+        // The bounded window of settled turns, keyed by turn id; size <= requestedTurns.
+        const recent = new Map();
+        for await (const event of this.sessionLedger.streamSession(dispatcherId, sessionId)) {
+            const turnId = event.turn_id;
+            if (turnId === null)
+                continue;
+            seqOf(turnId);
+            if (event.type === 'spawn' || event.type === 'send') {
+                submitMeta.set(turnId, {
+                    turn_origin: event.turn_origin,
+                    prompt_preview: event.prompt_preview,
+                    intent: event.intent,
+                    submitted_at: event.timestamp,
+                });
+                continue;
+            }
+            if (event.type !== 'settled')
+                continue;
+            const present = recent.get(turnId);
+            if (present !== undefined) {
+                // Duplicate/re-settle of a turn still in the window: override the settle
+                // fields in append order, keeping its already-paired submit fields.
+                present.settle_status = event.settle_status;
+                present.assistant = event.assistant;
+                present.assistant_preview = event.assistant_preview;
+                present.assistant_truncated = event.assistant_truncated;
+                present.settled_at = event.timestamp;
+                continue;
+            }
+            const submit = submitMeta.get(turnId);
+            submitMeta.delete(turnId);
+            recent.set(turnId, {
+                turn_id: turnId,
+                turn_origin: submit?.turn_origin ?? null,
+                prompt_preview: submit?.prompt_preview ?? null,
+                intent: submit?.intent ?? null,
+                submitted_at: submit?.submitted_at ?? null,
+                settled_at: event.timestamp,
+                settle_status: event.settle_status,
+                assistant: event.assistant,
+                assistant_preview: event.assistant_preview,
+                assistant_truncated: event.assistant_truncated,
+            });
+            if (recent.size > requestedTurns) {
+                // Evict the oldest-by-first-seen turn so the window holds the most recent
+                // `requestedTurns` turns by START order (a late re-settle of an already
+                // evicted, older turn is evicted again here rather than resurfacing).
+                let evictId;
+                let evictSeq = Infinity;
+                for (const id of recent.keys()) {
+                    const seq = firstSeq.get(id) ?? Infinity;
+                    if (seq < evictSeq) {
+                        evictSeq = seq;
+                        evictId = id;
+                    }
+                }
+                if (evictId !== undefined)
+                    recent.delete(evictId);
+            }
+        }
+        // `last` is the completion fallback, so it returns SETTLED turns (those with
+        // a durable assistant output), ordered oldest-first by start order.
+        const lastTurns = [...recent.values()].sort((a, b) => (firstSeq.get(a.turn_id) ?? 0) - (firstSeq.get(b.turn_id) ?? 0));
         return {
-            teammate: this.toStatus(live.state.current(), live.runtime),
-            context: await live.runtime.getContext(),
+            teammate,
+            session_id: sessionId,
+            requested_turns: requestedTurns,
+            returned_turns: lastTurns.length,
+            turns: lastTurns,
         };
     }
     async channelInputScoped(principal, name, input) {
@@ -262,13 +435,31 @@ export class TeamMateAgentService {
         const result = await live.runtime.channelInput(input);
         if (result.status === 'submitted') {
             recordTurnOrigin(live, result.turnId, 'channel');
+            // Capture the channel-origin turn in the durable session ledger (issue
+            // #182 PR-5, PR #187 review P1): a TeamLeader's normal user turns arrive
+            // through a bound Team channel here, not via send, and would otherwise be
+            // missing from the session reconstruction. Mint a session id lazily for a
+            // pre-PR-5 identity. Best-effort: the ledger swallows its own write errors.
+            await live.state.ensureSessionId();
+            await this.sessionLedger.append({
+                identity: live.state.current(),
+                type: 'send',
+                prompt: input.text,
+                turnId: result.turnId,
+                turnOrigin: 'channel',
+            });
         }
         return result;
     }
     async createTeamLeader(input) {
         const name = validateTeamMateName(input.name);
+        // #188: a concrete name is never reused — the duplicate check includes closed
+        // identities. The caller (TeamService) always passes a freshly allocated `tl-`
+        // name, so a pre-existing identity under this name (closed OR live) means a
+        // collision or a misuse of this seam; fail loud rather than rebinding the
+        // name to a new session (which would map one concrete name to >1 session).
         const existing = await this.identities.get(input.dispatcherId, name);
-        if (existing !== null && existing.status !== 'closed') {
+        if (existing !== null) {
             throw new Error(`TeamLeader ${JSON.stringify(name)} already exists`);
         }
         const agent = this.resolveAgent(input.dispatcherId, input.agentRuntime);
@@ -277,23 +468,18 @@ export class TeamMateAgentService {
             kind: 'dispatcher',
             dispatcher_id: input.dispatcherId,
         };
-        let identity = existing ??
-            (await this.identities.create({
-                dispatcherId: input.dispatcherId,
-                name,
-                owner,
-                role: 'team_leader',
-                teamId: input.teamId,
-                agentRuntime: input.agentRuntime,
-                sourceCwd: input.sourceCwd,
-                sourceRepo: input.sourceRepo,
-                cwd: input.runtimeCwd,
-                runtimeCwd: input.runtimeCwd,
-                worktree: input.worktree,
-                intent: input.intent ?? null,
-            }));
-        identity = await this.identities.update(identity, {
+        // A fresh TeamLeader session mints a new session id (issue #182 PR-5). The
+        // name is freshly allocated, so this is always a create — no reuse path.
+        const sessionId = randomUUID();
+        let identity = await this.identities.create({
+            dispatcherId: input.dispatcherId,
+            name,
+            displayName: input.displayName ?? null,
+            owner,
+            role: 'team_leader',
+            teamId: input.teamId,
             agentRuntime: input.agentRuntime,
+            sessionId,
             sourceCwd: input.sourceCwd,
             sourceRepo: input.sourceRepo,
             cwd: input.runtimeCwd,
@@ -301,18 +487,16 @@ export class TeamMateAgentService {
             worktree: input.worktree,
             intent: input.intent ?? null,
             status: 'starting',
-            closedAt: null,
-            closeNote: null,
-            lastError: null,
-            checkpoint: null,
         });
         const live = await this.startRuntime(input.dispatcherId, identity, provider, agent);
         identity = live.state.current();
         const turn = await this.submitPrompt(input.dispatcherId, name, input.prompt);
-        await this.identities.appendHistory(live.state.current(), {
+        await this.sessionLedger.append({
+            identity: live.state.current(),
             type: 'spawn',
             prompt: input.prompt,
             turnId: turn.turn_id ?? null,
+            turnOrigin: 'dispatcher',
         });
         return { teammate: this.toStatus(live.state.current(), live.runtime), turn };
     }
@@ -326,7 +510,6 @@ export class TeamMateAgentService {
                 'list',
                 'status',
                 'last',
-                'ctx',
                 'get_capabilities',
             ],
             agent_runtimes: Object.entries(this.opts.config.agents).map(([agentRuntimeId, agent]) => this.agentRuntimeCapability(agentRuntimeId, agent)),
@@ -383,6 +566,7 @@ export class TeamMateAgentService {
             dispatcherId: identity.dispatcher_id,
             teammateName: identity.name,
             cwd: identity.source_cwd,
+            dispatcherWorkspace: await this.dispatcherWorkspace(identity.dispatcher_id),
             request: {
                 mode: 'managed',
                 ...(identity.worktree.slug !== null ? { slug: identity.worktree.slug } : {}),
@@ -526,10 +710,32 @@ export class TeamMateAgentService {
                 status: settled.status,
                 result,
             };
-            await sink(dispatcherId, identity, envelope, turnOrigins.get(settled.turnId) ?? null);
+            // Attempt reverse delivery first (unchanged timing), but isolate its
+            // failure so it never skips the durable settled-turn capture below — a
+            // failed delivery is exactly when the recovery metadata matters most
+            // (issue #182 PR-5, PR #187 review P2).
+            try {
+                await sink(dispatcherId, identity, envelope, turnOrigins.get(settled.turnId) ?? null);
+            }
+            catch (err) {
+                this.opts.log.warn({ dispatcher_id: dispatcherId, teammate: name, err: errInfo(err) }, 'teammate completion delivery failed');
+            }
+            // Capture the settled turn in the durable session ledger AFTER the
+            // delivery attempt — regardless of its outcome — so capture never perturbs
+            // reverse-delivery timing: final assistant output + the runtime
+            // checkpoint/session id, read from the freshest identity so a thread id set
+            // after spawn is recorded.
+            const settledIdentity = (await this.identities.get(dispatcherId, name).catch(() => null)) ?? identity;
+            await this.sessionLedger.append({
+                identity: settledIdentity,
+                type: 'settled',
+                turnId: settled.turnId,
+                assistant: result,
+                settleStatus: settled.status,
+            });
         }
         catch (err) {
-            this.opts.log.warn({ dispatcher_id: dispatcherId, teammate: name, err: errInfo(err) }, 'teammate completion delivery failed');
+            this.opts.log.warn({ dispatcher_id: dispatcherId, teammate: name, err: errInfo(err) }, 'teammate settled-turn capture failed');
         }
     }
     async mustIdentity(dispatcherId, name, principal = dispatcherPrincipal(dispatcherId)) {
@@ -563,26 +769,34 @@ export class TeamMateAgentService {
         };
     }
     /**
-     * Per-teammate path context. The teammate runtime dir is the neutral root both
-     * built-in runtimes derive their state files from (Codex `codex.sock`, Claude
-     * Code `mcp.json`); only the central-tree log files vary by runtime, so the
-     * launcher selects them from the resolved provider ref.
+     * Per-teammate path context. The teammate runtime dir is the neutral root a
+     * runtime derives its state files from (Claude Code `mcp.json`; Codex keeps
+     * no per-teammate state files — its rendezvous socket is allocated per start
+     * under the private runtime-socket root, issue #182); only the central-tree
+     * log files vary by runtime, so the launcher selects them from the resolved
+     * provider ref.
      */
     runtimePaths(identity, providerRef) {
         const runtimeIdentity = runtimeIdentityName(identity);
         const dispatcherDir = () => dispatcherTeamMateRuntimeDir(identity.dispatcher_id, runtimeIdentity);
+        // Completion spill belongs to the OPERATOR dispatcher's cache, not the
+        // teammate's composite runtime id, so it groups with the rest of that
+        // dispatcher's ephemera (issue #182 PR-2).
+        const completionSpillDir = () => dispatcherCompletionSpillDir(identity.dispatcher_id);
         if (providerRef === BUILTIN_CLAUDE_CODE_PROVIDER_REF) {
             const streamLog = () => teammateClaudeCodeStreamLogPath(identity.dispatcher_id, runtimeIdentity);
             return {
                 dispatcherDir,
                 stdoutLogPath: streamLog,
                 stderrLogPath: streamLog,
+                completionSpillDir,
             };
         }
         return {
             dispatcherDir,
             stdoutLogPath: () => teammateCodexAppServerLogPath(identity.dispatcher_id, runtimeIdentity),
             stderrLogPath: () => teammateCodexAppServerErrorLogPath(identity.dispatcher_id, runtimeIdentity),
+            completionSpillDir,
         };
     }
     /**
@@ -623,9 +837,21 @@ export class TeamMateAgentService {
         return (this.opts.config.dispatchers.find((entry) => entry.id === dispatcherId) ??
             null);
     }
+    /**
+     * Resolve and validate the dispatcher workspace cwd (issue #182 PR-4): the
+     * root under which managed worktrees are placed. Fails loud when the
+     * dispatcher declares no explicit `cwd` — there is no state-dir fallback.
+     * Exposed so the Team service (which owns its own WorktreeManager) resolves
+     * the same workspace.
+     */
+    async dispatcherWorkspace(dispatcherId) {
+        return ensureDispatcherWorkspace(this.opts.config, dispatcherId);
+    }
     toStatus(identity, runtime) {
         return {
             name: identity.name,
+            display_name: identity.display_name,
+            session_id: identity.session_id,
             role: identity.role,
             team_id: identity.team_id,
             owner: identity.owner,
@@ -644,14 +870,22 @@ export class TeamMateAgentService {
             close_note: identity.close_note,
         };
     }
-    async toLedgerRow(identity) {
+    /**
+     * Build one recovery row for a teammate (issue #188). Historical recovery
+     * facts — last-seen, prompt/assistant previews, turn count — come from the
+     * durable SESSION LEDGER row (`session`), not the per-name history index. Live
+     * and identity-only facts (runtime status, resume checkpoint, worktree cleanup
+     * state, owner) come from the current identity. `session` is null for a
+     * legacy/never-captured teammate, which then shows identity facts only.
+     */
+    toLedgerRow(identity, session) {
         const runtime = this.live.get(liveKey(identity.dispatcher_id, identity.name))?.runtime ?? null;
-        const events = await this.identities.history(identity.dispatcher_id, identity.name);
-        const lastEvent = events.at(-1);
-        const lastPromptEvent = events.findLast((event) => event.prompt_preview !== null);
         return {
             id: identity.name,
             name: identity.name,
+            display_name: identity.display_name,
+            session_id: identity.session_id,
+            turn_count: session?.turn_count ?? 0,
             role: identity.role,
             team_id: identity.team_id,
             owner: identity.owner,
@@ -663,7 +897,7 @@ export class TeamMateAgentService {
             worktree: identity.worktree,
             created_at: identity.created_at,
             updated_at: identity.updated_at,
-            last_seen_at: lastEvent?.timestamp ?? identity.updated_at,
+            last_seen_at: session?.last_seen_at ?? identity.updated_at,
             state: identity.status,
             status: identity.status,
             runtime_status: runtime?.getStatus() ?? null,
@@ -673,8 +907,8 @@ export class TeamMateAgentService {
             closed_at: identity.closed_at,
             close_note: identity.close_note,
             close_note_preview: identity.close_note !== null ? previewText(identity.close_note) : null,
-            last_prompt_preview: lastPromptEvent?.prompt_preview ?? null,
-            last_assistant_preview: null,
+            last_prompt_preview: session?.last_prompt_preview ?? null,
+            last_assistant_preview: session?.last_assistant_preview ?? null,
             cleanup_state: identity.worktree.cleanup_state,
             resume: identity.closed_at === null || identity.checkpoint !== null
                 ? { tool: 'send', name: identity.name, checkpoint: identity.checkpoint }
@@ -835,6 +1069,21 @@ function clampHistoryLimit(input) {
     }
     return Math.min(input, 100);
 }
+const LAST_TURNS_DEFAULT = 1;
+const LAST_TURNS_MAX = 5;
+/**
+ * Validate the `last` turn count (issue #188): default 1, integer in 1..5.
+ * Out-of-range is rejected (fail loud) rather than silently clamped, so a
+ * caller asking for 10 turns learns its request was invalid.
+ */
+function validateLastTurns(input) {
+    if (input === undefined)
+        return LAST_TURNS_DEFAULT;
+    if (!Number.isInteger(input) || input < 1 || input > LAST_TURNS_MAX) {
+        throw new Error(`last turns must be an integer in 1..${LAST_TURNS_MAX}`);
+    }
+    return input;
+}
 function encodeCursor(offset) {
     return Buffer.from(JSON.stringify({ offset }), 'utf8').toString('base64url');
 }
@@ -859,6 +1108,9 @@ function ledgerRowMatchesText(row, grep) {
     return [
         row.id,
         row.name,
+        row.display_name,
+        row.session_id,
+        row.team_id,
         row.agent_runtime,
         row.source_cwd,
         row.source_repo,