@xmoon76/dsh-pi-tui 0.1.1 → 0.1.3

package/README.md

@@ -30,6 +30,65 @@ dsh plugin --profile pi-tui -- remove @xmoon76/dsh-pi-tui
 - `/title [title]` — show or set the current session's title
 - `/preset`, `/model`, `/settings`, `/export`, `/fork`, `/subagents` — see the command autocomplete (`/` + Tab)
 
+## ⚠️ One surface per session
+
+**Upstream limitation (a known dsh issue this TUI cannot fix):** dsh's session persistence has no cross-process coordination — each process numbers events from its own in-memory log length (`seq = log.length`) and appends to the same session file. When two processes hold the **same active session** at the same time (TUI + web GUI, two TUIs, TUI + any third-party plugin), one side's resume writes a `session/end-seed` marker and the other side's next append collides on the same seq — **the log corrupts and the session becomes unreadable** (`corrupt session log: seq gap in committed region`).
+
+Therefore:
+
+- **Do not open the same active session in two surfaces at once** (TUI, web GUI, or any other plugin);
+- To switch surfaces, close the session in the current one first, then open it in the other;
+- This TUI ships a **divergence guard**: before each message send it checks whether another process has written the session file, and **blocks the send with a warning** when it has (pressing Enter again force-sends at your own risk — it may corrupt the log);
+- If a session is already corrupted, fix it with the [session repair script](#session-repair) below (close every process holding the session first).
+
+## Diagnostic log
+
+The TUI writes its own diagnostics to stderr and a log file (`ctx.logger` is invisible in this process — no exporter):
+
+- Default file: `$DSH_HOME/logs/pi-tui-<pid>.log` (default `~/.dsh/logs/`);
+- Line format: `[tui] <ISO time> <level> <message> k=v ...`;
+- Default level `info`: key lifecycle events only (boot/resume/switch/exit, divergence-guard warnings, errors); `debug` additionally logs every guard check before a send.
+
+Configuration (environment variables):
+
+| Variable | Meaning | Default |
+|---|---|---|
+| `DSH_PI_TUI_LOG` | Log file path; `off` disables file logging | `$DSH_HOME/logs/pi-tui-<pid>.log` |
+| `DSH_PI_TUI_LOG_LEVEL` | `debug` / `info` / `warn` / `error` | `info` |
+
+Troubleshooting example:
+
+```sh
+DSH_PI_TUI_LOG_LEVEL=debug dsh --profile pi-tui
+tail -f ~/.dsh/logs/pi-tui-*.log
+```
+
+## Session repair
+
+**Background:** when a session log is corrupted (duplicate or missing seqs) dsh can no longer read that session. This repository ships a standalone repair script, `scripts/repair-session.mjs`: it locates the session file, diagnoses the damage, and repairs it — renumbering seqs (duplicates), truncating at the first missing/unparsable event (which cannot be recreated), or re-framing the log when the frame layout is wrong (dsh requires the first zstd frame to be exactly the header line; a whole-log single frame is structurally valid zstd but rejected by every dsh reader). It **always backs up the original before writing** and verifies the result with the same scans the reader performs (frame layout + event contiguity).
+
+**Dependency:** resolves `@deepseek-ai/dsh-session` from the dsh installation (auto-detected through the `dsh` launcher on PATH, or `--dsh-dir <path>`).
+
+**Repair one session (dry run by default; `--yes` writes):**
+
+```sh
+# Close every process holding the session first (TUI / web / plugins)!
+node scripts/repair-session.mjs session-ab79200b-0e36-4a62-a7a6-3ac620c05f1d          # diagnose + repair plan (no write)
+node scripts/repair-session.mjs session-ab79200b-0e36-4a62-a7a6-3ac620c05f1d --yes    # apply the repair
+```
+
+The original file is backed up to `session.jsonl.zstd.bak-<timestamp>` before writing (a failed backup aborts the write); the report prints the backup path.
+
+**Read-only scan of all sessions, listing damaged ids:**
+
+```sh
+node scripts/repair-session.mjs --scan
+```
+
+Prints one `CORRUPT <id>: <reason>` per damaged session; `no damaged sessions found` when everything is healthy.
+
+**Other options:** `--dsh-home <path>` sets the sessions root (default `$DSH_HOME` or `~/.dsh`); `--help` shows usage.
+
 ## Development
 
 Source and tests live in the [dsh-pi-tui repository](https://github.com/XMoon/dsh-pi-tui) (`packages/dsh-pi-tui/`); headless tests drive the UI through `@xterm/headless` with no TTY or model connection.

package/dist/index.d.mts

@@ -22,12 +22,40 @@ interface Config {
   sessionId?: string;
 }
 declare const Config: z<Config>;
+/**
+ * Read an explicit child-session reference from a future/extended job record.
+ * Current dsh JobSnapshot records do not expose one, so this normally returns
+ * undefined. Crucially, label, registration order and timestamps are never
+ * accepted as identity signals.
+ */
+declare function subagentJobTranscriptId(snapshot: unknown): string | undefined;
+/** Viewer body for a subagent job with no uniquely matched child. */
+declare function subagentJobViewHint(status: string, detail: string | undefined): string;
 /**
  * Whether a shell command matches a destructive pattern. `rm` is treated
  * specially: any spelling of recursive + force flags (`rm -rf`, `rm -r -f`,
  * `rm -rf /`) is dangerous; the remaining patterns are verbatim matches.
  */
 declare function dangerCommand(command: string): boolean;
+/**
+ * The dsh profile this process was launched with (the `--profile` flag),
+ * so the exit-time resume hint names the profile the TUI actually runs
+ * under. Falls back to `pi-tui` when the flag is absent (the TUI bundle
+ * cannot load without a profile, so this is defensive only).
+ * @param argv - the process argument vector.
+ * @param fallback - the default profile.
+ */
+declare function runningProfile(argv?: readonly string[], fallback?: string): string;
+/**
+ * The interactive-quit resume hint (pi parity): `dsh --profile <p>
+ * --session <id>`, printed after the terminal restores so the user can
+ * re-enter the session later. Returns undefined when there is no session
+ * to resume (deferred start never created one).
+ * @param profile - the running profile ({@link runningProfile}).
+ * @param sessionId - the live session id.
+ * @returns the resume command line, or undefined without a session.
+ */
+declare function resumeCommand(profile: string, sessionId: string): string | undefined;
 /** One agent's preset composition: the id to record and the setup that installs it. */
 interface AgentComposition {
   /** Preset id for the session header, absent when the deployment composes no roster. */
@@ -103,4 +131,4 @@ declare function recomposeBlank(ctx: Context, agent: {
  */
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { AgentComposition, Config, RecomposableSession, RecomposeOutcome, apply, composeAgent, dangerCommand, forkSeed, inject, name, recomposeBlank, recordedPreset };
+export { AgentComposition, Config, RecomposableSession, RecomposeOutcome, apply, composeAgent, dangerCommand, forkSeed, inject, name, recomposeBlank, recordedPreset, resumeCommand, runningProfile, subagentJobTranscriptId, subagentJobViewHint };