@deepseek-harness-tui/dsh-tui 0.6.1 → 0.7.1

package/lib/types/trajectory/motion.js

@@ -0,0 +1,143 @@
+/**
+ * Trajectory motion — five verbs, one shared clock, one hard rule.
+ *
+ * ## The rule: SGR-only
+ *
+ * The renderer diffs frames cell by cell and emits the smallest patch that
+ * reconciles them. A cell whose *style* changed costs a few bytes of SGR; a
+ * row whose *layout* changed costs a full row rewrite, and in inline mode a
+ * frame that got shorter takes the full-reset path that once deposited a copy
+ * of the whole UI into scrollback on every repaint (issues #38/#39/#19/#10).
+ *
+ * So every verb below animates colour and colour only. Nothing here changes a
+ * glyph count, a row count, or a box dimension. `verify-trace-motion` asserts
+ * this mechanically by capturing the write stream across a hundred ticks and
+ * failing on any row-level escape — the rule is machine-enforced, not a
+ * convention someone has to remember.
+ *
+ * ## The verbs
+ *
+ * | verb        | shape                      | used for                        |
+ * |-------------|----------------------------|---------------------------------|
+ * | `arrive`    | one bright frame, settle   | a row or wave column just landed |
+ * | `reproject` | dim → bright, two frames   | the same data, re-sorted/filtered |
+ * | `alert`     | two flashes, then steady   | an error, a retry, a pending ask |
+ * | `alive`     | slow breath, loops         | the running edge (1–2 cells max) |
+ * | `navigate`  | *nothing*                  | cursor, viewport, inspector      |
+ *
+ * `navigate` having no animation is a decision, not an omission: easing on a
+ * cursor is latency you can feel, and key auto-repeat already supplies the
+ * sense of continuity.
+ *
+ * ## Cost
+ *
+ * No timer is created here. The scene subscribes once to the Ink core's
+ * shared animation clock, which already pauses when the terminal loses focus
+ * or the view scrolls offscreen — so an idle session animates nothing.
+ */
+import { interpolateColor, parseRGB } from '../components/Spinner/spinnerUtils.js';
+/** Scene clock period. One tick drives every verb below. */
+export const MOTION_TICK_MS = 100;
+/** Ticks a one-shot verb runs for before settling. */
+export const MOTION_SPANS = {
+    arrive: 2,
+    reproject: 3,
+    /** Two flashes: bright, dim, bright, dim, then steady. */
+    alert: 8,
+};
+/** Ticks per half-breath of the `alive` verb (~600 ms in, 600 ms out). */
+const BREATH_TICKS = 6;
+/** Format an RGB triple the way the theme and `<Text color>` expect. */
+export function rgbString(color) {
+    return `rgb(${color.r},${color.g},${color.b})`;
+}
+/**
+ * Blend two colours, accepting either theme values (`rgb(r,g,b)`) or hex.
+ *
+ * @param base - Colour at `t = 0`.
+ * @param highlight - Colour at `t = 1`.
+ * @param t - Blend position, clamped into [0, 1].
+ * @returns A colour string `<Text color>` accepts, or `base` when either
+ *   input could not be parsed (a custom theme may carry an ANSI name).
+ */
+export function mix(base, highlight, t) {
+    const from = parseRGB(base);
+    const to = parseRGB(highlight);
+    // An unparseable input (a custom theme may carry an ANSI name, which has no
+    // channels to interpolate) falls back to the base rather than to grey.
+    if (from === null || to === null)
+        return base;
+    return rgbString(interpolateColor(from, to, Math.min(1, Math.max(0, t))));
+}
+/**
+ * The `alive` verb: a triangular breath in [0, 1], synchronized across every
+ * caller because they all read the same clock.
+ *
+ * @param tick - Current scene tick.
+ * @returns Blend position for {@link mix}.
+ */
+export function alive(tick) {
+    const phase = ((tick % (BREATH_TICKS * 2)) + BREATH_TICKS * 2) % (BREATH_TICKS * 2);
+    return phase < BREATH_TICKS ? phase / BREATH_TICKS : (BREATH_TICKS * 2 - phase) / BREATH_TICKS;
+}
+/**
+ * Progress of a one-shot verb.
+ *
+ * @param tick - Current scene tick.
+ * @param startTick - Tick the verb was triggered on.
+ * @param span - Duration in ticks.
+ * @returns Elapsed ticks, or `null` once the verb has settled (or when
+ *   `startTick` is in the future, which happens for one frame after a reset).
+ */
+function elapsed(tick, startTick, span) {
+    const age = tick - startTick;
+    return age < 0 || age >= span ? null : age;
+}
+/**
+ * The `arrive` verb: one bright frame, then settle.
+ *
+ * @returns Blend position, or 0 once settled.
+ */
+export function arrive(tick, startTick) {
+    const age = elapsed(tick, startTick, MOTION_SPANS.arrive);
+    if (age === null)
+        return 0;
+    return 1 - age / MOTION_SPANS.arrive;
+}
+/**
+ * The `reproject` verb: the view dims, then comes back up. Used when the same
+ * rows are re-ordered or re-filtered, so the eye is told "this is the same
+ * data, rearranged" rather than "this is a new screen".
+ *
+ * @returns Dim factor in [0, 1] where 1 is fully dimmed, 0 fully settled.
+ */
+export function reproject(tick, startTick) {
+    const age = elapsed(tick, startTick, MOTION_SPANS.reproject);
+    if (age === null)
+        return 0;
+    return 1 - (age + 1) / MOTION_SPANS.reproject;
+}
+/**
+ * The `alert` verb: two flashes, then steady. Deliberately one-shot — a
+ * looping alarm is noise, and an error that keeps blinking after you have
+ * seen it trains you to ignore it.
+ *
+ * @returns Blend position toward the highlight, or 0 once steady.
+ */
+export function alert(tick, startTick) {
+    const age = elapsed(tick, startTick, MOTION_SPANS.alert);
+    if (age === null)
+        return 0;
+    // 8 ticks: on, off, on, off — each phase two ticks wide.
+    return Math.floor(age / 2) % 2 === 0 ? 1 : 0;
+}
+/**
+ * Colour for a running cell (the `alive` verb applied to a theme pair).
+ *
+ * @param tick - Current scene tick.
+ * @param base - Settled colour.
+ * @param highlight - Peak-of-breath colour.
+ */
+export function aliveColor(tick, base, highlight) {
+    return mix(base, highlight, alive(tick));
+}

package/lib/types/trajectory/query.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Trajectory query — whole-session structured filtering.
+ *
+ * The official web trajectory is paged, and its own documentation is explicit
+ * that search covers only the currently loaded window. In the terminal the
+ * entire event log is already resident, so filtering can be exhaustive — and
+ * once it is exhaustive, plain substring search stops being enough. This is a
+ * small field language instead:
+ *
+ * ```
+ *   tool:web_search        name equals (case-insensitive)
+ *   kind:retry             row kind
+ *   turn:9                 owning turn
+ *   err:                   failed rows only
+ *   run:                   still-running rows only
+ *   >10s  <500ms           own duration bounds (ms / s / m suffixes)
+ *   tok>1k                 token bounds
+ *   anything else          free text over label, detail and outcome
+ * ```
+ *
+ * Everything is AND-ed. An unparseable term degrades to free text rather than
+ * erroring, so a half-typed query still narrows sensibly while you type.
+ */
+import type { TrajKind, TrajNode } from '../dsh-adapter/types.js';
+/** One parsed predicate. */
+type Term = {
+    readonly kind: 'text';
+    readonly value: string;
+} | {
+    readonly kind: 'tool';
+    readonly value: string;
+} | {
+    readonly kind: 'rowKind';
+    readonly value: string;
+} | {
+    readonly kind: 'turn';
+    readonly value: number;
+} | {
+    readonly kind: 'error';
+} | {
+    readonly kind: 'running';
+} | {
+    readonly kind: 'duration';
+    readonly op: '>' | '<';
+    readonly ms: number;
+} | {
+    readonly kind: 'tokens';
+    readonly op: '>' | '<';
+    readonly count: number;
+};
+/** A compiled query: the parsed terms plus the raw text they came from. */
+export interface TrajQuery {
+    readonly raw: string;
+    readonly terms: readonly Term[];
+    /** True when the query selects everything (empty or whitespace only). */
+    readonly empty: boolean;
+}
+/** Field prefixes offered in the query hint line. */
+export declare const QUERY_FIELDS: readonly ["tool:", "kind:", "turn:", "err:", "run:", ">10s", "<1s", "tok>1k"];
+/**
+ * Compile a query string.
+ *
+ * @param raw - The user's query text.
+ * @returns A query that {@link matchesQuery} can evaluate. Never throws.
+ */
+export declare function parseQuery(raw: string): TrajQuery;
+/** True when a row satisfies every term (an empty query matches everything). */
+export declare function matchesQuery(node: TrajNode, query: TrajQuery): boolean;
+/**
+ * Apply a query to the ledger.
+ *
+ * @returns The matching rows and, in parallel, their original ledger indexes —
+ *   the wave band highlights matches in place, so it needs the positions the
+ *   rows had before filtering, not after.
+ */
+export declare function applyQuery(nodes: readonly TrajNode[], query: TrajQuery): {
+    rows: TrajNode[];
+    indexes: number[];
+};
+/** Row kinds offered as `kind:` completions, in ledger-usefulness order. */
+export declare const QUERY_KINDS: readonly TrajKind[];
+export {};
+//# sourceMappingURL=query.d.ts.map

package/lib/types/trajectory/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/trajectory/query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAEjE,4BAA4B;AAC5B,KAAK,IAAI,GACL;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,GAAG,GAAG,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC1E;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,GAAG,GAAG,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAE/E,2EAA2E;AAC3E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAA;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CACxB;AAED,qDAAqD;AACrD,eAAO,MAAM,YAAY,+EAAgF,CAAA;AA2BzG;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAoCjD;AA8CD,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAItE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,SAAS,QAAQ,EAAE,EAC1B,KAAK,EAAE,SAAS,GACf;IAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAYzC;AAED,4EAA4E;AAC5E,eAAO,MAAM,WAAW,EAAE,SAAS,QAAQ,EAG1C,CAAA"}

package/lib/types/trajectory/query.js

@@ -0,0 +1,187 @@
+/**
+ * Trajectory query — whole-session structured filtering.
+ *
+ * The official web trajectory is paged, and its own documentation is explicit
+ * that search covers only the currently loaded window. In the terminal the
+ * entire event log is already resident, so filtering can be exhaustive — and
+ * once it is exhaustive, plain substring search stops being enough. This is a
+ * small field language instead:
+ *
+ * ```
+ *   tool:web_search        name equals (case-insensitive)
+ *   kind:retry             row kind
+ *   turn:9                 owning turn
+ *   err:                   failed rows only
+ *   run:                   still-running rows only
+ *   >10s  <500ms           own duration bounds (ms / s / m suffixes)
+ *   tok>1k                 token bounds
+ *   anything else          free text over label, detail and outcome
+ * ```
+ *
+ * Everything is AND-ed. An unparseable term degrades to free text rather than
+ * erroring, so a half-typed query still narrows sensibly while you type.
+ */
+import { burstErrors, burstRunning, previewText } from '../dsh-adapter/trajectory/index.js';
+/** Field prefixes offered in the query hint line. */
+export const QUERY_FIELDS = ['tool:', 'kind:', 'turn:', 'err:', 'run:', '>10s', '<1s', 'tok>1k'];
+/** Parse a duration literal (`500ms`, `2s`, `3m`) into milliseconds. */
+function parseDuration(text) {
+    const match = /^(\d+(?:\.\d+)?)(ms|s|m)?$/.exec(text);
+    if (match === null)
+        return undefined;
+    const value = Number(match[1]);
+    if (!Number.isFinite(value))
+        return undefined;
+    switch (match[2]) {
+        case 'm': return value * 60_000;
+        case 'ms': return value;
+        // A bare number is seconds: `>10` reads as ten seconds, which is what a
+        // user scanning for slow calls means.
+        default: return value * 1000;
+    }
+}
+/** Parse a token literal (`1k`, `20000`, `1.5M`). */
+function parseCount(text) {
+    const match = /^(\d+(?:\.\d+)?)([km])?$/i.exec(text);
+    if (match === null)
+        return undefined;
+    const value = Number(match[1]);
+    if (!Number.isFinite(value))
+        return undefined;
+    const unit = match[2]?.toLowerCase();
+    return unit === 'k' ? value * 1000 : unit === 'm' ? value * 1_000_000 : value;
+}
+/**
+ * Compile a query string.
+ *
+ * @param raw - The user's query text.
+ * @returns A query that {@link matchesQuery} can evaluate. Never throws.
+ */
+export function parseQuery(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === '')
+        return { raw, terms: [], empty: true };
+    const terms = [];
+    for (const token of trimmed.split(/\s+/)) {
+        const lower = token.toLowerCase();
+        if (lower === 'err:' || lower === 'error:') {
+            terms.push({ kind: 'error' });
+            continue;
+        }
+        if (lower === 'run:' || lower === 'running:') {
+            terms.push({ kind: 'running' });
+            continue;
+        }
+        const tool = /^tool:(.+)$/.exec(lower);
+        if (tool !== null) {
+            terms.push({ kind: 'tool', value: tool[1] });
+            continue;
+        }
+        const rowKind = /^kind:(.+)$/.exec(lower);
+        if (rowKind !== null) {
+            terms.push({ kind: 'rowKind', value: rowKind[1] });
+            continue;
+        }
+        const turn = /^turn:(\d+)$/.exec(lower);
+        if (turn !== null) {
+            terms.push({ kind: 'turn', value: Number(turn[1]) });
+            continue;
+        }
+        const tokens = /^tok([<>])(.+)$/.exec(lower);
+        if (tokens !== null) {
+            const count = parseCount(tokens[2]);
+            if (count !== undefined) {
+                terms.push({ kind: 'tokens', op: tokens[1], count });
+                continue;
+            }
+        }
+        const duration = /^([<>])(.+)$/.exec(lower);
+        if (duration !== null) {
+            const ms = parseDuration(duration[2]);
+            if (ms !== undefined) {
+                terms.push({ kind: 'duration', op: duration[1], ms });
+                continue;
+            }
+        }
+        // Anything unrecognized — including a half-typed `tool:` — is free text.
+        terms.push({ kind: 'text', value: lower });
+    }
+    return { raw, terms, empty: false };
+}
+/** Total tokens attributed to a row. */
+function tokenTotal(node) {
+    const t = node.tokens;
+    return t === undefined ? 0 : t.input + t.output + t.think;
+}
+/**
+ * Free-text haystack for one row.
+ *
+ * Bounded on purpose: a 200 KB tool result must not cost a full scan per row
+ * per keystroke, and a match beyond the first few hundred characters is not
+ * something the one-line ledger could show anyway.
+ */
+function haystack(node) {
+    return `${node.label} ${previewText(node.detail ?? '', 200)} ${previewText(node.outcome ?? '', 200)}`.toLowerCase();
+}
+/** Evaluate one row against one term. */
+function matchesTerm(node, term) {
+    switch (term.kind) {
+        case 'text':
+            return haystack(node).includes(term.value);
+        case 'tool':
+            return (node.kind === 'tool' || node.kind === 'subtool') && node.label.toLowerCase() === term.value;
+        case 'rowKind':
+            return node.kind === term.value;
+        case 'turn':
+            return node.turn === term.value;
+        case 'error':
+            return node.status === 'error' || (node.burst !== undefined && burstErrors(node.burst) > 0);
+        case 'running':
+            return node.status === 'running' || (node.burst !== undefined && burstRunning(node.burst));
+        case 'duration': {
+            const ms = node.durationMs;
+            if (ms === undefined)
+                return false;
+            return term.op === '>' ? ms > term.ms : ms < term.ms;
+        }
+        case 'tokens': {
+            const count = tokenTotal(node);
+            return term.op === '>' ? count > term.count : count < term.count;
+        }
+    }
+}
+/** True when a row satisfies every term (an empty query matches everything). */
+export function matchesQuery(node, query) {
+    if (query.empty)
+        return true;
+    for (const term of query.terms)
+        if (!matchesTerm(node, term))
+            return false;
+    return true;
+}
+/**
+ * Apply a query to the ledger.
+ *
+ * @returns The matching rows and, in parallel, their original ledger indexes —
+ *   the wave band highlights matches in place, so it needs the positions the
+ *   rows had before filtering, not after.
+ */
+export function applyQuery(nodes, query) {
+    if (query.empty)
+        return { rows: [...nodes], indexes: nodes.map((_, index) => index) };
+    const rows = [];
+    const indexes = [];
+    for (let index = 0; index < nodes.length; index++) {
+        const node = nodes[index];
+        if (matchesQuery(node, query)) {
+            rows.push(node);
+            indexes.push(index);
+        }
+    }
+    return { rows, indexes };
+}
+/** Row kinds offered as `kind:` completions, in ledger-usefulness order. */
+export const QUERY_KINDS = [
+    'tool', 'subtool', 'retry', 'assistant', 'thinking', 'user',
+    'approval', 'system', 'context', 'compaction', 'turn', 'step', 'todo',
+];

package/lib/types/trajectoryPrefs.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Persisted "the user has seen the trajectory" flag, at
+ * `~/.dsh-tui/trajectory.json`.
+ *
+ * It exists so the key hint beside the status-line wake can retire itself.
+ * A permanent `ctrl+t` printed on every frame forever is the classic symptom
+ * of an affordance that does not carry its own meaning — it is read once and
+ * then becomes furniture. Showing it only until the feature has actually been
+ * opened keeps the teaching where teaching belongs (the first minute) and
+ * leaves the steady state clean.
+ *
+ * Best effort, like every other pref here: a missing, unreadable or corrupt
+ * file simply means "not seen yet", which fails toward showing the hint.
+ */
+/**
+ * Parse a persisted `{ seen }` value.
+ *
+ * @param text - Raw file contents.
+ * @returns True only for an explicit `seen: true`.
+ */
+export declare function parseTrajectorySeen(text: string): boolean;
+/**
+ * Whether the trajectory scene has ever been opened on this machine.
+ *
+ * @param dir - Prefs directory (injectable for tests).
+ * @returns True when the flag is set.
+ */
+export declare function readTrajectorySeen(dir?: string): boolean;
+/**
+ * Record that the trajectory has been opened (best effort).
+ *
+ * @param dir - Prefs directory (injectable for tests).
+ * @returns True when the file was written.
+ */
+export declare function writeTrajectorySeen(dir?: string): boolean;
+//# sourceMappingURL=trajectoryPrefs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"trajectoryPrefs.d.ts","sourceRoot":"","sources":["../../src/trajectoryPrefs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAQH;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAQzD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAiB,GAAG,OAAO,CAMlE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAiB,GAAG,OAAO,CAQnE"}

package/lib/types/trajectoryPrefs.js

@@ -0,0 +1,65 @@
+/**
+ * Persisted "the user has seen the trajectory" flag, at
+ * `~/.dsh-tui/trajectory.json`.
+ *
+ * It exists so the key hint beside the status-line wake can retire itself.
+ * A permanent `ctrl+t` printed on every frame forever is the classic symptom
+ * of an affordance that does not carry its own meaning — it is read once and
+ * then becomes furniture. Showing it only until the feature has actually been
+ * opened keeps the teaching where teaching belongs (the first minute) and
+ * leaves the steady state clean.
+ *
+ * Best effort, like every other pref here: a missing, unreadable or corrupt
+ * file simply means "not seen yet", which fails toward showing the hint.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DATA_DIR } from './utils/paths.js';
+const FILE = 'trajectory.json';
+/**
+ * Parse a persisted `{ seen }` value.
+ *
+ * @param text - Raw file contents.
+ * @returns True only for an explicit `seen: true`.
+ */
+export function parseTrajectorySeen(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return false;
+        return parsed.seen === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether the trajectory scene has ever been opened on this machine.
+ *
+ * @param dir - Prefs directory (injectable for tests).
+ * @returns True when the flag is set.
+ */
+export function readTrajectorySeen(dir = DATA_DIR) {
+    try {
+        return parseTrajectorySeen(readFileSync(join(dir, FILE), 'utf8'));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Record that the trajectory has been opened (best effort).
+ *
+ * @param dir - Prefs directory (injectable for tests).
+ * @returns True when the file was written.
+ */
+export function writeTrajectorySeen(dir = DATA_DIR) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, FILE), JSON.stringify({ seen: true }, null, 2));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/lib/types/update.d.ts

@@ -1,3 +1,5 @@
+import { shellQuote } from './utils/shellQuote.js';
+export { shellQuote };
 export interface TuiUpdateInfo {
     current: string;
     latest: string;
@@ -53,8 +55,6 @@ export declare function resolveTuiUpdateTarget(): Promise<TuiUpdateTarget>;
  * or blocks the interactive TUI.
  */
 export declare function checkForTuiUpdate(): Promise<TuiUpdateInfo | undefined>;
-/** cmd.exe joins spawn arguments with spaces; quote anything that could split. */
-export declare function shellQuote(args: readonly string[]): string[];
 /**
  * Update the installed dsh-tui package and restart the same launcher while
  * preserving the active session. The TUI must already be unmounted before
@@ -63,7 +63,7 @@ export declare function shellQuote(args: readonly string[]): string[];
  * `--latest` is required: `pnpm add` writes a caret range into the profile
  * manifest, and a plain `pnpm update` stays inside that range — with this
  * project's minor-per-release cadence the TUI would restart unchanged while
- * reporting success. The restart carries `DSH_CC_UPDATED_FROM` so the new
+ * reporting success. The restart carries `DSH_TUI_UPDATED_FROM` so the new
  * process can warn when the version did not actually move (e.g. a mirror
  * registry still serving the old `latest`).
  *

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

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/update.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;CACf;AAED,4DAA4D;AAC5D,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAA;AAEvB,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,gFAAgF;AAChF,wBAAgB,mBAAmB,IAAI,MAAM,GAAG,SAAS,CAiBxD;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,SAAS,MAAM,EAAiB,GAAG,MAAM,GAAG,SAAS,CAahG;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAW5C;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAIzE;AA4BD;;;;GAIG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,eAAe,CAAC,CASvE;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAG5E;AAED,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAE5D;AAyCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAoBtG"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/update.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAIlD,OAAO,EAAE,UAAU,EAAE,CAAA;AAQrB,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;CACf;AAED,4DAA4D;AAC5D,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAA;AAEvB,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,gFAAgF;AAChF,wBAAgB,mBAAmB,IAAI,MAAM,GAAG,SAAS,CAiBxD;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,SAAS,MAAM,EAAiB,GAAG,MAAM,GAAG,SAAS,CAahG;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAW5C;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAIzE;AA4BD;;;;GAIG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,eAAe,CAAC,CASvE;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAG5E;AAgDD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAuBtG"}

package/lib/types/update.js

@@ -4,11 +4,15 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { gt, valid } from 'semver';
+import { shellQuote } from './utils/shellQuote.js';
+// Re-exported for scripts/verify-update.mjs and the bin launcher, which reads
+// the compiled copy at lib/types/utils/shellQuote.js.
+export { shellQuote };
 const PACKAGE_NAME = '@deepseek-harness-tui/dsh-tui';
 const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
 const UPDATE_CHECK_TIMEOUT_MS = 4000;
 /** env marker set on the /update restart; the new process verifies it at boot. */
-const UPDATED_FROM_ENV = 'DSH_CC_UPDATED_FROM';
+const UPDATED_FROM_ENV = 'DSH_TUI_UPDATED_FROM';
 /** Read the version from either the compiled package or the source checkout. */
 export function installedTuiVersion() {
     const here = dirname(fileURLToPath(import.meta.url));
@@ -130,10 +134,6 @@ export async function checkForTuiUpdate() {
     const target = await resolveTuiUpdateTarget();
     return target.kind === 'update' ? { current: target.current, latest: target.latest } : undefined;
 }
-/** cmd.exe joins spawn arguments with spaces; quote anything that could split. */
-export function shellQuote(args) {
-    return args.map(arg => (/[ \t"^&|<>()]/.test(arg) ? `"${arg.replace(/"/g, '""')}"` : arg));
-}
 /**
  * Run a child process with its output attached to the user's terminal. The
  * shell is opt-in per call: `dsh.cmd` needs it, but the node restart must
@@ -145,7 +145,15 @@ function runProcess(command, args, options = {}) {
     return new Promise(resolve => {
         let settled = false;
         const useShell = options.shell === true && process.platform === 'win32';
-        const child = spawn(command, useShell ? shellQuote(args) : args, {
+        // DEP0190 (issue #148): Node ≥22 warns on `shell: true` with a non-empty
+        // args array even when every arg is escaped — the check is syntactic.
+        // Fold the shell-quoted args into the command string instead (an empty
+        // args array does not trigger the warning); future Node majors may turn
+        // the deprecation into a hard error.
+        const [runCommand, runArgs] = useShell
+            ? [`${command} ${shellQuote(args).join(' ')}`, []]
+            : [command, args];
+        const child = spawn(runCommand, runArgs, {
             env: options.env,
             stdio: 'inherit',
             shell: useShell,
@@ -171,7 +179,7 @@ function runProcess(command, args, options = {}) {
  * `--latest` is required: `pnpm add` writes a caret range into the profile
  * manifest, and a plain `pnpm update` stays inside that range — with this
  * project's minor-per-release cadence the TUI would restart unchanged while
- * reporting success. The restart carries `DSH_CC_UPDATED_FROM` so the new
+ * reporting success. The restart carries `DSH_TUI_UPDATED_FROM` so the new
  * process can warn when the version did not actually move (e.g. a mirror
  * registry still serving the old `latest`).
  *
@@ -195,6 +203,9 @@ export async function updateTuiAndRestart(sessionId, profile) {
     const restartCode = await runProcess(process.execPath, [...process.execArgv, ...process.argv.slice(1)], {
         env: {
             ...process.env,
+            // Dual-write the resume contract (issue #120): the cordis layer of a
+            // still-old TUI build reads only DSH_CC_RESUME_SESSION.
+            DSH_TUI_RESUME_SESSION: sessionId,
             DSH_CC_RESUME_SESSION: sessionId,
             [UPDATED_FROM_ENV]: installedTuiVersion() ?? '',
         },