@aiaiai-pt/martha-cli 0.69.0 → 0.71.0

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 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.71.0] — 2026-11-14
+
+0.70.0 is `chat --events-file` and `sessions get`, published from `main` (#2650). These changes were first numbered 0.70.0 and 0.70.1 on `dev` and never published under those numbers.
+
+### Added
+
+- `martha events emit <type> [--data <json> | --data-file <path>] [--subject <s>]` puts a real event on the tenant's event bus through `POST /api/events/emit`: every active trigger listening to that type starts. The type must be registered for the tenant; an agent key goes through the agent rules. To check a trigger against a payload without starting anything, keep using `martha triggers test`.
+- `martha events types` lists the event types registered for the tenant, and `martha events list [--type <pattern>] [--since <age>] [--limit <n>]` shows the latest events on the bus.
+- `martha triggers get` shows whether the trigger is working: when it last ran and how often, the most recent failed firing with its reason, what its schedule or missing-event watcher is doing, and a warning when its target cannot be resolved. `martha triggers list` shows `failing` in the STATUS column. Before, this was only in `--json`, and the hint `martha events emit` prints pointed at text that was not there.
+
+### Fixed
+
+- The `martha-cli` skill has documented `martha events list`, `events types` and `events emit --type` since an early spec; none of them existed. They do now, with that interface (`--type` is accepted on `emit` as well as the positional type).
+
+## [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.71.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 */);
     }
@@ -17934,6 +18076,38 @@ function triggerKind(item) {
 function scheduleSummary(sched) {
   return String(sched.cron ?? sched.interval ?? sched.spec ?? "schedule");
 }
+function isFailing(t) {
+  const failedAt = Date.parse(String(t.last_error_at ?? ""));
+  if (!Number.isFinite(failedAt))
+    return false;
+  const ranAt = Date.parse(String(t.last_fired_at ?? ""));
+  return !Number.isFinite(ranAt) || failedAt > ranAt;
+}
+var plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+function triggerHealthLines(t) {
+  const lines = [];
+  const schedule = t.schedule;
+  if (schedule?.status) {
+    const next = schedule.next_run_at ? `, next run ${schedule.next_run_at}` : "";
+    lines.push(`State:       ${schedule.status}${next}`);
+  }
+  const watcher = t.deadman;
+  if (watcher?.status) {
+    const seen = watcher.last_seen_at ? `, last event seen ${watcher.last_seen_at}` : "";
+    lines.push(`Watcher:     ${watcher.status}${seen}`);
+  }
+  if (t.fire_count !== undefined || t.last_fired_at !== undefined) {
+    const runs = Number(t.fire_count ?? 0);
+    lines.push(t.last_fired_at ? `Last ran:    ${t.last_fired_at} (${plural(runs, "run")})` : "Last ran:    never");
+  }
+  if (isFailing(t)) {
+    lines.push(`Failing:     ${t.last_error_at}: ${t.last_error ?? "unknown error"} ` + `(${plural(Number(t.failure_count ?? 0), "failed attempt")})`);
+  }
+  if (t.target_exists === false && t.target_warning) {
+    lines.push(`Warning:     ${t.target_warning}`);
+  }
+  return lines;
+}
 var triggersConfig = {
   typeName: "trigger",
   typeNamePlural: "triggers",
@@ -17959,7 +18133,7 @@ var triggersConfig = {
     { header: "TARGET", accessor: (item) => String(item.target_name ?? "-") },
     {
       header: "STATUS",
-      accessor: (item) => item.is_active !== false ? "active" : "inactive"
+      accessor: (item) => item.is_active === false ? "inactive" : isFailing(item) ? "failing" : "active"
     }
   ],
   renderDetail: (t) => {
@@ -17982,6 +18156,10 @@ var triggersConfig = {
     if (deadman)
       console.log(`  Deadman:     ${JSON.stringify(deadman)}`);
     console.log(`  Target:      ${t.target_type ?? "workflow"} → ${t.target_name ?? "-"}`);
+    for (const line of triggerHealthLines(t)) {
+      const colour = line.startsWith("Failing") ? source_default.red : line.startsWith("Warning") ? source_default.yellow : (text) => text;
+      console.log(`  ${colour(line)}`);
+    }
     const mapping = t.input_mapping;
     if (mapping && Object.keys(mapping).length) {
       console.log(`
@@ -18079,8 +18257,144 @@ var triggersConfig = {
   }
 };
 
+// src/commands/events.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+init_errors();
+function context(program) {
+  const ctx = createContext({
+    profileOverride: program.opts().profile,
+    verbose: program.opts().verbose
+  });
+  if (program.opts().apiUrl) {
+    ctx.profile.api_url = program.opts().apiUrl;
+  }
+  return ctx;
+}
+function readData(opts) {
+  if (opts.data !== undefined && opts.dataFile !== undefined) {
+    throw new CLIError("Use --data or --data-file, not both", 4 /* Validation */);
+  }
+  let raw = opts.data;
+  if (opts.dataFile !== undefined) {
+    try {
+      raw = readFileSync2(opts.dataFile, "utf-8");
+    } catch {
+      throw new CLIError(`Cannot read --data-file ${opts.dataFile}`, 4 /* Validation */);
+    }
+  }
+  if (raw === undefined)
+    return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new CLIError("The event data must be valid JSON", 4 /* Validation */, `Example: martha events emit document.ingested --data '{"document_id":"123"}'`);
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new CLIError("The event data must be a JSON object", 4 /* Validation */);
+  }
+  return parsed;
+}
+function ageToMs(age) {
+  const match = /^(\d+)([mhd])$/.exec(age.trim());
+  if (!match) {
+    throw new CLIError("--since takes a number and a unit: 30m, 2h, 1d", 4 /* Validation */);
+  }
+  const unit = { m: 60000, h: 3600000, d: 86400000 }[match[2]];
+  return Number(match[1]) * unit;
+}
+function typePattern(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  return new RegExp(`^${escaped}$`);
+}
+function table(rows, cols) {
+  const widths = cols.map((col) => Math.max(col.header.length, ...rows.map((row) => col.accessor(row).length)));
+  const header = cols.map((col, i) => col.header.padEnd(widths[i])).join("  ");
+  console.log(source_default.bold(header));
+  console.log(source_default.dim("-".repeat(header.length)));
+  for (const row of rows) {
+    console.log(cols.map((col, i) => col.accessor(row).padEnd(widths[i])).join("  ").trimEnd());
+  }
+}
+function registerEventCommands(program) {
+  const events = program.command("events").description("Emit an event onto the tenant's event bus, and list event types and recent events");
+  events.command("emit [type]").description("Emit a real event: every active trigger listening to this type starts").option("--type <type>", "The event type (same as the positional argument)").option("--data <json>", "Event payload as a JSON object (default: {})").option("--data-file <path>", "Read the event payload from a JSON file").option("--subject <subject>", "Optional CloudEvent subject").option("--source <source>", "Override the event source (ignored for agent keys)").option("--idempotency-key <key>", "A retried emit with the same key does not fire twice (agent keys)").action(async (positional, opts) => {
+    if (positional && opts.type && positional !== opts.type) {
+      throw new CLIError(`Two different event types given: '${positional}' and --type '${opts.type}'`, 4 /* Validation */);
+    }
+    const type = positional ?? opts.type;
+    if (!type) {
+      throw new CLIError("An event type is required", 4 /* Validation */, 'Example: martha events emit document.ingested --data \'{"document_id":"123"}\'. `martha events types` lists the registered types.');
+    }
+    const data = readData(opts);
+    const ctx = context(program);
+    const body = { type, data };
+    if (opts.subject)
+      body.subject = opts.subject;
+    if (opts.source)
+      body.source = opts.source;
+    if (opts.idempotencyKey)
+      body.idempotency_key = opts.idempotencyKey;
+    const res = await ctx.api.post("/api/events/emit", body);
+    if (program.opts().json) {
+      console.log(JSON.stringify({ event_id: res.event_id, type }, null, 2));
+      return;
+    }
+    console.log(source_default.green(`✓ Emitted ${type}`) + source_default.dim(` (event ${res.event_id})`));
+    console.log(source_default.dim("  Active triggers listening to this type start now. " + "`martha triggers get <name>` shows a trigger's last run or failure."));
+  });
+  events.command("types").description("List the event types registered for the tenant").action(async () => {
+    const ctx = context(program);
+    const types = await ctx.api.get("/api/admin/triggers/events/types");
+    if (program.opts().json) {
+      console.log(JSON.stringify(types, null, 2));
+      return;
+    }
+    if (types.length === 0) {
+      console.log(source_default.dim("No event types are registered for this tenant."));
+      return;
+    }
+    table([...types].sort((a, b) => a.type.localeCompare(b.type)), [
+      { header: "TYPE", accessor: (t) => t.type },
+      { header: "DESCRIPTION", accessor: (t) => t.description ?? "" }
+    ]);
+  });
+  events.command("list").description("Show the most recent events on the tenant's event bus, newest first").option("--limit <n>", "How many of the latest events to read (1-200)", "50").option("--type <pattern>", "Only this type; `*` matches any run of characters (task.*)").option("--since <age>", "Only events newer than this: 30m, 2h, 1d").action(async (opts) => {
+    const limit = Number(opts.limit);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 200) {
+      throw new CLIError("--limit must be a whole number from 1 to 200", 4 /* Validation */);
+    }
+    const cutoff = opts.since === undefined ? null : Date.now() - ageToMs(opts.since);
+    const matchesType = opts.type === undefined ? null : typePattern(opts.type);
+    const ctx = context(program);
+    let recent = await ctx.api.get(`/api/admin/triggers/events/recent?limit=${limit}`);
+    if (matchesType)
+      recent = recent.filter((event) => matchesType.test(event.type ?? ""));
+    if (cutoff !== null) {
+      recent = recent.filter((event) => {
+        const at = Date.parse(event.time ?? "");
+        return Number.isFinite(at) && at >= cutoff;
+      });
+    }
+    if (program.opts().json) {
+      console.log(JSON.stringify(recent, null, 2));
+      return;
+    }
+    if (recent.length === 0) {
+      console.log(source_default.dim("No matching events among the latest " + limit + "."));
+      return;
+    }
+    table(recent, [
+      { header: "TIME", accessor: (e) => (e.time ?? "").slice(0, 19) },
+      { header: "TYPE", accessor: (e) => e.type ?? "" },
+      { header: "EVENT", accessor: (e) => e.id ?? "" },
+      { header: "SOURCE", accessor: (e) => e.source ?? "" }
+    ]);
+  });
+}
+
 // src/commands/documents.ts
-import fs10 from "node:fs";
+import fs11 from "node:fs";
 init_errors();
 
 // src/lib/document-lifecycle.ts
@@ -18512,7 +18826,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);
@@ -19263,7 +19577,7 @@ function registerAskCommands(program) {
 }
 
 // src/commands/tasks.ts
-import { readFileSync as readFileSync2 } from "node:fs";
+import { readFileSync as readFileSync3 } from "node:fs";
 init_errors();
 var truncate2 = (s, n) => s.length > n ? s.slice(0, n - 1) + "…" : s;
 var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -19758,7 +20072,7 @@ ${items.length} task(s) available`));
     let rawOutcome;
     if (opts.outcomeFile) {
       try {
-        rawOutcome = readFileSync2(opts.outcomeFile, "utf-8");
+        rawOutcome = readFileSync3(opts.outcomeFile, "utf-8");
       } catch {
         throw new CLIError(`--outcome-file could not be read: ${opts.outcomeFile}`, 4 /* Validation */);
       }
@@ -22304,7 +22618,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 +26422,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 +26527,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 +26555,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 +26571,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 */);
@@ -26921,7 +27235,7 @@ function registerPolicyCommands(program) {
 }
 
 // src/commands/agent-step.ts
-import { readFileSync as readFileSync3 } from "node:fs";
+import { readFileSync as readFileSync4 } from "node:fs";
 init_errors();
 var BASE = "/api/admin/agent-step/trust-roots";
 var FLEET_BASE = "/api/admin/agent-step/fleet";
@@ -26929,7 +27243,7 @@ function resolveKeyMaterial(value) {
   if (value.startsWith("@")) {
     const path = value.slice(1);
     try {
-      return readFileSync3(path, "utf8").trim();
+      return readFileSync4(path, "utf8").trim();
     } catch (e) {
       throw new CLIError(`Could not read public key file '${path}': ${e.message}`, 4 /* Validation */);
     }
@@ -28302,7 +28616,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 +28628,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 +28638,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) {
@@ -28515,6 +28829,7 @@ registerDefinitionCommands(program2, workflowsConfig);
 registerDefinitionCommands(program2, agentsConfig);
 registerDefinitionCommands(program2, promptsConfig);
 registerDefinitionCommands(program2, triggersConfig);
+registerEventCommands(program2);
 registerDefinitionsApply(program2);
 registerDefinitionsExport(program2);
 registerDocumentCommands(program2);

package/package.json

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

package/skills/martha-cli/SKILL.md

@@ -594,10 +594,11 @@ martha triggers update <name> -f trigger.yaml
 martha triggers delete <name> [--yes]
 martha triggers test <name> --event '{"type": "task.completed", "data": {...}}'   # Dry-run
 
-# Events (browse what's flowing)
-martha events list [--type task.*] [--since 1h] [--limit 50]
-martha events types                      # Available event types with sample payloads
-martha events emit --type custom.event --data '{"foo": "bar"}'   # Manual emit (admin only)
+# Events (browse what's flowing, and emit one)
+martha events list [--type task.*] [--since 1h] [--limit 50]   # Latest events on the tenant's bus (the API keeps the last 200 readable)
+martha events types                                             # Event types registered for the tenant
+martha events emit <type> --data '{"foo": "bar"}'               # REAL event: every active trigger on <type> starts
+martha events emit <type> --data-file payload.json [--subject <s>]
 
 # Webhooks
 martha webhooks list
@@ -742,18 +743,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)