@askdkc/dsh-cli 0.11.3

package/lib/types/sessionPins.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Pinned sessions for the `/resume` browser, kept at
+ * `~/.dsh-tui/session-pins.json` (a JSON array of session ids) so the pins
+ * survive restarts.
+ *
+ * The pin key is the DSH session id (`SessionSummary.id`, from the session
+ * header): stable across log revisions. Missing sessions are tolerated — the
+ * browser filters pins against the live listing instead of rewriting them.
+ */
+/**
+ * The persisted pin set, or empty when unset or unreadable.
+ * @param dir - Prefs directory (injectable for tests).
+ */
+export declare function readSessionPins(dir?: string): ReadonlySet<string>;
+/**
+ * Persist a complete pin set with a private, atomic replacement.
+ * @param ids - Every pinned session id, in any order.
+ * @param dir - Prefs directory (injectable for tests).
+ * @returns True when the file was replaced, false when locking/writing failed.
+ */
+export declare function writeSessionPins(ids: Iterable<string>, dir?: string): boolean;
+export type SessionPinMutationResult = {
+    readonly ok: boolean;
+    readonly pins: ReadonlySet<string>;
+};
+/**
+ * Update one pin under a cross-process lock. The file is re-read only after
+ * the lock is held, so two live TUI instances do not overwrite each other's
+ * unrelated pin changes. Malformed input is preserved and reported as failure
+ * instead of being silently replaced with an empty set.
+ */
+export declare function setSessionPinned(id: string, pinned: boolean, dir?: string): SessionPinMutationResult;
+//# sourceMappingURL=sessionPins.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sessionPins.d.ts","sourceRoot":"","sources":["../../src/sessionPins.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAwHH;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAiB,GAAG,WAAW,CAAC,MAAM,CAAC,CAM3E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,GAAG,GAAE,MAAiB,GAAG,OAAO,CAQvF;AAED,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CACnC,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,OAAO,EACf,GAAG,GAAE,MAAiB,GACrB,wBAAwB,CAmB1B"}

package/lib/types/sessionPins.js

@@ -0,0 +1,181 @@
+/**
+ * Pinned sessions for the `/resume` browser, kept at
+ * `~/.dsh-tui/session-pins.json` (a JSON array of session ids) so the pins
+ * survive restarts.
+ *
+ * The pin key is the DSH session id (`SessionSummary.id`, from the session
+ * header): stable across log revisions. Missing sessions are tolerated — the
+ * browser filters pins against the live listing instead of rewriting them.
+ */
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { DATA_DIR } from './utils/paths.js';
+const PINS_FILE = 'session-pins.json';
+const LOCK_FILE = 'session-pins.lock';
+const STALE_LOCK_MS = 30_000;
+let temporarySequence = 0;
+function hasCode(error, code) {
+    return typeof error === 'object' && error !== null && error.code === code;
+}
+/** Parse the persisted array. Missing is empty; malformed data is an error. */
+function readPinsStrict(dir) {
+    let raw;
+    try {
+        raw = readFileSync(join(dir, PINS_FILE), 'utf8');
+    }
+    catch (error) {
+        if (hasCode(error, 'ENOENT'))
+            return new Set();
+        throw error;
+    }
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed))
+        throw new TypeError('session-pins.json must contain an array');
+    return new Set(parsed.filter((id) => typeof id === 'string' && id.length > 0));
+}
+/** Atomically replace the preference while preserving private file modes. */
+function writePinsAtomic(ids, dir) {
+    const target = join(dir, PINS_FILE);
+    const temporary = join(dir, `${PINS_FILE}.${process.pid}.${Date.now()}.${temporarySequence++}.tmp`);
+    try {
+        const normalized = [...new Set([...ids].filter(id => id.length > 0))];
+        writeFileSync(temporary, JSON.stringify(normalized, null, 2), {
+            encoding: 'utf8',
+            flag: 'wx',
+            mode: 0o600,
+        });
+        renameSync(temporary, target);
+        return true;
+    }
+    catch {
+        try {
+            rmSync(temporary, { force: true });
+        }
+        catch {
+            // The old preference is still intact; nothing else is safe to do.
+        }
+        return false;
+    }
+}
+/**
+ * Take a short cross-process lock around read-modify-write. A crashed process
+ * can leave the tiny lock file behind, so one stale lock may be reclaimed.
+ */
+function acquirePinsLock(dir) {
+    try {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    catch {
+        return null;
+    }
+    const lockPath = join(dir, LOCK_FILE);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        let fd;
+        try {
+            fd = openSync(lockPath, 'wx', 0o600);
+        }
+        catch (error) {
+            if (!hasCode(error, 'EEXIST') || attempt > 0)
+                return null;
+            try {
+                if (Date.now() - statSync(lockPath).mtimeMs <= STALE_LOCK_MS)
+                    return null;
+                rmSync(lockPath, { force: true });
+            }
+            catch {
+                return null;
+            }
+            continue;
+        }
+        try {
+            writeFileSync(fd, `${process.pid}\n`, 'utf8');
+            return fd;
+        }
+        catch {
+            try {
+                closeSync(fd);
+            }
+            catch { }
+            try {
+                rmSync(lockPath, { force: true });
+            }
+            catch { }
+            return null;
+        }
+    }
+    return null;
+}
+function releasePinsLock(fd, dir) {
+    try {
+        closeSync(fd);
+    }
+    catch {
+        // Continue to remove the lock name even if close already happened.
+    }
+    try {
+        rmSync(join(dir, LOCK_FILE), { force: true });
+    }
+    catch {
+        // A stale lock is recoverable on the next mutation.
+    }
+}
+/**
+ * The persisted pin set, or empty when unset or unreadable.
+ * @param dir - Prefs directory (injectable for tests).
+ */
+export function readSessionPins(dir = DATA_DIR) {
+    try {
+        return readPinsStrict(dir);
+    }
+    catch {
+        return new Set();
+    }
+}
+/**
+ * Persist a complete pin set with a private, atomic replacement.
+ * @param ids - Every pinned session id, in any order.
+ * @param dir - Prefs directory (injectable for tests).
+ * @returns True when the file was replaced, false when locking/writing failed.
+ */
+export function writeSessionPins(ids, dir = DATA_DIR) {
+    const lock = acquirePinsLock(dir);
+    if (lock === null)
+        return false;
+    try {
+        return writePinsAtomic(ids, dir);
+    }
+    finally {
+        releasePinsLock(lock, dir);
+    }
+}
+/**
+ * Update one pin under a cross-process lock. The file is re-read only after
+ * the lock is held, so two live TUI instances do not overwrite each other's
+ * unrelated pin changes. Malformed input is preserved and reported as failure
+ * instead of being silently replaced with an empty set.
+ */
+export function setSessionPinned(id, pinned, dir = DATA_DIR) {
+    const fallback = readSessionPins(dir);
+    const lock = acquirePinsLock(dir);
+    if (lock === null)
+        return { ok: false, pins: fallback };
+    try {
+        let current;
+        try {
+            current = readPinsStrict(dir);
+        }
+        catch {
+            return { ok: false, pins: fallback };
+        }
+        if (pinned)
+            current.add(id);
+        else
+            current.delete(id);
+        return writePinsAtomic(current, dir)
+            ? { ok: true, pins: current }
+            : { ok: false, pins: fallback };
+    }
+    finally {
+        releasePinsLock(lock, dir);
+    }
+}

package/lib/types/sessions/format.d.ts

@@ -0,0 +1,125 @@
+import type { SessionKind, TitleSource } from '../dsh-adapter/sessions/index.js';
+import type { Theme } from '../theme.js';
+/**
+ * Truncate to a terminal DISPLAY width, CJK-aware (a wide character costs two
+ * columns).
+ *
+ * Used wherever the cut has to be exact: Ink's own `wrap="truncate"` appends
+ * its ellipsis as soon as content is as wide as its box rather than wider,
+ * which silently eats the last character of a row laid out at its natural
+ * width — and a row that then reflows pushes every row below it down.
+ *
+ * @param text - Plain text, no ANSI.
+ * @param maxWidth - Column budget, ellipsis included.
+ * @returns `text` when it fits, otherwise a cut ending in `…`.
+ */
+export declare function truncateWidth(text: string, maxWidth: number): string;
+/** A row laid out as `left`, blank columns, then `right`. */
+export interface SpreadRow {
+    /** The left-hand segment, cut only if it alone exceeds the row. */
+    readonly left: string;
+    /** Blank columns between the two segments; at least one. */
+    readonly gap: number;
+    /** The right-hand segment, cut to whatever room the left one left. */
+    readonly right: string;
+}
+/**
+ * Lay out one row with its two ends pushed apart.
+ *
+ * Measured in COLUMNS, which is the whole reason this is a function rather
+ * than three expressions at the call site. Every string it receives is
+ * localized, and in Chinese a character is two columns wide — arithmetic on
+ * `.length` overstates the gap by the width of the text itself, so the row
+ * overflows and the terminal either wraps it (shifting every region below it
+ * down a line) or clips it (silently eating the right-hand segment). Both
+ * failures are invisible to an English-only test.
+ *
+ * The invariant, which the regression checks exhaustively: the assembled row
+ * is never wider than `columns`.
+ *
+ * @param left - Text pinned to the start of the row.
+ * @param right - Text pinned to the end, truncated when it will not fit.
+ * @param columns - Total width available.
+ */
+export declare function spreadRow(left: string, right: string, columns: number): SpreadRow;
+/**
+ * Keep the END of a string within a display width, CJK-aware.
+ *
+ * What a single-line editor does: the caret lives at the end, so that is the
+ * part worth showing. Used where text the user is typing has to stay on ONE
+ * row — a wrapped input row steals a line from the list and can push the row
+ * below it off the bottom of the screen.
+ *
+ * @param text - Plain text, no ANSI.
+ * @param maxWidth - Column budget, leading ellipsis included.
+ * @returns `text` when it fits, otherwise `…` followed by its tail.
+ */
+export declare function tailWidth(text: string, maxWidth: number): string;
+/**
+ * Elapsed time as a person would say it: `just now`, `9 hours ago`, and an
+ * absolute date once "ago" stops being useful.
+ *
+ * The cut to an absolute date is at a week rather than a month because that is
+ * roughly where a relative offset stops locating anything — "23 days ago" is a
+ * number to be decoded, `Mar 3` is a memory.
+ *
+ * @param at - Epoch ms of the moment being described.
+ * @param now - Epoch ms of the present, injectable so the formatter is a pure
+ *   function and its regression does not depend on a clock.
+ */
+export declare function formatWhen(at: number, now: number): string;
+/**
+ * Absolute local wall-clock: `2026-09-01 14:30:22`. Companion to
+ * formatWhen's relative phrasing — the precise answer for telling three
+ * similar-looking sessions apart in a hover tooltip.
+ */
+export declare function formatAbsolute(at: number): string;
+/**
+ * Byte size at the precision the number is worth: `812 B`, `142.9 KB`,
+ * `4.2 MB`. One decimal from kilobytes up, because the digit distinguishes a
+ * short exchange from a long one and a second would not.
+ */
+export declare function formatBytes(bytes: number | undefined): string | undefined;
+/**
+ * Marker for a row's kind, or undefined for an ordinary conversation.
+ *
+ * Only the exceptional kinds are marked. A badge on every row would cost a
+ * column of width and teach nothing — what a reader needs to see at a glance
+ * is which rows are *not* the thing they came for.
+ */
+export declare function kindMark(kind: SessionKind): {
+    glyph: string;
+    color: keyof Theme;
+} | undefined;
+/**
+ * Wrap to a display width, CJK-aware.
+ *
+ * Greedy, breaking on a space when one is available in the line just filled
+ * and mid-character when it is not — which is the correct behaviour for CJK,
+ * where there are no spaces to break on and a word-only wrapper would emit one
+ * enormous unbreakable line. Newlines in the input are honoured.
+ *
+ * @param text - Plain text, no ANSI.
+ * @param width - Column budget per line.
+ * @returns The wrapped lines, never empty for non-empty input.
+ */
+export declare function wrapWidth(text: string, width: number): string[];
+/** Human name of a session kind, for the preview pane's header. */
+export declare function kindLabel(kind: SessionKind): string;
+/**
+ * Colour for a title, by how much is actually known about it.
+ *
+ * A title the user chose is stated plainly; one a model generated reads the
+ * same, because it is a real title; a first-prompt excerpt is dimmer, because
+ * it is the session speaking rather than a name; a directory basename is
+ * dimmest of all, because it says only "nothing here was readable".
+ */
+export declare function titleColor(source: TitleSource, focused: boolean): keyof Theme;
+/**
+ * Project label for a group header: the working directory, with `$HOME`
+ * collapsed to `~` so the eye lands on the part that differs.
+ */
+export declare function formatProject(cwd: string, home: string): string;
+/** Compact final path segment for the working-directory menu. */
+export declare function projectName(cwd: string): string;
+//# sourceMappingURL=format.d.ts.map

package/lib/types/sessions/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/sessions/format.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAA;AAChF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAExC;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAYpE;AAED,6DAA6D;AAC7D,MAAM,WAAW,SAAS;IACxB,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAajF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAchE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAc1D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAIjD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAKzE;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,KAAK,CAAA;CAAE,GAAG,SAAS,CAI7F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CA4B/D;AAED,mEAAmE;AACnE,wBAAgB,SAAS,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAInD;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,KAAK,CAQ7E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAkB/D;AAED,iEAAiE;AACjE,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM/C"}

package/lib/types/sessions/format.js

@@ -0,0 +1,276 @@
+/**
+ * Session browser formatting.
+ *
+ * Presentation only, and deliberately outside the adapter: these are choices
+ * about a terminal's width and a reader's eye, not about what a session log
+ * means.
+ *
+ * @module dsh-cli/sessions/format
+ */
+import { t } from '../i18n.js';
+import { stringWidth } from '../ink/stringWidth.js';
+/**
+ * Truncate to a terminal DISPLAY width, CJK-aware (a wide character costs two
+ * columns).
+ *
+ * Used wherever the cut has to be exact: Ink's own `wrap="truncate"` appends
+ * its ellipsis as soon as content is as wide as its box rather than wider,
+ * which silently eats the last character of a row laid out at its natural
+ * width — and a row that then reflows pushes every row below it down.
+ *
+ * @param text - Plain text, no ANSI.
+ * @param maxWidth - Column budget, ellipsis included.
+ * @returns `text` when it fits, otherwise a cut ending in `…`.
+ */
+export function truncateWidth(text, maxWidth) {
+    if (maxWidth <= 0)
+        return '';
+    if (stringWidth(text) <= maxWidth)
+        return text;
+    let width = 0;
+    let out = '';
+    for (const char of text) {
+        const charWidth = stringWidth(char);
+        if (width + charWidth > maxWidth - 1)
+            break;
+        width += charWidth;
+        out += char;
+    }
+    return `${out}…`;
+}
+/**
+ * Lay out one row with its two ends pushed apart.
+ *
+ * Measured in COLUMNS, which is the whole reason this is a function rather
+ * than three expressions at the call site. Every string it receives is
+ * localized, and in Chinese a character is two columns wide — arithmetic on
+ * `.length` overstates the gap by the width of the text itself, so the row
+ * overflows and the terminal either wraps it (shifting every region below it
+ * down a line) or clips it (silently eating the right-hand segment). Both
+ * failures are invisible to an English-only test.
+ *
+ * The invariant, which the regression checks exhaustively: the assembled row
+ * is never wider than `columns`.
+ *
+ * @param left - Text pinned to the start of the row.
+ * @param right - Text pinned to the end, truncated when it will not fit.
+ * @param columns - Total width available.
+ */
+export function spreadRow(left, right, columns) {
+    if (columns <= 0)
+        return { left: '', gap: 0, right: '' };
+    // One column of separation is always reserved, so the two segments can never
+    // run together into an unreadable single word — which means the left segment
+    // yields too when the row is narrower than it is.
+    const fittedLeft = truncateWidth(left, Math.max(0, columns - 1));
+    const leftWidth = stringWidth(fittedLeft);
+    const fittedRight = truncateWidth(right, Math.max(0, columns - leftWidth - 1));
+    return {
+        left: fittedLeft,
+        gap: Math.max(1, columns - leftWidth - stringWidth(fittedRight)),
+        right: fittedRight,
+    };
+}
+/**
+ * Keep the END of a string within a display width, CJK-aware.
+ *
+ * What a single-line editor does: the caret lives at the end, so that is the
+ * part worth showing. Used where text the user is typing has to stay on ONE
+ * row — a wrapped input row steals a line from the list and can push the row
+ * below it off the bottom of the screen.
+ *
+ * @param text - Plain text, no ANSI.
+ * @param maxWidth - Column budget, leading ellipsis included.
+ * @returns `text` when it fits, otherwise `…` followed by its tail.
+ */
+export function tailWidth(text, maxWidth) {
+    if (maxWidth <= 0)
+        return '';
+    if (stringWidth(text) <= maxWidth)
+        return text;
+    const characters = [...text];
+    let width = 0;
+    let out = '';
+    for (let at = characters.length - 1; at >= 0; at--) {
+        const character = characters[at];
+        const characterWidth = stringWidth(character);
+        if (width + characterWidth > maxWidth - 1)
+            break;
+        width += characterWidth;
+        out = character + out;
+    }
+    return `…${out}`;
+}
+/**
+ * Elapsed time as a person would say it: `just now`, `9 hours ago`, and an
+ * absolute date once "ago" stops being useful.
+ *
+ * The cut to an absolute date is at a week rather than a month because that is
+ * roughly where a relative offset stops locating anything — "23 days ago" is a
+ * number to be decoded, `Mar 3` is a memory.
+ *
+ * @param at - Epoch ms of the moment being described.
+ * @param now - Epoch ms of the present, injectable so the formatter is a pure
+ *   function and its regression does not depend on a clock.
+ */
+export function formatWhen(at, now) {
+    const seconds = Math.max(0, Math.round((now - at) / 1000));
+    if (seconds < 45)
+        return t('session-when-now');
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 60)
+        return t('session-when-minutes', { n: minutes });
+    const hours = Math.round(minutes / 60);
+    if (hours < 24)
+        return t('session-when-hours', { n: hours });
+    const days = Math.round(hours / 24);
+    if (days <= 7)
+        return t('session-when-days', { n: days });
+    const date = new Date(at);
+    return t('session-when-date', {
+        month: String(date.getMonth() + 1),
+        day: String(date.getDate()),
+    });
+}
+/**
+ * Absolute local wall-clock: `2026-09-01 14:30:22`. Companion to
+ * formatWhen's relative phrasing — the precise answer for telling three
+ * similar-looking sessions apart in a hover tooltip.
+ */
+export function formatAbsolute(at) {
+    const date = new Date(at);
+    const pad = (value) => String(value).padStart(2, '0');
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+/**
+ * Byte size at the precision the number is worth: `812 B`, `142.9 KB`,
+ * `4.2 MB`. One decimal from kilobytes up, because the digit distinguishes a
+ * short exchange from a long one and a second would not.
+ */
+export function formatBytes(bytes) {
+    if (bytes === undefined || !Number.isFinite(bytes) || bytes < 0)
+        return undefined;
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/**
+ * Marker for a row's kind, or undefined for an ordinary conversation.
+ *
+ * Only the exceptional kinds are marked. A badge on every row would cost a
+ * column of width and teach nothing — what a reader needs to see at a glance
+ * is which rows are *not* the thing they came for.
+ */
+export function kindMark(kind) {
+    if (kind.kind === 'subagent')
+        return { glyph: '⑂', color: 'autoAccept' };
+    if (kind.kind === 'fork')
+        return { glyph: '⑃', color: 'planMode' };
+    return undefined;
+}
+/**
+ * Wrap to a display width, CJK-aware.
+ *
+ * Greedy, breaking on a space when one is available in the line just filled
+ * and mid-character when it is not — which is the correct behaviour for CJK,
+ * where there are no spaces to break on and a word-only wrapper would emit one
+ * enormous unbreakable line. Newlines in the input are honoured.
+ *
+ * @param text - Plain text, no ANSI.
+ * @param width - Column budget per line.
+ * @returns The wrapped lines, never empty for non-empty input.
+ */
+export function wrapWidth(text, width) {
+    if (width <= 0)
+        return [];
+    const lines = [];
+    for (const paragraph of text.split('\n')) {
+        let line = '';
+        let used = 0;
+        for (const char of paragraph) {
+            const charWidth = stringWidth(char);
+            if (used + charWidth > width) {
+                // Prefer a word boundary, but only when it does not throw away most
+                // of the line — a single long token must still make progress.
+                const breakAt = line.lastIndexOf(' ');
+                if (breakAt > width / 2) {
+                    lines.push(line.slice(0, breakAt));
+                    line = line.slice(breakAt + 1);
+                    used = stringWidth(line);
+                }
+                else {
+                    lines.push(line);
+                    line = '';
+                    used = 0;
+                }
+            }
+            line += char;
+            used += charWidth;
+        }
+        lines.push(line);
+    }
+    return lines;
+}
+/** Human name of a session kind, for the preview pane's header. */
+export function kindLabel(kind) {
+    if (kind.kind === 'subagent')
+        return t('session-kind-subagent');
+    if (kind.kind === 'fork')
+        return t('session-kind-fork');
+    return t('session-kind-root');
+}
+/**
+ * Colour for a title, by how much is actually known about it.
+ *
+ * A title the user chose is stated plainly; one a model generated reads the
+ * same, because it is a real title; a first-prompt excerpt is dimmer, because
+ * it is the session speaking rather than a name; a directory basename is
+ * dimmest of all, because it says only "nothing here was readable".
+ */
+export function titleColor(source, focused) {
+    // Selection is green (see SessionListRow): blue is reserved for the pointer
+    // hover prompt, so the row under the cursor cannot look like the row the
+    // pointer is merely passing over.
+    if (focused)
+        return 'success';
+    if (source === 'fallback')
+        return 'subtle';
+    if (source === 'prompt')
+        return 'inactive';
+    return 'text';
+}
+/**
+ * Project label for a group header: the working directory, with `$HOME`
+ * collapsed to `~` so the eye lands on the part that differs.
+ */
+export function formatProject(cwd, home) {
+    if (cwd.length === 0)
+        return t('session-project-unknown');
+    const normalize = (value) => {
+        const normalized = value.replace(/\\/g, '/');
+        return normalized.length > 1 ? normalized.replace(/\/+$/, '') : normalized;
+    };
+    const normalized = normalize(cwd);
+    const base = normalize(home);
+    const comparableCwd = process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+    const comparableBase = process.platform === 'win32' ? base.toLowerCase() : base;
+    const isBelowHome = comparableBase === '/'
+        ? comparableCwd.startsWith('/')
+        : comparableCwd.startsWith(`${comparableBase}/`);
+    if (base.length > 0 && (comparableCwd === comparableBase || isBelowHome)) {
+        const suffix = normalized.slice(base.length);
+        return suffix.length === 0 ? '~' : `~${suffix.startsWith('/') ? suffix : `/${suffix}`}`;
+    }
+    return normalized;
+}
+/** Compact final path segment for the working-directory menu. */
+export function projectName(cwd) {
+    if (cwd.length === 0)
+        return t('session-project-unknown');
+    const slashed = cwd.replace(/\\/g, '/');
+    const normalized = /^\/+$/u.test(slashed) ? '/' : slashed.replace(/\/+$/, '');
+    const name = normalized.split('/').filter(Boolean).at(-1);
+    return name ?? normalized;
+}

package/lib/types/sessions/resumeFailure.d.ts

@@ -0,0 +1,38 @@
+/**
+ * One wording for "why a session could not be mounted".
+ *
+ * Four surfaces can refuse a mount — the supervisor, the session browser, the
+ * workspace home screen and the transcript itself — and each used to spell the
+ * same failures out on its own. That is how `/resume` and `/agentview` ended
+ * up telling the user different things about the same refusal, and it is why a
+ * newly added reason (the cross-process occupancy case) would have been
+ * silently mis-reported as a generic failure on whichever surface was missed.
+ *
+ * The mapping is pure and total: it takes the adapter's discriminated result
+ * and returns the sentence to show, or `undefined` for the outcomes that need
+ * no words. The `cancelled` case is deliberately silent — the user (or a rival
+ * switch) asked for it, so there is nothing to explain.
+ *
+ * @module dsh-cli/sessions/resumeFailure
+ */
+import type { ResumeResult } from '../adapter/ports/channel-view.js';
+import type { MountFailure } from '../sessionMounts.js';
+/**
+ * The message for a failed mount, or undefined when it should stay silent.
+ * @param result - The adapter's mount outcome.
+ * @returns The user-facing sentence, or undefined for `cancelled`.
+ */
+export declare function resumeFailureText(result: ResumeResult): string | undefined;
+/**
+ * The sentence for a ledger refusal that did NOT find a holder.
+ *
+ * A refusal to CHECK is not a refusal by a peer, so it must not borrow the
+ * "another terminal holds it" wording — that would invent a terminal. The
+ * `occupied` case is here too because it is a {@link MountFailure} and its
+ * sentence already exists; {@link resumeFailureText} reaches the same key from
+ * the adapter's own result.
+ * @param failure - Why the session could not be claimed.
+ * @returns The user-facing sentence.
+ */
+export declare function mountFailureText(failure: MountFailure): string;
+//# sourceMappingURL=resumeFailure.d.ts.map

package/lib/types/sessions/resumeFailure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resumeFailure.d.ts","sourceRoot":"","sources":["../../../src/sessions/resumeFailure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAA;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAGvD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,GAAG,SAAS,CAc1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAO9D"}