@pellux/goodvibes-sdk 0.37.2 → 1.0.0

package/dist/platform/control-plane/session-store-importer.js

@@ -0,0 +1,227 @@
+/**
+ * session-store-importer.ts
+ *
+ * Boot-time migration that folds every pre-existing session store into the ONE
+ * home-scoped durable broker store. Idempotent and safe to run repeatedly — the
+ * merge is keyed on session id, so a re-run over the same sources is a no-op.
+ *
+ * Sources folded in (One-Platform Wave 1, S1 spine):
+ *  1. Companion chat files — ~/.goodvibes/companion-chat/sessions/*.json
+ *     (home-scoped, projectless → project 'unknown'); INCLUDING closed sessions.
+ *  2. Per-project broker snapshots — <root>/.goodvibes/<surface>/control-plane/
+ *     sessions.json (the old project-scoped store path); stamped project = <root>.
+ *  3. The stale agent-fork store — same broker-snapshot shape under its surface.
+ *
+ * No session is dropped (closed included); deletion remains the GC's job. Corrupt
+ * or partial files are logged and skipped per-file — the run never aborts.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { PersistentStore } from '../state/persistent-store.js';
+import { CompanionChatPersistence } from '../companion/companion-chat-persistence.js';
+import { defaultSessionsDir } from '../companion/companion-chat-persistence.js';
+import { loadSessionBrokerState, createSessionBrokerSnapshot } from './session-broker-state.js';
+import { logger } from '../utils/logger.js';
+import { summarizeError } from '../utils/error-display.js';
+/**
+ * How many message bodies to retain PER SESSION when re-persisting the merged
+ * store. This is a per-session cap, not a global one: every session keeps its
+ * most-recent 2 000 bodies independently, and a session that is truncated is
+ * stamped with an honest `retainedMessageCount` (see createSessionBrokerSnapshot).
+ * Migration therefore never silently drops whole sessions' transcripts.
+ */
+const MAX_PERSISTED_MESSAGES_PER_SESSION = 2_000;
+/**
+ * Discover the legacy stores reachable from a single project root plus the
+ * home-scoped companion directory. Scans <projectRoot>/.goodvibes/<surface>/
+ * control-plane/sessions.json across every surface subdir (tui, goodvibes,
+ * agent, …). The home store itself is never returned as a source.
+ */
+export function discoverLegacySessionSources(input) {
+    const sources = [];
+    const companionDir = input.companionSessionsDir ?? defaultSessionsDir();
+    sources.push({ kind: 'companion-dir', path: companionDir, project: 'unknown' });
+    const goodvibesRoot = join(input.projectRoot, '.goodvibes');
+    let surfaceDirs = [];
+    try {
+        surfaceDirs = existsSync(goodvibesRoot)
+            ? readdirSync(goodvibesRoot, { withFileTypes: true })
+                .filter((entry) => entry.isDirectory())
+                .map((entry) => entry.name)
+            : [];
+    }
+    catch (error) {
+        logger.warn('[session-import] failed to scan project .goodvibes root', {
+            root: goodvibesRoot,
+            error: summarizeError(error),
+        });
+    }
+    for (const surface of surfaceDirs) {
+        const storePath = join(goodvibesRoot, surface, 'control-plane', 'sessions.json');
+        if (existsSync(storePath)) {
+            sources.push({ kind: 'broker-store', path: storePath, project: input.projectRoot });
+        }
+    }
+    return sources;
+}
+/**
+ * Fold every source into the home store at `homeStorePath`, idempotently.
+ * Starts from the existing home store, merges each source keyed by session id
+ * (newer updatedAt wins; messages/inputs union-deduped by id), and re-persists
+ * atomically. A second run over the same sources produces the same store.
+ */
+export async function importLegacySessionStores(input) {
+    const homeStore = new PersistentStore(input.homeStorePath);
+    const existing = loadSessionBrokerState(await safeLoad(homeStore));
+    const state = {
+        sessions: new Map(existing.sessions),
+        messages: new Map(),
+        inputs: new Map(),
+    };
+    for (const bucket of existing.messages.values())
+        for (const m of bucket)
+            state.messages.set(m.id, m);
+    for (const bucket of existing.inputs.values())
+        for (const i of bucket)
+            state.inputs.set(i.id, i);
+    const startCount = state.sessions.size;
+    const missingSources = [];
+    const skippedFiles = [];
+    for (const source of input.sources) {
+        if (!existsSync(source.path)) {
+            missingSources.push(source.path);
+            continue;
+        }
+        if (source.kind === 'companion-dir') {
+            await mergeCompanionDir(state, source, skippedFiles);
+        }
+        else {
+            await mergeBrokerStore(state, source, skippedFiles);
+        }
+    }
+    await homeStore.persist(buildSnapshot(state));
+    return {
+        total: state.sessions.size,
+        imported: state.sessions.size - startCount,
+        missingSources,
+        skippedFiles,
+    };
+}
+async function safeLoad(store) {
+    try {
+        return await store.load();
+    }
+    catch (error) {
+        logger.warn('[session-import] home store failed to load; starting empty', {
+            error: summarizeError(error),
+        });
+        return null;
+    }
+}
+async function mergeBrokerStore(state, source, skippedFiles) {
+    let loaded;
+    try {
+        const snapshot = await new PersistentStore(source.path).load();
+        loaded = loadSessionBrokerState(snapshot);
+    }
+    catch (error) {
+        logger.warn('[session-import] broker store failed to load; skipping', {
+            path: source.path,
+            error: summarizeError(error),
+        });
+        skippedFiles.push(source.path);
+        return;
+    }
+    for (const record of loaded.sessions.values()) {
+        const stamped = record.project === 'unknown' && source.project
+            ? { ...record, project: source.project }
+            : record;
+        upsertSession(state, stamped);
+    }
+    for (const bucket of loaded.messages.values()) {
+        for (const message of bucket)
+            if (!state.messages.has(message.id))
+                state.messages.set(message.id, message);
+    }
+    for (const bucket of loaded.inputs.values()) {
+        for (const inputRecord of bucket)
+            if (!state.inputs.has(inputRecord.id))
+                state.inputs.set(inputRecord.id, inputRecord);
+    }
+}
+async function mergeCompanionDir(state, source, skippedFiles) {
+    const persistence = new CompanionChatPersistence(source.path);
+    const stored = await persistence.loadAll();
+    for (const { meta, messages } of stored) {
+        const converted = companionMessagesToShared(meta.id, messages);
+        for (const message of converted)
+            if (!state.messages.has(message.id))
+                state.messages.set(message.id, message);
+        upsertSession(state, companionSessionToShared(meta, converted, source.project ?? 'unknown'));
+    }
+    // CompanionChatPersistence.loadAll already logs+skips corrupt files internally;
+    // there is no per-file signal to surface here beyond its own warnings.
+    void skippedFiles;
+}
+function upsertSession(state, incoming) {
+    const current = state.sessions.get(incoming.id);
+    if (!current || incoming.updatedAt >= current.updatedAt) {
+        const participants = current
+            ? mergeParticipants(current, incoming)
+            : incoming.participants;
+        state.sessions.set(incoming.id, { ...incoming, participants });
+    }
+}
+function mergeParticipants(current, incoming) {
+    const byId = new Map();
+    for (const p of current.participants)
+        byId.set(`${p.surfaceKind}:${p.surfaceId}:${p.userId ?? ''}`, p);
+    for (const p of incoming.participants)
+        byId.set(`${p.surfaceKind}:${p.surfaceId}:${p.userId ?? ''}`, p);
+    return [...byId.values()];
+}
+function companionSessionToShared(meta, messages, project) {
+    const lastMessageAt = messages.reduce((latest, m) => (latest === undefined || m.createdAt > latest ? m.createdAt : latest), undefined);
+    return {
+        id: meta.id,
+        kind: 'companion-chat',
+        project,
+        title: meta.title.trim().length > 0 ? meta.title : `Session ${meta.id}`,
+        status: meta.status,
+        createdAt: meta.createdAt,
+        updatedAt: meta.updatedAt,
+        ...(lastMessageAt !== undefined ? { lastMessageAt } : {}),
+        ...(meta.closedAt != null ? { closedAt: meta.closedAt } : {}),
+        lastActivityAt: meta.updatedAt,
+        messageCount: messages.length,
+        pendingInputCount: 0,
+        routeIds: [],
+        surfaceKinds: ['companion'],
+        participants: [{ surfaceKind: 'companion', surfaceId: meta.id, lastSeenAt: meta.updatedAt }],
+        metadata: {},
+    };
+}
+function companionMessagesToShared(sessionId, messages) {
+    return messages.map((message) => ({
+        id: message.id,
+        sessionId,
+        role: message.role,
+        body: message.content,
+        createdAt: message.createdAt,
+        surfaceKind: 'companion',
+        surfaceId: sessionId,
+        metadata: {},
+    }));
+}
+function buildSnapshot(state) {
+    const sessions = new Map(state.sessions);
+    const messages = new Map();
+    const inputs = new Map();
+    for (const message of state.messages.values()) {
+        messages.set(message.sessionId, [...(messages.get(message.sessionId) ?? []), message]);
+    }
+    for (const inputRecord of state.inputs.values()) {
+        inputs.set(inputRecord.sessionId, [...(inputs.get(inputRecord.sessionId) ?? []), inputRecord]);
+    }
+    return createSessionBrokerSnapshot({ sessions, messages, inputs }, MAX_PERSISTED_MESSAGES_PER_SESSION);
+}

package/dist/platform/control-plane/session-types.d.ts

@@ -1,10 +1,18 @@
 import type { AutomationRouteBinding } from '../automation/routes.js';
 import type { AutomationSurfaceKind } from '../automation/types.js';
+import type { SurfaceKind } from '../../events/surfaces.js';
 import type { SharedSessionInputIntent, SharedSessionInputRecord, SharedSessionRoutingIntent } from './session-intents.js';
 export type SharedSessionStatus = 'active' | 'closed';
 export type SharedSessionMessageRole = 'user' | 'assistant' | 'system';
+/**
+ * A session participant — the identity triple {surfaceKind, surfaceId, userId?}
+ * standardized on the canonical (wide) {@link SurfaceKind}, so product surfaces
+ * (agent/webui/companion) are first-class participants alongside transport
+ * surfaces. `userId` is the documented identity key. This is a DIFFERENT axis
+ * from {@link SharedSessionRecord.kind} (the session origin).
+ */
 export interface SharedSessionParticipant {
-    readonly surfaceKind: AutomationSurfaceKind;
+    readonly surfaceKind: SurfaceKind;
     readonly surfaceId: string;
     readonly externalId?: string | undefined;
     readonly userId?: string | undefined;
@@ -18,7 +26,7 @@ export interface SharedSessionMessage {
     readonly role: SharedSessionMessageRole;
     readonly body: string;
     readonly createdAt: number;
-    readonly surfaceKind?: AutomationSurfaceKind | undefined;
+    readonly surfaceKind?: SurfaceKind | undefined;
     readonly surfaceId?: string | undefined;
     readonly routeId?: string | undefined;
     readonly agentId?: string | undefined;
@@ -27,15 +35,46 @@ export interface SharedSessionMessage {
     readonly metadata: Record<string, unknown>;
 }
 /**
- * Discriminates the session origin.
- * - 'tui': created by the operator TUI (default for existing sessions)
+ * Discriminates the session ORIGIN — which product created the session. This is
+ * a separate axis from {@link SharedSessionParticipant.surfaceKind} (the surface
+ * a participant speaks through). Do not conflate them: a session's origin `kind`
+ * is stamped once at creation; a session can have many participants across many
+ * surfaces.
+ * - 'tui': created by the operator TUI (default for existing/legacy sessions)
+ * - 'agent': created by an agent runtime
+ * - 'webui': created by the rich web client
  * - 'companion-task': created via task-submit flow (agent spawn)
  * - 'companion-chat': created via companion chat-mode API (no agent spawn; uses per-session orchestrator)
+ * - 'automation': created by an automation job/run
  */
-export type SharedSessionKind = 'tui' | 'companion-task' | 'companion-chat';
+export type SharedSessionKind = 'tui' | 'agent' | 'webui' | 'companion-task' | 'companion-chat' | 'automation';
+/**
+ * Why a session was closed. Drives the honest reopen-on-heartbeat rule:
+ * - 'idle-reaped': the GC sweep closed an idle session. It AUTO-REOPENS on the
+ *   next register heartbeat from a participant (a surface coming back to a
+ *   session the SYSTEM closed underneath it is not a conflict).
+ * - 'user' / 'surface': a deliberate close. It does NOT auto-reopen — register
+ *   records the heartbeat and returns the still-closed record with a conflict
+ *   marker unless `reopen: true` is passed (the Wave-1 honest-register semantics).
+ *
+ * Carried on the record under `metadata[SESSION_CLOSE_REASON_METADATA_KEY]` so it
+ * rides the wire without a schema change and old readers ignore it (metadata is
+ * an open record). Absent means the session is open, or was closed by a build
+ * that predates this field.
+ */
+export type SharedSessionCloseReason = 'idle-reaped' | 'user' | 'surface';
 export interface SharedSessionRecord {
     readonly id: string;
     readonly kind: SharedSessionKind;
+    /**
+     * The workspace/project this session belongs to, carried as DATA on the
+     * record (not encoded in the store path). Typically the absolute working
+     * directory of the creating surface, or a stable project id. Legacy records
+     * lacking this field are backfilled to 'unknown' on load. Home-scoped,
+     * projectless surfaces (e.g. companion chat) use 'unknown'. This is what lets
+     * ONE home-scoped store serve every project and every surface filter honestly.
+     */
+    readonly project: string;
     readonly title: string;
     readonly status: SharedSessionStatus;
     readonly createdAt: number;
@@ -51,9 +90,19 @@ export interface SharedSessionRecord {
      */
     readonly lastActivityAt: number;
     readonly messageCount: number;
+    /**
+     * How many of this session's message BODIES are actually retained in the
+     * durable store, when that is fewer than {@link messageCount}. Persistence
+     * caps retained bodies per session (see MAX_PERSISTED_MESSAGES_PER_SESSION);
+     * when the cap prunes the oldest bodies, `messageCount` stays the honest
+     * logical total and this field records how many bodies survived. Omitted when
+     * nothing was pruned (retained === messageCount), so the common case carries
+     * no marker. Readers must treat an absent value as "fully retained".
+     */
+    readonly retainedMessageCount?: number | undefined;
     readonly pendingInputCount: number;
     readonly routeIds: readonly string[];
-    readonly surfaceKinds: readonly AutomationSurfaceKind[];
+    readonly surfaceKinds: readonly SurfaceKind[];
     readonly participants: readonly SharedSessionParticipant[];
     readonly activeAgentId?: string | undefined;
     readonly lastAgentId?: string | undefined;
@@ -66,7 +115,7 @@ export interface SharedSessionSubmission {
     readonly routeBinding?: AutomationRouteBinding | undefined;
     readonly input: SharedSessionInputRecord;
     readonly intent: SharedSessionInputIntent;
-    readonly mode: 'spawn' | 'continued-live' | 'queued-follow-up' | 'rejected';
+    readonly mode: 'spawn' | 'continued-live' | 'queued-follow-up' | 'queued-for-surface' | 'rejected';
     readonly state: SharedSessionInputRecord['state'];
     readonly task?: string | undefined;
     readonly activeAgentId?: string | undefined;
@@ -89,9 +138,95 @@ export interface SubmitSharedSessionMessageInput {
 export interface SteerSharedSessionMessageInput extends SubmitSharedSessionMessageInput {
     readonly allowSpawnFallback?: boolean | undefined;
 }
+/**
+ * The participant/route attach input consumed by the broker's participant merge.
+ * Identical to a submit message minus `metadata`, but `surfaceKind` is the WIDE
+ * canonical {@link SurfaceKind} so product-surface participants (agent/webui/
+ * companion) — which arrive via sessions.register, not the transport submit
+ * path — can be merged. Transport submit inputs (narrow surfaceKind) remain
+ * assignable to this type.
+ */
+export type ParticipantRouteAttachInput = Omit<SubmitSharedSessionMessageInput, 'metadata' | 'surfaceKind'> & {
+    readonly surfaceKind: SurfaceKind;
+};
 export interface FindSharedSessionOptions {
     readonly surfaceKind?: AutomationSurfaceKind | undefined;
     readonly routeId?: string | undefined;
     readonly includeClosed?: boolean | undefined;
+    /** Scope the search to a single project; omit for the cross-project union. */
+    readonly project?: string | undefined;
+}
+/** Options for {@link SharedSessionBroker.listSessions}. */
+export interface ListSharedSessionsOptions {
+    /** Scope to a single project; omit for the cross-project union (default). */
+    readonly project?: string | undefined;
+    /** Filter by origin kind. */
+    readonly kind?: SharedSessionKind | undefined;
+    /** Include closed sessions (default: closed sessions are included). */
+    readonly includeClosed?: boolean | undefined;
+}
+/** Input to {@link SharedSessionBroker.createSession}. */
+export interface CreateSharedSessionInput {
+    readonly id?: string | undefined;
+    readonly kind?: SharedSessionKind | undefined;
+    readonly project?: string | undefined;
+    readonly title?: string | undefined;
+    readonly metadata?: Record<string, unknown> | undefined;
+    readonly routeBinding?: AutomationRouteBinding | undefined;
+    readonly participant?: SharedSessionParticipant | undefined;
+}
+/** Input to {@link SharedSessionBroker.ensureSession} (idempotent create-or-adopt). */
+export interface EnsureSharedSessionInput {
+    readonly sessionId?: string | undefined;
+    readonly kind?: SharedSessionKind | undefined;
+    readonly project?: string | undefined;
+    readonly title?: string | undefined;
+    readonly metadata?: Record<string, unknown> | undefined;
+    readonly routeBinding?: AutomationRouteBinding | undefined;
+    readonly participant?: SharedSessionParticipant | undefined;
+}
+/**
+ * Input to {@link SharedSessionBroker.register} — the idempotent upsert keyed on
+ * a caller-supplied session id. Re-calling register with the same id is the
+ * heartbeat: it advances `participant.lastSeenAt`. Carries the identity spine
+ * (kind + project + participant triple) that {@link EnsureSharedSessionInput}
+ * threads into the record.
+ */
+export interface RegisterSharedSessionInput {
+    readonly sessionId: string;
+    readonly kind?: SharedSessionKind | undefined;
+    readonly project?: string | undefined;
+    readonly title?: string | undefined;
+    readonly participant: SharedSessionParticipant;
+    /**
+     * Explicit intent to reopen a CLOSED session. Default `false`: registering
+     * against a closed id does NOT silently reopen it — it records the heartbeat
+     * (participant.lastSeenAt) and returns the still-closed record with an honest
+     * conflict marker. Pass `true` to reopen as part of the register.
+     */
+    readonly reopen?: boolean | undefined;
+}
+/**
+ * Result of {@link SharedSessionBroker.register}. Carries the record plus honest
+ * lifecycle disposition so a caller (and the wire) never has to guess whether a
+ * closed session was resurrected.
+ *
+ * SPOOFING / TRUST NOTE: the control plane uses a single-admin-token model, so
+ * cross-surface writes under the same token (e.g. two surfaces heartbeating the
+ * same session id) are LEGITIMATE co-participation, not impersonation. `register`
+ * merges participants freely; what it will NOT do silently is change lifecycle
+ * status or rename a titled session.
+ */
+export interface SharedSessionRegisterResult {
+    readonly record: SharedSessionRecord;
+    /** True only when this call reopened a previously-closed session. */
+    readonly reopened: boolean;
+    /**
+     * Present when register targeted a CLOSED session without `reopen: true`. The
+     * record is returned as-is (still closed) with the heartbeat recorded.
+     */
+    readonly conflict?: {
+        readonly status: 'closed';
+    } | undefined;
 }
 //# sourceMappingURL=session-types.d.ts.map

package/dist/platform/control-plane/session-types.d.ts.map

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

package/dist/platform/core/adaptive-planner.d.ts

@@ -9,6 +9,7 @@
  *           /plan explain
  *           /plan override <strategy>
  */
+import { type PlanProposal, type PlanProposalIssue, type RawDecomposition } from './plan-proposal.js';
 /**
  * The five supported execution strategies.
  *
@@ -52,6 +53,18 @@ export interface StrategyCandidate {
     score: number;
     reasonCode: StrategyReasonCode;
 }
+/**
+ * The outcome of the deterministic "does this task warrant decomposition?"
+ * gate. This is a semantic projection of the existing strategy selection —
+ * `decompose` is simply `selected !== 'single'` — so every existing reason
+ * code and the `/plan explain` output stay authoritative. No new scoring
+ * logic lives here.
+ */
+export interface DecompositionGate {
+    decompose: boolean;
+    strategy: ExecutionStrategy;
+    reasonCode: StrategyReasonCode;
+}
 /** The outcome of a planner selection pass. */
 export interface PlannerDecision {
     /** The strategy that was ultimately selected. */
@@ -86,6 +99,43 @@ export declare class AdaptivePlanner {
      * The decision is appended to the history log.
      */
     select(inputs: PlannerInputs): PlannerDecision;
+    /**
+     * Deterministic gate: does this task warrant decomposition into a
+     * multi-phase workstream, or is a single-item workstream the honest
+     * answer?
+     *
+     * This calls the existing `select()` pipeline — no new scoring logic — and
+     * projects the result: `decompose` is `selected !== 'single'`. Because it
+     * goes through `select()`, the decision is appended to the same audit
+     * history as every other planner call, and `/plan explain` / `/plan
+     * status` remain authoritative for it.
+     */
+    shouldDecompose(inputs: PlannerInputs): DecompositionGate;
+    /**
+     * Produce a typed `PlanProposal` for the given inputs.
+     *
+     * `AdaptivePlanner` never spawns a planning agent and never performs LLM
+     * decomposition itself — it only gates (via `shouldDecompose`) and
+     * validates/assembles (via `assemblePlanProposal`, in `plan-proposal.ts`).
+     * The raw decomposition, if any, is expected to come from a planning
+     * agent that the ORCHESTRATION ENGINE spawns and hands back here.
+     *
+     * - If the gate says decomposition is not warranted, or no raw
+     *   decomposition is available yet, this returns the honest single-item
+     *   fallback (`singleItemProposal`) — never a partially-assembled guess.
+     * - Otherwise it validates `raw` via `assemblePlanProposal`, which never
+     *   throws: malformed decompositions degrade to an honest partial result
+     *   plus a list of `issues`.
+     *
+     * Returns the `gate` alongside the proposal so callers (the engine, or the
+     * TUI) can show WHY a proposal was or wasn't decomposed, reusing
+     * `AdaptivePlanner.explainReasonCode`.
+     */
+    proposeWorkstream(inputs: PlannerInputs, raw?: RawDecomposition): {
+        proposal: PlanProposal;
+        gate: DecompositionGate;
+        issues: PlanProposalIssue[];
+    };
     /**
      * Set the operating mode for future calls to `select()`.
      *

package/dist/platform/core/adaptive-planner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adaptive-planner.d.ts","sourceRoot":"","sources":["../../../src/platform/core/adaptive-planner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,GAAG,QAAQ,CAAC;AAEvF,yFAAyF;AACzF,eAAO,MAAM,gBAAgB,EAAE,iBAAiB,EAAyD,CAAC;AAE1G;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAE1B,oBAAoB,GACpB,4BAA4B,GAC5B,oBAAoB,GACpB,gBAAgB,GAChB,qBAAqB,GACrB,gBAAgB,GAChB,sBAAsB,GAEtB,eAAe,GACf,eAAe,GAEf,kBAAkB,CAAC;AAEvB,6DAA6D;AAC7D,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,eAAe,EAAE,MAAM,CAAC;IAExB,8EAA8E;IAC9E,WAAW,EAAE,OAAO,CAAC;IAErB,8DAA8D;IAC9D,eAAe,EAAE,OAAO,CAAC;IAEzB,qEAAqE;IACrE,kBAAkB,EAAE,OAAO,CAAC;IAE5B,wEAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED,0DAA0D;AAC1D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,kBAAkB,CAAC;CAChC;AAED,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,QAAQ,EAAE,iBAAiB,CAAC;IAE5B,6CAA6C;IAC7C,UAAU,EAAE,kBAAkB,CAAC;IAE/B,oDAAoD;IACpD,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAEhC,yEAAyE;IACzE,cAAc,EAAE,OAAO,CAAC;IAExB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAElB,iDAAiD;IACjD,MAAM,EAAE,aAAa,CAAC;CACvB;AAwGD,qBAAa,eAAe;IAC1B,mEAAmE;IACnE,OAAO,CAAC,gBAAgB,CAAkC;IAE1D,8CAA8C;IAC9C,OAAO,CAAC,IAAI,CAA6B;IAEzC,iEAAiE;IACjE,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAO;IAM1C;;;;;;;;;OASG;IACH,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,eAAe;IA+D9C;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI;IAKtC,sCAAsC;IACtC,OAAO,IAAI,iBAAiB;IAI5B;;;;;;OAMG;IACH,QAAQ,CACN,QAAQ,EAAE,MAAM,GACf;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,QAAQ,EAAE,iBAAiB,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,UAAU,EAAE,kBAAkB,CAAA;KAAE;IAW5F,sCAAsC;IACtC,aAAa,IAAI,IAAI;IAKrB,mDAAmD;IACnD,WAAW,IAAI,OAAO;IAItB,oDAAoD;IACpD,WAAW,IAAI,iBAAiB,GAAG,IAAI;IAIvC;;;OAGG;IACH,OAAO,CAAC,UAAU,CAAC,EAAE,kBAAkB,GAAG,MAAM;IAShD,4DAA4D;IAC5D,MAAM,CAAC,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM;IAI1D,wDAAwD;IACxD,UAAU,CAAC,KAAK,SAAK,GAAG,eAAe,EAAE;IAIzC,gDAAgD;IAChD,SAAS,IAAI,eAAe,GAAG,IAAI;IAQnC;;;OAGG;IACH,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,0BAA0B;CA6BnC"}
+{"version":3,"file":"adaptive-planner.d.ts","sourceRoot":"","sources":["../../../src/platform/core/adaptive-planner.ts"],"names":[],"mappings":"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"}

package/dist/platform/core/adaptive-planner.js

@@ -10,6 +10,7 @@
  *           /plan override <strategy>
  */
 import { logger } from '../utils/logger.js';
+import { assemblePlanProposal, singleItemProposal, } from './plan-proposal.js';
 /** All valid strategy names (including 'auto'). Exported for use in command handlers. */
 export const VALID_STRATEGIES = ['auto', 'single', 'cohort', 'background', 'remote'];
 // ---------------------------------------------------------------------------
@@ -172,6 +173,54 @@ export class AdaptivePlanner {
         });
         return decision;
     }
+    /**
+     * Deterministic gate: does this task warrant decomposition into a
+     * multi-phase workstream, or is a single-item workstream the honest
+     * answer?
+     *
+     * This calls the existing `select()` pipeline — no new scoring logic — and
+     * projects the result: `decompose` is `selected !== 'single'`. Because it
+     * goes through `select()`, the decision is appended to the same audit
+     * history as every other planner call, and `/plan explain` / `/plan
+     * status` remain authoritative for it.
+     */
+    shouldDecompose(inputs) {
+        const decision = this.select(inputs);
+        return {
+            decompose: decision.selected !== 'single',
+            strategy: decision.selected,
+            reasonCode: decision.reasonCode,
+        };
+    }
+    /**
+     * Produce a typed `PlanProposal` for the given inputs.
+     *
+     * `AdaptivePlanner` never spawns a planning agent and never performs LLM
+     * decomposition itself — it only gates (via `shouldDecompose`) and
+     * validates/assembles (via `assemblePlanProposal`, in `plan-proposal.ts`).
+     * The raw decomposition, if any, is expected to come from a planning
+     * agent that the ORCHESTRATION ENGINE spawns and hands back here.
+     *
+     * - If the gate says decomposition is not warranted, or no raw
+     *   decomposition is available yet, this returns the honest single-item
+     *   fallback (`singleItemProposal`) — never a partially-assembled guess.
+     * - Otherwise it validates `raw` via `assemblePlanProposal`, which never
+     *   throws: malformed decompositions degrade to an honest partial result
+     *   plus a list of `issues`.
+     *
+     * Returns the `gate` alongside the proposal so callers (the engine, or the
+     * TUI) can show WHY a proposal was or wasn't decomposed, reusing
+     * `AdaptivePlanner.explainReasonCode`.
+     */
+    proposeWorkstream(inputs, raw) {
+        const gate = this.shouldDecompose(inputs);
+        const task = inputs.taskDescription ?? '';
+        if (gate.decompose && raw) {
+            const { proposal, issues } = assemblePlanProposal(task, gate.strategy, raw);
+            return { proposal, gate, issues };
+        }
+        return { proposal: singleItemProposal(task), gate, issues: [] };
+    }
     /**
      * Set the operating mode for future calls to `select()`.
      *

package/dist/platform/core/execution-plan.d.ts

@@ -14,16 +14,43 @@ export interface PlanItem {
     agentId?: string;
     dependencies?: string[];
 }
+export type ExecutionPlanStatus = 'draft' | 'active' | 'complete' | 'failed' | 'dismissed';
 export interface ExecutionPlan {
     id: string;
     title: string;
     createdAt: string;
     updatedAt: string;
     sessionId?: string | undefined;
-    status: 'draft' | 'active' | 'complete' | 'failed';
+    status: ExecutionPlanStatus;
     items: PlanItem[];
     specPath?: string;
     awaitingPlan?: boolean;
+    /** ISO timestamp set when the plan was dismissed/archived (status 'dismissed'). */
+    dismissedAt?: string;
+    /** The status the plan held immediately before it was dismissed — preserved so
+     *  a completed/failed record is not silently rewritten to look like a draft. */
+    dismissedFrom?: Exclude<ExecutionPlanStatus, 'dismissed'>;
+}
+/**
+ * Outcome of {@link ExecutionPlanManager.dismiss}. Dismiss is intentionally
+ * refused mid-execution: an in-flight plan must be stopped via the workstream
+ * cancel path first, so `dismiss` never silently abandons running agent work.
+ *
+ *  - `no-active-plan`      — nothing to dismiss; no mutation.
+ *  - `requires-cancel`     — the active plan is mid-execution ('active');
+ *                            refused. Cancel the workstream first, then dismiss.
+ *  - `dismissed`           — a proposal/awaiting-approval or terminal plan was
+ *                            archived: retained on disk with status 'dismissed'
+ *                            + `dismissedAt`, and the active pointer cleared so a
+ *                            later `/plan <goal>` starts fresh.
+ */
+export type DismissPlanOutcome = 'no-active-plan' | 'requires-cancel' | 'dismissed';
+export interface DismissPlanResult {
+    readonly outcome: DismissPlanOutcome;
+    /** The archived plan (only when `outcome === 'dismissed'`). */
+    readonly plan?: ExecutionPlan;
+    /** The plan that blocked dismissal (only when `outcome === 'requires-cancel'`). */
+    readonly blockedBy?: ExecutionPlan;
 }
 export interface ExecutionPlanParseIssue {
     readonly line: number;
@@ -50,6 +77,21 @@ export declare class ExecutionPlanManager {
     create(title: string, items: Omit<PlanItem, 'id' | 'status'>[], sessionId?: string): ExecutionPlan;
     /** Update a plan item's status (and optionally assign an agent). */
     updateItem(planId: string, itemId: string, status: PlanItemStatus, agentId?: string): void;
+    /**
+     * Dismiss (archive) the active plan for the current session.
+     *
+     * Honest semantics for every plan state:
+     *   - No active plan → no-op (`{ outcome: 'no-active-plan' }`), nothing written.
+     *   - Active/mid-execution ('active') → refused (`{ outcome: 'requires-cancel' }`).
+     *     A running plan must be stopped via the workstream cancel path first;
+     *     dismiss never abandons in-flight agent work by fiat.
+     *   - Proposal/awaiting-approval ('draft') or a terminal record ('complete' /
+     *     'failed') → archived: the plan is RETAINED on disk with status
+     *     'dismissed', a `dismissedAt` timestamp, and `dismissedFrom` recording
+     *     the prior status; the active pointer is cleared so a later
+     *     `/plan <goal>` starts a fresh plan. Nothing is deleted.
+     */
+    dismiss(sessionId?: string): DismissPlanResult;
     /** List all plans (reads directory, excludes active.json). */
     list(): ExecutionPlan[];
     private nextCreatedAt;