@deepseek-harness-tui/dsh-tui 0.10.0 → 0.10.2

package/lib/types/dsh-adapter/command-trees.d.ts

@@ -12,6 +12,7 @@ export interface TuiCommandTreeProvider {
 /** Host-only completion access. Plugins see only their own provider through
  * the traceable service; the channel uses this facade to merge all providers. */
 export interface TuiCommandTreeHost {
+    register(provider: TuiCommandTreeProvider): () => void;
     children(canonicalPath: readonly string[]): readonly CommandCompletionNode[];
     descriptions(root: string): LocalizedDescriptions | undefined;
 }

package/lib/types/dsh-adapter/command-trees.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-trees.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/command-trees.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,KAAK,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAGlF,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,YAAY,CAAC,EAAE,qBAAqB,CAAA;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,qBAAqB,EAAE,CAAA;CAC7E;AAED;iFACiF;AACjF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,qBAAqB,EAAE,CAAA;IAC5E,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAAA;CAC9D;AAED,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,eAAe,EAAE,qBAAqB,CAAA;KACvC;CACF;AAED,eAAO,MAAM,IAAI,0BAA0B,CAAA;AAE3C,iFAAiF;AACjF,qBAAa,qBAAsB,SAAQ,OAAO;gBACpC,GAAG,EAAE,OAAO;IAYxB,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,IAAI;IAoBtD,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,qBAAqB,EAAE;IAM5E,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS;CAK9D;AAyCD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,qBAAqB,GAAG,SAAS,GAAG,kBAAkB,GAAG,SAAS,CAO9G;AAED,eAAe,qBAAqB,CAAA"}
+{"version":3,"file":"command-trees.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/command-trees.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,KAAK,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAQlF,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,YAAY,CAAC,EAAE,qBAAqB,CAAA;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,qBAAqB,EAAE,CAAA;CAC7E;AAED;iFACiF;AACjF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,IAAI,CAAA;IACtD,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,qBAAqB,EAAE,CAAA;IAC5E,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAAA;CAC9D;AAED,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,eAAe,EAAE,qBAAqB,CAAA;KACvC;CACF;AAED,eAAO,MAAM,IAAI,0BAA0B,CAAA;AAE3C,iFAAiF;AACjF,qBAAa,qBAAsB,SAAQ,OAAO;gBACpC,GAAG,EAAE,OAAO;IAwBxB,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,GAAG,MAAM,IAAI;IAqBtD,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,qBAAqB,EAAE;IAO5E,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,GAAG,SAAS;CAM9D;AA0CD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,qBAAqB,GAAG,SAAS,GAAG,kBAAkB,GAAG,SAAS,CAO9G;AAED,eAAe,qBAAqB,CAAA"}

package/lib/types/dsh-adapter/command-trees.js

@@ -1,6 +1,8 @@
 /** Provider-neutral subcommand completion registry for terminal front doors. */
 import { Service } from '@deepseek-ai/cordis';
 import { activationFiber, bindCallerEffect, compositionRoot, concreteService, requirePluginCaller } from './host-access.js';
+import { adapterRuntimeFor } from '../adapter/kernel/runtime-context.js';
+import { assertCapabilityShadowPolicy, } from '../adapter/kernel/runtime.js';
 export const name = 'dsh-tui-command-trees';
 /** Small host-only registry; command execution remains owned by dsh-commands. */
 export class TuiCommandTreeRuntime extends Service {
@@ -8,14 +10,29 @@ export class TuiCommandTreeRuntime extends Service {
         super(ctx, 'tuiCommandTrees');
         compositionRoot(ctx);
         const runtime = this;
-        const state = { providers: new Map(), owners: new Map(), host: undefined };
+        const state = { providers: new Map(), owners: new Map(), host: undefined, runtime: adapterRuntimeFor(ctx) };
         state.host = Object.freeze({
+            register: (provider) => {
+                const state = commandTreeStateFor(runtime);
+                const root = provider.root.trim().toLowerCase();
+                if (!/^[a-z][a-z0-9_-]*$/u.test(root) || state.providers.has(root))
+                    return () => { };
+                const normalized = { ...provider, root };
+                state.providers.set(root, normalized);
+                return () => {
+                    if (state.providers.get(root) !== normalized)
+                        return;
+                    state.providers.delete(root);
+                    state.owners.delete(root);
+                };
+            },
             children: path => childrenFor(runtime, path),
             descriptions: root => descriptionsFor(runtime, root),
         });
         commandTreeStates.set(this, state);
     }
     register(provider) {
+        assertCapabilityShadowPolicy('host.command-trees.register', commandTreeStateFor(this).runtime.mode, commandTreeStateFor(this).runtime.slices);
         const caller = requirePluginCaller(this.ctx, 'tuiCommandTrees.register', this);
         const state = commandTreeStateFor(this);
         const owner = activationFiber(caller);
@@ -39,11 +56,13 @@ export class TuiCommandTreeRuntime extends Service {
         return dispose;
     }
     children(canonicalPath) {
+        assertCapabilityShadowPolicy('host.command-trees.children', commandTreeStateFor(this).runtime.mode, commandTreeStateFor(this).runtime.slices);
         const caller = requirePluginCaller(this.ctx, 'tuiCommandTrees.children', this);
         const owner = activationFiber(caller);
         return childrenFor(this, canonicalPath, owner);
     }
     descriptions(root) {
+        assertCapabilityShadowPolicy('host.command-trees.descriptions', commandTreeStateFor(this).runtime.mode, commandTreeStateFor(this).runtime.slices);
         const caller = requirePluginCaller(this.ctx, 'tuiCommandTrees.descriptions', this);
         const owner = activationFiber(caller);
         return descriptionsFor(this, root, owner);

package/lib/types/dsh-adapter/compat/liveSession.d.ts

@@ -1,5 +1,5 @@
 import type { CreateAgentOptions } from '@deepseek-ai/dsh-agent';
-import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session';
+import type { Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session';
 /**
  * Snapshot of a live Session log, including any fork-inherited prefix.
  * Reuses upstream's frozen cache when the log has not appended.
@@ -47,13 +47,17 @@ export interface LiveSessionSeedMetadata {
  * Create-time seed ownership fields. Every copied source prefix is inherited
  * state for domain projections, even when `/fork` deliberately omits
  * `parentSession` so the copy is presented as an independent root. The exact
- * cut prevents schedule/inbox/subagent projections from replaying copied
- * history as child-owned events. A child snapshot length cannot reliably be
- * used as that cut because construction may append `session/end-seed`.
+ * cut distinguishes copied history from child-owned events. Not every
+ * projection skips inherited events: newer inbox folds restore pending input
+ * from them, so rewind must cancel that work through the child's Inbox API.
+ * A child snapshot length cannot reliably be used as the cut because
+ * construction may append `session/end-seed`.
  */
 export declare function liveSessionSeedMetadata(session: unknown, inheritedCount: number): LiveSessionSeedMetadata;
 /** Close an open turn with the `turn/end` shape a real user cancellation writes. */
 export declare function appendInterruptedTurnEnd(seed: SessionEvent[], turn: number): void;
+/** Close a V3 fork's open inherited turn as child-owned events, after its marker. */
+export declare function closeLiveForkTurn(session: Session, turn: number): void;
 export interface LiveSessionCreateRequest {
     readonly sessionId: SessionId;
     readonly seed: readonly SessionEvent[];

package/lib/types/dsh-adapter/compat/liveSession.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"liveSession.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/compat/liveSession.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAoCvE;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,YAAY,EAAE,CAWnF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAI1D;AAMD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQlF;AAED,iFAAiF;AACjF,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG;IAC1D,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CACxC,CAcA;AASD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE,CA4BxF;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;QAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAC5B,CAAA;IACD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;CACtC;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,OAAO,EAChB,cAAc,EAAE,MAAM,GACrB,uBAAuB,CAQzB;AAED,oFAAoF;AACpF,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CASjF;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,IAAI,EAAE,SAAS,YAAY,EAAE,CAAA;IACtC,4EAA4E;IAC5E,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,CAAA;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC,cAAc,CAAC,CAAA;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAA;CAC7C;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,wBAAwB,GAAG,kBAAkB,CAiB9F"}
+{"version":3,"file":"liveSession.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/compat/liveSession.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAChE,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAoChF;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,YAAY,EAAE,CAWnF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAI1D;AAMD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAQlF;AAED,iFAAiF;AACjF,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG;IAC1D,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5C,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CACxC,CAcA;AASD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE,CA4BxF;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;QAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAC5B,CAAA;IACD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;CACtC;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,OAAO,EAChB,cAAc,EAAE,MAAM,GACrB,uBAAuB,CAQzB;AAED,oFAAoF;AACpF,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CASjF;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAoBtE;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,IAAI,EAAE,SAAS,YAAY,EAAE,CAAA;IACtC,4EAA4E;IAC5E,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAA;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,CAAA;IAClC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC,cAAc,CAAC,CAAA;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAA;CAC7C;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,wBAAwB,GAAG,kBAAkB,CAiB9F"}

package/lib/types/dsh-adapter/compat/liveSession.js

@@ -148,9 +148,11 @@ export function sliceLiveSessionSeed(session, boundary) {
  * Create-time seed ownership fields. Every copied source prefix is inherited
  * state for domain projections, even when `/fork` deliberately omits
  * `parentSession` so the copy is presented as an independent root. The exact
- * cut prevents schedule/inbox/subagent projections from replaying copied
- * history as child-owned events. A child snapshot length cannot reliably be
- * used as that cut because construction may append `session/end-seed`.
+ * cut distinguishes copied history from child-owned events. Not every
+ * projection skips inherited events: newer inbox folds restore pending input
+ * from them, so rewind must cancel that work through the child's Inbox API.
+ * A child snapshot length cannot reliably be used as the cut because
+ * construction may append `session/end-seed`.
  */
 export function liveSessionSeedMetadata(session, inheritedCount) {
     if (usesIsSeeded(session)) {
@@ -173,6 +175,29 @@ export function appendInterruptedTurnEnd(seed, turn) {
         data: { turn, reason: { kind: 'aborted', reason: { kind: 'user' } } },
     });
 }
+/** Close a V3 fork's open inherited turn as child-owned events, after its marker. */
+export function closeLiveForkTurn(session, turn) {
+    for (const event of dshSession.interruptedTurnClosers(snapshotLiveSessionEvents(session))) {
+        switch (event.type) {
+            case 'tool/result':
+                session.append('tool/result', event.data, {
+                    surfaceOp: event.surfaceOp,
+                    ...(event.sourceEventSeqs === undefined ? {} : { sourceEventSeqs: event.sourceEventSeqs }),
+                });
+                break;
+            case 'step/end':
+                session.append('step/end', event.data);
+                break;
+            case 'turn/end':
+                if (event.data.turn !== turn)
+                    throw new Error('fork turn closure does not match its selected turn');
+                session.append('turn/end', { turn, reason: { kind: 'aborted', reason: { kind: 'user' } } });
+                break;
+            default:
+                throw new Error(`unsupported fork closure event: ${event.type}`);
+        }
+    }
+}
 /**
  * Dual-runtime seed metadata for `agents.create`. The only
  * CreateAgentOptions assertion lives here: rc.2 meta carries `seedLength`,

package/lib/types/dsh-adapter/compat/persistence.d.ts

@@ -0,0 +1,21 @@
+import type { SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session';
+interface StoredSession {
+    readonly meta: SessionHeader;
+    readonly events: readonly SessionEvent[];
+    readonly inheritedEventCount?: number;
+}
+/** Read-only persistence seam for legacy services and per-session handles. */
+export interface SessionReader {
+    load?(id: SessionId): Promise<StoredSession>;
+    open?(id: SessionId, access: 'read'): Promise<{
+        readonly header: SessionHeader;
+        readonly inheritedEventCount?: number;
+        read(): Promise<{
+            readonly events: readonly SessionEvent[];
+        }>;
+        close(): Promise<void>;
+    }>;
+}
+export declare function readPersistedSession(source: SessionReader, id: SessionId): Promise<StoredSession>;
+export {};
+//# sourceMappingURL=persistence.d.ts.map

package/lib/types/dsh-adapter/compat/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/compat/persistence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAGtF,UAAU,aAAa;IACrB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;IACxC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;CACtC;AAED,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IAC5C,IAAI,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAC5C,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;QAC9B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;QACrC,IAAI,IAAI,OAAO,CAAC;YAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;SAAE,CAAC,CAAA;QAC7D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;KACvB,CAAC,CAAA;CACH;AAED,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,aAAa,EAAE,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,CAavG"}

package/lib/types/dsh-adapter/compat/persistence.js

@@ -0,0 +1,17 @@
+import { ensureLegacySessionEventTypes } from './sessionLog.js';
+export async function readPersistedSession(source, id) {
+    ensureLegacySessionEventTypes();
+    if (typeof source.open === 'function') {
+        const handle = await source.open(id, 'read');
+        try {
+            const { events } = await handle.read();
+            return { meta: handle.header, events, inheritedEventCount: handle.inheritedEventCount };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    if (typeof source.load === 'function')
+        return source.load(id);
+    throw new Error('dsh-tui: session persistence has no read API');
+}

package/lib/types/dsh-adapter/compat/sessionLog.d.ts

@@ -53,6 +53,14 @@ import type { SessionEvent } from '@deepseek-ai/dsh-session';
  * UI frames — safe for the strict read path to accept and skip. Exported
  * for the regression verifier; grow it only with proof the type was always
  * inert (never load-bearing for session reconstruction).
+ *
+ * 0.1.5 note: the vouch is not only for OLD logs. `session/color` is written
+ * by the TUI itself on every host generation (session-metadata.ts), and
+ * 0.1.5's `validateStoredEvents` refuses unknown non-ignorable types at load
+ * — without this registration a single color pick makes that session
+ * permanently unresumable (probed: SessionFormatUnsupportedError without the
+ * vouch, clean load with it). The type stays inert for reconstruction either
+ * way: it only re-tints the row.
  */
 export declare const LEGACY_SESSION_EVENT_TYPES: readonly string[];
 /**
@@ -67,14 +75,39 @@ export declare function sessionsRoots(): string[];
 /**
  * Locate a session's log by scanning workspace directories for the session
  * id — deliberately NOT replicating the persistence plugin's workspace-key
- * sanitization, so the helpers survive upstream key-scheme changes.
+ * sanitization, so the helpers survive upstream key-scheme changes. Every
+ * committed generation is considered; the newest wins (the backend migrates
+ * historical artifacts by publishing a `session.vN` sibling and reading only
+ * it, so the newest generation is always the authoritative one).
  * @param sessionId - Session id (directory name under each workspace dir).
- * @returns Absolute path of session.jsonl.zstd, or undefined when absent.
+ * @returns Absolute path of the selected log, or undefined when absent.
  */
 export declare function findSessionLogFile(sessionId: string): string | undefined;
+/** A located session log and its on-disk encoding. */
+interface SessionLogFile {
+    readonly path: string;
+    /** true for session.jsonl.zstd (default), false for compression:"none". */
+    readonly compressed: boolean;
+}
+/**
+ * Resolve a `persistence.locate()` hint to a readable log. The hint may name
+ * the physical artifact directly or the backend's LOGICAL name for it (the
+ * jsonl backend's raw-artifact filename carries no encoding suffix), so the
+ * compressed twin is probed as well. Since 0.1.5 the hint names the CURRENT
+ * generation (`session.vN.jsonl[.zstd]`) without touching the filesystem —
+ * for a session never opened since its format was superseded that file does
+ * not exist yet, and the authoritative artifact is an older-generation
+ * sibling in the same directory. Encoding is sniffed from content, never
+ * inferred from the extension.
+ * @param hint - Absolute path from SessionPersistence.locate().
+ * @returns The readable log, or undefined when nothing materialized there.
+ */
+export declare function resolveLocatedPath(hint: string): SessionLogFile | undefined;
 /** Outcome of reading an EXISTING log through the bounded reader. */
 export interface SessionLogRead {
     readonly events: readonly SessionEvent[];
+    /** Physical generation of these sequence coordinates, read from the header. */
+    readonly formatVersion?: number;
     /** False when the read stopped early (event/scan budget) — a plain
      *  truncation; the collected prefix is fully usable. */
     readonly complete: boolean;
@@ -117,11 +150,12 @@ export declare function readSessionEventsFromFile(path: string, maxEvents?: numb
  * cost-bounded. Built for the session tree (buildSessionTree), whose browse
  * must satisfy three constraints the strict backend read cannot:
  *
- *  - READ-ONLY: `persistence.inspect` rejects logs carrying third-party
- *    event types (working-activity's `activity/status`), and the resume
- *    seam's answer (in-process type registration, issue #153) must not be
- *    inverted here: opening a picker never rewrites a history log. This
- *    reader never writes; unknown types are simply passed through
+ *  - READ-ONLY: the strict backend read (`persistence.inspect` on pre-0.1.5
+ *    hosts, the validated `handle.read` path since) rejects logs carrying
+ *    third-party event types (working-activity's `activity/status`), and
+ *    the resume seam's answer (in-process type registration, issue #153)
+ *    must not be inverted here: opening a picker never rewrites a history
+ *    log. This reader never writes; unknown types are simply passed through
  *    (extractEntries skips what it does not know).
  *  - TOLERANT: envelope-shape or decode anomalies degrade to
  *    `failed: true` (a structure-only tree node) instead of rejecting the
@@ -173,12 +207,16 @@ export declare function readSessionEventsFromFile(path: string, maxEvents?: numb
  */
 export declare function readSessionEventsFromLog(sessionId: string, maxEvents?: number, maxScanned?: number, skipBelowSeq?: number): SessionLogRead | undefined;
 /**
- * Read the physical JSONL header's `seedLength` from the first record.
- * Logical alpha.4 list headers only have `isSeeded`; the exact cut stays on
- * this first line. Does not scan events or guess from `session/end-seed`.
+ * Read the exact inherited-prefix length from a log. Pre-V2 physical headers
+ * carry it as `seedLength` on the first line; V2/V3 headers only have
+ * `isSeeded`, and the cut is the seq of the `session/end-seed` marker event
+ * stamped with `inherited: true` — scanned for, bounded, only when the
+ * header says the session is seeded. Logical list headers never carry the
+ * cut on any generation. Never guesses from snapshot length, and an
+ * unseeded or marker-less log reports undefined (no cut to report).
  */
 export declare function readPhysicalHeaderSeedLength(path: string): number | undefined;
-/** Locate a session log by id and read its physical header `seedLength`. */
+/** Locate a session log by id and read its inherited-prefix cut. */
 export declare function readPhysicalHeaderSeedLengthForSession(sessionId: string): number | undefined;
 /**
  * Register every {@link LEGACY_SESSION_EVENT_TYPES} type as known in EVERY
@@ -249,4 +287,5 @@ export declare function appendSessionTitle(sessionId: string, title: string): 'a
  * @returns 'deleted', or 'unavailable' when the log is absent.
  */
 export declare function deleteSessionLog(sessionId: string): 'deleted' | 'unavailable';
+export {};
 //# sourceMappingURL=sessionLog.d.ts.map

package/lib/types/dsh-adapter/compat/sessionLog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sessionLog.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/compat/sessionLog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAiB5D;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAAwB,CAAA;AAKhF;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CASxC;AAaD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAexE;AAsXD,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;IACxC;4DACwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB;;;;;;yDAMqD;IACrD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAC1B;AA+DD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,MAAiC,EAC5C,UAAU,GAAE,MAAqC,EACjD,YAAY,GAAE,MAAU,GACvB,cAAc,GAAG,SAAS,CAI5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,SAAS,GAAE,MAAiC,EAC5C,UAAU,GAAE,MAAqC,EACjD,YAAY,GAAE,MAAU,GACvB,cAAc,GAAG,SAAS,CAI5B;AAWD;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAqB7E;AAED,4EAA4E;AAC5E,wBAAgB,sCAAsC,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI5F;AA+BD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,6BAA6B,IAAI,IAAI,CAkCpD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,GAChB;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAyBzD;AAyBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,aAAa,CAwB/F;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAwB7E"}
+{"version":3,"file":"sessionLog.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/compat/sessionLog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAiB5D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAAyC,CAAA;AAKjG;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CASxC;AAsED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAiBxE;AAqOD,sDAAsD;AACtD,UAAU,cAAc;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;CAC7B;AA+SD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAa3E;AAED,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;IACxC,+EAA+E;IAC/E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B;4DACwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB;;;;;;yDAMqD;IACrD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAC1B;AAoED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,MAAiC,EAC5C,UAAU,GAAE,MAAqC,EACjD,YAAY,GAAE,MAAU,GACvB,cAAc,GAAG,SAAS,CAI5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,SAAS,GAAE,MAAiC,EAC5C,UAAU,GAAE,MAAqC,EACjD,YAAY,GAAE,MAAU,GACvB,cAAc,GAAG,SAAS,CAI5B;AA4CD;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAqC7E;AAED,oEAAoE;AACpE,wBAAgB,sCAAsC,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI5F;AA+BD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,6BAA6B,IAAI,IAAI,CAkCpD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,GAChB;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAyBzD;AAyBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,aAAa,CAwB/F;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAwB7E"}