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

package/lib/types/dsh-adapter/channel/mode-permission-actions.d.ts

@@ -0,0 +1,35 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type SessionModeSpec } from '../../sessionModes.js';
+import type { createChannelBinding } from './binding.js';
+import { createModeActions } from './mode-actions.js';
+import { type PermissionIdentity } from './mode-permission.js';
+import type { PermissionModeRoster } from './mode-roster.js';
+import type { ChannelState } from './types.js';
+type Binding = ReturnType<typeof createChannelBinding>;
+type ModeState = Pick<ChannelState, 'mode' | 'modeIndex' | 'emit'>;
+type ModeCapture = ReturnType<Binding['capture']>;
+/** The composition seam `createModeActions` owns; this factory forwards every
+ *  member verbatim so both stay in lockstep. */
+type BaseModeActionDeps = Parameters<typeof createModeActions>[2];
+/**
+ * Permission-aware session-mode actions: main's mode transition (plan
+ * exclusivity, atom application, plan-exit restore) composed with the durable
+ * permission identity, on top of the refactored `createModeActions`.
+ *
+ * Construction is inert. The returned shape is a superset of
+ * `ReturnType<typeof createModeActions>`, so the composition root and
+ * `createBindingEvents` can consume it unchanged, plus
+ * `runPermissionPreset` for the public `ChannelUi` surface.
+ */
+export declare function createPermissionModeActions(ctx: Context, state: ModeState, deps: Pick<BaseModeActionDeps, 'owner' | 'runtime' | 'binding' | 'sessionModes' | 'commandService' | 'executeRegistryCommand' | 'notify'> & {
+    roster: PermissionModeRoster;
+}): {
+    refreshMode(): void;
+    cycleMode(): Promise<void>;
+    applyMode(spec: SessionModeSpec, capture?: ModeCapture): Promise<void>;
+    onSessionEvent(session: unknown, event: unknown): void;
+    runPermissionPreset(name: string): Promise<boolean>;
+    permission: PermissionIdentity;
+};
+export {};
+//# sourceMappingURL=mode-permission-actions.d.ts.map

package/lib/types/dsh-adapter/channel/mode-permission-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode-permission-actions.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/mode-permission-actions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAE7E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,EAAkD,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAC9G,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,KAAK,OAAO,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAA;AACtD,KAAK,SAAS,GAAG,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC,CAAA;AAClE,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAA;AACjD;gDACgD;AAChD,KAAK,kBAAkB,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAA;AAmEjE;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,IAAI,CACR,kBAAkB,EAClB,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,cAAc,GAAG,gBAAgB,GAAG,wBAAwB,GAAG,QAAQ,CAC1G,GAAG;IAAE,MAAM,EAAE,oBAAoB,CAAA;CAAE,GACnC;IACD,WAAW,IAAI,IAAI,CAAA;IACnB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1B,SAAS,CAAC,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtE,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;IACtD,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACnD,UAAU,EAAE,kBAAkB,CAAA;CAC/B,CAuHA"}

package/lib/types/dsh-adapter/channel/mode-permission-actions.js

@@ -0,0 +1,199 @@
+import { assertShadowPolicy } from '../../adapter/kernel/runtime.js';
+import { t } from '../../i18n.js';
+import { modeDisplayName } from '../../sessionModes.js';
+import { snapshotLiveSessionEvents } from '../compat/liveSession.js';
+import { createModeActions } from './mode-actions.js';
+import { createPermissionIdentity, foldPermissionPreset } from './mode-permission.js';
+// Atom folds mirrored from mode-actions.ts: `createModeActions` does not
+// export them, and the permission-aware derive below must reproduce its
+// atom fallback exactly to stay the single source of the indicator.
+const foldPlanActive = (events) => {
+    let active = false;
+    for (const event of events) {
+        if (event.type === 'plan/mode') {
+            active = event.data.active === true;
+        }
+    }
+    return active;
+};
+const foldSandboxMode = (events) => {
+    let mode;
+    for (const event of events) {
+        if (event.type === 'sandbox/mode') {
+            const value = event.data.mode;
+            if (typeof value === 'string')
+                mode = value;
+        }
+    }
+    return mode;
+};
+const foldApprovalPolicy = (events) => {
+    let policy;
+    for (const event of events) {
+        if (event.type === 'approval/policy') {
+            const value = event.data.policy;
+            if (typeof value === 'string')
+                policy = value;
+        }
+    }
+    return policy;
+};
+/**
+ * Durable-identity-first mode index. A durable permission identity is
+ * STRONGER than the derived sandbox/approval atoms: it keeps a runtime preset
+ * (including one that maps to the same atoms as a static mode) selected after
+ * resume or manual commands instead of snapping to a look-alike static mode.
+ * Permission-only dynamic specs declare no atoms and would wildcard-match ANY
+ * session state, so they can only be selected through the identity branch —
+ * never through the atom fallback.
+ */
+function derivePermissionModeIndex(modes, events) {
+    const identity = foldPermissionPreset(events);
+    if (identity !== undefined) {
+        const permissionIndex = modes.findIndex(spec => spec.permission === identity
+            && (spec.plan === undefined || foldPlanActive(events) === spec.plan));
+        if (permissionIndex >= 0)
+            return permissionIndex;
+    }
+    const index = modes.findIndex(spec => spec.permission === undefined
+        && (spec.plan === undefined || foldPlanActive(events) === spec.plan)
+        && (spec.sandbox === undefined || foldSandboxMode(events) === spec.sandbox)
+        && (spec.approval === undefined || foldApprovalPolicy(events) === spec.approval));
+    return index >= 0 ? index : 0;
+}
+/**
+ * Permission-aware session-mode actions: main's mode transition (plan
+ * exclusivity, atom application, plan-exit restore) composed with the durable
+ * permission identity, on top of the refactored `createModeActions`.
+ *
+ * Construction is inert. The returned shape is a superset of
+ * `ReturnType<typeof createModeActions>`, so the composition root and
+ * `createBindingEvents` can consume it unchanged, plus
+ * `runPermissionPreset` for the public `ChannelUi` surface.
+ */
+export function createPermissionModeActions(ctx, state, deps) {
+    const { owner, binding, sessionModes, roster, commandService, executeRegistryCommand, notify } = deps;
+    const base = createModeActions(ctx, state, {
+        owner,
+        runtime: deps.runtime,
+        binding,
+        sessionModes,
+        commandService,
+        executeRegistryCommand,
+        notify,
+    });
+    const permission = createPermissionIdentity(ctx, {
+        agent: () => binding.agent,
+        roster,
+        commandService,
+        executeRegistryCommand,
+        notify,
+    });
+    // An in-turn /plan off commits at pre-step, after the command has returned.
+    const explicitPlanExits = new WeakSet();
+    /** Re-derive the roster and the current mode. The roster rebuild rides on
+     *  every refresh: a registry mount/unmount and a re-bind both land here. */
+    const refreshMode = () => {
+        roster.rebuild(binding.agent);
+        const index = derivePermissionModeIndex(sessionModes, snapshotLiveSessionEvents(binding.agent.session));
+        state.modeIndex = index;
+        state.mode = sessionModes[index];
+    };
+    /** Apply the configured atoms; an explicit exit owns its target mode.
+     *  Permission identity is applied BEFORE plan and atom changes: dynamic
+     *  presets use the official command path (or the service write fallback)
+     *  and are confirmed by event/registry readback; the TUI never manufactures
+     *  permission events. */
+    const applyMode = async (spec, capture = binding.capture()) => {
+        if (!owner.current() || !binding.isCurrent(capture))
+            return;
+        // This action writes durable session policy; the permission switch writes
+        // the same kind of durable identity, so it is under the same guard.
+        assertShadowPolicy('mutate', deps.runtime.mode);
+        const agent = capture.agent;
+        const session = agent.session;
+        const planMode = ctx.get('planMode');
+        const planActive = foldPlanActive(snapshotLiveSessionEvents(session));
+        const planChange = spec.plan !== undefined && (planMode?.get?.(agent).pending ?? planActive) !== spec.plan;
+        if (planActive && planMode?.get?.(agent).pending === undefined) {
+            explicitPlanExits.delete(session);
+        }
+        // Capture the pre-plan preset identity BEFORE any permission
+        // canonicalization can append replacement events.
+        if (planChange && spec.plan === true && !planActive) {
+            permission.rememberPrePlanIdentity(session);
+        }
+        if (planChange && spec.plan === false) {
+            // An explicit switch away from plan owns its target mode; the
+            // remembered pre-plan identity no longer applies.
+            explicitPlanExits.add(session);
+            permission.forgetPrePlanIdentity(session);
+        }
+        if (spec.permission !== undefined) {
+            if (!(await permission.applyPermissionIdentity(spec.permission)))
+                return;
+        }
+        else if (!(await permission.canonicalizeForMode(spec, session))) {
+            return;
+        }
+        if (!owner.current() || !binding.isCurrent(capture) || session !== agent.session)
+            return;
+        await base.applyMode(spec, capture);
+        if (!owner.current() || !binding.isCurrent(capture))
+            return;
+        const before = state.modeIndex;
+        refreshMode();
+        if (state.modeIndex !== before)
+            state.emit();
+    };
+    /** Shift+Tab: advance from the mode DERIVED from the session log (never a
+     *  stored index), so manual `/plan` use can never desync the cycle. */
+    const cycleMode = async () => {
+        const capture = binding.capture();
+        if (!owner.current() || !binding.isCurrent(capture))
+            return;
+        const index = derivePermissionModeIndex(sessionModes, snapshotLiveSessionEvents(capture.agent.session));
+        await applyMode(sessionModes[(index + 1) % sessionModes.length], capture);
+    };
+    const onSessionEvent = (session, event) => {
+        const subject = session;
+        const sessionEvent = event;
+        base.onSessionEvent(subject, sessionEvent);
+        const type = sessionEvent.type;
+        if (type === 'permission/preset')
+            refreshMode();
+        if (type !== 'plan/mode' || sessionEvent.data.active !== false)
+            return;
+        const remembered = permission.prePlanPermissionIdentity(subject);
+        const explicit = explicitPlanExits.delete(subject);
+        permission.forgetPrePlanIdentity(subject);
+        if (explicit || remembered === undefined)
+            return;
+        if (subject !== binding.agent.session)
+            return;
+        // The atom restore is queued by the base actions in this same turn; the
+        // identity restore runs after it and re-seats the user on their own
+        // preset. Both write the same atom values, so the order cannot diverge.
+        queueMicrotask(() => {
+            if (subject !== binding.agent.session || foldPlanActive(snapshotLiveSessionEvents(subject)))
+                return;
+            void permission.applyPermissionIdentity(remembered).then((ok) => {
+                if (!ok || subject !== binding.agent.session)
+                    return;
+                refreshMode();
+                notify(t('mode-switched', { name: modeDisplayName(state.mode) }));
+                state.emit();
+            }).catch(() => {
+                // Best-effort; failures already surfaced through applyPermissionIdentity.
+            });
+        });
+    };
+    return {
+        refreshMode,
+        cycleMode,
+        applyMode,
+        onSessionEvent,
+        runPermissionPreset: name => permission.runPermissionPreset(name),
+        permission,
+    };
+}

package/lib/types/dsh-adapter/channel/mode-permission.d.ts

@@ -0,0 +1,58 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import { type SessionModeSpec } from '../../sessionModes.js';
+import type { PermissionModeRoster } from './mode-roster.js';
+import type { ChannelState } from './types.js';
+/** Last durable permission preset identity (`permission/preset`), if any.
+ *  Registered by the harness permission preset service, never manufactured
+ *  by the TUI. */
+export declare function foldPermissionPreset(events: readonly SessionEvent[]): string | undefined;
+/** Effective sandbox of a mode target: its explicit atom, else the folded
+ *  session value, else the sandbox-policy service default. Unknown means the
+ *  bundle is not safely mappable. */
+export declare function effectiveSandboxForMode(ctx: Context, spec: SessionModeSpec, events: readonly SessionEvent[]): SessionModeSpec['sandbox'] | undefined;
+/** Effective approval policy of a mode target: its explicit atom, else the
+ *  folded session value, else the approval service configuration. */
+export declare function effectiveApprovalForMode(ctx: Context, spec: SessionModeSpec, session: Agent['session']): SessionModeSpec['approval'] | undefined;
+/** Durable permission identity operations for one channel. */
+export interface PermissionIdentity {
+    /** Folded durable identity of one session log. */
+    foldPermissionPreset(session: Agent['session']): string | undefined;
+    /** Canonical preset for a mode's effective sandbox/approval bundle, when
+     *  the deployment's runtime table (or the stock built-ins) has one. */
+    canonicalPermissionForMode(spec: SessionModeSpec, session: Agent['session']): string | undefined;
+    /** True when the durable identity OR a runtime registry readback reports
+     *  the target. */
+    permissionTargetConfirmed(target: string, session: Agent['session']): boolean;
+    /** Poll fold/registry readback for the target within a grace window. */
+    confirmPermissionTarget(target: string, session: Agent['session'], timeoutMs: number): Promise<boolean>;
+    /** Official `/permission <preset>` switch (or the service write fallback),
+     *  then confirmation. The TUI never fabricates permission events. */
+    applyPermissionIdentity(target: string): Promise<boolean>;
+    /** Static-mode guard: canonicalize a durable identity BEFORE atoms, and
+     *  fail closed when no canonical preset exists for the target bundle. */
+    canonicalizeForMode(spec: SessionModeSpec, session: Agent['session']): Promise<boolean>;
+    /** Capture the preset the user is on before plan mode runs. */
+    rememberPrePlanIdentity(session: Agent['session']): void;
+    /** The captured pre-plan identity, if one is still pending. */
+    prePlanPermissionIdentity(session: Agent['session']): string | undefined;
+    forgetPrePlanIdentity(session: Agent['session']): void;
+    /** `ChannelUi.runPermissionPreset` (see the public Channel type). */
+    runPermissionPreset(name: string): Promise<boolean>;
+}
+/**
+ * Durable `permission/preset` identity: readback, canonical mapping, the
+ * official switch path, and the pre-plan identity memory. Construction is
+ * inert — it acquires nothing and subscribes to nothing.
+ */
+export declare function createPermissionIdentity(ctx: Context, deps: {
+    agent: () => Agent;
+    roster: PermissionModeRoster;
+    commandService?: {
+        find(agent: Agent, name: string): unknown;
+    };
+    executeRegistryCommand(name: string, input: string): Promise<string | undefined>;
+    notify: ChannelState['notify'];
+}): PermissionIdentity;
+//# sourceMappingURL=mode-permission.d.ts.map

package/lib/types/dsh-adapter/channel/mode-permission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode-permission.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/mode-permission.ts"],"names":[],"mappings":"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"}

package/lib/types/dsh-adapter/channel/mode-permission.js

@@ -0,0 +1,240 @@
+import { isCommandCompletionToken } from '../../commands.js';
+import { snapshotLiveSessionEvents } from '../compat/liveSession.js';
+import { t } from '../../i18n.js';
+import { modeDisplayName } from '../../sessionModes.js';
+import { PERMISSION_PRESET_CUSTOM, permissionPresetRuntime } from './permissions.js';
+/** Last durable permission preset identity (`permission/preset`), if any.
+ *  Registered by the harness permission preset service, never manufactured
+ *  by the TUI. */
+export function foldPermissionPreset(events) {
+    let preset;
+    for (const event of events) {
+        if (event.type === 'permission/preset') {
+            const value = event.data.preset;
+            if (typeof value === 'string')
+                preset = value;
+        }
+    }
+    return preset;
+}
+/** Effective sandbox of a mode target: its explicit atom, else the folded
+ *  session value, else the sandbox-policy service default. Unknown means the
+ *  bundle is not safely mappable. */
+export function effectiveSandboxForMode(ctx, spec, events) {
+    if (spec.sandbox !== undefined)
+        return spec.sandbox;
+    let folded;
+    for (const event of events) {
+        if (event.type === 'sandbox/mode') {
+            folded = event.data.mode;
+        }
+    }
+    if (folded === 'read-only' || folded === 'workspace-write' || folded === 'danger-full-access')
+        return folded;
+    try {
+        const sandbox = ctx.get('sandboxPolicy');
+        const value = sandbox?.defaultMode;
+        if (value === 'read-only' || value === 'workspace-write' || value === 'danger-full-access')
+            return value;
+    }
+    catch {
+        // Optional service; an unknown default means the target is not safely
+        // mappable.
+    }
+    return undefined;
+}
+/** Effective approval policy of a mode target: its explicit atom, else the
+ *  folded session value, else the approval service configuration. */
+export function effectiveApprovalForMode(ctx, spec, session) {
+    if (spec.approval !== undefined)
+        return spec.approval;
+    let folded;
+    for (const event of snapshotLiveSessionEvents(session)) {
+        if (event.type === 'approval/policy') {
+            folded = event.data.policy;
+        }
+    }
+    if (folded === 'ask' || folded === 'never')
+        return folded;
+    try {
+        const approval = ctx.get('approval');
+        const value = approval?.effectivePolicy?.(session) ?? approval?.config?.policy;
+        if (value === 'ask' || value === 'never')
+            return value;
+    }
+    catch {
+        // Optional service; an unknown default means the target is not safely
+        // mappable.
+    }
+    return undefined;
+}
+/**
+ * Durable `permission/preset` identity: readback, canonical mapping, the
+ * official switch path, and the pre-plan identity memory. Construction is
+ * inert — it acquires nothing and subscribes to nothing.
+ */
+export function createPermissionIdentity(ctx, deps) {
+    /** Durable preset identity captured when plan mode starts; an implicit plan
+     *  exit prefers returning to it over the canonical bundle of the restored
+     *  atoms, so the user lands back on their own preset (e.g. a third-party
+     *  `auto`), not on a look-alike static mode. */
+    const prePlanIdentity = new WeakMap();
+    const fold = (session) => foldPermissionPreset(snapshotLiveSessionEvents(session));
+    const canonicalForMode = (spec, session) => {
+        const sandbox = effectiveSandboxForMode(ctx, spec, snapshotLiveSessionEvents(session));
+        const approval = effectiveApprovalForMode(ctx, spec, session);
+        if (sandbox === undefined || approval === undefined)
+            return undefined;
+        return deps.roster.canonicalFor(sandbox, approval);
+    };
+    const targetConfirmed = (target, session) => {
+        if (fold(session) === target)
+            return true;
+        try {
+            const snapshot = deps.roster.readSnapshot(deps.agent());
+            if (snapshot !== undefined
+                && snapshot.current?.kind === 'preset'
+                && snapshot.current.value === target) {
+                return true;
+            }
+        }
+        catch {
+            // The registry may be unmounted mid-switch; the fold check above
+            // remains authoritative for the durable identity.
+        }
+        return false;
+    };
+    const confirmTarget = async (target, session, timeoutMs) => {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (session !== deps.agent().session)
+                return false;
+            if (targetConfirmed(target, session))
+                return true;
+            await new Promise(resolve => setTimeout(resolve, 50));
+        }
+        ctx.logger.warn(`dsh-tui: permission mode "${target}" was not confirmed by permissionPresets.current()/permission/preset`);
+        deps.notify(t('mode-permission-unconfirmed'), { color: 'warning' });
+        return false;
+    };
+    const apply = async (target) => {
+        if (!isCommandCompletionToken(target)) {
+            ctx.logger.warn(`dsh-tui: permission mode "${target}" skipped because its identity is not a safe command token`);
+            return false;
+        }
+        const agent = deps.agent();
+        const session = agent.session;
+        if (targetConfirmed(target, session))
+            return true;
+        let registered = false;
+        try {
+            registered = deps.commandService?.find(agent, 'permission') !== undefined;
+        }
+        catch {
+            registered = false;
+        }
+        if (!registered) {
+            // The same handler the official command drives; the TUI never appends
+            // a permission event itself.
+            let service;
+            try {
+                service = ctx.get('permissionPresets');
+            }
+            catch {
+                service = undefined;
+            }
+            const runtime = permissionPresetRuntime(service);
+            if (runtime !== undefined && typeof runtime.set === 'function') {
+                try {
+                    runtime.set(session, target);
+                }
+                catch (error) {
+                    ctx.logger.warn(`dsh-tui: permission mode "${target}" could not be applied by the permissionPresets service: ${error instanceof Error ? error.message : String(error)}`);
+                    deps.notify(t('mode-permission-invoke-failed'), { color: 'warning' });
+                    return false;
+                }
+                return await confirmTarget(target, session, 2000);
+            }
+            ctx.logger.warn(`dsh-tui: permission mode "${target}" skipped because /permission is not registered`);
+            deps.notify(t('mode-permission-unregistered'), { color: 'warning' });
+            return false;
+        }
+        const result = await deps.executeRegistryCommand('permission', ` ${target}`);
+        if (session !== deps.agent().session)
+            return false;
+        if (result === undefined) {
+            ctx.logger.warn(`dsh-tui: permission mode "${target}" could not invoke /permission`);
+            deps.notify(t('mode-permission-invoke-failed'), { color: 'warning' });
+            return false;
+        }
+        let availability = 'unavailable';
+        try {
+            availability = deps.roster.readSnapshot(deps.agent()) === undefined ? 'unavailable' : 'runtime';
+        }
+        catch {
+            // keep the default (fail-closed short grace)
+        }
+        return await confirmTarget(target, session, availability === 'runtime' ? 2000 : 300);
+    };
+    const canonicalizeForMode = async (spec, session) => {
+        // Static modes own a canonical permission identity. Leaving any OTHER
+        // durable identity behind (third-party preset OR a stale canonical, e.g.
+        // plan left `read-only` while atoms were restored to workspace-write)
+        // would make a static mode appear selected only because its
+        // sandbox/approval bundle happens to match, and would let the durable
+        // identity lie about the real policy.
+        const current = fold(session);
+        if (current === undefined || current === PERMISSION_PRESET_CUSTOM)
+            return true;
+        const canonical = canonicalForMode(spec, session);
+        if (canonical === undefined) {
+            ctx.logger.warn(`dsh-tui: static mode "${spec.id}" cannot safely clear permission identity "${current}"`);
+            deps.notify(t('mode-permission-no-canonical', { name: modeDisplayName(spec) }), { color: 'warning' });
+            return false;
+        }
+        if (canonical === current)
+            return true;
+        return apply(canonical);
+    };
+    const rememberPrePlanIdentity = (session) => {
+        // The runtime registry must still recognize the identity as current: a
+        // drifted knob combination reads back as custom and must fall back to the
+        // canonical bundle of the restored atoms.
+        const identity = fold(session);
+        if (identity === undefined || identity === PERMISSION_PRESET_CUSTOM) {
+            prePlanIdentity.delete(session);
+            return;
+        }
+        try {
+            const snapshot = deps.roster.readSnapshot(deps.agent());
+            if (snapshot === undefined) {
+                prePlanIdentity.delete(session);
+                return;
+            }
+            if (snapshot.current?.kind !== 'preset' || snapshot.current.value !== identity) {
+                prePlanIdentity.delete(session);
+                return;
+            }
+            if (!snapshot.options.some(option => option.value === identity)) {
+                prePlanIdentity.delete(session);
+                return;
+            }
+            prePlanIdentity.set(session, identity);
+        }
+        catch {
+            prePlanIdentity.delete(session);
+        }
+    };
+    return {
+        foldPermissionPreset: fold,
+        canonicalPermissionForMode: canonicalForMode,
+        permissionTargetConfirmed: (target, session) => targetConfirmed(target, session),
+        confirmPermissionTarget: (target, session, timeoutMs) => confirmTarget(target, session, timeoutMs),
+        applyPermissionIdentity: apply,
+        canonicalizeForMode,
+        rememberPrePlanIdentity,
+        prePlanPermissionIdentity: session => prePlanIdentity.get(session),
+        forgetPrePlanIdentity: session => { prePlanIdentity.delete(session); },
+        runPermissionPreset: name => apply(name.trim()),
+    };
+}

package/lib/types/dsh-adapter/channel/mode-roster.d.ts

@@ -0,0 +1,51 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import { type SessionModeSpec } from '../../sessionModes.js';
+import { type PermissionPresetBundle } from './permissions.js';
+import type { PermissionPresetSnapshot } from './types.js';
+/** Durable identities the configured modes already own; a runtime preset with
+ *  one of them is the same switch by another route and never duplicated. */
+export declare function configuredPermissionIds(modes: readonly SessionModeSpec[]): ReadonlySet<string>;
+/** Canonical targets of the STATIC modes. On a stock table that is the three
+ *  built-in names; on renamed tables the deployment's own names for the same
+ *  bundles. They are never dynamic entries: the indicator would otherwise
+ *  snap to a dynamic look-alike instead of the static mode. */
+export declare function staticCanonicalTargets(modes: readonly SessionModeSpec[], bundles: readonly PermissionPresetBundle[]): ReadonlySet<string>;
+/** The mounted `permissionPresets` registry as a runtime snapshot, or
+ *  undefined when no runtime table is mounted (legacy/unavailable tables are
+ *  not a roster). Reads are fail-closed: a throwing registry is no roster. */
+export declare function readRuntimePermissionSnapshot(ctx: Context, target: Agent): PermissionPresetSnapshot | undefined;
+/** Warn at most once per (agent, identity, reason) — a registry that keeps
+ *  re-listing an unusable preset must not flood the log on every rebuild. */
+export declare function warnOnceForPermissionEntry(warned: Set<string>, warn: (message: string) => void, target: Agent, value: string, reason: string): void;
+/** The Shift+Tab roster: configured modes first, runtime presets appended. */
+export interface PermissionModeRoster {
+    /** LIVE roster. The array identity is stable and mutated in place, so a
+     *  consumer that captured it at construction always sees the latest
+     *  roster after {@link PermissionModeRoster.rebuild}. */
+    readonly modes: readonly SessionModeSpec[];
+    /** Re-read the runtime preset registry for `target` and re-derive. */
+    rebuild(target: Agent): void;
+    /** Runtime snapshot for `target`, undefined when no runtime table is mounted. */
+    readSnapshot(target: Agent): PermissionPresetSnapshot | undefined;
+    /** Canonical preset name for one effective sandbox/approval bundle. */
+    canonicalFor(sandbox: NonNullable<SessionModeSpec['sandbox']>, approval: NonNullable<SessionModeSpec['approval']>): string | undefined;
+}
+/**
+ * Dynamic session-mode roster (main's `sessionModes` / `rebuildSessionModes`).
+ *
+ * Runtime permission presets are appended AFTER the configured/default modes
+ * whenever the SERVICE snapshot is usable — no dependency on the external
+ * `/permission` command reaching this agent's registry, because switching
+ * falls back to the service's own write path when the command row is absent.
+ * Registry order is authoritative on first observation; later rebuilds
+ * preserve the relative order of identities already seen so unrelated
+ * command-registry churn cannot reshuffle Shift+Tab. Removed identities drop
+ * out and a later re-add is treated as new.
+ */
+export declare function createPermissionModeRoster(ctx: Context, deps: {
+    configuredModes: readonly SessionModeSpec[];
+    agent: () => Agent;
+    warn?: (message: string) => void;
+}): PermissionModeRoster;
+//# sourceMappingURL=mode-roster.d.ts.map

package/lib/types/dsh-adapter/channel/mode-roster.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode-roster.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/channel/mode-roster.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AAEnD,OAAO,EAKL,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,kBAAkB,CAAA;AACzB,OAAO,KAAK,EAA0B,wBAAwB,EAAE,MAAM,YAAY,CAAA;AAElF;4EAC4E;AAC5E,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,GAAG,WAAW,CAAC,MAAM,CAAC,CAE9F;AAED;;;+DAG+D;AAC/D,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,SAAS,eAAe,EAAE,EACjC,OAAO,EAAE,SAAS,sBAAsB,EAAE,GACzC,WAAW,CAAC,MAAM,CAAC,CAQrB;AAED;;8EAE8E;AAC9E,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,KAAK,GACZ,wBAAwB,GAAG,SAAS,CAUtC;AAED;6EAC6E;AAC7E,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,EACnB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,EAC/B,MAAM,EAAE,KAAK,EACb,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,IAAI,CAMN;AAED,8EAA8E;AAC9E,MAAM,WAAW,oBAAoB;IACnC;;6DAEyD;IACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAA;IAC1C,sEAAsE;IACtE,OAAO,CAAC,MAAM,EAAE,KAAK,GAAG,IAAI,CAAA;IAC5B,iFAAiF;IACjF,YAAY,CAAC,MAAM,EAAE,KAAK,GAAG,wBAAwB,GAAG,SAAS,CAAA;IACjE,uEAAuE;IACvE,YAAY,CACV,OAAO,EAAE,WAAW,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC,EAChD,QAAQ,EAAE,WAAW,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC,GACjD,MAAM,GAAG,SAAS,CAAA;CACtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE;IACJ,eAAe,EAAE,SAAS,eAAe,EAAE,CAAA;IAC3C,KAAK,EAAE,MAAM,KAAK,CAAA;IAClB,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACjC,GACA,oBAAoB,CAgEtB"}