@pellux/goodvibes-sdk 0.37.2 → 1.0.0

package/dist/platform/state/vibe-projection.js

@@ -0,0 +1,115 @@
+/**
+ * vibe-projection.ts — VIBE.md as a PROJECTION of memory records (Wave-6 E6).
+ *
+ * BEFORE E6, VIBE.md was a persona file read off disk and injected into the prompt
+ * — a projection of ITSELF, a source of truth disjoint from the memory store. E6
+ * demotes the file to an import/export FORMAT and makes the prompt block a
+ * projection of first-class memory records:
+ *
+ *   - Persona/preference facts persist as MemoryRecords with cls 'constraint',
+ *     scope project|team, tagged VIBE_PERSONA_TAG.
+ *   - renderVibeProjection(records) emits the same '## GoodVibes Agent VIBE.md'
+ *     prompt block from those records — the block the file used to emit.
+ *   - The file round-trips THROUGH the record set (vibeBodyToConstraintOptions
+ *     imports a VIBE.md body into records; the records export back through the
+ *     normal MemoryStore bundle seam). The file is a format, not the truth.
+ *
+ * INVARIANT PRESERVED. The projected block keeps the precedence caveat verbatim:
+ * persona instructions are followed only when they do not conflict with explicit
+ * user instructions, safety policy, tool contracts, confirmation requirements, or
+ * secret-handling rules. Demoting the file to a projection must not drop that.
+ */
+/** Tag marking a constraint record as a VIBE.md persona/preference line. */
+export const VIBE_PERSONA_TAG = 'vibe';
+/** The projected prompt block heading. */
+export const VIBE_PROJECTION_HEADING = '## GoodVibes Agent VIBE.md';
+/**
+ * The precedence caveat. MUST accompany every projected block — persona records
+ * never override explicit instructions, safety, tool contracts, confirmations, or
+ * secret-handling.
+ */
+export const VIBE_PROJECTION_CAVEAT = 'These user-authored vibe/personality instructions shape the same serial assistant conversation. Follow them only when they do not conflict with explicit user instructions, safety policy, tool contracts, confirmation requirements, or secret-handling rules.';
+/** Scopes eligible for the VIBE projection (persona applies at project/team scope, not per-session). */
+const VIBE_PROJECTION_SCOPES = ['project', 'team'];
+/**
+ * Select the constraint records that make up the VIBE persona: cls 'constraint',
+ * tagged VIBE_PERSONA_TAG, in an eligible scope. Ordered stably by scope (team
+ * after project) then creation time so the projected block is deterministic.
+ */
+export function selectVibeRecords(records, options = {}) {
+    const scopes = new Set(options.scopes ?? VIBE_PROJECTION_SCOPES);
+    return records
+        .filter((record) => record.cls === 'constraint')
+        .filter((record) => record.tags.includes(VIBE_PERSONA_TAG))
+        .filter((record) => scopes.has(record.scope))
+        .sort((left, right) => {
+        if (left.scope !== right.scope)
+            return left.scope === 'project' ? -1 : 1;
+        return left.createdAt - right.createdAt;
+    });
+}
+function vibeLine(record) {
+    const detail = record.detail?.trim();
+    return detail && detail !== record.summary ? `- ${record.summary} — ${detail}` : `- ${record.summary}`;
+}
+/**
+ * Render the VIBE.md prompt block from persona/constraint records. Returns null
+ * when there are no persona records to project (no empty block). The caveat is
+ * always included when a block is produced.
+ */
+export function renderVibeProjection(records, options = {}) {
+    const persona = selectVibeRecords(records, options);
+    if (persona.length === 0)
+        return null;
+    return [
+        VIBE_PROJECTION_HEADING,
+        VIBE_PROJECTION_CAVEAT,
+        '',
+        ...persona.map(vibeLine),
+    ].join('\n');
+}
+const BULLET_PREFIX = /^\s*[-*]\s+/;
+/**
+ * Turn a VIBE.md body into constraint MemoryAddOptions — the file demoted to an
+ * IMPORT FORMAT. Each bullet line becomes one persona record so that editing a
+ * single record later changes exactly one line of the projected block. A body
+ * with no bullets becomes a single record carrying the whole body as detail.
+ *
+ * Heading lines (starting with '#') and blank lines are dropped; they carry no
+ * persona instruction.
+ */
+export function vibeBodyToConstraintOptions(body, options = {}) {
+    const scope = options.scope ?? 'project';
+    const tags = options.name ? [VIBE_PERSONA_TAG, options.name] : [VIBE_PERSONA_TAG];
+    const provenance = options.sourceRef
+        ? [{ kind: 'file', ref: options.sourceRef }]
+        : undefined;
+    const lines = body.split('\n');
+    const bullets = lines
+        .filter((line) => BULLET_PREFIX.test(line))
+        .map((line) => line.replace(BULLET_PREFIX, '').trim())
+        .filter((line) => line.length > 0);
+    if (bullets.length > 0) {
+        return bullets.map((summary) => ({
+            scope,
+            cls: 'constraint',
+            summary,
+            tags: [...tags],
+            ...(provenance ? { provenance } : {}),
+        }));
+    }
+    const prose = lines
+        .filter((line) => !line.trimStart().startsWith('#'))
+        .join('\n')
+        .trim();
+    if (!prose)
+        return [];
+    return [{
+            scope,
+            cls: 'constraint',
+            summary: options.name ?? 'VIBE.md persona',
+            detail: prose,
+            tags: [...tags],
+            ...(provenance ? { provenance } : {}),
+        }];
+}

package/dist/platform/tools/agent/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/agent/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAG7D,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,EAAmB,YAAY,EAAoB,MAAM,cAAc,CAAC;AAK/E,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAiHhD,wBAAgB,eAAe,CAAC,MAAM,EAAE;IACtC,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,IAAI,CAAC,eAAe,EAAE,aAAa,GAAG,MAAM,CAAC,CAAC;IAC1D,cAAc,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,YAAY,CAAC,GAAG,SAAS,CAAC;IAChE,eAAe,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,eAAe,CAAC,GAAG,SAAS,CAAC;IACrE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;CAC3C,GAAG,IAAI,CAwlBP"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/agent/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAG7D,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,EAAmB,YAAY,EAAoB,MAAM,cAAc,CAAC;AAK/E,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAiHhD,wBAAgB,eAAe,CAAC,MAAM,EAAE;IACtC,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,IAAI,CAAC,eAAe,EAAE,aAAa,GAAG,MAAM,CAAC,CAAC;IAC1D,cAAc,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,YAAY,CAAC,GAAG,SAAS,CAAC;IAChE,eAAe,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,eAAe,CAAC,GAAG,SAAS,CAAC;IACrE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;CAC3C,GAAG,IAAI,CAgmBP"}

package/dist/platform/tools/agent/index.js

@@ -493,6 +493,13 @@ export function createAgentTool(config) {
                                 error: `Failed to collapse role-decomposition batch into a WRFC owner chain: ${summarizeError(error)}`,
                             };
                         }
+                        // Part (a): when a requested fan-out was collapsed, state it plainly for
+                        // the host to surface to the user — what was requested, what the guard
+                        // did, and why — so the collapse is never a silent, confusing rewrite.
+                        const fanout = batchPolicy.ownerInput?.fanoutCollapse;
+                        const announcement = fanout
+                            ? `Requested ${fanout.requestedShape}; the WRFC topology guard ran them as one reviewed chain instead (${batchPolicy.reason ?? 'topology enforcement'}).`
+                            : undefined;
                         return {
                             success: true,
                             output: JSON.stringify({
@@ -503,6 +510,7 @@ export function createAgentTool(config) {
                                 collapsedToWrfc: true,
                                 collapsedTaskCount: input.tasks.length,
                                 reason: batchPolicy.reason,
+                                ...(announcement ? { announcement } : {}),
                                 roleTaskIndexes: batchPolicy.roleTaskIndexes ?? [],
                                 compoundTaskIndexes: batchPolicy.compoundTaskIndexes ?? [],
                                 scopeMutation: batchPolicy.scopeMutation ?? null,

package/dist/platform/tools/agent/manager.d.ts

@@ -2,10 +2,12 @@ import { ArchetypeLoader } from '../../agents/archetypes.js';
 import { AgentMessageBus } from '../../agents/message-bus.js';
 import { WrfcController } from '../../agents/wrfc-controller.js';
 import type { ConfigManager } from '../../config/manager.js';
+import type { ConversationMessageSnapshot } from '../../core/conversation.js';
 import type { RuntimeEventBus } from '../../runtime/events/index.js';
 import type { ExecutionIntent } from '../../runtime/execution-intents.js';
 import type { AgentInput } from './schema.js';
 import type { WrfcAgentRole } from '../../agents/wrfc-types.js';
+import type { TurnInjectionRecord } from '../../agents/turn-knowledge-injection.js';
 export type AgentExecutor = {
     runAgent(record: AgentRecord): Promise<void>;
 };
@@ -15,7 +17,25 @@ export interface AgentManagerDependencies {
     readonly wrfcController?: Pick<WrfcController, 'createChain'> | null | undefined;
     readonly executor?: AgentExecutor | null | undefined;
     readonly configManager?: Pick<ConfigManager, 'get'> | undefined;
+    /**
+     * Bound on how many finished agents' final conversation snapshot are kept
+     * in the retention ring (see getConversationSnapshot). Defaults to
+     * DEFAULT_CONVERSATION_SNAPSHOT_RETENTION. Test-only knob in practice.
+     */
+    readonly conversationSnapshotRetention?: number | undefined;
 }
+/**
+ * Wave-3 tab attach point (Part C6): default bound on how many recently
+ * finished agents' final conversation snapshot AgentManager keeps around
+ * after their live source is released. Without a bound, a long-lived process
+ * that spawns many short-lived agents would retain every finished agent's
+ * full message history forever — this is the "leaking unbounded memory" the
+ * brief calls out. RUNNING agents are unaffected by this bound: their
+ * snapshot is read live from the still-open ConversationManager, whose size
+ * is already governed by the existing context-window compaction machinery
+ * (core/context-compaction.ts), not by this retention ring.
+ */
+export declare const DEFAULT_CONVERSATION_SNAPSHOT_RETENTION = 20;
 export declare const AGENT_TEMPLATES: Record<string, {
     description: string;
     defaultTools: string[];
@@ -33,6 +53,16 @@ export interface AgentRecord {
     context?: string | undefined;
     tools: string[];
     status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+    /**
+     * Set by cancel(id, kind) when status transitions to 'cancelled'. Distinguishes
+     * a graceful interrupt request from a hard kill for display purposes
+     * (Wave-3 verb formalization) without overloading `status`, which is
+     * consumed widely (ledger parse, orchestrator finalize, exportState/
+     * importState). Absent on records cancelled before this field existed, and
+     * on any record cancelled via the single-arg cancel(id) call — both default
+     * to 'kill' at the read site (fleet/adapters/agent.ts deriveAgentState).
+     */
+    terminationKind?: 'interrupt' | 'kill' | undefined;
     startedAt: number;
     completedAt?: number | undefined;
     progress?: string | undefined;
@@ -56,7 +86,28 @@ export interface AgentRecord {
     wrfcSubtaskId?: string | undefined;
     wrfcRouteReason?: string | undefined;
     wrfcSubtasks?: AgentInput['wrfcSubtasks'] | undefined;
+    /** Set when this owner agent's chain was created by collapsing a requested fan-out (schema.ts FanoutCollapseInfo). */
+    fanoutCollapse?: AgentInput['fanoutCollapse'] | undefined;
     dangerously_disable_wrfc?: boolean | undefined;
+    /**
+     * Wave-4 orchestration engine tag (wo701): set by phase-runner.ts when it
+     * spawns an agent to run one WorkItem through one Phase. Mirrors
+     * wrfcId/wrfcSubtaskId — the fleet's agent adapter uses it to parent this
+     * agent node under its work-item ProcessNode (adapters/agent.ts
+     * resolveParentId), separate from the WRFC parenting track so the two
+     * systems' agents are never conflated.
+     */
+    workItemId?: string | undefined;
+    /**
+     * Overrides this agent's tool working directory (absolute path) — see
+     * AgentInput.workingDirectory. Copied from the spawn input at construction
+     * (NOT settable post-hoc like workItemId: AgentOrchestrator.runAgent reads
+     * it synchronously to select/build the per-cwd ToolRegistry before the
+     * caller of spawn() gets its return value back). Absent ⇒ the
+     * orchestrator's default working directory, unchanged from before this
+     * field existed.
+     */
+    workingDirectory?: string | undefined;
     cohort?: string | undefined;
     orchestrationGraphId?: string | undefined;
     orchestrationNodeId?: string | undefined;
@@ -80,6 +131,17 @@ export interface AgentRecord {
         confidence: number;
         reviewState: 'fresh' | 'reviewed' | 'stale' | 'contradicted';
     }>;
+    /**
+     * Wave-5 (wo801, W5.1) bounded ring of per-turn passive-injection honesty
+     * records — one entry per turn that actually ran retrieval (turns that
+     * reused the prior turn's cached block, or that ran with the feature
+     * flag/budget off, append nothing). See turn-knowledge-injection.ts for
+     * the record shape and recordTurnInjection for the ring-eviction policy.
+     * Deliberately a plain field (no new KnowledgeEvent contract member) —
+     * the same entries are also appended to the agent's session transcript
+     * via `session.appendMessage({type:'knowledge_injection', ...})`.
+     */
+    turnInjections?: TurnInjectionRecord[] | undefined;
 }
 export declare class AgentManager {
     private agents;
@@ -90,12 +152,89 @@ export declare class AgentManager {
     private wrfcController;
     private executor;
     private readonly configManager;
+    /**
+     * Live snapshot accessors for RUNNING agents (Wave-3 Part C6 bridge).
+     * Registered by the executor (orchestrator-runner.ts) right after it
+     * creates the agent's ConversationManager; the manager never stores
+     * messages itself while an agent is running — it just holds a callback.
+     */
+    private readonly conversationSources;
+    /**
+     * Wave-4 cooperative cancellation bridge (wo701): per-agent AbortSignal
+     * registered by an orchestration-engine work item for the duration of one
+     * phase run. AgentOrchestrator reads this via
+     * setCancellationSource/getCancellationSignal and threads it into
+     * toolRegistry.execute opts so opted-in tools (exec, fetch) can abort an
+     * in-flight child process/request immediately, instead of only at the next
+     * turn boundary's status poll. Purely additive — no caller is required to
+     * register anything, and an agent with no registered signal behaves
+     * exactly as before this change.
+     */
+    private readonly cancellationSignals;
+    /**
+     * Frozen final snapshots for agents whose live source was released (their
+     * run ended). Map insertion order doubles as the bounded ring's age order:
+     * oldest entry (first key) is evicted once conversationSnapshotRetention is
+     * exceeded. See getConversationSnapshot for the read-side contract.
+     */
+    private readonly frozenConversationSnapshots;
+    private readonly conversationSnapshotRetention;
     constructor(deps?: AgentManagerDependencies);
     setRuntimeBus(runtimeBus: RuntimeEventBus | null): void;
     private deriveEffectiveTools;
     spawn(input: AgentInput): AgentRecord;
     getStatus(id: string): AgentRecord | null;
-    cancel(id: string): boolean;
+    cancel(id: string, kind?: 'interrupt' | 'kill'): boolean;
+    /**
+     * Register the live conversation-snapshot source for a running agent
+     * (Wave-3 Part C6 bridge). Called by the executor (orchestrator-runner.ts)
+     * once its ConversationManager exists — `source` is invoked on demand by
+     * getConversationSnapshot(); the manager never copies or stores the
+     * messages itself while the agent is running.
+     */
+    registerConversationSource(agentId: string, source: () => ConversationMessageSnapshot[]): void;
+    /**
+     * Wave-4 cooperative cancellation bridge (wo701): register the AbortSignal
+     * an orchestration engine's cancellation registry created for a work
+     * item's current agent. Called by the engine right after
+     * AgentManager.spawn() so the signal is in place before the agent's first
+     * turn/tool call.
+     */
+    registerCancellationSignal(agentId: string, signal: AbortSignal): void;
+    /** Drop the registered signal once the run ends (success, failure, or cancel). Safe to call unconditionally. */
+    releaseCancellationSignal(agentId: string): void;
+    /** Read back the registered signal for AgentOrchestrator's per-tool-call opts. */
+    getCancellationSignal(agentId: string): AbortSignal | undefined;
+    /**
+     * Release the live source for an agent whose run has ended, freezing one
+     * final snapshot into the bounded retention ring (see
+     * DEFAULT_CONVERSATION_SNAPSHOT_RETENTION) so a transcript tab that was
+     * open at the moment of completion keeps showing content instead of going
+     * blank. Once evicted (oldest-first, beyond the retention bound),
+     * getConversationSnapshot falls back to an empty array — callers past that
+     * point are expected to degrade to the on-disk event ledger (Wave-3 TUI
+     * Part C6's documented fallback for completed/detached agents).
+     *
+     * Safe to call even when no source was ever registered for this agentId
+     * (e.g. a WRFC owner agent, which never runs its own turn loop).
+     */
+    releaseConversationSource(agentId: string): void;
+    /**
+     * The Wave-3 tab attach point: a full-fidelity conversation history for a
+     * fleet agent (ConversationMessageSnapshot[] — the same shape the main
+     * session surface renders via MessageLineCache/conversation.ts).
+     *
+     * - RUNNING agent with a registered source → the current live snapshot.
+     * - Agent whose run just ended → the frozen final snapshot, until evicted
+     *   from the bounded retention ring (oldest-first beyond
+     *   conversationSnapshotRetention completed agents).
+     * - Unknown agent, or one long since evicted → empty array. The disk
+     *   ledger (<agentId>.jsonl, written by AgentSession) is NOT a substitute
+     *   for this array — it is a truncated event log (tool args/results
+     *   sliced to 500 chars, no assistant message text), so callers past
+     *   eviction get a degraded activity view, never a fabricated replay.
+     */
+    getConversationSnapshot(agentId: string): ConversationMessageSnapshot[];
     listByGraph(graphId: string): AgentRecord[];
     cancelSubtree(rootAgentId: string): string[];
     cancelGraph(graphId: string): string[];

package/dist/platform/tools/agent/manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/agent/manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/agent/manager.ts"],"names":[],"mappings":"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"}

package/dist/platform/tools/agent/manager.js

@@ -8,11 +8,27 @@ import { logger } from '../../utils/logger.js';
 import { summarizeError } from '../../utils/error-display.js';
 import { splitModelRegistryKey } from '../../providers/registry-helpers.js';
 import { isRootReviewRoleTask, resolveAuthoritativeWrfcScope, resolveImplementationToolContract, resolveNarrowedRootSpawnScope, } from './wrfc-batch-policy.js';
+/**
+ * Wave-3 tab attach point (Part C6): default bound on how many recently
+ * finished agents' final conversation snapshot AgentManager keeps around
+ * after their live source is released. Without a bound, a long-lived process
+ * that spawns many short-lived agents would retain every finished agent's
+ * full message history forever — this is the "leaking unbounded memory" the
+ * brief calls out. RUNNING agents are unaffected by this bound: their
+ * snapshot is read live from the still-open ConversationManager, whose size
+ * is already governed by the existing context-window compaction machinery
+ * (core/context-compaction.ts), not by this retention ring.
+ */
+export const DEFAULT_CONVERSATION_SNAPSHOT_RETENTION = 20;
 export const AGENT_TEMPLATES = {
     orchestrator: {
         description: 'WRFC coordination and decomposition agent',
         defaultTools: ['read', 'find', 'analyze', 'inspect', 'registry'],
     },
+    planner: {
+        description: 'Read-only goal-decomposition agent (no write/edit/exec/delegate)',
+        defaultTools: ['read', 'find', 'analyze', 'inspect'],
+    },
     engineer: {
         description: 'Full-stack implementation agent',
         defaultTools: ['read', 'write', 'edit', 'find', 'exec', 'analyze', 'inspect', 'fetch', 'registry'],
@@ -65,12 +81,40 @@ export class AgentManager {
     wrfcController;
     executor;
     configManager;
+    /**
+     * Live snapshot accessors for RUNNING agents (Wave-3 Part C6 bridge).
+     * Registered by the executor (orchestrator-runner.ts) right after it
+     * creates the agent's ConversationManager; the manager never stores
+     * messages itself while an agent is running — it just holds a callback.
+     */
+    conversationSources = new Map();
+    /**
+     * Wave-4 cooperative cancellation bridge (wo701): per-agent AbortSignal
+     * registered by an orchestration-engine work item for the duration of one
+     * phase run. AgentOrchestrator reads this via
+     * setCancellationSource/getCancellationSignal and threads it into
+     * toolRegistry.execute opts so opted-in tools (exec, fetch) can abort an
+     * in-flight child process/request immediately, instead of only at the next
+     * turn boundary's status poll. Purely additive — no caller is required to
+     * register anything, and an agent with no registered signal behaves
+     * exactly as before this change.
+     */
+    cancellationSignals = new Map();
+    /**
+     * Frozen final snapshots for agents whose live source was released (their
+     * run ended). Map insertion order doubles as the bounded ring's age order:
+     * oldest entry (first key) is evicted once conversationSnapshotRetention is
+     * exceeded. See getConversationSnapshot for the read-side contract.
+     */
+    frozenConversationSnapshots = new Map();
+    conversationSnapshotRetention;
     constructor(deps = {}) {
         this.archetypeLoader = deps.archetypeLoader ?? new ArchetypeLoader();
         this.messageBus = deps.messageBus ?? new AgentMessageBus();
         this.wrfcController = deps.wrfcController ?? null;
         this.executor = deps.executor ?? null;
         this.configManager = deps.configManager ?? null;
+        this.conversationSnapshotRetention = deps.conversationSnapshotRetention ?? DEFAULT_CONVERSATION_SNAPSHOT_RETENTION;
     }
     setRuntimeBus(runtimeBus) {
         this.runtimeBus = runtimeBus;
@@ -285,6 +329,7 @@ export class AgentManager {
             communicationLane,
             systemPromptAddendum: input.systemPromptAddendum,
             wrfcSubtasks: input.wrfcSubtasks,
+            ...(input.fanoutCollapse ? { fanoutCollapse: input.fanoutCollapse } : {}),
             status: 'pending',
             startedAt: Date.now(),
             toolCallCount: 0,
@@ -298,6 +343,7 @@ export class AgentManager {
                 reasoningSummaryCount: 0,
             },
             dangerously_disable_wrfc: input.dangerously_disable_wrfc,
+            workingDirectory: input.workingDirectory,
             cohort: input.cohort,
             ...(orchestrationGraphId ? {
                 orchestrationGraphId,
@@ -446,12 +492,13 @@ export class AgentManager {
     getStatus(id) {
         return this.agents.get(id) ?? null;
     }
-    cancel(id) {
+    cancel(id, kind = 'kill') {
         const record = this.agents.get(id);
         if (!record)
             return false;
         if (record.status === 'pending' || record.status === 'running') {
             record.status = 'cancelled';
+            record.terminationKind = kind;
             record.completedAt = Date.now();
             if (this.runtimeBus) {
                 emitAgentCancelled(this.runtimeBus, {
@@ -480,6 +527,99 @@ export class AgentManager {
         this.agents.set(id, record);
         return true;
     }
+    /**
+     * Register the live conversation-snapshot source for a running agent
+     * (Wave-3 Part C6 bridge). Called by the executor (orchestrator-runner.ts)
+     * once its ConversationManager exists — `source` is invoked on demand by
+     * getConversationSnapshot(); the manager never copies or stores the
+     * messages itself while the agent is running.
+     */
+    registerConversationSource(agentId, source) {
+        this.conversationSources.set(agentId, source);
+    }
+    /**
+     * Wave-4 cooperative cancellation bridge (wo701): register the AbortSignal
+     * an orchestration engine's cancellation registry created for a work
+     * item's current agent. Called by the engine right after
+     * AgentManager.spawn() so the signal is in place before the agent's first
+     * turn/tool call.
+     */
+    registerCancellationSignal(agentId, signal) {
+        this.cancellationSignals.set(agentId, signal);
+    }
+    /** Drop the registered signal once the run ends (success, failure, or cancel). Safe to call unconditionally. */
+    releaseCancellationSignal(agentId) {
+        this.cancellationSignals.delete(agentId);
+    }
+    /** Read back the registered signal for AgentOrchestrator's per-tool-call opts. */
+    getCancellationSignal(agentId) {
+        return this.cancellationSignals.get(agentId);
+    }
+    /**
+     * Release the live source for an agent whose run has ended, freezing one
+     * final snapshot into the bounded retention ring (see
+     * DEFAULT_CONVERSATION_SNAPSHOT_RETENTION) so a transcript tab that was
+     * open at the moment of completion keeps showing content instead of going
+     * blank. Once evicted (oldest-first, beyond the retention bound),
+     * getConversationSnapshot falls back to an empty array — callers past that
+     * point are expected to degrade to the on-disk event ledger (Wave-3 TUI
+     * Part C6's documented fallback for completed/detached agents).
+     *
+     * Safe to call even when no source was ever registered for this agentId
+     * (e.g. a WRFC owner agent, which never runs its own turn loop).
+     */
+    releaseConversationSource(agentId) {
+        const source = this.conversationSources.get(agentId);
+        if (!source)
+            return;
+        this.conversationSources.delete(agentId);
+        let finalSnapshot;
+        try {
+            finalSnapshot = source();
+        }
+        catch (error) {
+            logger.warn('AgentManager: conversation source threw on release', { agentId, error: summarizeError(error) });
+            return;
+        }
+        // Re-insert at the end (freshest) even if already present, so the ring's
+        // insertion order tracks recency of completion, not first appearance.
+        this.frozenConversationSnapshots.delete(agentId);
+        this.frozenConversationSnapshots.set(agentId, finalSnapshot);
+        while (this.frozenConversationSnapshots.size > this.conversationSnapshotRetention) {
+            const oldestKey = this.frozenConversationSnapshots.keys().next().value;
+            if (oldestKey === undefined)
+                break;
+            this.frozenConversationSnapshots.delete(oldestKey);
+        }
+    }
+    /**
+     * The Wave-3 tab attach point: a full-fidelity conversation history for a
+     * fleet agent (ConversationMessageSnapshot[] — the same shape the main
+     * session surface renders via MessageLineCache/conversation.ts).
+     *
+     * - RUNNING agent with a registered source → the current live snapshot.
+     * - Agent whose run just ended → the frozen final snapshot, until evicted
+     *   from the bounded retention ring (oldest-first beyond
+     *   conversationSnapshotRetention completed agents).
+     * - Unknown agent, or one long since evicted → empty array. The disk
+     *   ledger (<agentId>.jsonl, written by AgentSession) is NOT a substitute
+     *   for this array — it is a truncated event log (tool args/results
+     *   sliced to 500 chars, no assistant message text), so callers past
+     *   eviction get a degraded activity view, never a fabricated replay.
+     */
+    getConversationSnapshot(agentId) {
+        const liveSource = this.conversationSources.get(agentId);
+        if (liveSource) {
+            try {
+                return liveSource();
+            }
+            catch (error) {
+                logger.warn('AgentManager: conversation source threw', { agentId, error: summarizeError(error) });
+                return [];
+            }
+        }
+        return this.frozenConversationSnapshots.get(agentId) ?? [];
+    }
     listByGraph(graphId) {
         return this.list().filter((agent) => agent.orchestrationGraphId === graphId);
     }
@@ -521,6 +661,8 @@ export class AgentManager {
     clear() {
         this.agents.clear();
         this.orchestrationGraphs.clear();
+        this.conversationSources.clear();
+        this.frozenConversationSnapshots.clear();
     }
     exportState() {
         return [...this.agents.values()].map((agent) => {

package/dist/platform/tools/agent/schema.d.ts

@@ -10,6 +10,21 @@ export interface AgentProviderRoutingPolicy {
     providerFailurePolicy?: 'ordered-fallbacks' | 'fail' | undefined;
     fallbackModels?: readonly string[] | undefined;
 }
+/**
+ * Internal marker recording that a requested multi-agent fan-out was collapsed
+ * into a single WRFC owner chain by the topology guard. Set by the collapse
+ * guards (wrfc-batch-policy.ts / the TUI wrfc-agent-guard), threaded onto the
+ * owner AgentRecord and then the WrfcChain. It lets the controller mechanically
+ * recognise — and never fail the review on — the parallelism/spawn-count
+ * constraints the collapse itself made unsatisfiable, and lets the host state
+ * the collapse plainly to the user. Never set by the model-facing tool call.
+ */
+export interface FanoutCollapseInfo {
+    /** How many separate agents the requester asked to fan out into. */
+    readonly requestedAgentCount: number;
+    /** Short human phrase describing the requested shape, for the user-facing announcement. */
+    readonly requestedShape: string;
+}
 /** Input shape for the agent tool. */
 export interface AgentInput {
     mode: 'spawn' | 'batch-spawn' | 'status' | 'cancel' | 'list' | 'templates' | 'get' | 'budget' | 'plan' | 'wait' | 'message' | 'wrfc-chains' | 'wrfc-history' | 'cohort-status' | 'cohort-report';
@@ -29,6 +44,8 @@ export interface AgentInput {
     systemPromptAddendum?: string | undefined;
     /** Internal compound WRFC deliverables owned by one top-level WRFC chain. */
     wrfcSubtasks?: AgentInput['tasks'] | undefined;
+    /** Internal: set by the topology guard when a requested fan-out was collapsed into this owner chain. */
+    fanoutCollapse?: FanoutCollapseInfo | undefined;
     successCriteria?: string[] | undefined;
     requiredEvidence?: string[] | undefined;
     writeScope?: string[] | undefined;
@@ -40,6 +57,15 @@ export interface AgentInput {
     orchestrationNodeId?: string | undefined;
     parentNodeId?: string | undefined;
     dangerously_disable_wrfc?: boolean | undefined;
+    /**
+     * Overrides this spawn's tool working directory (absolute path), e.g. an
+     * orchestration-engine item's dedicated git worktree in `worktree`
+     * isolation mode (see platform/orchestration/worktree-isolation.ts).
+     * Omitted ⇒ the orchestrator's default working directory, exactly as
+     * before this field existed. Internal — not part of any user-facing agent
+     * template surface.
+     */
+    workingDirectory?: string | undefined;
     cohort?: string | undefined;
     tasks?: Array<{
         task: string;

package/dist/platform/tools/agent/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/agent/schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/agent/schema.ts"],"names":[],"mappings":"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"}

package/dist/platform/tools/agent/schema.js

@@ -43,7 +43,7 @@ export const AGENT_TOOL_SCHEMA = {
             },
             template: {
                 type: 'string',
-                enum: ['orchestrator', 'engineer', 'reviewer', 'tester', 'researcher', 'integrator', 'general'],
+                enum: ['orchestrator', 'planner', 'engineer', 'reviewer', 'tester', 'researcher', 'integrator', 'general'],
                 description: 'Agent template to use (mode: spawn). Default: general. ' +
                     'Each template includes a pre-selected tool set.',
             },
@@ -167,7 +167,7 @@ export const AGENT_TOOL_SCHEMA = {
                     required: ['task'],
                     properties: {
                         task: { type: 'string', description: 'Task description for the agent.' },
-                        template: { type: 'string', enum: ['orchestrator', 'engineer', 'reviewer', 'tester', 'researcher', 'integrator', 'general'], description: 'Agent template.' },
+                        template: { type: 'string', enum: ['orchestrator', 'planner', 'engineer', 'reviewer', 'tester', 'researcher', 'integrator', 'general'], description: 'Agent template.' },
                         model: { type: 'string', description: 'Provider-qualified model registry key.' },
                         provider: { type: 'string', description: 'Provider override.' },
                         fallbackModels: { type: 'array', items: { type: 'string' }, description: 'Ordered provider-qualified registry keys.' },