@aiwayds/dsh-tui-pi 0.28.0 → 1.0.0

package/lib/writer-lock.js

@@ -0,0 +1,206 @@
+/**
+ * Single-writer guard — a vendored, zero-dependency per-session pid-file
+ * lock, byte-for-byte the same contract the feishu plugin's guard uses so
+ * both surfaces compete on one file.
+ *
+ * Why it exists: two dsh processes pointed at the same profile each keep
+ * their own agent registry; `agents.get` cannot see the other process's
+ * live agent. A cold resume there therefore forks the log: two agents
+ * append to one jsonl and the interleaved seq numbers make the loader
+ * reject the session ("corrupt session log"). The lock sits NEXT to the
+ * log (`<sessionDir>/writer.lock`), derived with the exact path encoding
+ * upstream's jsonl backend uses, so every process about to create or
+ * cold-resume competes on the same file.
+ *
+ * Claiming protocol (concurrency-critical):
+ * - The payload is written FULLY to `<lock>.tmp-<pid>-<uniq>` first, then
+ *   claimed with `link(2)` — atomic at the kernel level, never writable
+ *   half-way, so no observer can read an empty/partial lock file.
+ * - Two processes that both judge the same residue dead cannot both win:
+ *   they race ONE link(); the loser sees EEXIST and re-evaluates against
+ *   the WINNER's fresh live pid, then refuses. Stealing (renaming the dead
+ *   residue aside) is merely garbage collection of readable history — the
+ *   exclusive right is granted by link(), not by who cleared what.
+ * - PID reuse can misreport a dead lock as alive; removing such a residual
+ *   stays an explicit manual act (delete the file), never automatic.
+ */
+import { link, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import { join, resolve } from 'node:path';
+/** Thrown when a cold arm refused to open a second writer for a session. */
+export class WriterLockedError extends Error {
+    holder;
+    constructor(holder) {
+        super(`session is locked by a live process (pid ${holder.pid}`
+            + `${holder.createdAt !== '' ? `, since ${holder.createdAt}` : ''})`
+            + ' — refusing to fork the log');
+        this.name = 'WriterLockedError';
+        this.holder = holder;
+    }
+}
+const LOCK_HOLDER = 'tui';
+/** Contention budget across residue-clearing rounds before giving up loudly. */
+const MAX_CLAIM_ROUNDS = 4;
+/**
+ * Dirs where THIS process established (created or stole) the lock. Only an
+ * establishing acquisition may release the file: a cooperative re-acquire
+ * (same pid already recorded) inherits it without removal rights.
+ */
+const established = new Set();
+export function writerLockPath(dir) {
+    return join(dir, 'writer.lock');
+}
+/**
+ * Project-directory name under which the jsonl backend groups a cwd's
+ * sessions — byte-identical port of upstream `projectKey()` in
+ * @deepseek-ai/dsh-session-persistence-jsonl (also mirrored by the feishu
+ * plugin's guard). The derived session dir additionally relies on upstream's
+ * `encodeSegment(sessionId)` being the IDENTITY for dsh ids — true while ids
+ * are UUIDs (safe charset ⊇ UUID charset). If upstream ever introduces
+ * non-UUID ids, port encodeSegment too or locks land beside decoy paths;
+ * update only in lockstep with upstream either way.
+ */
+export function projectKeyFor(cwd) {
+    if (cwd.length === 0)
+        throw new Error('cannot encode an empty project path');
+    let readable = '';
+    let separatorRun = false;
+    for (let i = 0; i < cwd.length; i++) {
+        const code = cwd.charCodeAt(i);
+        const ch = String.fromCharCode(code);
+        if (ch === '/' || ch === '\\' || ch === ':') {
+            if (!separatorRun)
+                readable += '-';
+            separatorRun = true;
+        }
+        else if (ch !== '~' && /^[A-Za-z0-9._-]$/.test(ch)) {
+            readable += ch;
+            separatorRun = false;
+        }
+        else {
+            readable += `~${code.toString(16).toUpperCase().padStart(4, '0')}`;
+            separatorRun = false;
+        }
+    }
+    return `--${(readable.replace(/^-+/, '') || 'root').slice(0, 251)}--`;
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means the process exists but belongs to another user — alive.
+        return error.code === 'EPERM';
+    }
+}
+async function readHolder(path) {
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Number.isInteger(parsed.pid) || parsed.pid <= 0)
+            return undefined;
+        return {
+            pid: parsed.pid,
+            createdAt: typeof parsed.createdAt === 'string' ? parsed.createdAt : '',
+            holder: typeof parsed.holder === 'string' ? parsed.holder : LOCK_HOLDER,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Fully write the payload to a private temp file, then CLAIM the lock name
+ * with link() — atomic: exactly one contender wins; everyone else gets
+ * EEXIST and re-reads whoever actually holds the name. Returns true iff WE
+ * claimed it (and thus own its release).
+ */
+async function claimFresh(path) {
+    const tmp = `${path}.tmp-${process.pid}-${randomBytes(4).toString('hex')}`;
+    await writeFile(tmp, JSON.stringify({
+        pid: process.pid,
+        createdAt: new Date().toISOString(),
+        holder: LOCK_HOLDER,
+    }));
+    try {
+        try {
+            await link(tmp, path);
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                return false;
+            throw error;
+        }
+    }
+    finally {
+        await unlink(tmp).catch(() => { });
+    }
+}
+async function clearResidue(path) {
+    try {
+        await rename(path, `${path}.stale-${Date.now()}-${randomBytes(3).toString('hex')}`);
+    }
+    catch (error) {
+        // Another contender cleared (or replaced) it already — harmless; the
+        // caller simply loops and re-reads the CURRENT state of the name.
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}
+/**
+ * Acquire the single-writer lock for `dir`. Fresh creation or a cleared
+ * residue establishes ownership (releasable later); a same-pid token is a
+ * cooperative re-acquire — success WITHOUT rewriting the existing file and
+ * without release rights. A lock held by another LIVE process refuses with
+ * its holder info.
+ */
+export async function acquireWriterLock(dir) {
+    await mkdir(dir, { recursive: true });
+    const path = writerLockPath(dir);
+    for (let round = 0; round < MAX_CLAIM_ROUNDS; round++) {
+        if (await claimFresh(path)) {
+            established.add(resolve(dir));
+            return { ok: true };
+        }
+        const holder = await readHolder(path);
+        if (holder !== undefined && holder.pid === process.pid) {
+            // Cooperative re-acquire: inherit, do not rewrite, never releasable.
+            return { ok: true };
+        }
+        if (holder !== undefined && processAlive(holder.pid)) {
+            return { ok: false, holder };
+        }
+        // Dead-or-corrupt-or-raced-away holder: collect the residue and re-try
+        // the atomic claim; any live winner introduced meanwhile is re-read and
+        // respected on the next round.
+        await clearResidue(path);
+    }
+    fail(`writer.lock contention did not settle after ${MAX_CLAIM_ROUNDS} rounds: ${path}`);
+}
+function fail(message) {
+    throw new Error(message);
+}
+/**
+ * Release the lock on `dir`, but ONLY when this process established it.
+ * A cooperative/inherited token — or a dir we never touched — is untouched.
+ */
+export async function releaseOwnedWriterLock(dir) {
+    const key = resolve(dir);
+    if (!established.delete(key))
+        return;
+    try {
+        await unlink(writerLockPath(dir));
+    }
+    catch {
+        // Already gone (or raced away) — nothing left to clean.
+    }
+}
+//# sourceMappingURL=writer-lock.js.map

package/lib/writer-lock.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwayds/dsh-tui-pi",
-  "version": "0.28.0",
+  "version": "1.0.0",
   "description": "pi-style terminal UI for DeepSeek Harness (dsh) — pi-tui look & feel, dsh slash commands, GitHub light/dark themes, powerline footer",
   "repository": {
     "type": "git",

package/scripts/repair-session-log.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+/**
+ * repair-session-log.mjs — offline surgery for session logs corrupted by
+ * concurrent writers. When two dsh processes append to one session log
+ * (the cross-process double-resume incident) the storage rows interleave
+ * two seq sequences and the loader refuses the log: "corrupt session log:
+ * seq gap in committed region …".
+ *
+ * Storage model (mirrors @deepseek-ai/dsh-session packChunkRuns +
+ * dsh-session-persistence-jsonl framing):
+ *   `<name>.jsonl.zstd` = concatenated independent zstd frames, each holding
+ *   ≥1 storage rows joined by "\n". A row is either
+ *   - a plain event `{type, seq?, time?, data}` (seq absent only on the very
+ *     first identity rows), or
+ *   - a packed delta run `{type:"text-chunks"|"reasoning-chunks"|
+ *     "tool-call-chunks", seq0, time0, data:{…, dt:[…]}}`, occupying the seq
+ *     span `[seq0, seq0 + payload.length - 1]`.
+ *
+ * Repair policy (deterministic, conservative):
+ *   1. Identity rows without seq are kept verbatim at the top.
+ *   2. Every seq-bearing row maps onto its span; rows are then processed in
+ *      ascending (seqStart, originalIndex) order — duplicate COVERAGE is
+ *      dropped ("loser writer" copies arrive behind the same slots), while
+ *      every event slot never seen before survives, whichever writer wrote it.
+ *      A row that only PARTIALLY overlaps already-covered slots is still
+ *      kept whole (its fresh slots win; the shadowed middle slots stay
+ *      duplicated inside the repaired log) — splitting packed rows is
+ *      deliberately deferred; such rows are reported explicitly.
+ *   3. Survivors are renumbered into one dense seq space (packed rows keep
+ *      their internal span width) and written to `<name>.repaired.jsonl[.zstd]`
+ *      re-encoded in the writer's multi-frame shape — frame 1 carries the
+ *      header line alone, remaining rows chunked 512 per frame — so the
+ *      output loads in dsh directly (a single-frame rewrite would be
+ *      rejected with "first frame is not exactly one header line").
+ *      beside the original. The original is NEVER modified or deleted; to
+ *      actually LOAD the repair you must move it over the corrupted name
+ *      yourself (the success line prints the exact mv command).
+ *
+ * Torn/truncated lines (another artifact of concurrent appends) abort the
+ * run unless --skip-bad-lines is given, which drops and reports them.
+ *
+ * Usage:
+ *   node scripts/repair-session-log.mjs <log.jsonl.zstd | log.jsonl> [--apply] [--skip-bad-lines]
+ *
+ * Exit codes: 0 clean/repaired · 3 corrupt (diagnosed; repaired only with
+ * --apply) · 2 usage/environment/unparseable-input error. Stop the processes
+ * driving the live session BEFORE repairing — this fixes bytes, not agents.
+ */
+
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+
+const PACKED_TYPES = new Set(['text-chunks', 'reasoning-chunks', 'tool-call-chunks'])
+
+function fail(message) {
+  console.error(`repair-session-log: ${message}`)
+  process.exit(2)
+}
+
+function parseRow(line, index) {
+  let value
+  try {
+    value = JSON.parse(line)
+  } catch {
+    return undefined // caller decides: fatal without --skip-bad-lines
+  }
+  const type = typeof value.type === 'string' ? value.type : '(none)'
+  const row = { index, line, type, start: null, end: null, slots: 0, hash: '' }
+  const payloadLen = () => {
+    const data = value.data ?? {}
+    const payload = Array.isArray(data.texts) ? data.texts : Array.isArray(data.args) ? data.args : []
+    return Math.max(payload.length, 1)
+  }
+  if (PACKED_TYPES.has(type)) {
+    if (!Number.isSafeInteger(value.seq0)) return row // treated as identity-row companion
+    row.slots = payloadLen()
+    row.start = value.seq0
+    row.end = value.seq0 + row.slots - 1
+  } else if (Number.isSafeInteger(value.seq)) {
+    row.slots = 1
+    row.start = value.seq
+    row.end = value.seq
+  }
+  row.hash = createHash('sha256').update(line).digest('hex').slice(0, 12)
+  return row
+}
+
+function analyze(rows) {
+  let prevEnd = -1
+  const violations = []
+  for (const r of rows) {
+    if (r.start === null) continue
+    if (r.start <= prevEnd) {
+      violations.push({ index: r.index, start: r.start, end: r.end, prevEnd, type: r.type })
+    }
+    if (r.end > prevEnd) prevEnd = r.end
+  }
+  return violations
+}
+
+/**
+ * Survivor selection: identity rows ride along; seq rows sorted by
+ * (start, originalIndex) keep every previously-unseen slot. Deterministic
+ * across runs, never biased toward a particular writer. Rows whose span
+ * crosses the frontier are kept whole AND reported (their shadowed middle
+ * slots stay duplicated; see the header note on splitting).
+ */
+function selectSurvivors(rows) {
+  const identity = rows.filter(r => r.start === null)
+  const carriers = rows.filter(r => r.start !== null).sort((a, b) => a.start - b.start || a.index - b.index)
+  const survivors = []
+  const dropped = []
+  const partialOverlaps = []
+  let frontier = -1
+  for (const r of carriers) {
+    if (r.end <= frontier) {
+      dropped.push({ index: r.index, start: r.start, end: r.end, type: r.type, hash: r.hash })
+      continue
+    }
+    if (r.start <= frontier && r.end > frontier) {
+      partialOverlaps.push({ index: r.index, start: r.start, end: r.end })
+    }
+    survivors.push(r)
+    frontier = r.end
+  }
+  return { identity, survivors, dropped, partialOverlaps }
+}
+
+/** Dense renumbering in survivor emission order. */
+function renumber(identity, survivors) {
+  const out = [...identity.map(r => r.line)]
+  let next = 0
+  for (const r of survivors) {
+    const value = JSON.parse(r.line)
+    if (PACKED_TYPES.has(r.type)) {
+      value.seq0 = next
+      next += r.slots
+    } else {
+      value.seq = next
+      next += 1
+    }
+    out.push(JSON.stringify(value))
+  }
+  return { lines: out, lastIndex: next - 1 }
+}
+
+function decompress(file) {
+  const proc = spawnSync('zstd', ['-dc', file], { maxBuffer: 1 << 30 })
+  if (proc.error) fail(`cannot run zstd: ${proc.error.message}`)
+  if (proc.status !== 0) fail(`zstd -dc failed on ${file}: ${String(proc.stderr).slice(0, 200)}`)
+  return proc.stdout.toString('utf8')
+}
+
+function compressToFrames(lines, outPathTmp) {
+  // dsh's jsonl backend reads frame 1 as exactly one header line and frames
+  // 2+ as row batches; a single-frame rewrite of the whole body loads as
+  // "first frame is not exactly one header line". Frame 1 = the identity
+  // line alone, remaining rows chunked FRAME_ROWS per frame.
+  const FRAME_ROWS = 512
+  const chunks = [lines.slice(0, 1)]
+  for (let i = 1; i < lines.length; i += FRAME_ROWS) chunks.push(lines.slice(i, i + FRAME_ROWS))
+  const parts = chunks.map(chunk => {
+    const proc = spawnSync('zstd', ['-19'], { input: Buffer.from(`${chunk.join('\n')}\n`, 'utf8'), maxBuffer: 1 << 30 })
+    if (proc.error) fail(`cannot run zstd: ${proc.error.message}`)
+    if (proc.status !== 0) fail(`zstd compress failed: ${String(proc.stderr).slice(0, 200)}`)
+    return proc.stdout
+  })
+  writeFileSync(outPathTmp, Buffer.concat(parts))
+}
+
+function main() {
+  const args = process.argv.slice(2)
+  const apply = args.includes('--apply')
+  const skipBadLines = args.includes('--skip-bad-lines')
+  const positional = args.filter(a => !a.startsWith('--'))
+  if (positional.length !== 1) {
+    fail('usage: repair-session-log.mjs <log.jsonl.zstd|log.jsonl> [--apply] [--skip-bad-lines]')
+  }
+  const file = positional[0]
+
+  const isZstd = file.endsWith('.jsonl.zstd')
+  const text = isZstd ? decompress(file) : readFileSync(file, 'utf8')
+  const rawLines = text.split('\n').filter(l => l.trim() !== '')
+  const rows = []
+  const badLines = []
+  for (let i = 0; i < rawLines.length; i++) {
+    const parsed = parseRow(rawLines[i], i)
+    if (parsed === undefined) {
+      badLines.push({ index: i + 1, preview: rawLines[i].slice(0, 120) })
+      continue
+    }
+    rows.push(parsed)
+  }
+  if (badLines.length > 0 && !skipBadLines) {
+    for (const bad of badLines.slice(0, 5)) {
+      console.error(`repair-session-log: line ${bad.index} unparseable: ${bad.preview}`)
+    }
+    fail(`${badLines.length} torn/unparseable line(s) — re-run with --skip-bad-lines to drop and report them`)
+  }
+
+  const violations = analyze(rows)
+  const maxSeq = rows.reduce((m, r) => Math.max(m, r.end ?? -1), -1)
+
+  console.log(`rows: ${rows.length}${badLines.length > 0 ? ` (+${badLines.length} skipped bad lines)` : ''} | maxSeq: ${maxSeq} | seq violations: ${violations.length}`)
+  for (const v of violations.slice(0, 10)) {
+    console.log(`  ✗ line ${v.index + 1}: ${v.type} covers ${v.start}..${v.end} after coverage through ${v.prevEnd}`)
+  }
+  if (violations.length > 10) console.log(`  … and ${violations.length - 10} more`)
+
+  if (violations.length === 0) {
+    console.log('verdict: CLEAN — nothing to do.')
+    return
+  }
+
+  const { identity, survivors, dropped, partialOverlaps } = selectSurvivors(rows)
+  console.log(`plan: keep ${identity.length} identity + ${survivors.length} event rows (${dropped.length} duplicate-coverage rows dropped), renumber dense.`)
+  for (const d of dropped.slice(0, 10)) {
+    console.log(`  − line ${d.index + 1}: ${d.type} ${d.start}..${d.end} (shadowed copy [${d.hash}])`)
+  }
+  for (const p of partialOverlaps.slice(0, 10)) {
+    console.log(`  ⚠ line ${p.index + 1}: spans ${p.start}..${p.end}, partially overlapping covered slots — kept whole; the shadowed middle slots stay duplicated in the repaired log`)
+  }
+
+  if (!apply) {
+    console.log('dry-run: nothing written. Re-run with --apply to write *.repaired beside the original.')
+    process.exit(3)
+  }
+
+  const { lines: fixedLines, lastIndex } = renumber(identity, survivors)
+  const body = `${fixedLines.join('\n')}\n`
+  const check = analyze(body.split('\n').filter(l => l.trim() !== '').map(parseRow))
+  if (check.length > 0) fail('internal: repaired output still violates seq order — refusing to write')
+
+  const stem = basename(file).replace(/\.jsonl(\.zstd)?$/, '')
+  const outPath = join(dirname(file), `${stem}.repaired.jsonl${isZstd ? '.zstd' : ''}`)
+  const tmpPath = `${outPath}.tmp`
+  if (isZstd) compressToFrames(fixedLines, tmpPath)
+  else writeFileSync(tmpPath, body)
+  renameSync(tmpPath, outPath)
+  console.log(`wrote ${outPath} (${fixedLines.length} rows, dense seq 0..${lastIndex}). Original untouched.`)
+  console.log(`activate with:  mv '${outPath}' '${file}'   # only while no process is writing that session`)
+}
+
+main()