@aiwayds/dsh-tui-pi 0.28.0 → 1.0.0

package/lib/log-repair.js

@@ -0,0 +1,273 @@
+/**
+ * Corrupted-resume-log repair orchestration — the /resume safety net.
+ *
+ * When a persisted session's log was forked by a historical double-writer
+ * (two dsh processes appending to one jsonl), the loader refuses it with
+ * "corrupt session log: seq gap …" and /resume dead-ends. The offline
+ * surgery itself lives in scripts/repair-session-log.mjs (deterministic
+ * dedupe + dense renumbering; the original is NEVER modified there). This
+ * module is the TUI-free bridge around it: it runs the script, verifies the
+ * result, and — only after an explicit user confirmation upstream — swaps
+ * the repaired copy in beside a kept backup, under the single-writer lock.
+ *
+ * Contract of the script (its own header is authoritative):
+ *   exit 0 → the log is CLEAN (nothing written), or — with --apply — a
+ *            `<stem>.repaired.jsonl[.zstd]` artifact was written BESIDE the
+ *            original (the CLEAN verdict line distinguishes the two);
+ *   exit 3 → corrupt diagnosed, nothing written (dry-run only by contract);
+ *   exit 2 → usage/environment error (missing zstd, torn lines without
+ *            --skip-bad-lines, …).
+ *
+ * Safety invariants (all enforced here, testable without a terminal):
+ * - The original log is never edited in place — swapping moves it aside to
+ *   `<name>.corrupt-bak` first and only then renames the verified repaired
+ *   copy over the canonical name.
+ * - A repaired copy that does not itself verify CLEAN is never swapped in.
+ * - The writer lock beside the log (<sessionDir>/writer.lock, same file the
+ *   cold arms and the feishu guard compete on) is claimed for the whole
+ *   apply→verify→swap window and always released, success or not.
+ */
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, renameSync, statSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { SESSION_LOG_FILE_NAMES } from "./retention.js";
+import { acquireWriterLock, projectKeyFor, releaseOwnedWriterLock, } from "./writer-lock.js";
+/** The repair script rides the published package (`files` includes scripts/). */
+export function repairScriptPath() {
+    return new URL('../scripts/repair-session-log.mjs', import.meta.url).pathname;
+}
+/** Hard wall-clock budget for one script invocation (big logs still finish; a hung zstd must not freeze /resume). */
+export const REPAIR_TIMEOUT_MS = 120_000;
+/**
+ * The path the repair script writes its artifact to (mirrors the script's
+ * own `<stem>.repaired.jsonl[.zstd]` naming, stem = name minus the jsonl[.zstd]
+ * suffix). Exported so tests and callers can predict the artifact location.
+ */
+export function repairedArtifactPath(logPath) {
+    const isZstd = /\.jsonl\.zstd$/.test(logPath);
+    const stem = basename(logPath).replace(/\.jsonl(\.zstd)?$/, '');
+    return join(dirname(logPath), `${stem}.repaired.jsonl${isZstd ? '.zstd' : ''}`);
+}
+function firstLine(text) {
+    const line = text.split('\n').map(l => l.trim()).find(l => l !== '');
+    return line ?? '';
+}
+/**
+ * Run scripts/repair-session-log.mjs against one log. Never touches the log
+ * itself (the script cannot); classifies the outcome per the exit contract
+ * above. A missing zstd binary surfaces as the script's exit 2 — or, should
+ * the spawn itself fail with ENOENT, as a failed result with an install hint.
+ */
+export function runRepair(logPath, options = {}) {
+    const apply = options.apply ?? false;
+    const spawn = options.spawnSyncFn ?? spawnSync;
+    let proc;
+    try {
+        proc = spawn(process.execPath, [repairScriptPath(), logPath, ...(apply ? ['--apply'] : [])], { encoding: 'utf8', timeout: REPAIR_TIMEOUT_MS, maxBuffer: 1 << 26 });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { status: 'failed', detail: `cannot run the repair script: ${message}` };
+    }
+    if (proc.error !== undefined) {
+        const code = proc.error.code;
+        const hint = code === 'ENOENT' ? ' — is zstd installed and on PATH?' : '';
+        return {
+            status: 'failed',
+            detail: `cannot run the repair script: ${proc.error.message}${hint}`,
+        };
+    }
+    const out = proc.stdout ?? '';
+    const err = proc.stderr ?? '';
+    if (proc.status === 0) {
+        // Exit 0 is ambiguous by contract (CLEAN vs. repaired+written); the
+        // CLEAN verdict line disambiguates without guessing at files.
+        if (out.includes('verdict: CLEAN'))
+            return { status: 'clean' };
+        const repairedPath = repairedArtifactPath(logPath);
+        if (existsSync(repairedPath)) {
+            return { status: 'repaired', repairedPath, detail: firstLine(out) };
+        }
+        return {
+            status: 'failed',
+            detail: 'repair script exited 0 but wrote no repaired artifact beside the log',
+        };
+    }
+    if (proc.status === 3) {
+        // By the script's contract exit 3 means "corrupt, dry-run, nothing
+        // written" — with --apply this is a contract violation, but either way
+        // there is nothing to swap in, so it is a failure for our caller.
+        return {
+            status: 'failed',
+            detail: firstLine(out) || 'log is corrupt — the script diagnosed it without writing a repair',
+        };
+    }
+    return {
+        status: 'failed',
+        detail: firstLine(err) || `repair script exited ${proc.status ?? 'by signal'}`,
+    };
+}
+/**
+ * Verify one log loads clean (dry-run diagnosis, never writes). Used on the
+ * repaired artifact BEFORE it replaces the canonical log.
+ */
+export function verifyClean(logPath, options = {}) {
+    const run = runRepair(logPath, { ...options, apply: false });
+    return run.status === 'clean' ? { ok: true } : { ok: false, detail: run.detail };
+}
+/**
+ * Swap the verified repaired copy in over the canonical log name: the
+ * original moves aside to `<name>.corrupt-bak` (suffixed with the epoch
+ * millisecond when that name is taken — never overwritten), the repaired
+ * copy takes its place with owner-only permissions, matching the store's
+ * private-file hygiene. Synchronous on purpose: the swap window sits under
+ * the writer lock and must be a tight rename-rename pair. A failed swap-in
+ * restores the original best-effort (mirroring the feishu surface) before
+ * rethrowing, so the session is never stranded without its canonical log.
+ */
+export function swapRepaired(logPath, repairedPath, options = {}) {
+    let backupPath = `${logPath}.corrupt-bak`;
+    try {
+        statSync(backupPath);
+        backupPath = `${backupPath}.${Date.now()}`;
+    }
+    catch {
+        // Free — the plain .corrupt-bak name is ours.
+    }
+    renameSync(logPath, backupPath);
+    try {
+        renameSync(repairedPath, logPath);
+    }
+    catch (error) {
+        // Best-effort restore first — the canonical name must not stay missing
+        // with the original parked in the backup; the rethrow is the signal.
+        try {
+            renameSync(backupPath, logPath);
+        }
+        catch {
+            // Nothing further is recoverable here; the caller reports the swap
+            // failure and the .corrupt-bak copy still holds the original.
+        }
+        throw error;
+    }
+    try {
+        ;
+        (options.chmodFn ?? chmodSync)(logPath, 0o600);
+    }
+    catch {
+        // Permissions are store hygiene, not log integrity: the swap already
+        // succeeded, so a chmod failure never flips the outcome. A later
+        // successful repair (or any manual chmod) fixes the mode.
+    }
+    return { backupPath };
+}
+/**
+ * End-to-end repair of one session log, under the single-writer lock beside
+ * it: claim → apply → verify the repaired copy → swap → release. ANY failure
+ * leaves the canonical log untouched, releases the lock, and reports
+ * {kind:'failed'}; only a verified artifact is ever swapped in. The lock dir
+ * is the log's own directory — the same `<sessionDir>/writer.lock` the cold
+ * arms and the feishu guard compete on.
+ */
+export async function repairSessionLog(logPath, options = {}) {
+    const dir = dirname(logPath);
+    let claim;
+    try {
+        claim = await acquireWriterLock(dir);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { kind: 'failed', detail: `cannot claim the writer lock: ${message}` };
+    }
+    if (!claim.ok)
+        return { kind: 'locked', holder: claim.holder };
+    try {
+        const run = runRepair(logPath, { apply: true, spawnSyncFn: options.spawnSyncFn });
+        if (run.status === 'failed')
+            return { kind: 'failed', detail: run.detail };
+        if (run.status === 'clean')
+            return { kind: 'clean' };
+        const verdict = verifyClean(run.repairedPath, options);
+        if (!verdict.ok) {
+            return {
+                kind: 'failed',
+                detail: `the repaired copy still fails verification: ${verdict.detail}`,
+            };
+        }
+        return {
+            kind: 'repaired',
+            backupPath: swapRepaired(logPath, run.repairedPath, options).backupPath,
+        };
+    }
+    catch (error) {
+        // swapRepaired restored the original best-effort before rethrowing; map
+        // the residue to a plain failure so no exception ever escapes toward the
+        // command dispatch — this module's contract is results, not throws.
+        const message = error instanceof Error ? error.message : String(error);
+        return { kind: 'failed', detail: `swap failed: ${message}` };
+    }
+    finally {
+        await releaseOwnedWriterLock(dir);
+    }
+}
+/**
+ * The /resume corrupt-log fingerprint: the loader's "corrupt session log:
+ * seq gap …" refusal, plus the raw-decompression twin ("corrupt zstandard
+ * log"). Case-insensitive; anything else (locked session, missing
+ * persistence, network) must NOT route into the repair flow.
+ */
+const CORRUPT_LOG_PATTERN = /corrupt .*(session|zstandard) log/i;
+export function isCorruptLogError(message) {
+    return CORRUPT_LOG_PATTERN.test(message);
+}
+/**
+ * User-facing notice for a repair attempt that did NOT swap anything;
+ * undefined when the flow should proceed to resume ('repaired' | 'clean').
+ * Pure so the wording is testable without a terminal (English-only).
+ */
+export function repairFailureNotice(result) {
+    if (result.kind === 'locked') {
+        return `session is driven by pid ${result.holder.pid} — close it on the other side first`;
+    }
+    if (result.kind === 'failed') {
+        return `repair failed: ${result.detail} — log untouched`;
+    }
+    return undefined;
+}
+/**
+ * Locate one session's canonical log file on disk the same way the
+ * single-writer guard derives it: `<root>/<projectKeyFor(cwd)>/<sessionId>/<name>`,
+ * with the cwd taken from the persisted header list (the log lives under
+ * THAT project key). Best-effort: no header, no cwd, or no log file under
+ * the derived dir yields undefined — the caller reports a failure instead
+ * of repairing a decoy. When both suffixes coexist (a kept raw copy beside
+ * the compressed log) the compressed name wins: it is what the writer
+ * appends to and what the loader reads.
+ */
+export async function locateSessionLog(persistence, sessionId, root) {
+    let cwd;
+    try {
+        const stored = (await persistence?.list?.().catch(() => [])) ?? [];
+        const header = stored.find(candidate => String(candidate.id) === sessionId);
+        if (typeof header?.cwd === 'string' && header.cwd !== '')
+            cwd = header.cwd;
+    }
+    catch {
+        return undefined;
+    }
+    if (cwd === undefined)
+        return undefined;
+    const dir = join(root, projectKeyFor(cwd), sessionId);
+    for (const name of SESSION_LOG_FILE_NAMES.slice().reverse()) {
+        const file = join(dir, name);
+        try {
+            statSync(file);
+            return file;
+        }
+        catch {
+            // Not this suffix — try the next one.
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=log-repair.js.map

package/lib/log-repair.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-repair.js","sourceRoot":"","sources":["../src/log-repair.ts"],"names":[],"mappings":"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"}

package/lib/remote-tail.d.ts

@@ -0,0 +1,49 @@
+/**
+ * RemoteSessionTail — a READ-ONLY view over a session log that another
+ * dsh PROCESS is driving. Firehose events do not cross the process
+ * boundary, so a surface refusing to fork the log (single-writer guard)
+ * can still satisfy "both ends eventually show the final reply" by
+ * watching persisted bytes: poll-decode the whole jsonl.zstd (frames are
+ * independent concatenations, so full decode is append-correct), and emit
+ * only the durable suffix rows that appeared since the previous tick.
+ *
+ * Display contract (deliberately lossy): streaming deltas are skipped;
+ * durable rows only — user/message, assistant/message (the FINAL LLM text),
+ * tool/call + tool/result, plus turn/start|end so the viewer can
+ * synthesize a working/idle indicator from the driver's lifecycle.
+ * Latency is the poll interval; detail may be coarser than the driving
+ * surface's live view — but every turn's final assistant message arrives.
+ */
+export interface RemoteTailEvent {
+    type?: string;
+    seq?: number;
+}
+export interface RemoteTailCallbacks {
+    /** New durable events, in log-append order (possibly empty per tick). */
+    onEvents(events: RemoteTailEvent[]): void;
+    /** Decode failure tick — transient IO hiccups are non-fatal noise. */
+    onError?(error: unknown): void;
+}
+export interface RemoteTailOptions {
+    /** Poll cadence; defaults to 2s (cross-process latency is accepted). */
+    intervalMs?: number;
+    /** Decoder seam — tests substitute a pure function; default shells zstd. */
+    decode?(file: string): Promise<string>;
+}
+export declare class RemoteSessionTail {
+    private timer;
+    private ticking;
+    /** Rows already emitted — append-only watermark across ticks. */
+    private seenRows;
+    private readonly file;
+    private readonly callbacks;
+    private readonly options;
+    constructor(file: string, callbacks: RemoteTailCallbacks, options?: RemoteTailOptions);
+    start(): void;
+    stop(): void;
+    /** Force one poll immediately — the deterministic backfill entry point. */
+    tickOnce(): Promise<void>;
+    /** Where the watched log lives — tests assert on it. */
+    getWatchedFile(): string;
+    private tick;
+}

package/lib/remote-tail.js

@@ -0,0 +1,114 @@
+/**
+ * RemoteSessionTail — a READ-ONLY view over a session log that another
+ * dsh PROCESS is driving. Firehose events do not cross the process
+ * boundary, so a surface refusing to fork the log (single-writer guard)
+ * can still satisfy "both ends eventually show the final reply" by
+ * watching persisted bytes: poll-decode the whole jsonl.zstd (frames are
+ * independent concatenations, so full decode is append-correct), and emit
+ * only the durable suffix rows that appeared since the previous tick.
+ *
+ * Display contract (deliberately lossy): streaming deltas are skipped;
+ * durable rows only — user/message, assistant/message (the FINAL LLM text),
+ * tool/call + tool/result, plus turn/start|end so the viewer can
+ * synthesize a working/idle indicator from the driver's lifecycle.
+ * Latency is the poll interval; detail may be coarser than the driving
+ * surface's live view — but every turn's final assistant message arrives.
+ */
+import { execFile } from 'node:child_process';
+import { join } from 'node:path';
+const TURN_START = 'turn/start';
+const TURN_END = 'turn/end';
+/** Durable row types rendered in a remote view, in log order — streaming
+ * deltas excluded (see module doc for the display contract). */
+const DURABLE_TYPES = new Set([
+    'user/message',
+    'assistant/message',
+    'tool/call',
+    'tool/result',
+    TURN_START,
+    TURN_END,
+]);
+function defaultDecode(file) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        execFile('zstd', ['-dc', file], { maxBuffer: 1 << 30 }, (error, stdout) => {
+            if (error !== null && error !== undefined)
+                rejectPromise(error);
+            else
+                resolvePromise(Buffer.from(stdout, 'utf8').toString('utf8'));
+        });
+    });
+}
+export class RemoteSessionTail {
+    timer;
+    ticking = false;
+    /** Rows already emitted — append-only watermark across ticks. */
+    seenRows = 0;
+    file;
+    callbacks;
+    options;
+    constructor(file, callbacks, options = {}) {
+        this.file = file;
+        this.callbacks = callbacks;
+        this.options = options;
+    }
+    start() {
+        if (this.timer !== undefined)
+            return;
+        this.timer = setInterval(() => void this.tick(), this.options.intervalMs ?? 2000);
+    }
+    stop() {
+        if (this.timer === undefined)
+            return;
+        clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    /** Force one poll immediately — the deterministic backfill entry point. */
+    tickOnce() {
+        return this.tick(true);
+    }
+    /** Where the watched log lives — tests assert on it. */
+    getWatchedFile() {
+        return join(this.file);
+    }
+    async tick(force = false) {
+        if (this.ticking)
+            return;
+        if (!force && this.timer === undefined)
+            return;
+        this.ticking = true;
+        try {
+            const decode = this.options.decode ?? defaultDecode;
+            const text = await decode(this.file);
+            const lines = text.split('\n').filter(line => line.trim() !== '');
+            // Log shrank underneath us (repair/rename) — treat as a fresh stream
+            // rather than emitting a bogus negative diff.
+            if (lines.length < this.seenRows)
+                this.seenRows = 0;
+            const fresh = [];
+            for (let i = this.seenRows; i < lines.length; i++) {
+                let value;
+                try {
+                    value = JSON.parse(lines[i]);
+                }
+                catch {
+                    continue; // torn trailing frame mid-decode — next tick re-reads it
+                }
+                if (typeof value !== 'object' || value === null)
+                    continue;
+                const event = value;
+                if (event.type !== undefined && DURABLE_TYPES.has(event.type))
+                    fresh.push(event);
+            }
+            this.seenRows = lines.length;
+            if (fresh.length > 0)
+                this.callbacks.onEvents(fresh);
+        }
+        catch (error) {
+            this.callbacks.onError?.(error);
+        }
+        finally {
+            this.ticking = false;
+        }
+    }
+}
+//# sourceMappingURL=remote-tail.js.map

package/lib/remote-tail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-tail.js","sourceRoot":"","sources":["../src/remote-tail.ts"],"names":[],"mappings":"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"}

package/lib/repair-dialog.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The /resume repair confirmation dialog — shown when a picked session's
+ * log fails to load with a corrupt-log error (src/log-repair.ts
+ * `isCorruptLogError`). Repairing rewrites user data on disk, so it is
+ * NEVER done implicitly: this dialog is the explicit confirmation gate.
+ *
+ * Two options, in the spec's button order:
+ *   1. Repair & resume — run the guarded in-place repair, then re-enter the
+ *      selected row's resume path.
+ *   2. Cancel — leave the log untouched; /resume reports the original error.
+ * ↑↓ moves the selection, `1`/`2` select directly, Enter confirms, Esc
+ * cancels — the exact keymap of the submit routing dialog (route-dialog.ts),
+ * whose pure-reducer split this file mirrors so the decision matrix stays
+ * unit-testable without a terminal. Framing/focus follow the shared overlay
+ * contract: PanelHost framing, close re-focuses the CURRENT editor instance
+ * through `restoreFocus`.
+ */
+import { type Component, type TUI } from '@earendil-works/pi-tui';
+import { type TuiTheme } from './theme/index.ts';
+/** The two choices in display order; index 0 is preselected. */
+export declare const REPAIR_CONFIRM_OPTIONS: ReadonlyArray<{
+    id: 'repair' | 'cancel';
+    title: string;
+    hint: string;
+}>;
+/** The fixed body copy (spec wording): what happened, what repair does, what is kept. */
+export declare const REPAIR_CONFIRM_MESSAGE: string;
+/** Footer hint — hardcoded like every other panel footer (English-only). */
+export declare const REPAIR_CONFIRM_FOOTER = "\u2191\u2193 select \u00B7 1/2 pick \u00B7 Enter confirm \u00B7 Esc cancel";
+/** Pure dialog state: which row is highlighted, and the terminal outcome. */
+export interface RepairConfirmState {
+    selected: number;
+    /**
+     * Set once by a terminal key: `'confirm'` (Enter on a selection) or
+     * `'cancel'` (Esc). Further input is ignored afterwards.
+     */
+    settled?: 'confirm' | 'cancel';
+}
+export declare function initialRepairConfirmState(): RepairConfirmState;
+/**
+ * Apply one raw key sequence to the dialog state. Unknown keys are no-ops;
+ * anything after a settle is ignored (single terminal outcome guard).
+ */
+export declare function updateRepairConfirm(state: RepairConfirmState, data: string): RepairConfirmState;
+/** Resolved dialog outcome: the chosen action, or undefined on cancel. */
+export declare function repairConfirmOutcome(state: RepairConfirmState): 'repair' | 'cancel' | undefined;
+/**
+ * The framed overlay component. Renders the fixed body copy plus the two
+ * option rows; every key goes through {@link updateRepairConfirm}, and the
+ * first terminal key fires `onFinish` exactly once.
+ */
+export declare class RepairConfirmPanel implements Component {
+    private readonly theme;
+    private readonly onFinish;
+    private readonly requestRenderFn;
+    private state;
+    constructor(theme: TuiTheme, onFinish: (outcome: 'repair' | 'cancel' | undefined) => void, requestRender: () => void);
+    invalidate(): void;
+    render(width: number): string[];
+    handleInput(data: string): void;
+}
+/**
+ * Open the repair confirmation dialog for one corrupt resume target.
+ * Resolves `'repair'` when the user explicitly confirmed, `'cancelled'`
+ * otherwise (Esc, or an overlay that failed to mount — treated as cancel so
+ * a half-mounted dialog can never imply consent). Closing always hands
+ * focus back through `restoreFocus` before the promise settles.
+ */
+export declare function openRepairConfirmDialog(tui: TUI, theme: TuiTheme, restoreFocus: () => void): Promise<'repair' | 'cancelled'>;