@aiaiai-pt/martha-cli 0.69.0 → 0.70.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to `@aiaiai-pt/martha-cli`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project adheres to semver — `0.x` releases may include breaking changes between minor versions.
 
+## [0.70.0] — 2026-11-14
+
+### Added
+
+- `martha chat --events-file <path>` writes lifecycle events (session, turns, approvals, exit) as JSONL so a terminal host can follow the session without reading the screen. Each line is `{"v":1,"ts":<epoch ms>,"event":"..."}`. Events: `session` (REPL start and `/history` switch), `turn_started`, `turn_ended` (with `ok` and `pending_approvals`), `approval_resolved`, `exit`. Interactive REPL only; no message text, tool args/results, tokens or keys in any event. The file is created 0600; an unwritable path fails before session creation (#2633).
+- `martha sessions get <id>` prints a single session; `--json` gives the full object. A nonexistent session exits non-zero with a clear "not found" message distinct from auth/network errors (#2633).
+
 ## [0.69.0] — 2026-11-13
 
 ### Added

package/dist/index.js

@@ -11244,9 +11244,10 @@ init_config();
 init_errors();
 
 // src/version.ts
-var CLI_VERSION = "0.69.0";
+var CLI_VERSION = "0.70.0";
 
 // src/commands/sessions.ts
+init_errors();
 function relativeTime(iso) {
   const now = Date.now();
   const then = new Date(iso).getTime();
@@ -11319,6 +11320,46 @@ function printSessionTable(sessions) {
     }).join("  "));
   }
 }
+async function fetchSession(ctx, sessionId) {
+  try {
+    return await ctx.api.get(`/api/sessions/${encodeURIComponent(sessionId)}`);
+  } catch (err) {
+    if (!(err instanceof MarthaAPIError && err.status === 405))
+      throw err;
+  }
+  const PAGE = 50;
+  let skip = 0;
+  for (;; ) {
+    const data = await fetchSessions(ctx, {
+      limit: PAGE,
+      skip,
+      includeArchived: true
+    });
+    const match = data.items.find((s) => s.session_id === sessionId);
+    if (match)
+      return match;
+    skip += data.items.length;
+    if (skip >= data.total || data.items.length === 0)
+      break;
+  }
+  throw new CLIError(`Session not found: ${sessionId}`, 3 /* NotFound */, "Check the ID with `martha sessions list`.");
+}
+function printSessionDetail(session) {
+  const rows = [
+    ["Session ID", session.session_id],
+    ["Title", session.title ?? source_default.dim("(untitled)")],
+    ["Type", session.session_type],
+    ["Client", session.client_name],
+    ["Messages", String(session.message_count)],
+    ["Created", session.created_at],
+    ["Last Active", session.last_active],
+    ["Active", session.is_active ? "yes" : "no"]
+  ];
+  const labelWidth = Math.max(...rows.map(([k]) => k.length)) + 1;
+  for (const [label, value] of rows) {
+    console.log(`${source_default.bold((label + ":").padEnd(labelWidth + 1))} ${value}`);
+  }
+}
 function registerSessionCommands(program) {
   const cmd = program.command("sessions").description("Browse conversation history");
   function getCtx() {
@@ -11356,6 +11397,51 @@ Showing ${data.items.length} of ${data.total} sessions. Use --skip and --limit t
 ${data.total} session(s)`));
     }
   });
+  cmd.command("get <id>").description("Show a single session by ID").action(async (id) => {
+    const ctx = getCtx();
+    const session = await fetchSession(ctx, id);
+    if (isJson()) {
+      console.log(JSON.stringify(session, null, 2));
+      return;
+    }
+    printSessionDetail(session);
+  });
+}
+
+// src/lib/events-file.ts
+import fs5 from "node:fs";
+function createEventsWriter(filePath) {
+  let fd = null;
+  function ensureOpen() {
+    if (fd !== null)
+      return fd;
+    fd = fs5.openSync(filePath, fs5.constants.O_WRONLY | fs5.constants.O_CREAT | fs5.constants.O_APPEND, 384);
+    return fd;
+  }
+  return {
+    write(payload) {
+      const line = {
+        v: 1,
+        ts: Date.now(),
+        ...payload
+      };
+      const data = JSON.stringify(line) + `
+`;
+      const f = ensureOpen();
+      fs5.writeSync(f, data);
+    }
+  };
+}
+function validateEventsFilePath(filePath) {
+  let fd;
+  try {
+    fd = fs5.openSync(filePath, fs5.constants.O_WRONLY | fs5.constants.O_CREAT | fs5.constants.O_APPEND, 384);
+  } catch {
+    throw new Error(`Cannot write events file to ${filePath} — the path does not exist or is not writable.`);
+  } finally {
+    if (fd !== undefined)
+      fs5.closeSync(fd);
+  }
 }
 
 // src/commands/agents.ts
@@ -12431,7 +12517,7 @@ init_errors();
 // src/lib/local-exec.ts
 import { spawn } from "node:child_process";
 import { randomBytes as randomBytes2 } from "node:crypto";
-import { closeSync, openSync, promises as fs5 } from "node:fs";
+import { closeSync, openSync, promises as fs6 } from "node:fs";
 import * as path4 from "node:path";
 function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
@@ -12443,14 +12529,14 @@ function runnerDir(cwd) {
 }
 async function runHostCommand(command, toolCallId, opts) {
   const dir = runnerDir(opts.cwd);
-  await fs5.mkdir(dir, { recursive: true });
+  await fs6.mkdir(dir, { recursive: true });
   const logPath = path4.join(dir, `${safeName(toolCallId)}.log`);
-  await fs5.writeFile(logPath, "");
+  await fs6.writeFile(logPath, "");
   const fd = openSync(logPath, "a");
   const cap = opts.maxOutputBytes ?? MAX_OUTPUT;
   const readLog = async () => {
     try {
-      const buf = await fs5.readFile(logPath);
+      const buf = await fs6.readFile(logPath);
       return buf.subarray(-cap).toString("utf8");
     } catch {
       return "";
@@ -12528,7 +12614,7 @@ class Journal {
   }
   async load() {
     try {
-      const raw = JSON.parse(await fs5.readFile(this.file(), "utf8"));
+      const raw = JSON.parse(await fs6.readFile(this.file(), "utf8"));
       if (raw["entries"] !== undefined) {
         const f = raw;
         if (!f.secrets)
@@ -12547,31 +12633,31 @@ class Journal {
     }
   }
   async save(data) {
-    await fs5.mkdir(runnerDir(this.cwd), { recursive: true });
+    await fs6.mkdir(runnerDir(this.cwd), { recursive: true });
     const tmp = `${this.file()}.${randomBytes2(6).toString("hex")}.tmp`;
-    await fs5.writeFile(tmp, JSON.stringify(data, null, 2));
-    await fs5.rename(tmp, this.file());
+    await fs6.writeFile(tmp, JSON.stringify(data, null, 2));
+    await fs6.rename(tmp, this.file());
   }
   chain = Promise.resolve();
   async acquireFileLock() {
     const lockPath = path4.join(runnerDir(this.cwd), "journal.lock");
-    await fs5.mkdir(runnerDir(this.cwd), { recursive: true });
+    await fs6.mkdir(runnerDir(this.cwd), { recursive: true });
     const deadline = Date.now() + 5000;
     for (;; ) {
       try {
-        const fh = await fs5.open(lockPath, "wx");
+        const fh = await fs6.open(lockPath, "wx");
         await fh.write(String(process.pid));
         await fh.close();
         return async () => {
-          await fs5.rm(lockPath, { force: true });
+          await fs6.rm(lockPath, { force: true });
         };
       } catch (e) {
         if (e.code !== "EEXIST")
           throw e;
         try {
-          const st = await fs5.stat(lockPath);
+          const st = await fs6.stat(lockPath);
           if (Date.now() - st.mtimeMs > 1e4) {
-            await fs5.rm(lockPath, { force: true });
+            await fs6.rm(lockPath, { force: true });
             continue;
           }
         } catch {
@@ -12934,7 +13020,7 @@ class BrowserSession {
 }
 
 // src/lib/host-files.ts
-import { promises as fs6 } from "node:fs";
+import { promises as fs7 } from "node:fs";
 import * as os3 from "node:os";
 import * as path5 from "node:path";
 var READ_CAP = 256 * 1024;
@@ -12954,7 +13040,7 @@ async function applyFileAction(cwd, req) {
   try {
     switch (req.action) {
       case "host_read": {
-        const raw = await fs6.readFile(abs, "utf8");
+        const raw = await fs7.readFile(abs, "utf8");
         let body = raw;
         if (typeof req.offset === "number" || typeof req.limit === "number") {
           const lines = raw.split(`
@@ -12973,8 +13059,8 @@ async function applyFileAction(cwd, req) {
       case "host_write": {
         if (typeof req.content !== "string")
           return { error: true, message: "host_write requires `content`" };
-        await fs6.mkdir(path5.dirname(abs), { recursive: true });
-        await fs6.writeFile(abs, req.content, "utf8");
+        await fs7.mkdir(path5.dirname(abs), { recursive: true });
+        await fs7.writeFile(abs, req.content, "utf8");
         return {
           text: `Wrote ${Buffer.byteLength(req.content, "utf8")} bytes to ${req.path}.`
         };
@@ -12990,7 +13076,7 @@ async function applyFileAction(cwd, req) {
             error: true,
             message: "old_string and new_string are identical"
           };
-        const raw = await fs6.readFile(abs, "utf8");
+        const raw = await fs7.readFile(abs, "utf8");
         const count = req.oldString ? raw.split(req.oldString).length - 1 : 0;
         if (count === 0)
           return { error: true, message: "old_string not found in file" };
@@ -13000,7 +13086,7 @@ async function applyFileAction(cwd, req) {
             message: `old_string is not unique (${count} matches); pass replace_all=true to replace all`
           };
         const next = req.replaceAll ? raw.split(req.oldString).join(req.newString) : raw.replace(req.oldString, req.newString);
-        await fs6.writeFile(abs, next, "utf8");
+        await fs7.writeFile(abs, next, "utf8");
         return {
           text: `Edited ${req.path} (${req.replaceAll ? count : 1} replacement${(req.replaceAll ? count : 1) === 1 ? "" : "s"}).`
         };
@@ -13047,7 +13133,7 @@ function parseHostFileRequests(data) {
 // src/lib/local-jobs.ts
 import { execFileSync, spawn as spawn2 } from "node:child_process";
 import { randomBytes as randomBytes3 } from "node:crypto";
-import { closeSync as closeSync2, openSync as openSync2, readFileSync, promises as fs7 } from "node:fs";
+import { closeSync as closeSync2, openSync as openSync2, readFileSync, promises as fs8 } from "node:fs";
 import * as path6 from "node:path";
 var POLL_CAP = 64 * 1024;
 function mintJobId() {
@@ -13088,7 +13174,7 @@ function isProcessAlive(pid) {
 }
 async function readSentinel(p) {
   try {
-    const raw = (await fs7.readFile(p, "utf8")).trim();
+    const raw = (await fs8.readFile(p, "utf8")).trim();
     if (raw === "")
       return { present: true };
     const n = parseInt(raw, 10);
@@ -13099,25 +13185,25 @@ async function readSentinel(p) {
 }
 async function readLogOrNull(p) {
   try {
-    return await fs7.readFile(p);
+    return await fs8.readFile(p);
   } catch {
     return null;
   }
 }
 async function writeSentinelAtomic(p, content) {
   const tmp = `${p}.${randomBytes3(4).toString("hex")}.tmp`;
-  await fs7.writeFile(tmp, content);
-  await fs7.rename(tmp, p);
+  await fs8.writeFile(tmp, content);
+  await fs8.rename(tmp, p);
 }
 async function dispatchBackgroundJob(command, jobId, journal, opts) {
   if (process.platform === "win32") {
     throw new Error("background jobs are not supported on Windows (POSIX-only: /bin/sh + " + "process groups). Run this command in the foreground instead.");
   }
   const dir = runnerDir2(opts.cwd);
-  await fs7.mkdir(dir, { recursive: true });
+  await fs8.mkdir(dir, { recursive: true });
   const logPath = path6.join(dir, `${jobId}.log`);
   const sentinelPath = path6.join(dir, `${jobId}.exit`);
-  await fs7.writeFile(logPath, "");
+  await fs8.writeFile(logPath, "");
   const fd = openSync2(logPath, "a");
   const env = { ...process.env, MARTHA_JOB_SENTINEL: sentinelPath };
   const stdin = opts.stdinData != null ? "pipe" : "ignore";
@@ -14011,7 +14097,7 @@ async function stageApprovalConfirmation(ctx, command, args) {
 ` + renderApprovalDetail(item) + `
 `);
     process.stderr.write(source_default.dim(`${verb} this case under your own user (not the agent)? [y/N] `));
-    return { id, decision, comment };
+    return { id: String(item.id ?? id), decision, comment };
   } catch (err) {
     printApprovalError(err);
     return null;
@@ -14023,7 +14109,7 @@ async function applyPendingApproval(ctx, pending, answer) {
     process.stderr.write(source_default.dim(`Cancelled.
 
 `));
-    return;
+    return false;
   }
   const verb = pending.decision === "approved" ? "Approved" : "Rejected";
   try {
@@ -14031,8 +14117,10 @@ async function applyPendingApproval(ctx, pending, answer) {
     process.stderr.write(source_default.green(`${verb} case ${shortId(pending.id)}.
 
 `));
+    return true;
   } catch (err) {
     printApprovalError(err);
+    return false;
   }
 }
 async function showHistoryPicker(ctx, rl) {
@@ -14073,13 +14161,16 @@ async function showHistoryPicker(ctx, rl) {
   }
   return data.items[idx].session_id;
 }
-async function runRepl(ctx, initialSessionId, clientId, agentName, showTools, timeoutMs, localExec) {
+async function runRepl(ctx, initialSessionId, clientId, agentName, showTools, timeoutMs, localExec, eventsWriter) {
   let sessionId = initialSessionId;
   process.stderr.write(source_default.dim(`martha v${CLI_VERSION} | session: ${sessionId.slice(0, 8)}...
 `));
   process.stderr.write(source_default.dim(`Type a message, or /help for commands.
 
 `));
+  if (eventsWriter) {
+    eventsWriter.write({ event: "session", session_id: sessionId });
+  }
   const rl = createInterface2({
     input: process.stdin,
     output: process.stderr,
@@ -14089,6 +14180,7 @@ async function runRepl(ctx, initialSessionId, clientId, agentName, showTools, ti
   let activeAbort = null;
   let streaming = false;
   let pendingApproval = null;
+  let exitWritten = false;
   rl.on("SIGINT", () => {
     if (pendingApproval) {
       pendingApproval = null;
@@ -14108,6 +14200,10 @@ Cancelled.
       activeAbort = null;
       rl.prompt();
     } else {
+      if (eventsWriter && !exitWritten) {
+        eventsWriter.write({ event: "exit" });
+        exitWritten = true;
+      }
       process.stderr.write(`
 `);
       rl.close();
@@ -14119,7 +14215,14 @@ Cancelled.
     if (pendingApproval) {
       const p = pendingApproval;
       pendingApproval = null;
-      await applyPendingApproval(ctx, p, input);
+      const resolved = await applyPendingApproval(ctx, p, input);
+      if (resolved && eventsWriter) {
+        eventsWriter.write({
+          event: "approval_resolved",
+          case_id: p.id,
+          decision: p.decision
+        });
+      }
       rl.prompt();
       continue;
     }
@@ -14177,6 +14280,9 @@ Cancelled.
             process.stderr.write(source_default.green(`Switched to session ${sessionId.slice(0, 8)}...
 
 `));
+            if (eventsWriter) {
+              eventsWriter.write({ event: "session", session_id: sessionId });
+            }
           }
           break;
         }
@@ -14197,6 +14303,10 @@ Cancelled.
           break;
         }
         case "quit":
+          if (eventsWriter && !exitWritten) {
+            eventsWriter.write({ event: "exit" });
+            exitWritten = true;
+          }
           rl.close();
           return;
       }
@@ -14205,8 +14315,12 @@ Cancelled.
     }
     streaming = true;
     activeAbort = new AbortController;
+    if (eventsWriter) {
+      eventsWriter.write({ event: "turn_started", session_id: sessionId });
+    }
     let stripper = createApprovalTagStripper();
     const approvalHints = [];
+    const turnApprovalCaseIds = [];
     try {
       const result = await sendMessage(ctx, sessionId, input, {
         timeoutMs,
@@ -14219,6 +14333,9 @@ Cancelled.
           const hint = approvalHintFromToolResult(data);
           if (hint)
             approvalHints.push(hint);
+          const parsed = parsePendingApprovalHint(data);
+          if (parsed)
+            turnApprovalCaseIds.push(parsed.caseId);
         },
         onToolStatus: (data) => {
           const out = formatToolStatus(data);
@@ -14245,7 +14362,23 @@ Cancelled.
           process.stderr.write(hint + `
 `);
       }
+      if (eventsWriter) {
+        eventsWriter.write({
+          event: "turn_ended",
+          session_id: sessionId,
+          ok: !result.aborted,
+          pending_approvals: turnApprovalCaseIds
+        });
+      }
     } catch (err) {
+      if (eventsWriter) {
+        eventsWriter.write({
+          event: "turn_ended",
+          session_id: sessionId,
+          ok: false,
+          pending_approvals: turnApprovalCaseIds
+        });
+      }
       if (activeAbort.signal.aborted) {} else if (err instanceof CLIError) {
         process.stderr.write(source_default.red(`
 Error: ${err.message}
@@ -14263,6 +14396,10 @@ Error: ${err instanceof Error ? err.message : String(err)}
     }
     rl.prompt();
   }
+  if (eventsWriter && !exitWritten) {
+    eventsWriter.write({ event: "exit" });
+    exitWritten = true;
+  }
   process.stderr.write(`
 `);
 }
@@ -14314,7 +14451,7 @@ async function runOneShot(ctx, sessionId, message, isJson, clientId, agentName,
   }
 }
 function registerChatCommand(program) {
-  program.command("chat").description("Chat with a Martha agent").option("--session <id>", "Resume an existing session").option("--client <nameOrId>", "Use a specific client (name or ID)").option("--agent <name>", "Drive the chat with a specific copilot agent (defaults to profile.default_agent)").option("--message <text>", "Send a single message (non-interactive)").option("--show-tools", "Show tool calls and results during chat").option("--local-exec", "Allow the agent to run host tools on THIS machine (#568). Requires the server to have LOCAL_EXEC_ENABLED=1.").option("--yes", "Auto-approve host tool execution (required with --local-exec for non-interactive runs).").option("--local-agent <name>", "Which local coding agent `local_agent` delegates to: a preset (claude | codex | cursor-agent) or a raw command. Overrides MARTHA_LOCAL_AGENT_CMD and `config local_agent` for this run.").option("--timeout <seconds>", "Per-message HTTP timeout in seconds (default: 600)").action(async (opts) => {
+  program.command("chat").description("Chat with a Martha agent").option("--session <id>", "Resume an existing session").option("--client <nameOrId>", "Use a specific client (name or ID)").option("--agent <name>", "Drive the chat with a specific copilot agent (defaults to profile.default_agent)").option("--message <text>", "Send a single message (non-interactive)").option("--show-tools", "Show tool calls and results during chat").option("--local-exec", "Allow the agent to run host tools on THIS machine (#568). Requires the server to have LOCAL_EXEC_ENABLED=1.").option("--yes", "Auto-approve host tool execution (required with --local-exec for non-interactive runs).").option("--local-agent <name>", "Which local coding agent `local_agent` delegates to: a preset (claude | codex | cursor-agent) or a raw command. Overrides MARTHA_LOCAL_AGENT_CMD and `config local_agent` for this run.").option("--timeout <seconds>", "Per-message HTTP timeout in seconds (default: 600)").option("--events-file <path>", "Write lifecycle events (session, turns, approvals, exit) as JSONL to this file. For terminal hosts that need to follow the session without reading the screen.").action(async (opts) => {
     const ctx = createContext({
       profileOverride: program.opts().profile,
       verbose: program.opts().verbose
@@ -14356,6 +14493,10 @@ function registerChatCommand(program) {
         }
       } catch {}
     }
+    const eventsFilePath = opts.eventsFile;
+    if (eventsFilePath) {
+      validateEventsFilePath(eventsFilePath);
+    }
     let sessionId;
     if (opts.session) {
       sessionId = opts.session;
@@ -14372,7 +14513,8 @@ function registerChatCommand(program) {
       if (isJson) {
         throw new CLIError("The --json flag requires --message for non-interactive mode.", 4 /* Validation */, 'Example: martha --json chat --message "hello"');
       }
-      await runRepl(ctx, sessionId, clientId, agentName, showTools, timeoutMs, localExec);
+      const eventsWriter = eventsFilePath ? createEventsWriter(eventsFilePath) : undefined;
+      await runRepl(ctx, sessionId, clientId, agentName, showTools, timeoutMs, localExec, eventsWriter);
     }
   });
 }
@@ -15886,7 +16028,7 @@ function registerConfigCommand(program) {
 
 // src/commands/definitions-apply.ts
 import { createHash as createHash3 } from "node:crypto";
-import fs8 from "node:fs";
+import fs9 from "node:fs";
 import path8 from "node:path";
 init_dist();
 init_errors();
@@ -16181,17 +16323,17 @@ function validateAgentWriteBody(body, source) {
 }
 function loadDefinitions(inputPath) {
   const resolved = path8.resolve(inputPath);
-  if (!fs8.existsSync(resolved)) {
+  if (!fs9.existsSync(resolved)) {
     throw new CLIError(`Path not found: ${inputPath}`, 1 /* Error */);
   }
-  const stat = fs8.statSync(resolved);
+  const stat = fs9.statSync(resolved);
   if (stat.isDirectory()) {
     return loadDirectory(resolved);
   }
   return loadFile(resolved);
 }
 function loadDirectory(dirPath) {
-  const entries = fs8.readdirSync(dirPath).sort();
+  const entries = fs9.readdirSync(dirPath).sort();
   const validExts = new Set([".yaml", ".yml", ".json"]);
   const files = entries.filter((e) => validExts.has(path8.extname(e).toLowerCase())).map((e) => path8.join(dirPath, e));
   if (files.length === 0) {
@@ -16204,7 +16346,7 @@ function loadDirectory(dirPath) {
   return results;
 }
 function loadFile(filePath) {
-  const content = fs8.readFileSync(filePath, "utf-8");
+  const content = fs9.readFileSync(filePath, "utf-8");
   const ext = path8.extname(filePath).toLowerCase();
   if (ext === ".json") {
     const parsed = parseJsonFile(content, filePath);
@@ -16947,7 +17089,7 @@ Examples:
 }
 
 // src/commands/definitions-export.ts
-import fs9 from "node:fs";
+import fs10 from "node:fs";
 init_errors();
 async function exportDefinitions(ctx, opts, isJsonMode) {
   const params = {};
@@ -16963,7 +17105,7 @@ async function exportDefinitions(ctx, opts, isJsonMode) {
   const text = await res.text();
   if (opts.output) {
     try {
-      fs9.writeFileSync(opts.output, text);
+      fs10.writeFileSync(opts.output, text);
     } catch (err) {
       throw new CLIError(`Failed to write ${opts.output}: ${err instanceof Error ? err.message : String(err)}`, 1 /* Error */);
     }
@@ -18080,7 +18222,7 @@ var triggersConfig = {
 };
 
 // src/commands/documents.ts
-import fs10 from "node:fs";
+import fs11 from "node:fs";
 init_errors();
 
 // src/lib/document-lifecycle.ts
@@ -18512,7 +18654,7 @@ ${items.length} collections`));
   });
   cmd.command("upload <collection-id> <file>").description("Upload a document to a collection").option("--wait", "Wait for ingestion to complete").option("--follow", "Follow ingestion progress in real time").action(async (collectionId, filePath, opts) => {
     const ctx = getCtx();
-    if (!fs10.existsSync(filePath)) {
+    if (!fs11.existsSync(filePath)) {
       throw new CLIError(`File not found: ${filePath}`, 4 /* Validation */);
     }
     const result = await ctx.api.upload(`/api/admin/collections/${encodeURIComponent(collectionId)}/documents`, filePath);
@@ -22304,7 +22446,7 @@ function registerBudgetCommands(program) {
 }
 
 // src/commands/wiki.ts
-import fs11 from "node:fs";
+import fs12 from "node:fs";
 
 // node_modules/zod/v4/core/core.js
 var NEVER = Object.freeze({
@@ -26108,7 +26250,7 @@ ${pages.length} pages`));
     const body = page.data.body;
     const bytes = Buffer.byteLength(body, "utf8");
     if (opts.out) {
-      fs11.writeFileSync(opts.out, body);
+      fs12.writeFileSync(opts.out, body);
       if (!isJson()) {
         console.log(source_default.dim(`wrote ${bytes} bytes to ${opts.out}`));
       } else {
@@ -26213,10 +26355,10 @@ ${pages.length} pages`));
     }
     if (opts.compilePromptOverrideFile) {
       const file = String(opts.compilePromptOverrideFile);
-      if (!fs11.existsSync(file)) {
+      if (!fs12.existsSync(file)) {
         throw new CLIError(`override file not found: ${file}`, 3 /* NotFound */);
       }
-      const content = fs11.readFileSync(file, "utf8");
+      const content = fs12.readFileSync(file, "utf8");
       const bytes = Buffer.byteLength(content, "utf8");
       if (bytes > 16 * 1024) {
         throw new CLIError(`compile prompt override exceeds 16 KB (${bytes} bytes)`, 4 /* Validation */);
@@ -26241,7 +26383,7 @@ ${pages.length} pages`));
     const slug = encodeURIComponent(opts.wiki ?? DEFAULT_WIKI_SLUG);
     const resp = await ctx.api.get(`/api/wiki/${slug}/schema`);
     if (opts.out) {
-      fs11.writeFileSync(opts.out, resp.body);
+      fs12.writeFileSync(opts.out, resp.body);
       if (!isJson()) {
         console.log(source_default.dim(`wrote ${resp.body.length} bytes to ${opts.out}`));
       } else {
@@ -26257,10 +26399,10 @@ ${pages.length} pages`));
   });
   schemaCmd.command("set").description("Replace a wiki's schema with the contents of <file>").requiredOption("--file <file>", "Path to schema markdown file").option("--wiki <slug>", "Wiki slug (default: the tenant default wiki)").action(async (opts) => {
     const ctx = getCtx();
-    if (!fs11.existsSync(opts.file)) {
+    if (!fs12.existsSync(opts.file)) {
       throw new CLIError(`schema file not found: ${opts.file}`, 3 /* NotFound */);
     }
-    const body = fs11.readFileSync(opts.file, "utf8");
+    const body = fs12.readFileSync(opts.file, "utf8");
     const bytes = Buffer.byteLength(body, "utf8");
     if (bytes > 64 * 1024) {
       throw new CLIError(`schema body exceeds 64 KB (${bytes} bytes)`, 4 /* Validation */);
@@ -28302,7 +28444,7 @@ function registerDoctorCommand(program) {
 
 // src/commands/skill.ts
 init_errors();
-import fs12 from "node:fs";
+import fs13 from "node:fs";
 import path9 from "node:path";
 import { fileURLToPath } from "node:url";
 function locateSkill() {
@@ -28314,7 +28456,7 @@ function locateSkill() {
     path9.join(here, "..", "..", "skills", "martha-cli", "SKILL.md")
   ];
   for (const p of candidates) {
-    if (fs12.existsSync(p))
+    if (fs13.existsSync(p))
       return p;
   }
   return null;
@@ -28324,7 +28466,7 @@ async function skillCommand() {
   if (!skillPath) {
     throw new CLIError("SKILL.md not found in the installed package. Reinstall via `npm i -g @aiaiai-pt/martha-cli` or `npx -y @aiaiai-pt/martha-cli@latest skill`.", 1 /* Error */);
   }
-  const body = fs12.readFileSync(skillPath, "utf-8");
+  const body = fs13.readFileSync(skillPath, "utf-8");
   process.stdout.write(body);
 }
 function registerSkillCommand(program) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/martha-cli",
-  "version": "0.69.0",
+  "version": "0.70.0",
   "description": "Terminal-first client for the Martha AI platform",
   "homepage": "https://docs.martha.nomadriver.co",
   "repository": {

package/skills/martha-cli/SKILL.md

@@ -742,18 +742,24 @@ martha clients access <name-or-id>                                    # All gran
 
 ```bash
 martha sessions list [--search QUERY] [--limit 20] [--type api|sms|whatsapp]
-martha sessions get <session-id>                          # Messages + tool calls
+martha sessions get <session-id>                          # Single session detail (--json for object)
 martha sessions delete <session-id> [--yes]
 
 # Interactive chat (REPL)
-martha chat [--session <id>] [--client <name>] [--message "text"] [--show-tools]
+martha chat [--session <id>] [--client <name>] [--message "text"] [--show-tools] \
+    [--events-file <path>]
 
 # Single-message mode
 martha chat --client web --message "What's the weather?"  # Creates new session, prints response
+
+# Events file for terminal hosts (#2633)
+martha chat --events-file /tmp/martha-events.jsonl        # JSONL lifecycle events
 ```
 
 `--show-tools` prints each tool call + result inline so you can debug agent reasoning.
 
+`--events-file <path>` writes lifecycle events as JSONL so a terminal host (e.g. Muster) can follow the session without reading the screen. Events: `session` (start + `/history` switch), `turn_started`, `turn_ended` (with `ok` bool and `pending_approvals` array), `approval_resolved`, `exit`. Each line is `{"v":1,"ts":<epoch ms>,"event":"..."}`. No message text, tool args/results, tokens or keys. Interactive REPL only. The file is created 0600; an unwritable path fails before session creation.
+
 ---
 
 ## Integrations (OpenAPI specs + plugins)