@bigknoxy/hashpilot 4.6.3

package/src/commands/maintenance.ts

@@ -0,0 +1,191 @@
+import type { Command } from "commander";
+import {
+  health,
+  doctor,
+  finish,
+  ExitCode,
+  getOutputFormat,
+} from "../core/index";
+import { writeFileSync, rmSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+
+/** Register the `maintenance` command group. */
+export function register(program: Command): void {
+  program
+    .command("doctor")
+    .description("Verify HashPilot installation health")
+
+    .action(() => {
+      // Both formats go through finish(): it is the only place that sets the
+      // process exit code, and the old console.log bypass is why `doctor`
+      // always exited 0 no matter how broken the install was (#46).
+      const report = doctor();
+      finish(report, report.exitCode as ExitCode);
+    });
+
+  program
+    .command("upgrade")
+    .description("Upgrade HashPilot to the latest version from GitHub")
+    .option("--channel <channel>", "Release channel (default: main)", "main")
+    .option("--target <dir>", "Install target directory (default: ~/.agentic-tools)")
+    .option("--keep-telemetry", "Preserve existing telemetry on upgrade")
+    .option("--force", "Skip confirmation prompt")
+    .option("--dry-run", "Show what would be done without executing")
+    .action(async (opts) => {
+      const channel = opts.channel;
+      const targetDir = opts.target || join(process.env.HOME || "/root", ".agentic-tools");
+      const keepTelemetry = opts.keepTelemetry;
+      const force = opts.force;
+      const dryRun = opts.dryRun;
+
+      const installUrl = `https://raw.githubusercontent.com/bigknoxy/HashPilot/${channel}/scripts/install.sh`;
+      console.error(`Upgrading HashPilot from ${channel}...`);
+      console.error(`Target: ${targetDir}`);
+
+      if (dryRun) {
+        finish({ success: true, message: "Dry run - would upgrade", dryRun: true, channel, targetDir, keepTelemetry, force });
+        console.error("Dry run - would upgrade");
+        return;
+      }
+
+      try {
+        const response = await fetch(installUrl);
+        if (!response.ok) {
+          throw new Error(`Failed to download install script: ${response.status} ${response.statusText}`);
+        }
+        const script = await response.text();
+
+        // Write script to temp file and execute
+        const tmpScript = join(targetDir, `.hashpilot-upgrade-${Date.now()}.sh`);
+        writeFileSync(tmpScript, script, { mode: 0o755 });
+
+        const args = ["--target", targetDir];
+        if (keepTelemetry) args.push("--keep-telemetry");
+        if (force) args.push("--force");
+
+        const proc = Bun.spawn(["bash", tmpScript, ...args], {
+          stdout: "pipe",
+          stderr: "pipe",
+          env: { ...process.env, PATH: `${join(targetDir, "bin")}:${process.env.PATH || ""}` },
+        });
+
+        const stdout = await new Response(proc.stdout).text();
+        const stderr = await new Response(proc.stderr).text();
+        const exitCode = await proc.exited;
+
+        try { rmSync(tmpScript); } catch {}
+
+        if (stdout) console.error(stdout.trim());
+        if (stderr) console.error(stderr.trim());
+
+        if (exitCode !== 0) {
+          finish({ success: false, error: `Upgrade failed with exit code ${exitCode}` }, ExitCode.INTERNAL);
+          return;
+        }
+
+        finish({ success: true, message: "Upgrade completed successfully" });
+        console.error("Upgrade completed successfully");
+      } catch (e: any) {
+        finish({ success: false, error: e.message }, ExitCode.INTERNAL);
+        console.error(`Upgrade failed: ${e.message}`);
+      }
+    });
+
+  program
+    .command("uninstall")
+    .description("Remove HashPilot and all its components from the system")
+    .option("--keep-config", "Preserve config and telemetry data")
+    .option("--force", "Skip confirmation prompt (auto-detected when piped)")
+    .option("--dry-run", "Show what would be removed without deleting anything")
+    .option("--target <dir>", "Install target directory (default: ~/.agentic-tools)")
+
+    .action(async (opts) => {
+      const targetDir = opts.target || join(process.env.HOME || "/root", ".agentic-tools");
+
+      if (opts.dryRun) {
+        const components: string[] = [];
+        const keep = Boolean(opts.keepConfig);
+        const kept = (label: string) => keep ? `${label} [preserved by --keep-config]` : label;
+        if (existsSync(join(targetDir, "bin", "hashpilot"))) components.push(`CLI launcher: ${targetDir}/bin/hashpilot`);
+        if (existsSync(join(targetDir, "structured-editing"))) components.push(`Core source: ${targetDir}/structured-editing`);
+        components.push(kept(`Telemetry logs: ${targetDir}/logs`));
+        if (existsSync(join(targetDir, "manifest.json"))) components.push(`Manifest: ${targetDir}/manifest.json`);
+        components.push(kept("Config: ~/.config/hashpilot/config.json"));
+        if (existsSync(join(process.env.HOME || "/root", ".claude", "CLAUDE.md")))
+          components.push("Claude integration: ~/.claude/CLAUDE.md (section removal)");
+        if (existsSync(join(process.env.HOME || "/root", ".config", "opencode", "skills", "hashpilot", "SKILL.md")))
+          components.push("OpenCode skill: ~/.config/opencode/skills/hashpilot/SKILL.md");
+        if (existsSync(join(process.env.HOME || "/root", ".config", "opencode", "agent", "hashpilot.md")))
+          components.push("OpenCode agent: ~/.config/opencode/agent/hashpilot.md");
+        if (existsSync(join(process.env.HOME || "/root", ".pi", "agent", "extensions", "hashpilot.ts")))
+          components.push("Pi extension: ~/.pi/agent/extensions/hashpilot.ts");
+        if (existsSync(join(process.env.HOME || "/root", ".pi", "agent", "skills", "hashpilot", "SKILL.md")))
+          components.push("Pi skill: ~/.pi/agent/skills/hashpilot/SKILL.md");
+        finish({
+          success: true,
+          dryRun: true,
+          keepConfig: Boolean(opts.keepConfig),
+          targetDir,
+          components: components.length > 0 ? components : ["Nothing to remove — no HashPilot installation detected."],
+        });
+        return;
+      }
+
+      const uninstallUrl = `https://raw.githubusercontent.com/bigknoxy/HashPilot/main/scripts/uninstall.sh`;
+      console.error(`Uninstalling HashPilot from ${targetDir}...`);
+
+      if (!opts.force && process.stdin.isTTY) {
+        console.error("This will remove HashPilot and all its components.");
+        console.error(`  Target: ${targetDir}`);
+        console.error(`  Keep config: ${Boolean(opts.keepConfig)}`);
+        console.error("  Pass --force to skip this prompt.");
+      }
+
+      try {
+        const response = await fetch(uninstallUrl);
+        if (!response.ok) {
+          throw new Error(`Failed to download uninstall script: ${response.status} ${response.statusText}`);
+        }
+        const script = await response.text();
+
+        const tmpScript = join(targetDir, `.hashpilot-uninstall-${Date.now()}.sh`);
+        try { mkdirSync(join(targetDir), { recursive: true }); } catch {}
+        writeFileSync(tmpScript, script, { mode: 0o755 });
+
+        const args: string[] = [];
+        if (opts.target) args.push("--target", opts.target);
+        if (opts.keepConfig) args.push("--keep-config");
+        if (opts.force || !process.stdin.isTTY) args.push("--force");
+
+        const proc = Bun.spawn(["bash", tmpScript, ...args], {
+          stdout: "pipe",
+          stderr: "pipe",
+          env: {
+            ...process.env,
+            HASHPILOT_DIR: targetDir,
+            PATH: `${join(targetDir, "bin")}:${process.env.PATH || ""}`,
+          },
+        });
+
+        const stdout = await new Response(proc.stdout).text();
+        const stderr = await new Response(proc.stderr).text();
+        const exitCode = await proc.exited;
+
+        try { rmSync(tmpScript); } catch {}
+
+        if (stdout) console.error(stdout.trim());
+        if (stderr) console.error(stderr.trim());
+
+        if (exitCode !== 0) {
+          finish({ success: false, error: `Uninstall failed with exit code ${exitCode}` }, ExitCode.INTERNAL);
+          return;
+        }
+
+        finish({ success: true, message: "HashPilot uninstalled successfully" });
+        console.error("Uninstall completed successfully");
+      } catch (e: any) {
+        finish({ success: false, error: e.message }, ExitCode.INTERNAL);
+        console.error(`Uninstall failed: ${e.message}`);
+      }
+    });
+}

package/src/commands/mcp.ts

@@ -0,0 +1,28 @@
+import type { Command } from "commander";
+import {
+  recordEvent,
+} from "../core/index";
+import { runStdioServer } from "../mcp/server";
+
+/** Register the `mcp` command group. */
+export function register(program: Command): void {
+  program
+    .command("mcp")
+    .description("Run HashPilot as an MCP server over stdio")
+    .option("--stdio", "Speak MCP over stdin/stdout (the only transport, and the default)")
+    .action(async () => {
+      // stdout is the protocol stream from here on, so nothing may print to it —
+      // including the JSON envelope every other command emits. The server runs
+      // until the host closes stdin; the telemetry event is recorded on the way
+      // out, when the session length is actually known.
+      const start = Date.now();
+      await runStdioServer();
+      recordEvent({
+        operation: "mcp",
+        route: "none",
+        success: true,
+        elapsed_ms: Date.now() - start,
+      });
+      process.exit(0);
+    });
+}

package/src/commands/provenance.ts

@@ -0,0 +1,111 @@
+import type { Command } from "commander";
+import {
+  ErrorCode,
+  setCurrentChangeSet,
+  listChangeSets,
+  lastChangeSetId,
+  undoChangeSet,
+  provenanceQuery,
+  changeSetQuery,
+  formatProvenanceHuman,
+  finish,
+  usageError,
+  ExitCode,
+  exitCodeFor,
+} from "../core/index";
+import { parseIntFlag } from "./shared";
+
+/** Register the `provenance` command group. */
+export function register(program: Command): void {
+  const provCmd = program
+    .command("provenance")
+    .description("Query edit provenance — who changed what, when, and why");
+
+  provCmd
+    .command("query")
+    .description("Show edit history for a file (like git blame for agent edits)")
+    .argument("<file>", "File path")
+    .argument("[line]", "Optional line number to filter by")
+    .option("--human", "Human-readable output")
+
+    .option("--fuzzy", "Include edits without diff data in line-filtered queries")
+    .option("--limit <n>", "Max entries to show")
+    .action((file, line, opts) => {
+      const lineNum = line ? parseInt(line) : undefined;
+      let results = provenanceQuery(file, lineNum, !!opts.fuzzy);
+      if (opts.limit) results = results.slice(0, parseInt(opts.limit));
+      if (opts.human) {
+        console.log(formatProvenanceHuman(results));
+        return;
+      }
+      // A file with no recorded edits is an empty history, not a failure.
+      finish(results, ExitCode.OK);
+    });
+
+  provCmd
+    .command("changeset")
+    .description("Show all edits in a changeSet")
+    .argument("<changeSetId>", "ChangeSet UUID")
+    .option("--human", "Human-readable output")
+    .action((changeSetId, opts) => {
+      const result = changeSetQuery(changeSetId);
+      if (!result) {
+        return finish(
+          {
+            success: false,
+            errorCode: ErrorCode.FILE_NOT_FOUND,
+            changeSetId,
+            message: `No edits found for changeSet: ${changeSetId}`,
+            recovery: "hashpilot telemetry sessions",
+          },
+          ExitCode.USAGE,
+        );
+      }
+      if (opts.human) {
+        console.log(`ChangeSet: ${result.changeSetId}`);
+        console.log(`Actor: ${result.actor}`);
+        console.log(`Task: ${result.taskId ?? "N/A"}`);
+        console.log(`Reason: ${result.reason}`);
+        console.log(`Edits: ${result.editCount}`);
+        console.log(`Time: ${result.timeRange.first} -- ${result.timeRange.last}\n`);
+        console.log(formatProvenanceHuman(result.entries));
+        process.exitCode = exitCodeFor(result);
+      } else {
+        finish(result);
+      }
+    });
+
+  program
+    .command("changesets")
+    .description("List undoable changeSets, newest first")
+    .option("--limit <n>", "Max changeSets to list (default 20)")
+    .action((opts) => {
+      const limit = parseIntFlag(opts.limit, "--limit", 20);
+      if (typeof limit === "object") return usageError(limit.error);
+      finish({ changeSets: listChangeSets(limit) }, ExitCode.OK);
+    });
+
+  program
+    .command("undo")
+    .description("Restore every file in a changeSet to its pre-edit contents")
+    .argument("[changeSetId]", "ChangeSet to undo; omit with --last")
+    .option("--last", "Undo the most recent changeSet")
+    .option("--force", "Restore even files modified since the edit was applied")
+    .option("--dry-run", "Report what would be restored without touching the disk")
+    .action((changeSetId, opts) => {
+      const id = opts.last ? lastChangeSetId() : changeSetId;
+      if (!id) {
+        return usageError(
+          opts.last
+            ? "No changeSets have been recorded yet."
+            : "Provide a changeSet ID, or pass --last.",
+          { recovery: "hashpilot changesets" },
+        );
+      }
+      // The undo's own write must not be snapshotted as a new changeSet — that
+      // would make `undo --last` toggle between two states forever.
+      setCurrentChangeSet(null);
+      const result = undoChangeSet(id, { force: Boolean(opts.force), dryRun: Boolean(opts.dryRun) });
+      finish(result, result.success ? ExitCode.OK : ExitCode.PRECONDITION);
+    });
+}

package/src/commands/read.ts

@@ -0,0 +1,117 @@
+import type { Command } from "commander";
+import {
+  readMany,
+  readHash,
+  grepMany,
+  symbolLookupMany,
+  recordEvent,
+  safeWrite,
+  finish,
+  usageError,
+} from "../core/index";
+import { parseIntFlag } from "./shared";
+
+/** Register the `read` command group. */
+export function register(program: Command): void {
+  program
+    .command("read-many")
+    .description("Read multiple files, return content + hashes")
+    .argument("<files...>", "File paths")
+
+    .action(async (files: string[], opts) => {
+      const start = Date.now();
+      const results = await readMany(files);
+      recordEvent({
+        operation: "read-many",
+        route: "read",
+        files_count: files.length,
+        success: !results.some((r) => r.error),
+        elapsed_ms: Date.now() - start,
+      });
+      finish(results);
+    });
+
+  program
+    .command("read-hash")
+    .description("Read a line with hash and context")
+    .argument("<file>", "File path")
+    .argument("<line>", "Line number", parseInt)
+    .option("-c, --context <n>", "Context lines", "3")
+
+    .action(async (file: string, line: number, opts) => {
+      const start = Date.now();
+      const context = parseIntFlag(opts.context, "--context", 3);
+      if (typeof context === "object") return usageError(context.error, { path: file });
+      const result = await readHash(file, line, context);
+      recordEvent({
+        operation: "read-hash",
+        route: "hash",
+        file,
+        success: !result.error,
+        lines_read: 1 + (result.contextBefore?.length || 0) + (result.contextAfter?.length || 0),
+        elapsed_ms: Date.now() - start,
+      });
+      finish(result);
+    });
+
+  program
+    .command("grep-many")
+    .description(
+      'Search pattern across multiple paths. Usage: grep-many "safeWrite" src/ ' +
+        '(or the flag form: grep-many --pattern "safeWrite" --path src/)',
+    )
+    .argument("[pattern]", "Regex pattern (or use --pattern)")
+    .argument("[paths...]", "Paths to search (or use --path)")
+    .option("-i, --ignore-case", "Case insensitive")
+    .option("--pattern <p>", "Regex pattern, flag form of the positional")
+    .option(
+      "--path <dir>",
+      "Path to search, flag form of the positional (repeatable)",
+      (value: string, previous: string[]) => previous.concat([value]),
+      [] as string[],
+    )
+    .option("--file-pattern <glob>", "File pattern filter")
+    .option("--max-results <n>", "Max results", parseInt)
+
+    .action(async (patternArg: string | undefined, pathsArg: string[], opts) => {
+      if (patternArg !== undefined && opts.pattern !== undefined) {
+        return usageError('Pass the pattern positionally or as --pattern, not both.');
+      }
+      if (pathsArg.length > 0 && opts.path.length > 0) {
+        return usageError("Pass the paths positionally or as --path, not both.");
+      }
+      const pattern = patternArg ?? opts.pattern;
+      const paths = pathsArg.length > 0 ? pathsArg : opts.path;
+      if (!pattern) {
+        return usageError('A pattern is required: grep-many "<pattern>" <paths...> (or --pattern/--path).');
+      }
+      if (paths.length === 0) {
+        return usageError('At least one path is required: grep-many "<pattern>" <paths...> (or --pattern/--path).');
+      }
+      const result = await grepMany(pattern, paths, {
+        ignoreCase: opts.ignoreCase,
+        filePattern: opts.filePattern,
+        maxResults: opts.maxResults,
+      });
+      recordEvent({
+        operation: "grep-many",
+        route: "grep",
+        files_count: paths.length,
+        success: !result.error,
+        elapsed_ms: result.elapsed_ms,
+      });
+      finish(result);
+    });
+
+  program
+    .command("symbol-lookup-many")
+    .description("Find symbol definitions. Usage: symbol-lookup-many <paths...> --names n1,n2")
+    .argument("<paths...>", "Paths to search")
+    .option("--names <names>", "Comma-separated symbol names")
+
+    .action(async (paths: string[], opts) => {
+      const names = (opts.names || "").split(",").filter(Boolean);
+      const results = await symbolLookupMany(names, paths);
+      finish(results);
+    });
+}

package/src/commands/route.ts

@@ -0,0 +1,42 @@
+import type { Command } from "commander";
+import {
+  detectLanguage,
+  chooseRoute,
+  loadConfig,
+  finish,
+} from "../core/index";
+
+/** Register the `route` command group. */
+export function register(program: Command): void {
+  program
+    .command("route")
+    .description("Show which edit route would be chosen (with detailed explanation)")
+    .argument("<file>", "File path")
+    .argument("<operation>", "Operation name")
+    .option("--policy <json>", "Inline policy JSON to test")
+    .option("--no-default-config", "Ignore config file policies")
+    .action((file: string, operation: string, opts) => {
+      const lang = detectLanguage(file);
+      let policy = opts.policy ? JSON.parse(opts.policy) : undefined;
+      if (!policy && !opts.defaultConfig) {
+        policy = loadConfig().routePolicy;
+      }
+      const { route, explanation } = chooseRoute(file, operation, policy);
+      finish({
+        file,
+        operation,
+        language: lang,
+        route,
+        explanation,
+      });
+    });
+
+  program
+    .command("config")
+    .description("Show current HashPilot configuration")
+    .option("--config <path>", "Config file path override")
+    .action((opts) => {
+      const config = loadConfig(opts.config);
+      finish(config);
+    });
+}

package/src/commands/shared.ts

@@ -0,0 +1,65 @@
+import type { Command } from "commander";
+
+/**
+ * Parse `--range`. Accepts `N` (meaning `N:N`) or `N:M`, both 1-indexed and
+ * inclusive. Returns an error string rather than throwing so the caller can
+ * emit it through `usageError`.
+ *
+ * The old implementation was `opts.range.split(":").map(Number)`, which turned
+ * `--range 5` into `{start: 5, end: NaN}` and silently duplicated the file.
+ */
+export function parseRange(raw: string): { range: { start: number; end: number } } | { error: string } {
+  const match = /^(\d+)(?::(\d+))?$/.exec(raw.trim());
+  if (!match) {
+    return { error: `Invalid --range "${raw}": expected N or N:M with positive integers.` };
+  }
+  const start = Number(match[1]);
+  const end = match[2] === undefined ? start : Number(match[2]);
+  if (start < 1) return { error: `Invalid --range "${raw}": line numbers are 1-indexed.` };
+  if (start > end) return { error: `Invalid --range "${raw}": start is after end.` };
+  return { range: { start, end } };
+}
+
+/** Parse a numeric flag, rejecting the NaN that bare `parseInt` yields on garbage. */
+export function parseIntFlag(raw: string | undefined, name: string, fallback: number): number | { error: string } {
+  if (raw === undefined) return fallback;
+  if (!/^\d+$/.test(String(raw).trim())) {
+    return { error: `Invalid ${name} "${raw}": expected a non-negative integer.` };
+  }
+  return Number(raw);
+}
+
+/**
+ * The provenance flag trio, previously copy-pasted onto nine commands (#48).
+ * Appended last so `--help` output keeps the order it always had.
+ */
+export function withProvenance(cmd: Command): Command {
+  return cmd
+    .option("--actor <name>", "Agent identity for provenance tracking")
+    .option("--task-id <id>", "Task/issue reference for provenance")
+    .option("--reason <text>", "Human-readable reason for the edit");
+}
+
+/** The routed-edit flag block shared by `route-edit` and `batch` (#48). */
+export function withEditFlags(cmd: Command): Command {
+  return cmd
+    .option("--method <route>", "Force a specific route (ast, hash, diff)")
+    .option("--old-hash <hash>", "Hash for hash-route verification")
+    .option("--new-content <text>", "New content (or @file)")
+    .option("--old-content <text>", "Old content for diff-route search-and-replace")
+    .option("--range <start:end>", "Line range for hash route")
+    .option("--old-name <name>", "Old symbol name (rename-symbol)")
+    .option("--new-name <name>", "New symbol name (rename-symbol)")
+    .option("--symbol <name>", "Symbol name (replace-body, insert-before, insert-after)")
+    .option("--new-body <text>", "New body statements only — no braces, no indentation (replace-body, or @file)")
+    .option("--import-spec <spec>", 'Import spec, module path quoted: \'{ Foo } from "./bar"\'')
+    .option("--content <text>", "Content (insert-before, insert-after, or @file)")
+    .option("--policy <json>", "Inline RoutePolicy JSON");
+}
+
+/** `--dry-run` + `--include-source`, shared by every previewing edit command. */
+export function withPreview(cmd: Command, dryRunDescription = "Preview without writing"): Command {
+  return cmd
+    .option("--dry-run", dryRunDescription)
+    .option("--include-source", "On a dry run, return the whole post-edit file instead of a diff");
+}

package/src/commands/telemetry.ts

@@ -0,0 +1,126 @@
+import type { Command } from "commander";
+import {
+  readEvents,
+  lastReadSkipped,
+  clearEvents,
+  summary,
+  health,
+  healthTrend,
+  listSessions,
+  exportEvents,
+  pruneEvents,
+  finish,
+  usageError,
+  addWarning,
+  ExitCode,
+} from "../core/index";
+import { parseIntFlag } from "./shared";
+
+/** Register the `telemetry` command group. */
+export function register(program: Command): void {
+  /**
+   * Corruption must be visible. It rides the envelope's `warnings` array (so a
+   * machine consumer sees it) and stderr (so a human running the command does).
+   */
+  function warnSkipped(): void {
+    const skipped = lastReadSkipped();
+    if (skipped > 0) {
+      const message = `skipped ${skipped} malformed telemetry line(s) — the log is corrupt`;
+      addWarning({ code: "TELEMETRY_LOG_CORRUPT", message, skipped });
+      console.error(`warning: ${message}`);
+    }
+  }
+
+  const telCmd = program
+    .command("telemetry")
+    .description("View or manage telemetry");
+
+  telCmd
+    .command("show")
+    .description("Show recent telemetry events")
+    .option("-n, --limit <n>", "Number of events", "20")
+    .action(async (opts) => {
+      const limit = parseIntFlag(opts.limit, "--limit", 20);
+      if (typeof limit === "object") return usageError(limit.error);
+      const events = readEvents(limit);
+      warnSkipped();
+      // A telemetry event's `success` field describes the operation it recorded,
+      // not this query. Letting `finish` infer the code turns "your log contains a
+      // failure" into "the query failed" (exit 2). Reads that complete are exit 0.
+      finish(events, ExitCode.OK);
+    });
+
+  telCmd
+    .command("summary")
+    .description("Show telemetry summary")
+    .action(() => {
+      const result = summary();
+      warnSkipped();
+      // Read-only query: see the note on `telemetry show`.
+      finish(result, ExitCode.OK);
+    });
+
+  telCmd
+    .command("health")
+    .description("Show telemetry health report with per-language stats and threshold warnings")
+    .option("-w, --window <days>", "Time window in days", "7")
+    .option("-t, --trend", "Compare current window to previous window")
+    .action((opts) => {
+      const window = parseIntFlag(opts.window, "--window", 7);
+      if (typeof window === "object") return usageError(window.error);
+      const report = opts.trend ? healthTrend(window) : health(window);
+      warnSkipped();
+      // Read-only query: see the note on `telemetry show`.
+      finish(report, ExitCode.OK);
+    });
+
+  telCmd
+    .command("clear")
+    .description("Clear telemetry log")
+    .action(() => {
+      clearEvents();
+      finish({ success: true, message: "Telemetry cleared." }, ExitCode.OK);
+    });
+
+  telCmd
+    .command("sessions")
+    .description("List session summaries")
+    .action(() => {
+      const sessions = listSessions();
+      warnSkipped();
+      // Read-only query: see the note on `telemetry show`.
+      finish(sessions, ExitCode.OK);
+    });
+
+  telCmd
+    .command("export")
+    .description("Export telemetry events as NDJSON")
+    .option("--from <date>", "Start date (ISO format)")
+    .option("--to <date>", "End date (ISO format)")
+    .option("--session <id>", "Session ID filter")
+    .option("--ndjson", "Stream one compact event per line instead of the JSON envelope")
+    .action((opts) => {
+      const events = exportEvents({
+        from: opts.from ? new Date(opts.from) : undefined,
+        to: opts.to ? new Date(opts.to) : undefined,
+        sessionId: opts.session,
+      });
+      warnSkipped();
+      // Default to the envelope like every other command; `--ndjson` keeps the
+      // streamable one-object-per-line form for pipes into jq and friends.
+      if (opts.ndjson) {
+        for (const e of events) console.log(JSON.stringify(e));
+        return;
+      }
+      finish(events, ExitCode.OK);
+    });
+
+  telCmd
+    .command("prune")
+    .description("Delete old rotated telemetry files")
+    .option("-d, --older-than <days>", "Days threshold", "30")
+    .action((opts) => {
+      const deleted = pruneEvents(parseInt(opts.olderThan));
+      finish({ success: true, deleted, message: `Pruned ${deleted} telemetry file(s).` }, ExitCode.OK);
+    });
+}