Add TermDeck safety and lifecycle controls

Author: NolanHo

README.md

@@ -142,6 +142,8 @@ Inspection:
 ```bash
 termdeck state <session> [--lines N] [--autostart]
 termdeck summary <session> [--lines N] [--events N] [--autostart]
+termdeck last-command <session>
+termdeck sensitive <session> --on|--off
 termdeck screen <session>
 termdeck scrollback <session> [--lines N]
 termdeck transcript <session>
@@ -157,7 +159,7 @@ termdeck clear-scrollback <session>
 Background task helpers:
 
 ```bash
-termdeck task start <name> <command> --cwd <path> [--owner USER] [--labels a,b] [--ttl-ms N] [--ready-url URL] [--ready-port N] [--expect PATTERN]
+termdeck task start <name> <command> --cwd <path> [--owner USER] [--labels a,b] [--ttl-ms N] [--restart-policy never|on-exit|on-failure] [--max-restarts N] [--backoff-ms N] [--ready-url URL] [--ready-port N] [--expect PATTERN]
 termdeck task status <name>
 termdeck task recover <name>
 termdeck task logs <name> [--lines N]
@@ -188,9 +190,11 @@ env = { TERMDECK_HOME = "/path/to/project/.termdeck" }
 
 The MCP `step` tool is the agent-friendly default entrypoint. It can autostart `termdeckd`, create a missing session when `cwd` is supplied, and returns stable JSON fields such as `status`, `reason`, `prompt`, `exitCode`, `timedOut`, `outputTruncated`, `lastSeq`, `transcriptPath`, and `cwd`. `project_step` goes one level higher by deriving a stable session id from `cwd` and an optional label.
 
-`summary` returns a compact inspection object with a screen tail, output tail, recent events, and likely error lines. Use it when an agent needs state without replaying a large transcript.
+`summary` returns a compact inspection object with a screen tail, output tail, recent events, and likely error lines. `last_command` returns structured command id, command text, seq bounds, duration, exit code, timeout flag, and output tail. Use these when an agent needs state without replaying a large transcript.
 
-Task helpers report stale metadata, expired TTLs, exited backing processes, restart counts, readiness diagnostics, and orphan `task-*` sessions. The web UI surfaces the same dashboard data with filters for active and attention-needed work.
+Sensitive mode redacts returned text, log/events views, summaries, and web output while hiding web snapshots. Raw transcripts remain local artifacts and should still be treated as sensitive.
+
+Task helpers report stale metadata, expired TTLs, exited backing processes, restart counts, readiness diagnostics, and orphan `task-*` sessions. Optional restart policies can restart exited tasks on any exit or only non-zero exit. The web UI surfaces the same dashboard data with filters for active and attention-needed work plus safe task stop/recover/prune controls.
 
 Synchronization:
 

README_zh.md

@@ -135,6 +135,8 @@ termdeck signal <session> <signal> [--timeout-ms N] [--quiescence-ms N]
 ```bash
 termdeck state <session> [--lines N] [--autostart]
 termdeck summary <session> [--lines N] [--events N] [--autostart]
+termdeck last-command <session>
+termdeck sensitive <session> --on|--off
 termdeck screen <session>
 termdeck scrollback <session> [--lines N]
 termdeck transcript <session>
@@ -151,7 +153,9 @@ termdeck clear-scrollback <session>
 
 `run` 会在 shell 内加入 begin/exit marker，以便从终端回显中稳定切出命令输出并返回 `exitCode`。命令仍在持久 shell 中执行，所以 `cd`、环境变量和 shell 函数等状态会保留。
 
-后台任务支持 `--owner`、`--labels`、`--ttl-ms`、`task dashboard`、`task prune` 和 `task recover`。状态会区分 stale metadata、TTL 过期、进程已退出、restart count 和 orphan `task-*` session。Web UI 会展示 task dashboard，并提供 active/attention 过滤。
+`last-command` 返回结构化 command id、命令、seq 范围、duration、exit code、timeout 和 output tail。`sensitive` 模式会对返回文本、log/events/summary 和 Web 输出做 redaction，并隐藏 Web snapshot；原始 transcript 仍是本地磁盘 artifact，需要继续按敏感数据处理。
+
+后台任务支持 `--owner`、`--labels`、`--ttl-ms`、`--restart-policy`、`--max-restarts`、`--backoff-ms`、`task dashboard`、`task prune` 和 `task recover`。状态会区分 stale metadata、TTL 过期、进程已退出、restart count 和 orphan `task-*` session。Web UI 会展示 task dashboard，并提供 active/attention 过滤以及 stop/recover/prune 安全控制，但仍不向 PTY 发送输入。
 
 同步等待：
 

docs/usage.md

@@ -103,6 +103,20 @@ termdeck run main 'echo ok' --json
 
 `run` wraps the command with shell markers so the response can separate command output from terminal echo and report `exitCode` when the command completes. The persistent shell still executes the command itself, so stateful operations such as `cd`, exported variables, and shell functions remain in the session.
 
+Read the last structured command record:
+
+```bash
+termdeck last-command main --json
+```
+
+Enable sensitive mode when returned views may contain secrets:
+
+```bash
+termdeck sensitive main --on
+```
+
+Sensitive mode redacts returned command output, screen/log/events/summary views, and web output. It also hides the web snapshot for that session. The raw local transcript remains an artifact on disk, so keep `TERMDECK_HOME` permissions tight and avoid entering secrets unless necessary.
+
 Use `--raw` when a command path needs the original PTY bytes, including ANSI color/control sequences:
 
 ```bash
@@ -299,7 +313,7 @@ termdeck transcript main
 Task helpers are named TermDeck sessions with small readiness metadata. They do not bypass the daemon or create a separate terminal runner.
 
 ```bash
-termdeck task start web 'pnpm dev --host 127.0.0.1' --cwd "$PWD" --labels dev,web --ttl-ms 7200000 --ready-port 5173 --autostart
+termdeck task start web 'pnpm dev --host 127.0.0.1' --cwd "$PWD" --labels dev,web --ttl-ms 7200000 --restart-policy on-failure --max-restarts 2 --backoff-ms 3000 --ready-port 5173 --autostart
 termdeck task status web
 termdeck task recover web
 termdeck task logs web --lines 100
@@ -308,7 +322,9 @@ termdeck task prune --stale --expired --dry-run
 termdeck task stop web
 ```
 
-Readiness can be detected with `--ready-url`, `--ready-port`, or `--expect`. When more than one readiness check is supplied, all checks must pass and `task status` reports per-check diagnostics plus a short log tail on failure. Task metadata can include `--owner`, `--labels`, and `--ttl-ms`. Status distinguishes stale metadata, expired TTLs, exited backing processes, and restart counts. If task metadata exists but the backing session is gone, status reports a stale task; `task recover` recreates the session from metadata and reruns the task command. `task dashboard` also reports orphan `task-*` sessions that have no task metadata.
+Readiness can be detected with `--ready-url`, `--ready-port`, or `--expect`. When more than one readiness check is supplied, all checks must pass and `task status` reports per-check diagnostics plus a short log tail on failure. Task metadata can include `--owner`, `--labels`, `--ttl-ms`, and restart policy fields. Status distinguishes stale metadata, expired TTLs, exited backing processes, and restart counts. If task metadata exists but the backing session is gone, status reports a stale task; `task recover` recreates the session from metadata and reruns the task command. `task dashboard` also reports orphan `task-*` sessions that have no task metadata.
+
+Restart policies are `never`, `on-exit`, and `on-failure`. Automatic restarts honor `--max-restarts` and `--backoff-ms`.
 
 ## MCP
 
@@ -356,7 +372,7 @@ The browser uses:
 - JSON REST for serialized xterm snapshots
 - binary protobuf WebSocket events for live output after the snapshot sequence
 
-The browser loads a serialized xterm snapshot first, then subscribes with `afterSeq=lastSeq`. Reconnects use `afterSeq` to replay events missed during a disconnect while the daemon retains them. The sidebar supports active and attention filters for sessions and tasks; the top dashboard summarizes session count, task count, ready tasks, and attention-needed items.
+The browser loads a serialized xterm snapshot first, then subscribes with `afterSeq=lastSeq`. Reconnects use `afterSeq` to replay events missed during a disconnect while the daemon retains them. The sidebar supports active and attention filters for sessions and tasks; the top dashboard summarizes session count, task count, ready tasks, and attention-needed items. Web task controls can stop, recover, and prune stale/expired tasks, but the browser remains observe-only for PTY input.
 
 ## Automation pattern
 

src/cli.ts

@@ -1,7 +1,9 @@
 import { readFileSync } from 'node:fs';
 import { Command } from 'commander';
 import { ensureSession, request, requestWithDaemon, stateSnapshot } from './client.js';
+import { lastCommand } from './commands.js';
 import { projectSessionName } from './project.js';
+import { setSensitiveSession } from './sensitive.js';
 import { sessionSummary } from './summary.js';
 import { listSessions, listTasks, pruneSessions, taskDashboard, taskLogs, taskRecover, taskPrune, taskStart, taskStatus, taskStop } from './tasks.js';
 import type { Response } from './protocol.js';
@@ -137,6 +139,21 @@ program.command('summary')
   .option('--autostart', 'start termdeckd when it is not running')
   .action(async (session, opts) => printResponse(await sessionSummary({ session, lines: opts.lines, events: opts.events, autostart: opts.autostart }), opts.json ? 'json' : 'default'));
 
+program.command('last-command')
+  .argument('<session>')
+  .option('--json')
+  .action(async (session, opts) => printObject({ command: lastCommand(session) }, opts.json));
+
+program.command('sensitive')
+  .argument('<session>')
+  .option('--on', 'enable sensitive mode')
+  .option('--off', 'disable sensitive mode')
+  .option('--json')
+  .action(async (session, opts) => {
+    if (Boolean(opts.on) === Boolean(opts.off)) throw new Error('pass exactly one of --on or --off');
+    printObject(setSensitiveSession(session, Boolean(opts.on)), opts.json);
+  });
+
 program.command('step')
   .argument('<session>')
   .argument('[command]')
@@ -437,6 +454,9 @@ task.command('start')
   .option('--owner <owner>')
   .option('--labels <labels>', 'comma-separated labels')
   .option('--ttl-ms <ms>', 'task metadata TTL', (v) => Number(v))
+  .option('--restart-policy <policy>', 'never, on-exit, or on-failure')
+  .option('--max-restarts <count>', 'maximum automatic restarts', (v) => Number(v))
+  .option('--backoff-ms <ms>', 'minimum delay between automatic restarts', (v) => Number(v))
   .option('--ready-url <url>')
   .option('--ready-port <port>', 'localhost port readiness probe', (v) => Number(v))
   .option('--expect <pattern>')
@@ -457,6 +477,9 @@ task.command('start')
       owner: opts.owner,
       labels: opts.labels ? String(opts.labels).split(',').map((s) => s.trim()).filter(Boolean) : undefined,
       ttlMs: opts.ttlMs,
+      restartPolicy: opts.restartPolicy,
+      maxRestarts: opts.maxRestarts,
+      backoffMs: opts.backoffMs,
       readyUrl: opts.readyUrl,
       readyPort: opts.readyPort,
       expect: opts.expect,

src/commands.ts

@@ -0,0 +1,36 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { redactValue } from './redact.js';
+import { isSensitiveSession } from './sensitive.js';
+import { sessionDir } from './paths.js';
+
+export type LastCommand = {
+  id: string;
+  kind: string;
+  data: string;
+  tsMs: number;
+  startSeq?: number;
+  endSeq?: number;
+  durationMs?: number;
+  exitCode?: number;
+  timedOut?: boolean;
+  outputTail?: string;
+};
+
+export function lastCommand(session: string): LastCommand | undefined {
+  const file = join(sessionDir(session), 'commands.log');
+  if (!existsSync(file)) return undefined;
+  const rows = readFileSync(file, 'utf8').split('\n').filter(Boolean);
+  const byId = new Map<string, Partial<LastCommand>>();
+  for (const row of rows) {
+    try {
+      const parsed = JSON.parse(row) as Partial<LastCommand> & { result?: Partial<LastCommand> };
+      const id = parsed.id ?? `${parsed.tsMs ?? byId.size}`;
+      const current = byId.get(id) ?? {};
+      byId.set(id, { ...current, ...parsed, ...(parsed.result ?? {}) });
+    } catch {}
+  }
+  const last = [...byId.values()].filter((row): row is LastCommand => typeof row.data === 'string' && typeof row.tsMs === 'number').at(-1);
+  if (!last) return undefined;
+  return isSensitiveSession(session) ? redactValue(last) as LastCommand : last;
+}

src/daemon.ts

@@ -8,10 +8,12 @@ import type { Duplex } from 'node:stream';
 import stripAnsi from 'strip-ansi';
 import { encodeEvent, FrameReader, writeFrame, type Event, type Request, type Response } from './protocol.js';
 import { socketAccessMode } from './platform.js';
+import { redactJsonl, redactText } from './redact.js';
 import { rootDir, sessionDir, sessionsDir, socketPath } from './paths.js';
 import { replayTranscript } from './replay.js';
 import { TermSession } from './session.js';
-import { taskDashboard } from './tasks.js';
+import { isSensitiveSession } from './sensitive.js';
+import { taskDashboard, taskPrune, taskRecover, taskStop } from './tasks.js';
 import { webAppJs, webHtml } from './web.js';
 
 const require = createRequire(import.meta.url);
@@ -123,10 +125,10 @@ function inspectSession(id: string): Record<string, unknown> {
   return JSON.parse(readFileSync(file, 'utf8')) as Record<string, unknown>;
 }
 
-function tailFile(file: string, lines: number): string {
+function tailFile(file: string, lines: number, redact = false): string {
   const text = readFileSync(file, 'utf8');
-  if (!lines || lines <= 0) return text;
-  return text.split('\n').slice(-lines).join('\n');
+  const out = !lines || lines <= 0 ? text : text.split('\n').slice(-lines).join('\n');
+  return redact ? redactText(out) : out;
 }
 
 function eventLines(id: string, afterSeq: number, limit: number): string {
@@ -138,7 +140,8 @@ function eventLines(id: string, afterSeq: number, limit: number): string {
       return false;
     }
   });
-  return rows.slice(0, limit || rows.length).join('\n');
+  const out = rows.slice(0, limit || rows.length).join('\n');
+  return isSensitiveSession(id) ? redactJsonl(out) : out;
 }
 
 async function handle(req: Request, socket?: Socket): Promise<Response> {
@@ -229,7 +232,7 @@ async function handle(req: Request, socket?: Socket): Promise<Response> {
       case 'inspect':
         return { id: req.id, ok: true, metadata: manager.list()?.some((s) => s.id === req.session) ? manager.get(req.session).metadata() : inspectSession(req.session) };
       case 'log':
-        return { id: req.id, ok: true, logText: tailFile(join(sessionDir(req.session), 'transcript.log'), req.lines ?? 200) };
+        return { id: req.id, ok: true, logText: tailFile(join(sessionDir(req.session), 'transcript.log'), req.lines ?? 200, isSensitiveSession(req.session)) };
       case 'events':
         return { id: req.id, ok: true, eventsText: eventLines(req.session, req.afterSeq ?? 0, req.limit ?? 200) };
       case 'replay': {
@@ -328,6 +331,20 @@ function handleWebRequest(req: IncomingMessage, res: { writeHead(code: number, h
       void taskDashboard({ timeoutMs: 1 }).then((dashboard) => send(res, 200, 'application/json', JSON.stringify(dashboard))).catch((err: unknown) => send(res, 500, 'text/plain; charset=utf-8', err instanceof Error ? err.message : String(err)));
       return;
     }
+    if (req.method === 'POST') {
+      const taskActionMatch = url.pathname.match(/^\/api\/tasks\/([^/]+)\/(stop|recover)$/);
+      if (taskActionMatch) {
+        const name = decodeURIComponent(taskActionMatch[1]);
+        const action = taskActionMatch[2];
+        const run = action === 'stop' ? taskStop(name, true) : taskRecover(name, { autostart: true });
+        void run.then((body) => send(res, 200, 'application/json', JSON.stringify(body))).catch((err: unknown) => send(res, 500, 'text/plain; charset=utf-8', err instanceof Error ? err.message : String(err)));
+        return;
+      }
+      if (url.pathname === '/api/tasks/prune') {
+        void taskPrune({ stale: true, expired: true, autostart: true }).then((body) => send(res, 200, 'application/json', JSON.stringify(body))).catch((err: unknown) => send(res, 500, 'text/plain; charset=utf-8', err instanceof Error ? err.message : String(err)));
+        return;
+      }
+    }
     const screenMatch = url.pathname.match(/^\/api\/sessions\/([^/]+)\/screen$/);
     if (screenMatch) {
       const s = manager.get(decodeURIComponent(screenMatch[1]));
@@ -336,7 +353,7 @@ function handleWebRequest(req: IncomingMessage, res: { writeHead(code: number, h
     const snapshotMatch = url.pathname.match(/^\/api\/sessions\/([^/]+)\/snapshot$/);
     if (snapshotMatch) {
       const s = manager.get(decodeURIComponent(snapshotMatch[1]));
-      return send(res, 200, 'application/json', JSON.stringify({ status: s.status().status, lastSeq: s.info().lastSeq, rows: s.rows, cols: s.cols, snapshot: s.snapshot() }));
+      return send(res, 200, 'application/json', JSON.stringify({ status: s.status().status, lastSeq: s.info().lastSeq, rows: s.rows, cols: s.cols, sensitive: s.isSensitive(), snapshot: s.snapshot() }));
     }
     send(res, 404, 'text/plain; charset=utf-8', 'not found');
   } catch (err) {
@@ -377,9 +394,14 @@ function handleWebSocketUpgrade(req: IncomingMessage, socket: Duplex): void {
     }
   });
   const onEvent = (event: Event) => {
-    if (event.session === session) socket.write(wsBinary(encodeEvent(event)));
+    if (event.session !== session) return;
+    const out = s.isSensitive() && (event.kind === 'output' || event.kind === 'input') ? { ...event, data: redactText(event.data) } as Event : event;
+    socket.write(wsBinary(encodeEvent(out)));
   };
-  for (const event of s.eventsAfter(afterSeq)) socket.write(wsBinary(encodeEvent(event)));
+  for (const event of s.eventsAfter(afterSeq)) {
+    const out = s.isSensitive() && (event.kind === 'output' || event.kind === 'input') ? { ...event, data: redactText(event.data) } as Event : event;
+    socket.write(wsBinary(encodeEvent(out)));
+  }
   s.on('event', onEvent);
   socket.on('close', () => s.off('event', onEvent));
 }