@askdkc/dsh-cli 0.11.3

package/lib/types/sessionHistory.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Store the session to resume and report the launcher invocation.
+ * @param sessionId - Session id for `dsh-tui --resume` on the next launch.
+ */
+export declare function writeResumeTarget(sessionId: string): void;
+/** Forget the resume marker (`/new` starts a fresh conversation). */
+export declare function clearResumeTarget(): void;
+/**
+ * The session id requested by `dsh-tui --resume`, if any.
+ * @returns The stored session id, or undefined when none is set.
+ */
+export declare function readResumeTarget(): string | undefined;
+/**
+ * The session id requested through `--resume`/`-c`/`--continue` in app args,
+ * mirroring the standalone bin's interception (issue #120/#53). The
+ * `dsh --profile tui` boot path forwards these args to the booted app
+ * verbatim and never parses them into DSH_TUI_RESUME_SESSION, so the
+ * in-profile plugin reads them itself. A bare flag with no id defers to the
+ * exit-time marker, exactly like the bin.
+ * @param argv - the app arguments (typically `process.argv.slice(2)`).
+ * @returns The requested session id, or undefined when none was given.
+ */
+export declare function resumeTargetFromArgv(argv: readonly string[]): string | undefined;
+/**
+ * Session-id → last-used epoch ms map for MRU ordering.
+ * @returns The parsed map; best effort, an unreadable file yields {}.
+ */
+export declare function readLastUsed(): Readonly<Record<string, number>>;
+/**
+ * Record that a session was just used (resumed or written to) so `/resume`
+ * can sort most-recently-used first. Best effort — never throws.
+ * @param sessionId - Session id to touch.
+ */
+export declare function touchSession(sessionId: string): void;
+/**
+ * Drop a session's last-used entry (`/resume` picker delete) so the MRU map
+ * never accumulates ids whose logs are gone. Best effort — never throws.
+ * @param sessionId - Session id to forget.
+ */
+export declare function forgetSession(sessionId: string): void;
+/**
+ * The agent-view ledger (see {@link AGENT_VIEW_SESSIONS_FILE}): session-id →
+ * epoch-ms. Best effort — an unreadable file yields {}.
+ * @returns The parsed map.
+ */
+export declare function readAgentViewSessions(): Readonly<Record<string, number>>;
+/**
+ * Record a session as agent-view-managed (dispatched, backgrounded, or
+ * attached from the view). Best effort — never throws.
+ * @param sessionId - Session id to record.
+ */
+export declare function touchAgentViewSession(sessionId: string): void;
+/**
+ * Drop a session from the agent-view ledger (its log was deleted). Best
+ * effort — never throws.
+ * @param sessionId - Session id to forget.
+ */
+export declare function forgetAgentViewSession(sessionId: string): void;
+//# sourceMappingURL=sessionHistory.d.ts.map

package/lib/types/sessionHistory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionHistory.d.ts","sourceRoot":"","sources":["../../src/sessionHistory.ts"],"names":[],"mappings":"AAyCA;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAGzD;AAED,qEAAqE;AACrE,wBAAgB,iBAAiB,IAAI,IAAI,CAMxC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,SAAS,CAOrD;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAehF;AAED;;;GAGG;AACH,wBAAgB,YAAY,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAyB/D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAUpD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAYrD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAiBxE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAQ7D;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAU9D"}

package/lib/types/sessionHistory.js

@@ -0,0 +1,223 @@
+/**
+ * Launcher contract for `dsh-tui --resume`: the TUI writes the chosen session
+ * id to `~/.dsh-tui/resume.txt`, and the launcher feeds it back as
+ * `DSH_TUI_RESUME_SESSION`. Session *records* live in DSH's own persistence
+ * backend (dsh-session-persistence-jsonl) — `/resume` lists those via
+ * `sessionPersistence.list()`, this file only carries the id across
+ * processes. It also keeps a small `last-used.json` of session-id → epoch-ms
+ * touches so `/resume` can sort most-recently-used first (DSH session
+ * headers carry only `createdAt`).
+ */
+import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DATA_DIR } from './utils/paths.js';
+const DIR = DATA_DIR;
+const RESUME_FILE = join(DIR, 'resume.txt');
+const LAST_USED_FILE = join(DIR, 'last-used.json');
+let lastUsedStamp;
+let lastUsedCache;
+function lastUsedFileStamp() {
+    try {
+        const stats = statSync(LAST_USED_FILE);
+        return `${stats.dev}:${stats.ino}:${stats.size}:${stats.mtimeMs}:${stats.ctimeMs}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The agent view's OWN ledger: session-id → epoch-ms of the moments this TUI
+ * dispatched, backgrounded, or attached to a session FROM the agent view.
+ * Unlike last-used.json (every /resume touch), this is the "background
+ * session" record used by the session overview — ordinary history never lands
+ * here, so the view lists only sessions it actually manages.
+ */
+const AGENT_VIEW_SESSIONS_FILE = join(DIR, 'agent-view-sessions.json');
+function ensureDir() {
+    mkdirSync(DIR, { recursive: true });
+}
+/**
+ * Store the session to resume and report the launcher invocation.
+ * @param sessionId - Session id for `dsh-tui --resume` on the next launch.
+ */
+export function writeResumeTarget(sessionId) {
+    ensureDir();
+    writeFileSync(RESUME_FILE, sessionId);
+}
+/** Forget the resume marker (`/new` starts a fresh conversation). */
+export function clearResumeTarget() {
+    try {
+        writeFileSync(RESUME_FILE, '');
+    }
+    catch {
+        // Best effort — the marker is a launcher nicety.
+    }
+}
+/**
+ * The session id requested by `dsh-tui --resume`, if any.
+ * @returns The stored session id, or undefined when none is set.
+ */
+export function readResumeTarget() {
+    try {
+        const value = readFileSync(RESUME_FILE, 'utf8').trim();
+        return value || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The session id requested through `--resume`/`-c`/`--continue` in app args,
+ * mirroring the standalone bin's interception (issue #120/#53). The
+ * `dsh --profile tui` boot path forwards these args to the booted app
+ * verbatim and never parses them into DSH_TUI_RESUME_SESSION, so the
+ * in-profile plugin reads them itself. A bare flag with no id defers to the
+ * exit-time marker, exactly like the bin.
+ * @param argv - the app arguments (typically `process.argv.slice(2)`).
+ * @returns The requested session id, or undefined when none was given.
+ */
+export function resumeTargetFromArgv(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--resume' || a === '-c' || a === '--continue' || a.startsWith('--resume=')) {
+            let sessionId = '';
+            if (a.startsWith('--resume=')) {
+                sessionId = a.slice('--resume='.length).trim();
+            }
+            else if (a === '--resume' && argv[i + 1] !== undefined && !argv[i + 1].startsWith('-')) {
+                sessionId = argv[++i].trim();
+            }
+            if (!sessionId)
+                sessionId = readResumeTarget() ?? '';
+            if (sessionId)
+                return sessionId;
+        }
+    }
+    return undefined;
+}
+/**
+ * Session-id → last-used epoch ms map for MRU ordering.
+ * @returns The parsed map; best effort, an unreadable file yields {}.
+ */
+export function readLastUsed() {
+    const stamp = lastUsedFileStamp();
+    if (lastUsedCache !== undefined && lastUsedStamp === stamp)
+        return lastUsedCache;
+    try {
+        const parsed = JSON.parse(readFileSync(LAST_USED_FILE, 'utf8'));
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            lastUsedCache = {};
+            lastUsedStamp = stamp;
+            return lastUsedCache;
+        }
+        const record = parsed;
+        const result = {};
+        for (const [id, value] of Object.entries(record)) {
+            if (typeof value === 'number' && Number.isFinite(value)) {
+                result[id] = value;
+            }
+        }
+        lastUsedCache = result;
+        lastUsedStamp = stamp;
+        return result;
+    }
+    catch {
+        lastUsedCache = {};
+        lastUsedStamp = stamp;
+        return lastUsedCache;
+    }
+}
+/**
+ * Record that a session was just used (resumed or written to) so `/resume`
+ * can sort most-recently-used first. Best effort — never throws.
+ * @param sessionId - Session id to touch.
+ */
+export function touchSession(sessionId) {
+    try {
+        ensureDir();
+        const lastUsed = { ...readLastUsed(), [sessionId]: Date.now() };
+        writeFileSync(LAST_USED_FILE, JSON.stringify(lastUsed));
+        lastUsedCache = lastUsed;
+        lastUsedStamp = lastUsedFileStamp();
+    }
+    catch {
+        // Best effort — MRU ordering is a nicety.
+    }
+}
+/**
+ * Drop a session's last-used entry (`/resume` picker delete) so the MRU map
+ * never accumulates ids whose logs are gone. Best effort — never throws.
+ * @param sessionId - Session id to forget.
+ */
+export function forgetSession(sessionId) {
+    try {
+        const lastUsed = { ...readLastUsed() };
+        if (!(sessionId in lastUsed))
+            return;
+        delete lastUsed[sessionId];
+        ensureDir();
+        writeFileSync(LAST_USED_FILE, JSON.stringify(lastUsed));
+        lastUsedCache = lastUsed;
+        lastUsedStamp = lastUsedFileStamp();
+    }
+    catch {
+        // Best effort — a stale entry only skews sort order.
+    }
+}
+/**
+ * The agent-view ledger (see {@link AGENT_VIEW_SESSIONS_FILE}): session-id →
+ * epoch-ms. Best effort — an unreadable file yields {}.
+ * @returns The parsed map.
+ */
+export function readAgentViewSessions() {
+    try {
+        const parsed = JSON.parse(readFileSync(AGENT_VIEW_SESSIONS_FILE, 'utf8'));
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return {};
+        }
+        const record = parsed;
+        const result = {};
+        for (const [id, value] of Object.entries(record)) {
+            if (typeof value === 'number' && Number.isFinite(value)) {
+                result[id] = value;
+            }
+        }
+        return result;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Record a session as agent-view-managed (dispatched, backgrounded, or
+ * attached from the view). Best effort — never throws.
+ * @param sessionId - Session id to record.
+ */
+export function touchAgentViewSession(sessionId) {
+    try {
+        ensureDir();
+        const sessions = { ...readAgentViewSessions(), [sessionId]: Date.now() };
+        writeFileSync(AGENT_VIEW_SESSIONS_FILE, JSON.stringify(sessions));
+    }
+    catch {
+        // Best effort — the ledger is a display filter, not state.
+    }
+}
+/**
+ * Drop a session from the agent-view ledger (its log was deleted). Best
+ * effort — never throws.
+ * @param sessionId - Session id to forget.
+ */
+export function forgetAgentViewSession(sessionId) {
+    try {
+        const sessions = { ...readAgentViewSessions() };
+        if (!(sessionId in sessions))
+            return;
+        delete sessions[sessionId];
+        ensureDir();
+        writeFileSync(AGENT_VIEW_SESSIONS_FILE, JSON.stringify(sessions));
+    }
+    catch {
+        // Best effort — a stale entry only lists one extra stopped row.
+    }
+}

package/lib/types/sessionModes.d.ts

@@ -0,0 +1,83 @@
+import type { SessionModeSpec } from './adapter/ports/channel-display.js';
+export type { SessionModeSpec } from './adapter/ports/channel-display.js';
+/** The shipped cycle when cordis.yml pins no `modes` — array order IS the
+ *  Shift+Tab cycle order; index 0 is the unmarked base mode. */
+export declare const DEFAULT_SESSION_MODES: readonly SessionModeSpec[];
+/** Preset names the TUI treats as the canonical built-ins. They are covered
+ *  by the static modes of the default cycle, so they never enter the cycle as
+ *  dynamic entries; `/permission` targets them whenever the deployment's
+ *  preset table keeps the stock names. */
+export declare const CANONICAL_PERMISSION_PRESETS: ReadonlySet<string>;
+/** The stock bundle each canonical preset name stands for. */
+export declare const CANONICAL_PERMISSION_BUNDLES: readonly {
+    value: string;
+    sandbox: 'read-only' | 'workspace-write' | 'danger-full-access';
+    approval: 'ask' | 'never';
+}[];
+/** One runtime roster entry the deployment exposes (`optionOf` shape). */
+export interface PermissionRosterOptionLike {
+    readonly value: string;
+    readonly name: string;
+    readonly description?: string;
+}
+/** Reserved identity names never treated as switchable presets. */
+export declare const RESERVED_PERMISSION_PRESETS: ReadonlySet<string>;
+/**
+ * Resolve the canonical preset for an effective sandbox/approval bundle.
+ * When the deployment's preset table is atom-resolving (`extras` non-empty)
+ * the FIRST matching table entry wins — stock names behave exactly as
+ * before, while renamed/extended tables stay table-driven instead of
+ * hard-coding names. Without a resolving table the stock canonical bundles
+ * are the fallback (identical behavior on harnesses whose service does not
+ * expose preset atoms). Undefined means no visible preset matches.
+ */
+export declare function canonicalPresetFor(sandbox: 'read-only' | 'workspace-write' | 'danger-full-access', approval: 'ask' | 'never', extras?: readonly {
+    value: string;
+    sandbox?: 'read-only' | 'workspace-write' | 'danger-full-access';
+    approval?: 'ask' | 'never';
+}[]): string | undefined;
+/**
+ * Keep a runtime permission roster stable across refreshes without overriding
+ * the registry's order on first observation. Existing identities retain their
+ * relative order; newly observed identities follow the latest official order.
+ * Removed identities are omitted, so a later re-add is treated as new.
+ */
+export declare function stablePermissionRosterOrder(previous: readonly string[], current: readonly string[]): readonly string[];
+/**
+ * Decide whether one runtime roster option may enter the Shift+Tab cycle.
+ * Third-party presets are appended after configured/default modes; reserved
+ * sentinels, canonical stock presets (they already ARE the static modes),
+ * duplicate identities and unsafe command tokens are excluded with a reason.
+ */
+export declare function permissionCycleEntry(option: PermissionRosterOptionLike, configuredPermissions: ReadonlySet<string>): {
+    accepted: true;
+    option: PermissionRosterOptionLike;
+} | {
+    accepted: false;
+    reason: string;
+};
+/** Config → cycle list: undefined/empty → DEFAULT_SESSION_MODES; entries
+ *  declaring no plan/sandbox/approval/permission atom are dropped (their ids
+ *  are returned for the caller to warn about). A `permission` atom may be
+ *  paired with `plan`, but is mutually exclusive with `sandbox`/`approval`;
+ *  conflicting entries are excluded without being reported as dropped (the
+ *  caller warns about them separately). If nothing survives,
+ *  DEFAULT_SESSION_MODES. Atom vocabularies are already enforced by the
+ *  plugin Schema at load, so no value validation happens here. */
+export declare function resolveSessionModes(raw: readonly SessionModeSpec[] | undefined): {
+    modes: readonly SessionModeSpec[];
+    dropped: readonly string[];
+};
+/** Display name: explicit `label` > built-in i18n (`mode-default`/
+ *  `mode-plan`/`mode-full` for those ids) > the raw id. */
+export declare function modeDisplayName(spec: SessionModeSpec): string;
+/**
+ * One dynamic Shift+Tab entry for a runtime permission preset. The id is
+ * namespaced so it can never collide with a configured mode id, the label
+ * carries the registry's display name, and the entry declares NO atoms: a
+ * dynamic preset is selected through its durable `permission/preset`
+ * identity only, never by an atom wildcard match (which would steal the
+ * indicator on sessions that never held that identity).
+ */
+export declare function permissionModeSpec(option: PermissionRosterOptionLike): SessionModeSpec;
+//# sourceMappingURL=sessionModes.d.ts.map

package/lib/types/sessionModes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionModes.d.ts","sourceRoot":"","sources":["../../src/sessionModes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAA;AACzE,YAAY,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAA;AAYzE;gEACgE;AAChE,eAAO,MAAM,qBAAqB,EAAE,SAAS,eAAe,EAI3D,CAAA;AAED;;;0CAG0C;AAC1C,eAAO,MAAM,4BAA4B,EAAE,WAAW,CAAC,MAAM,CAI3D,CAAA;AAEF,8DAA8D;AAC9D,eAAO,MAAM,4BAA4B,EAAE,SAAS;IAClD,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,WAAW,GAAG,iBAAiB,GAAG,oBAAoB,CAAA;IAC/D,QAAQ,EAAE,KAAK,GAAG,OAAO,CAAA;CAC1B,EAIA,CAAA;AAED,0EAA0E;AAC1E,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,mEAAmE;AACnE,eAAO,MAAM,2BAA2B,EAAE,WAAW,CAAC,MAAM,CAAiC,CAAA;AAE7F;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,WAAW,GAAG,iBAAiB,GAAG,oBAAoB,EAC/D,QAAQ,EAAE,KAAK,GAAG,OAAO,EACzB,MAAM,CAAC,EAAE,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,WAAW,GAAG,iBAAiB,GAAG,oBAAoB,CAAC;IAAC,QAAQ,CAAC,EAAE,KAAK,GAAG,OAAO,CAAA;CAAE,EAAE,GAClI,MAAM,GAAG,SAAS,CAQpB;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,SAAS,MAAM,EAAE,CAiBnB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,0BAA0B,EAClC,qBAAqB,EAAE,WAAW,CAAC,MAAM,CAAC,GACzC;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,0BAA0B,CAAA;CAAE,GAAG;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAK9F;AAED;;;;;;;kEAOkE;AAClE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,SAAS,eAAe,EAAE,GAAG,SAAS,GAAG;IAChF,KAAK,EAAE,SAAS,eAAe,EAAE,CAAA;IACjC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3B,CAgBA;AAED;2DAC2D;AAC3D,wBAAgB,eAAe,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAM7D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,0BAA0B,GAAG,eAAe,CAEtF"}

package/lib/types/sessionModes.js

@@ -0,0 +1,141 @@
+/**
+ * Configurable Shift+Tab session modes (the `modes` dsh-tui plugin config):
+ * each mode is a named bundle of optional DSH plane switches — plan mode
+ * (dsh-plan-mode `/plan`), sandbox mode (dsh-sandbox-policy `sandbox/mode`
+ * session events), approval policy (dsh-user-approval `approval/policy`
+ * events), or a durable permission preset identity. An absent atom means
+ * "this mode does not touch that plane"; `permission` may be combined with
+ * `plan`, but not with `sandbox` or `approval`.
+ */
+import { t } from './i18n.js';
+/** The shipped cycle when cordis.yml pins no `modes` — array order IS the
+ *  Shift+Tab cycle order; index 0 is the unmarked base mode. */
+export const DEFAULT_SESSION_MODES = [
+    { id: 'default', plan: false, sandbox: 'workspace-write', approval: 'ask' },
+    { id: 'plan', plan: true, sandbox: 'read-only', approval: 'ask' },
+    { id: 'full', plan: false, sandbox: 'danger-full-access', approval: 'never' },
+];
+/** Preset names the TUI treats as the canonical built-ins. They are covered
+ *  by the static modes of the default cycle, so they never enter the cycle as
+ *  dynamic entries; `/permission` targets them whenever the deployment's
+ *  preset table keeps the stock names. */
+export const CANONICAL_PERMISSION_PRESETS = new Set([
+    'read-only',
+    'workspace-write',
+    'danger-full-access',
+]);
+/** The stock bundle each canonical preset name stands for. */
+export const CANONICAL_PERMISSION_BUNDLES = [
+    { value: 'read-only', sandbox: 'read-only', approval: 'ask' },
+    { value: 'workspace-write', sandbox: 'workspace-write', approval: 'ask' },
+    { value: 'danger-full-access', sandbox: 'danger-full-access', approval: 'never' },
+];
+/** Reserved identity names never treated as switchable presets. */
+export const RESERVED_PERMISSION_PRESETS = new Set(['custom', 'status']);
+/**
+ * Resolve the canonical preset for an effective sandbox/approval bundle.
+ * When the deployment's preset table is atom-resolving (`extras` non-empty)
+ * the FIRST matching table entry wins — stock names behave exactly as
+ * before, while renamed/extended tables stay table-driven instead of
+ * hard-coding names. Without a resolving table the stock canonical bundles
+ * are the fallback (identical behavior on harnesses whose service does not
+ * expose preset atoms). Undefined means no visible preset matches.
+ */
+export function canonicalPresetFor(sandbox, approval, extras) {
+    if (extras !== undefined && extras.length > 0) {
+        const extra = extras.find(entry => entry.sandbox === sandbox && entry.approval === approval);
+        if (extra !== undefined)
+            return extra.value;
+        return undefined;
+    }
+    const stock = CANONICAL_PERMISSION_BUNDLES.find(bundle => bundle.sandbox === sandbox && bundle.approval === approval);
+    return stock?.value;
+}
+/**
+ * Keep a runtime permission roster stable across refreshes without overriding
+ * the registry's order on first observation. Existing identities retain their
+ * relative order; newly observed identities follow the latest official order.
+ * Removed identities are omitted, so a later re-add is treated as new.
+ */
+export function stablePermissionRosterOrder(previous, current) {
+    const available = new Set(current);
+    const ordered = [];
+    const seen = new Set();
+    for (const value of previous) {
+        if (available.has(value) && !seen.has(value)) {
+            seen.add(value);
+            ordered.push(value);
+        }
+    }
+    for (const value of current) {
+        if (!seen.has(value)) {
+            seen.add(value);
+            ordered.push(value);
+        }
+    }
+    return ordered;
+}
+/**
+ * Decide whether one runtime roster option may enter the Shift+Tab cycle.
+ * Third-party presets are appended after configured/default modes; reserved
+ * sentinels, canonical stock presets (they already ARE the static modes),
+ * duplicate identities and unsafe command tokens are excluded with a reason.
+ */
+export function permissionCycleEntry(option, configuredPermissions) {
+    if (RESERVED_PERMISSION_PRESETS.has(option.value))
+        return { accepted: false, reason: 'reserved sentinel' };
+    if (CANONICAL_PERMISSION_PRESETS.has(option.value))
+        return { accepted: false, reason: 'canonical preset' };
+    if (configuredPermissions.has(option.value))
+        return { accepted: false, reason: 'duplicate identity' };
+    return { accepted: true, option };
+}
+/** Config → cycle list: undefined/empty → DEFAULT_SESSION_MODES; entries
+ *  declaring no plan/sandbox/approval/permission atom are dropped (their ids
+ *  are returned for the caller to warn about). A `permission` atom may be
+ *  paired with `plan`, but is mutually exclusive with `sandbox`/`approval`;
+ *  conflicting entries are excluded without being reported as dropped (the
+ *  caller warns about them separately). If nothing survives,
+ *  DEFAULT_SESSION_MODES. Atom vocabularies are already enforced by the
+ *  plugin Schema at load, so no value validation happens here. */
+export function resolveSessionModes(raw) {
+    if (raw === undefined || raw.length === 0)
+        return { modes: DEFAULT_SESSION_MODES, dropped: [] };
+    const dropped = [];
+    const modes = raw.filter(spec => {
+        const hasPermission = spec.permission !== undefined;
+        const conflicts = hasPermission && (spec.sandbox !== undefined || spec.approval !== undefined);
+        const usable = !conflicts && (spec.plan !== undefined
+            || spec.sandbox !== undefined
+            || spec.approval !== undefined
+            || hasPermission);
+        if (!usable && !conflicts)
+            dropped.push(spec.id);
+        return usable;
+    });
+    return modes.length === 0 ? { modes: DEFAULT_SESSION_MODES, dropped } : { modes, dropped };
+}
+/** Display name: explicit `label` > built-in i18n (`mode-default`/
+ *  `mode-plan`/`mode-full` for those ids) > the raw id. */
+export function modeDisplayName(spec) {
+    if (spec.label !== undefined)
+        return spec.label;
+    if (spec.id === 'default')
+        return t('mode-default');
+    if (spec.id === 'plan')
+        return t('mode-plan');
+    if (spec.id === 'full')
+        return t('mode-full');
+    return spec.id;
+}
+/**
+ * One dynamic Shift+Tab entry for a runtime permission preset. The id is
+ * namespaced so it can never collide with a configured mode id, the label
+ * carries the registry's display name, and the entry declares NO atoms: a
+ * dynamic preset is selected through its durable `permission/preset`
+ * identity only, never by an atom wildcard match (which would steal the
+ * indicator on sessions that never held that identity).
+ */
+export function permissionModeSpec(option) {
+    return { id: `permission:${option.value}`, label: option.name, permission: option.value };
+}