@monoes/monomindcli 2.9.22 → 2.9.24

package/dist/src/commands/org-observe.js

@@ -1,15 +1,19 @@
 // packages/@monomind/cli/src/commands/org-observe.ts
 // Read-side org subcommands (logs / report) + template scaffolding (create).
 // Kept out of org.ts to respect the 500-line file ceiling.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { output } from '../output.js';
-import { ORG_DIR, OrgDefSchema } from '../orgrt/types.js';
-import { formatEvent, listRunDirs, readHistory, readRunEvents, summarizeRun } from '../orgrt/reporting.js';
-import { ORG_TEMPLATES, buildFromTemplate } from '../orgrt/templates.js';
+import { branchCheckpoint } from '../orgrt/checkpoint-ops.js';
 import { checkOrgStructure } from '../orgrt/migrate.js';
+import { formatEvent, listRunDirs, readHistory, readRunEvents, summarizeRun, } from '../orgrt/reporting.js';
+import { resolveModel } from '../orgrt/session.js';
+import { buildFromTemplate, ORG_TEMPLATES } from '../orgrt/templates.js';
+import { ORG_DIR, OrgDefSchema } from '../orgrt/types.js';
+import { output } from '../output.js';
 import { listOrgConfigFiles, validateOrgName } from './org.js';
-const log = (text) => { console.log(text); };
+const log = (text) => {
+    console.log(text);
+};
 /** Validate org config(s) against OrgDefSchema — the exact parse `org run`/`org serve`
  * perform — plus the structural invariants the runtime assumes but the schema can't
  * express (single root role, resolvable reports_to, unique ids, parseable schedule). */
@@ -24,7 +28,10 @@ export const validateAction = async (ctx) => {
     }
     else {
         if (!existsSync(orgsDir))
-            return { success: false, message: 'no orgs directory — create an org first with /mastermind:createorg' };
+            return {
+                success: false,
+                message: 'no orgs directory — create an org first with /mastermind:createorg',
+            };
         files = listOrgConfigFiles(orgsDir);
         if (!files.length)
             return { success: false, message: 'no org configs found' };
@@ -75,11 +82,14 @@ const resolveRun = (cwd, name, runFlag) => {
 };
 /** `org logs <name> [--run id] [--role r] [--filter-tool t] [--filter-role r] [--tools-only] [--audit-filter allow|deny] [--follow]` — formatted bus.jsonl tail. */
 export const logsAction = async (ctx, name) => {
-    const run = resolveRun(ctx.cwd, name, ctx.flags['run']);
+    const run = resolveRun(ctx.cwd, name, ctx.flags.run);
     if (!run)
-        return { success: false, message: `no runs found for org ${name} — start one with: monomind org run ${name}` };
+        return {
+            success: false,
+            message: `no runs found for org ${name} — start one with: monomind org run ${name}`,
+        };
     const file = join(ctx.cwd, ORG_DIR, name, run, 'bus.jsonl');
-    const roleFilter = typeof ctx.flags['role'] === 'string' ? ctx.flags['role'] : null;
+    const roleFilter = typeof ctx.flags.role === 'string' ? ctx.flags.role : null;
     const filterTool = typeof ctx.flags['filter-tool'] === 'string' ? ctx.flags['filter-tool'] : null;
     const filterRole = typeof ctx.flags['filter-role'] === 'string' ? ctx.flags['filter-role'] : null;
     const auditFilter = typeof ctx.flags['audit-filter'] === 'string' ? ctx.flags['audit-filter'] : null;
@@ -119,13 +129,19 @@ export const logsAction = async (ctx, name) => {
         }
     };
     drain();
-    if (ctx.flags['follow'] !== true)
+    if (ctx.flags.follow !== true)
         return { success: true };
     log(output.info('following — Ctrl-C to stop'));
-    await new Promise(resolve => {
+    await new Promise((resolve) => {
         const iv = setInterval(drain, 500);
-        process.once('SIGINT', () => { clearInterval(iv); resolve(); });
-        process.once('SIGTERM', () => { clearInterval(iv); resolve(); });
+        process.once('SIGINT', () => {
+            clearInterval(iv);
+            resolve();
+        });
+        process.once('SIGTERM', () => {
+            clearInterval(iv);
+            resolve();
+        });
     });
     return { success: true };
 };
@@ -153,19 +169,22 @@ export const watchAction = async (ctx, name) => {
     const role = ctx.args[1];
     if (!role)
         return { success: false, message: 'usage: monomind org watch <org> <role>' };
-    const run = resolveRun(ctx.cwd, name, ctx.flags['run']);
+    const run = resolveRun(ctx.cwd, name, ctx.flags.run);
     if (!run)
-        return { success: false, message: `no runs found for org ${name} — start one with: monomind org run ${name}` };
+        return {
+            success: false,
+            message: `no runs found for org ${name} — start one with: monomind org run ${name}`,
+        };
     const file = join(ctx.cwd, ORG_DIR, name, run, 'bus.jsonl');
-    const verbose = ctx.flags['verbose'] === true;
-    const stats = ctx.flags['stats'] === true;
+    const verbose = ctx.flags.verbose === true;
+    const stats = ctx.flags.stats === true;
     let totalTokens = 0;
     let totalCostUsd = 0;
     const show = (e) => {
         if (e.from !== role)
             return;
         if (e.type === 'chat') {
-            log(`${output.info(role + ':')} ${e.msg ?? ''}`);
+            log(`${output.info(`${role}:`)} ${e.msg ?? ''}`);
             return;
         }
         if (verbose && e.type === 'status') {
@@ -199,30 +218,38 @@ export const watchAction = async (ctx, name) => {
         }
     };
     drain();
-    if (ctx.flags['follow'] === false)
+    if (ctx.flags.follow === false)
         return { success: true }; // --follow=false opts out of the default live tail
-    await new Promise(resolve => {
+    await new Promise((resolve) => {
         const iv = setInterval(drain, 500);
-        process.once('SIGINT', () => { clearInterval(iv); resolve(); });
-        process.once('SIGTERM', () => { clearInterval(iv); resolve(); });
+        process.once('SIGINT', () => {
+            clearInterval(iv);
+            resolve();
+        });
+        process.once('SIGTERM', () => {
+            clearInterval(iv);
+            resolve();
+        });
     });
     return { success: true };
 };
 /** `org report <name> [--run id] [--all] [--by-role] [--format mermaid]` — summarize a run (or list run history). */
 export const reportAction = async (ctx, name) => {
-    if (ctx.flags['all'] === true) {
+    if (ctx.flags.all === true) {
         const history = readHistory(ctx.cwd, name);
         if (!history.length)
             return { success: false, message: `no run history for org ${name}` };
         log(output.info(`org ${name} — ${history.length} recorded run(s):`));
         for (const h of history) {
             const dur = h.durationMs != null ? `${Math.round(h.durationMs / 1000)}s` : '?';
-            const outcome = h.outcome ? `${h.outcome.status}: ${h.outcome.summary.slice(0, 60)}` : 'no outcome recorded';
+            const outcome = h.outcome
+                ? `${h.outcome.status}: ${h.outcome.summary.slice(0, 60)}`
+                : 'no outcome recorded';
             log(output.info(`  • ${h.run}  ${dur}  ${h.totalTokens} tokens  ${h.messages} msgs  — ${outcome}`));
         }
         return { success: true };
     }
-    const run = resolveRun(ctx.cwd, name, ctx.flags['run']);
+    const run = resolveRun(ctx.cwd, name, ctx.flags.run);
     if (!run)
         return { success: false, message: `no runs found for org ${name}` };
     const events = readRunEvents(ctx.cwd, name, run);
@@ -230,9 +257,9 @@ export const reportAction = async (ctx, name) => {
         return { success: false, message: `run ${run} has no recorded events` };
     const s = summarizeRun(events);
     // Mermaid flowchart (--format mermaid flag)
-    if (ctx.flags['format'] === 'mermaid') {
+    if (ctx.flags.format === 'mermaid') {
         // Extract message flow from events
-        const messageEvents = events.filter(e => e.type === 'message' || e.type === 'xorg');
+        const messageEvents = events.filter((e) => e.type === 'message' || e.type === 'xorg');
         const roleSet = new Set();
         const edges = new Set();
         for (const e of messageEvents) {
@@ -267,15 +294,15 @@ export const reportAction = async (ctx, name) => {
         return { success: true, message: `Mermaid flowchart exported for ${name} / ${run}` };
     }
     // Tool audit filter (--audit flag) - show only tool decision events
-    if (ctx.flags['audit'] === true) {
-        let toolEvents = events.filter(e => e.type === 'tool');
+    if (ctx.flags.audit === true) {
+        let toolEvents = events.filter((e) => e.type === 'tool');
         // Optional --tool flag filters to a specific tool name
-        if (typeof ctx.flags['tool'] === 'string' && ctx.flags['tool']) {
-            const toolName = ctx.flags['tool'];
-            toolEvents = toolEvents.filter(e => e.tool === toolName);
+        if (typeof ctx.flags.tool === 'string' && ctx.flags.tool) {
+            const toolName = ctx.flags.tool;
+            toolEvents = toolEvents.filter((e) => e.tool === toolName);
         }
         if (!toolEvents.length) {
-            const toolFilter = typeof ctx.flags['tool'] === 'string' ? ` for tool "${ctx.flags['tool']}"` : '';
+            const toolFilter = typeof ctx.flags.tool === 'string' ? ` for tool "${ctx.flags.tool}"` : '';
             log(output.info(`No tool events found${toolFilter} in ${run}`));
             return { success: true };
         }
@@ -325,7 +352,9 @@ export const reportAction = async (ctx, name) => {
             roleCeiling.set(r.id, max ?? r.budget_tokens ?? perRoleBudget);
         }
     }
-    catch { /* config gone or invalid — report without budget context */ }
+    catch {
+        /* config gone or invalid — report without budget context */
+    }
     const budgetNote = (id, tokens) => {
         const cap = roleCeiling.get(id);
         if (!cap)
@@ -394,9 +423,11 @@ export const questionsAction = async (ctx, name) => {
         log(output.error(`Cannot read questions for org ${name}: ${err instanceof Error ? err.message : String(err)}`));
         return { success: false, message: 'questions.json unreadable' };
     }
-    const shown = ctx.flags['all'] === true ? all : all.filter(q => q.answer === null);
+    const shown = ctx.flags.all === true ? all : all.filter((q) => q.answer === null);
     if (!shown.length) {
-        log(output.info(all.length ? `No pending questions for org ${name} (${all.length} answered — use --all).` : `No questions recorded for org ${name}.`));
+        log(output.info(all.length
+            ? `No pending questions for org ${name} (${all.length} answered — use --all).`
+            : `No questions recorded for org ${name}.`));
         return { success: true };
     }
     for (const q of shown) {
@@ -405,7 +436,7 @@ export const questionsAction = async (ctx, name) => {
         if (q.answer !== null)
             log(output.info(`     ↳ ${q.answer}`));
     }
-    if (shown.some(q => q.answer === null))
+    if (shown.some((q) => q.answer === null))
         log(output.info(`\nAnswer with: monomind org answer ${name} <question-id> "your answer"`));
     return { success: true };
 };
@@ -416,7 +447,10 @@ export const answerAction = async (ctx, name) => {
     const questionId = ctx.args[1];
     const answer = ctx.args.slice(2).join(' ').trim();
     if (!questionId || !answer)
-        return { success: false, message: `usage: monomind org answer ${name} <question-id> "answer text"` };
+        return {
+            success: false,
+            message: `usage: monomind org answer ${name} <question-id> "answer text"`,
+        };
     let questions;
     try {
         questions = readQuestions(ctx.cwd, name);
@@ -425,7 +459,7 @@ export const answerAction = async (ctx, name) => {
         log(output.error(`Cannot read questions for org ${name}: ${err instanceof Error ? err.message : String(err)}`));
         return { success: false, message: 'questions.json unreadable — answer not recorded' };
     }
-    const q = questions.find(x => x.questionId === questionId);
+    const q = questions.find((x) => x.questionId === questionId);
     if (!q) {
         log(output.error(`Question "${questionId}" not found for org ${name} — list with: monomind org questions ${name}`));
         return { success: false, message: 'question not found' };
@@ -439,11 +473,15 @@ export const answerAction = async (ctx, name) => {
         const cred = normalizeCredential(remote.credential);
         try {
             const res = await fetch(`${remote.url}/api/answer-question`, {
-                method: 'POST', headers: { 'Content-Type': 'application/json', ...(cred ? { 'x-monomind-cred': cred } : {}) },
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...(cred ? { 'x-monomind-cred': cred } : {}),
+                },
                 body: JSON.stringify({ org: name, role: q.role, questionId, answer }),
                 signal: AbortSignal.timeout(10_000),
             });
-            const data = await res.json().catch(() => ({}));
+            const data = (await res.json().catch(() => ({})));
             if (res.ok && data.ok) {
                 log(output.success(`Answer delivered to ${name}:${q.role} (live).`));
                 return { success: true };
@@ -470,9 +508,12 @@ export const answerAction = async (ctx, name) => {
         log(output.warning(`The answer was NOT recorded. Fix or restore ${join(ctx.cwd, ORG_DIR, name, 'questions.json')}, then retry.`));
         return { success: false, message: 'questions.json unreadable — answer not recorded' };
     }
-    const freshQ = fresh.find(x => x.questionId === questionId);
+    const freshQ = fresh.find((x) => x.questionId === questionId);
     if (freshQ && freshQ.answer !== null) {
-        return { success: false, message: `question "${questionId}" was answered while this command was running` };
+        return {
+            success: false,
+            message: `question "${questionId}" was answered while this command was running`,
+        };
     }
     // Queue BEFORE marking answered (same rule as daemon.answerQuestion): if the
     // append fails, the question must stay pending and answerable. Marking first meant
@@ -481,7 +522,8 @@ export const answerAction = async (ctx, name) => {
     const { queueMessage } = await import('../orgrt/inbox.js');
     try {
         queueMessage(ctx.cwd, name, {
-            fromQualified: 'human', toRole: q.role,
+            fromQualified: 'human',
+            toRole: q.role,
             subject: `answer:${questionId}`,
             body: `question: ${q.question}\n\nanswer: ${answer}`,
             ts: Date.now(),
@@ -491,8 +533,8 @@ export const answerAction = async (ctx, name) => {
         log(output.error(`Could not queue the answer for ${name}:${q.role} (${err instanceof Error ? err.message : String(err)}) — answer NOT recorded, retry it.`));
         return { success: false, message: 'queueing failed — answer not recorded' };
     }
-    const merged = fresh.some(x => x.questionId === questionId)
-        ? fresh.map(x => x.questionId === questionId ? { ...x, answer, answeredAt: Date.now() } : x)
+    const merged = fresh.some((x) => x.questionId === questionId)
+        ? fresh.map((x) => (x.questionId === questionId ? { ...x, answer, answeredAt: Date.now() } : x))
         : [...fresh, { ...q, answer, answeredAt: Date.now() }];
     const dest = join(ctx.cwd, ORG_DIR, name, 'questions.json');
     const tmp = `${dest}.${process.pid}.tmp`;
@@ -511,7 +553,7 @@ export const answerAction = async (ctx, name) => {
  *  semantics as a queued human answer. */
 export const inboxAction = async (ctx, name) => {
     let payload = {};
-    const rawJson = ctx.flags['json'];
+    const rawJson = ctx.flags.json;
     if (typeof rawJson === 'string') {
         try {
             payload = JSON.parse(rawJson);
@@ -521,7 +563,7 @@ export const inboxAction = async (ctx, name) => {
         }
     }
     else {
-        payload = { from: ctx.flags['from'], subject: ctx.flags['subject'], body: ctx.flags['body'] };
+        payload = { from: ctx.flags.from, subject: ctx.flags.subject, body: ctx.flags.body };
     }
     const from = typeof payload.from === 'string' ? payload.from.trim() : '';
     const subject = typeof payload.subject === 'string' ? payload.subject : '';
@@ -532,7 +574,7 @@ export const inboxAction = async (ctx, name) => {
     }
     // Target role: explicit --to, else the org's coordinator (reports_to == null),
     // else the first role — matching where a role-less cross-org message should land.
-    let toRole = typeof ctx.flags['to'] === 'string' ? ctx.flags['to'] : '';
+    let toRole = typeof ctx.flags.to === 'string' ? ctx.flags.to : '';
     if (toRole && !/^[a-z0-9][a-z0-9_-]*$/i.test(toRole)) {
         log(output.error(`Invalid role id: ${toRole}`));
         return { success: false, message: 'invalid role id' };
@@ -546,7 +588,7 @@ export const inboxAction = async (ctx, name) => {
         try {
             const def = JSON.parse(readFileSync(defPath, 'utf8'));
             const roles = Array.isArray(def.roles) ? def.roles : [];
-            toRole = roles.find(r => r.reports_to == null)?.id ?? roles[0]?.id ?? '';
+            toRole = roles.find((r) => r.reports_to == null)?.id ?? roles[0]?.id ?? '';
         }
         catch (err) {
             log(output.error(`Could not read org config for ${name}: ${err instanceof Error ? err.message : String(err)}`));
@@ -566,11 +608,14 @@ export const inboxAction = async (ctx, name) => {
         try {
             const res = await fetch(`${remote.url}/api/xdeliver`, {
                 method: 'POST',
-                headers: { 'Content-Type': 'application/json', ...(cred ? { 'x-monomind-cred': cred } : {}) },
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...(cred ? { 'x-monomind-cred': cred } : {}),
+                },
                 body: JSON.stringify({ fromOrg, fromRole, toOrg: name, toRole, subject, body }),
                 signal: AbortSignal.timeout(10_000),
             });
-            const data = await res.json().catch(() => ({}));
+            const data = (await res.json().catch(() => ({})));
             if (res.ok && data.ok) {
                 log(output.success(data.receipt ?? `delivered to ${name}:${toRole}`));
                 return { success: true, message: data.receipt ?? 'delivered' };
@@ -583,7 +628,13 @@ export const inboxAction = async (ctx, name) => {
     }
     // Offline path: spool; drained into the role's mailbox when the org next starts.
     const { queueMessage } = await import('../orgrt/inbox.js');
-    const queued = queueMessage(ctx.cwd, name, { fromQualified: from, toRole, subject, body, ts: Date.now() });
+    const queued = queueMessage(ctx.cwd, name, {
+        fromQualified: from,
+        toRole,
+        subject,
+        body,
+        ts: Date.now(),
+    });
     if (!queued) {
         log(output.error(`Could not queue the message for ${name}:${toRole} (disk full or permissions).`));
         return { success: false, message: 'queueing failed' };
@@ -594,37 +645,72 @@ export const inboxAction = async (ctx, name) => {
 };
 /** `org create <name> --template <t> [--goal g] [--schedule s]` — scaffold a config from a template. */
 export const createAction = async (ctx, name) => {
-    const templateName = typeof ctx.flags['template'] === 'string' ? ctx.flags['template'] : '';
+    const templateName = typeof ctx.flags.template === 'string' ? ctx.flags.template : '';
     if (!templateName) {
         log(output.info(`Available templates: ${Object.keys(ORG_TEMPLATES).join(', ')}`));
-        return { success: false, message: 'usage: monomind org create <name> --template <template> [--goal "..."] [--schedule 30m]' };
+        return {
+            success: false,
+            message: 'usage: monomind org create <name> --template <template> [--goal "..."] [--schedule 30m]',
+        };
     }
-    const def = buildFromTemplate(templateName, name, typeof ctx.flags['goal'] === 'string' ? ctx.flags['goal'] : undefined);
+    const def = buildFromTemplate(templateName, name, typeof ctx.flags.goal === 'string' ? ctx.flags.goal : undefined);
     if (!def) {
         log(output.error(`Unknown template "${templateName}" — available: ${Object.keys(ORG_TEMPLATES).join(', ')}`));
         return { success: false, message: 'unknown template' };
     }
-    if (typeof ctx.flags['schedule'] === 'string')
-        def.schedule = ctx.flags['schedule'];
+    if (typeof ctx.flags.schedule === 'string')
+        def.schedule = ctx.flags.schedule;
     const file = join(ctx.cwd, ORG_DIR, `${name}.json`);
-    if (existsSync(file) && ctx.flags['force'] !== true) {
+    if (existsSync(file) && ctx.flags.force !== true) {
         log(output.error(`Org "${name}" already exists — pass --force to overwrite.`));
         return { success: false, message: 'org exists' };
     }
     OrgDefSchema.parse(def); // templates must always produce a runnable config
+    // Per-role model — the single most consequential setting the template picked on
+    // the user's behalf. Mirror resolveModel() (same helper `org run`'s cost estimate
+    // uses) so a role relying on its runtime/vendor default isn't mislabeled here.
+    const modelRows = def.roles.map((r) => {
+        const explicit = r.adapter_config?.model;
+        return {
+            id: r.id,
+            model: String(explicit ?? resolveModel(r, r.runtime ?? def.runtime, r.provider?.vendor)),
+            explicit: !!explicit,
+        };
+    });
+    const printModels = () => {
+        log(output.bold('  Models:'));
+        for (const r of modelRows) {
+            log(`    ${r.id.padEnd(20)} ${r.model}${r.explicit ? '' : '  (default)'}`);
+        }
+    };
+    if (ctx.interactive && ctx.flags.yes !== true) {
+        log(output.bold(`\nAbout to create org "${name}" from template "${templateName}" (${def.roles.length} roles):`));
+        printModels();
+        const { confirm } = await import('../prompt.js');
+        const proceed = await confirm({ message: 'Create this org?', default: true });
+        if (!proceed) {
+            log(output.info('Cancelled — no file written. Adjust --template/--goal, or edit the template, then retry (pass --yes to skip this prompt).'));
+            return { success: false, message: 'cancelled by user' };
+        }
+    }
     const { mkdirSync } = await import('node:fs');
     mkdirSync(join(ctx.cwd, ORG_DIR), { recursive: true });
-    writeFileSync(file, JSON.stringify(def, null, 2) + '\n', 'utf8');
+    writeFileSync(file, `${JSON.stringify(def, null, 2)}\n`, 'utf8');
     log(output.success(`Org "${name}" created from template "${templateName}" (${def.roles.length} roles).`));
     log(output.info(`  Budget: ${def.run_config.budget_tokens} tokens · Turn limit: ${def.run_config.max_turns_per_message} per message (effectively unlimited by default — set run_config.max_turns_per_message, or a role's own max_turns_per_message, to cap it).`));
+    if (!ctx.interactive || ctx.flags.yes === true)
+        printModels();
     log(output.info(`  Edit the goal/roles in ${file}, then: monomind org run ${name}`));
     return { success: true };
 };
 /** `org costs <name> [--run id]` — show per-role cost tracking from runtime.json */
 export const costsAction = async (ctx, name) => {
-    const run = resolveRun(ctx.cwd, name, ctx.flags['run']);
+    const run = resolveRun(ctx.cwd, name, ctx.flags.run);
     if (!run)
-        return { success: false, message: `no runs found for org ${name} — start one with: monomind org run ${name}` };
+        return {
+            success: false,
+            message: `no runs found for org ${name} — start one with: monomind org run ${name}`,
+        };
     // Read runtime.json for the per-role metrics
     const rtPath = join(ctx.cwd, ORG_DIR, name, 'runtime.json');
     if (!existsSync(rtPath)) {
@@ -653,7 +739,7 @@ export const costsAction = async (ctx, name) => {
             roleData.set(roleId, {
                 tokens: metrics.tokens,
                 costUsd: metrics.costUsd,
-                messages: 0
+                messages: 0,
             });
         }
     }
@@ -664,7 +750,7 @@ export const costsAction = async (ctx, name) => {
             roleData.set(roleId, {
                 tokens: existing.tokens || roleStats.tokens,
                 costUsd: existing.costUsd || roleStats.costUsd,
-                messages: roleStats.messagesSent
+                messages: roleStats.messagesSent,
             });
         }
     }
@@ -691,14 +777,17 @@ export const costsAction = async (ctx, name) => {
 };
 /** `org flow <name> [--run id]` — export org flow as Mermaid diagram */
 export const flowAction = async (ctx, name) => {
-    const run = resolveRun(ctx.cwd, name, ctx.flags['run']);
+    const run = resolveRun(ctx.cwd, name, ctx.flags.run);
     if (!run)
-        return { success: false, message: `no runs found for org ${name} — start one with: monomind org run ${name}` };
+        return {
+            success: false,
+            message: `no runs found for org ${name} — start one with: monomind org run ${name}`,
+        };
     const events = readRunEvents(ctx.cwd, name, run);
     if (!events.length)
         return { success: false, message: `run ${run} has no recorded events` };
     // Extract message flow from events
-    const messageEvents = events.filter(e => e.type === 'message' || e.type === 'xorg');
+    const messageEvents = events.filter((e) => e.type === 'message' || e.type === 'xorg');
     const roleSet = new Set();
     const edges = new Set();
     for (const e of messageEvents) {
@@ -745,13 +834,19 @@ async function resolveApproval(ctx, name, role, action, approved) {
         const cred = normalizeCredential(remote.credential);
         try {
             const res = await fetch(`${remote.url}/api/set-approval`, {
-                method: 'POST', headers: { 'Content-Type': 'application/json', ...(cred ? { 'x-monomind-cred': cred } : {}) },
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...(cred ? { 'x-monomind-cred': cred } : {}),
+                },
                 body: JSON.stringify({ org: name, role, action, approved }),
                 signal: AbortSignal.timeout(10_000),
             });
-            const data = await res.json().catch(() => ({}));
+            const data = (await res.json().catch(() => ({})));
             if (res.ok && data.ok) {
-                log(approved ? output.success(`Approved: ${role} may execute ${action} (live).`) : output.info(`Denied: ${role} may NOT execute ${action} (live).`));
+                log(approved
+                    ? output.success(`Approved: ${role} may execute ${action} (live).`)
+                    : output.info(`Denied: ${role} may NOT execute ${action} (live).`));
                 return { success: true, message: `${verb} ${action} for ${role}` };
             }
             log(output.warning(`Live delivery rejected (${data.error ?? res.status}) — falling back to offline queue.`));
@@ -769,12 +864,17 @@ async function resolveApproval(ctx, name, role, action, approved) {
     const pending = data.approvals ?? [];
     const item = pending.find((a) => a.roleId === role && a.action === action);
     if (!item) {
-        return { success: false, message: `no pending approval found for role ${role} action ${action}` };
+        return {
+            success: false,
+            message: `no pending approval found for role ${role} action ${action}`,
+        };
     }
     item.approved = approved;
     item.ts = Date.now();
     writeFileSync(approvalsPath, JSON.stringify({ approvals: pending }, null, 2));
-    log(approved ? output.success(`Approved: ${role} may execute ${action}`) : output.info(`Denied: ${role} may NOT execute ${action}`));
+    log(approved
+        ? output.success(`Approved: ${role} may execute ${action}`)
+        : output.info(`Denied: ${role} may NOT execute ${action}`));
     return { success: true, message: `${verb} ${action} for ${role}` };
 }
 /** `org approve <org> <role> <action>` — approve a pending tool/action approval */
@@ -795,7 +895,10 @@ export const denyAction = async (ctx, name) => {
     }
     return resolveApproval(ctx, name, role, action, false);
 };
-/** `org replay <org> <run-id>` — time-travel debugging: resume from checkpoint */
+/** `org replay <org> <run-id>` — time-travel debugging: re-emit a past run's bus
+ *  events into a fresh replay run for inspection. This is event-log replay only —
+ *  it does not restart agent execution or restore live sessions. To actually
+ *  resume an org's execution from where it left off, use `org run --resume`. */
 export const replayAction = async (ctx, name) => {
     const run = ctx.args[1];
     if (!run) {
@@ -809,65 +912,62 @@ export const replayAction = async (ctx, name) => {
     if (!existsSync(busFile)) {
         return { success: false, message: `no bus events found for run ${run}` };
     }
-    log(output.info(`Resuming org ${name} from checkpoint ${run}...`));
-    // Create daemon and resume from checkpoint
+    log(output.info(`Replaying org ${name} events from checkpoint ${run}...`));
+    // Create daemon and replay the bus events for debugging/inspection
     const { OrgDaemon } = await import('../orgrt/daemon.js');
     const daemon = new OrgDaemon(ctx.cwd, { forward: false });
     const resumed = await daemon.replayFrom(name, run);
     if (!resumed) {
-        return { success: false, message: `replay failed - check bus.jsonl and org config for ${name} are valid` };
+        return {
+            success: false,
+            message: `replay failed - check bus.jsonl and org config for ${name} are valid`,
+        };
     }
-    log(output.success(`Org ${name} resumed from ${run} - ${resumed.agents.size} role(s) restored`));
+    log(output.success(`Org ${name} events replayed from ${run} as run ${resumed.run}`));
     log(output.info(`Use: monomind org logs ${name} --run ${resumed.run} to inspect events.`));
-    log(output.info(`Stop with: monomind org stop ${name}`));
-    return { success: true, message: `resumed from checkpoint ${run} as ${resumed.run}` };
+    log(output.info(`This is debug replay only — it does not restart agent execution. To resume live execution, use: monomind org run ${name} --resume`));
+    return { success: true, message: `replayed events from checkpoint ${run} as ${resumed.run}` };
 };
-/** `org resume-from <org> <run-id>` — resume from checkpoint (alias for replay) */
+/** `org resume-from <org>` — resume live execution from the org's persisted
+ *  checkpoint (runtime.json): restores mailbox queues, policy/token counters,
+ *  and session state, subject to checkpoint TTL and checksum validation. Unlike
+ *  `replay`, this restarts real agent execution via `startOrg(..., { resume: true })`. */
 export const resumeFromAction = async (ctx, name) => {
-    const run = ctx.args[1];
-    if (!run) {
-        return { success: false, message: 'usage: org resume-from <org> <run-id>' };
+    log(output.info(`Resuming org ${name} from checkpoint...`));
+    const { OrgDaemon } = await import('../orgrt/daemon.js');
+    const daemon = new OrgDaemon(ctx.cwd, { forward: false });
+    const resumed = await daemon.resumeOrg(name);
+    if (!resumed) {
+        return {
+            success: false,
+            message: `resume failed for ${name} - check runtime.json checkpoint is present, unexpired, and valid`,
+        };
     }
-    // Reuse replay logic
-    return replayAction(ctx, name);
+    log(output.success(`Org ${name} resumed - ${resumed.agents.size} role(s) restored`));
+    log(output.info(`Stop with: monomind org stop ${name}`));
+    return { success: true, message: `resumed ${name} - ${resumed.agents.size} role(s) restored` };
 };
-/** `org branch <org> <run-id> <branch-name>` — create a branch from checkpoint for what-if experiments */
+/** `org branch <org> <run-id> <branch-name>` — snapshot a run's event log for replay.
+ *  This is NOT an executable what-if scenario: it copies bus.jsonl into a new
+ *  run directory tagged with a `.branch-source` marker so it can be inspected
+ *  or replayed later; it does not fork or re-run agent execution.
+ *  Delegates to the shared, atomic (tmp+rename) implementation in checkpoint-ops.ts. */
 export const branchAction = async (ctx, name) => {
     const run = ctx.args[1];
     const branchName = ctx.args[2];
     if (!run || !branchName) {
         return { success: false, message: 'usage: org branch <org> <run-id> <branch-name>' };
     }
-    const runDir = join(ctx.cwd, ORG_DIR, name, run);
-    if (!existsSync(runDir)) {
-        return { success: false, message: `run ${run} not found for org ${name}` };
-    }
-    const branchRun = `branch-${new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14)}-${Math.random().toString(36).slice(2, 6)}`;
-    const branchDir = join(ctx.cwd, ORG_DIR, name, branchRun);
-    try {
-        mkdirSync(branchDir, { recursive: true });
-        // Copy bus.jsonl to branch
-        const busFile = join(runDir, 'bus.jsonl');
-        if (existsSync(busFile)) {
-            const busContent = readFileSync(busFile, 'utf8');
-            writeFileSync(join(branchDir, 'bus.jsonl'), busContent);
-        }
-        // Create branch marker file
-        writeFileSync(join(branchDir, '.branch-source'), JSON.stringify({
-            from: run,
-            branchedAt: new Date().toISOString(),
-            name: branchName
-        }, null, 2));
-        log(output.success(`Created branch "${branchName}" from ${run} as ${branchRun}`));
-        return { success: true, message: `branch ${branchName} created as ${branchRun}` };
-    }
-    catch (err) {
-        return { success: false, message: `failed to create branch: ${err instanceof Error ? err.message : String(err)}` };
+    const result = branchCheckpoint(ctx.cwd, name, run, branchName);
+    if (!result.ok) {
+        return { success: false, message: result.error };
     }
+    log(output.success(`Created branch "${branchName}" from ${run} as ${result.branchRun}`));
+    return { success: true, message: `branch ${branchName} created as ${result.branchRun}` };
 };
 /** `org decisions <org> [--run id]` — show Rifft-style decision traces */
 export const decisionsAction = async (ctx, name) => {
-    const run = resolveRun(ctx.cwd, name, ctx.flags['run']);
+    const run = resolveRun(ctx.cwd, name, ctx.flags.run);
     if (!run) {
         return { success: false, message: `no runs found for org ${name}` };
     }
@@ -876,10 +976,7 @@ export const decisionsAction = async (ctx, name) => {
         return { success: false, message: `run ${run} has no recorded events` };
     }
     // Filter decision trace events
-    const decisionEvents = events.filter(e => e.type === 'audit' &&
-        e.reason === 'decision-trace' &&
-        e.data &&
-        typeof e.data === 'object');
+    const decisionEvents = events.filter((e) => e.type === 'audit' && e.reason === 'decision-trace' && e.data && typeof e.data === 'object');
     if (!decisionEvents.length) {
         log(output.info(`No decision traces found in ${run}`));
         return { success: true };
@@ -906,17 +1003,52 @@ function readGatesFile(cwd, org) {
         return { gates: [] };
     }
 }
+/** Read gates.json for a write path. A MISSING file legitimately means "no gates" → [].
+ *  Any other failure (unreadable, malformed — e.g. a partial daemon write) THROWS:
+ *  gateResolveAction rewrites this file from what this returns, so silently coercing a
+ *  failed read to [] would surface a real I/O error as "gate not found" and a
+ *  subsequent write would replace every recorded gate with just this one. */
+function readGatesFileStrict(cwd, org) {
+    const path = join(cwd, ORG_DIR, org, 'gates.json');
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { gates: [] };
+        throw new Error(`cannot read ${path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${path} is not valid JSON (${err instanceof Error ? err.message : String(err)})`);
+    }
+    if (parsed?.gates === undefined || parsed.gates === null)
+        return { gates: [] };
+    if (!Array.isArray(parsed.gates))
+        throw new Error(`${path}: "gates" is not an array`);
+    return { gates: parsed.gates };
+}
 export const gatesAction = async (ctx, name) => {
     const data = readGatesFile(ctx.cwd, name);
-    const showAll = ctx.flags['all'] === true;
-    const gates = showAll ? data.gates : data.gates.filter(g => g.status === 'pending');
+    const showAll = ctx.flags.all === true;
+    const gates = showAll ? data.gates : data.gates.filter((g) => g.status === 'pending');
     if (!gates.length) {
-        log(output.info(showAll ? `No gates for org "${name}"` : `No pending gates for org "${name}" (use --all to include resolved)`));
+        log(output.info(showAll
+            ? `No gates for org "${name}"`
+            : `No pending gates for org "${name}" (use --all to include resolved)`));
         return { success: true };
     }
     log(output.info(`${showAll ? 'All' : 'Pending'} gates for org "${name}" (${gates.length}):\n`));
     for (const g of gates) {
-        const status = g.status === 'pending' ? '⏳ pending' : g.status === 'approved' ? '✅ approved' : '❌ rejected';
+        const status = g.status === 'pending'
+            ? '⏳ pending'
+            : g.status === 'approved'
+                ? '✅ approved'
+                : '❌ rejected';
         log(output.info(`  ${g.id}  ${status}  role:${g.roleId}`));
         log(output.info(`    name: ${g.name}`));
         log(output.info(`    desc: ${g.description}`));
@@ -930,9 +1062,19 @@ export const gateResolveAction = async (ctx, name, approved) => {
     const gateId = ctx.args[1];
     const resolution = ctx.args.slice(2).join(' ') || undefined;
     if (!gateId)
-        return { success: false, message: `usage: monomind org gate-${approved ? 'approve' : 'reject'} ${name} <gate-id> [resolution]` };
-    const data = readGatesFile(ctx.cwd, name);
-    const gate = data.gates.find(g => g.id === gateId);
+        return {
+            success: false,
+            message: `usage: monomind org gate-${approved ? 'approve' : 'reject'} ${name} <gate-id> [resolution]`,
+        };
+    let data;
+    try {
+        data = readGatesFileStrict(ctx.cwd, name);
+    }
+    catch (err) {
+        log(output.error(`Cannot read gates for org ${name}: ${err instanceof Error ? err.message : String(err)}`));
+        return { success: false, message: 'gates.json unreadable — gate not resolved' };
+    }
+    const gate = data.gates.find((g) => g.id === gateId);
     if (!gate)
         return { success: false, message: `gate "${gateId}" not found for org "${name}"` };
     if (gate.status !== 'pending')
@@ -943,23 +1085,58 @@ export const gateResolveAction = async (ctx, name, approved) => {
         const cred = normalizeCredential(remote.credential);
         try {
             const res = await fetch(`${remote.url}/api/resolve-gate`, {
-                method: 'POST', headers: { 'Content-Type': 'application/json', ...(cred ? { 'x-monomind-cred': cred } : {}) },
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...(cred ? { 'x-monomind-cred': cred } : {}),
+                },
                 body: JSON.stringify({ org: name, gateId, approved, resolution }),
                 signal: AbortSignal.timeout(10_000),
             });
-            const d = await res.json().catch(() => ({}));
+            const d = (await res.json().catch(() => ({})));
             if (res.ok && d.ok) {
                 log(output.success(`Gate ${gateId} ${approved ? 'approved' : 'rejected'} (live).`));
                 return { success: true, message: `gate ${approved ? 'approved' : 'rejected'}` };
             }
-            log(output.error(`Live resolution rejected: ${d.error ?? res.status}`));
-            return { success: false, message: d.error ?? `HTTP ${res.status}` };
+            log(output.warning(`Live resolution rejected (${d.error ?? res.status}) — falling back to offline queue.`));
         }
         catch (err) {
-            log(output.error(`Hosting daemon unreachable: ${err instanceof Error ? err.message : 'error'}`));
-            return { success: false, message: 'daemon unreachable — gate can only be resolved while the org is running' };
+            log(output.warning(`Hosting daemon unreachable (${err instanceof Error ? err.message : 'error'}) — falling back to offline queue.`));
         }
     }
-    return { success: false, message: `org "${name}" is not running — gates can only be resolved on a live org` };
+    // Offline path: no live daemon hosts this org (or the live call failed) —
+    // resolve gates.json directly, same as resolveApproval's offline branch.
+    // Re-read fresh (mirrors answerAction/resolveApproval) in case a live
+    // daemon resolved this gate concurrently while the live call above was
+    // in flight or timing out.
+    const { writeGates } = await import('../orgrt/decisions.js');
+    let fresh;
+    try {
+        fresh = readGatesFileStrict(ctx.cwd, name);
+    }
+    catch (err) {
+        log(output.error(`Refusing to rewrite gates.json — ${err instanceof Error ? err.message : String(err)}`));
+        log(output.warning(`The gate was NOT resolved. Fix or restore ${join(ctx.cwd, ORG_DIR, name, 'gates.json')}, then retry.`));
+        return { success: false, message: 'gates.json unreadable — gate not resolved' };
+    }
+    const idx = fresh.gates.findIndex((g) => g.id === gateId);
+    if (idx === -1)
+        return { success: false, message: `gate "${gateId}" not found for org "${name}"` };
+    if (fresh.gates[idx].status !== 'pending') {
+        return {
+            success: false,
+            message: `gate "${gateId}" already resolved (${fresh.gates[idx].status})`,
+        };
+    }
+    fresh.gates[idx] = {
+        ...fresh.gates[idx],
+        status: approved ? 'approved' : 'rejected',
+        resolvedAt: Date.now(),
+        resolvedBy: 'human',
+        resolution,
+    };
+    writeGates(ctx.cwd, name, fresh);
+    log(output.success(`Gate ${gateId} ${approved ? 'approved' : 'rejected'} — ${name} picks it up on its next cycle.`));
+    return { success: true, message: `gate ${approved ? 'approved' : 'rejected'} (queued)` };
 };
 //# sourceMappingURL=org-observe.js.map