@mnemom/mnemom 0.17.0-next.8 → 0.17.0

package/dist/commands/agent-sessions.d.ts

@@ -0,0 +1,99 @@
+/**
+ * `mnemom agent sessions [--all] [--json]` and `mnemom agent show [ref] [--json]`
+ * — the read side of the local session ledger (`~/.mnemom/sessions.jsonl`, one
+ * line per real launch) merged with the gateway's live goal state for one
+ * session (`GET /v1/agent/sessions/{conversationId}` via mnemom-api).
+ *
+ * Pure apart from the injected deps (`readRecords`, `fetchSession`, `out`,
+ * `err`), so every arm is unit-tested; `liveSessionDeps` is the thin driver
+ * index.ts wires in.
+ *
+ * Hash note: the CLI's launch-time envelope sha will NOT equal the gateway's
+ * sealed hash in general (the gateway normalises absent arrays to `[]`), so the
+ * local sha is never printed as "the sealed hash" and no mismatch is flagged —
+ * only the server's hash is shown, labelled "sealed hash".
+ */
+import { type SessionRecord } from "../lib/agent-ledger.js";
+import { type AgentSessionResponse } from "../lib/api.js";
+export interface SessionCommandDeps {
+    /** The ledger, newest first. */
+    readRecords: () => SessionRecord[];
+    /** The live state from mnemom-api; rejects when unreachable / not found. */
+    fetchSession: (conversationId: string, agentId: string, orgId: string) => Promise<AgentSessionResponse>;
+    out: (line: string) => void;
+    err: (line: string) => void;
+}
+/** The production wiring (index.ts). Lazy so a test that mocks lib/api without
+ *  this export can still import index.ts. */
+export declare const liveSessionDeps: SessionCommandDeps;
+export declare const NO_SESSIONS_MESSAGE = "No sessions yet \u2014 run `mnemom agent` to start one.";
+export declare const DEFAULT_SESSIONS_LIMIT = 20;
+export interface SessionRefMatch {
+    record: SessionRecord;
+    /** Older records sharing the same session name (only for name matches). */
+    others: SessionRecord[];
+}
+export interface SessionRefAmbiguous {
+    record: null;
+    /** Every record whose conversation id starts with the ref. */
+    candidates: SessionRecord[];
+}
+/**
+ * Resolve `[ref]` against the ledger (newest first):
+ *   - no ref → the newest record;
+ *   - an exact session name → the newest record with that name, older ones in `others`;
+ *   - else a conversation-id prefix → the unique match, or `{record: null, candidates}`
+ *     when several share the prefix;
+ *   - nothing matches (or the ledger is empty) → null.
+ */
+export declare function resolveSessionRef(records: SessionRecord[], ref?: string): SessionRefMatch | SessionRefAmbiguous | null;
+/** Goal alignment as the ledger recorded it: a contract at launch ⇒ on. */
+export declare function localGoalFlag(record: SessionRecord): "on" | "off";
+/**
+ * Render the ledger as a table, newest first — the newest
+ * `DEFAULT_SESSIONS_LIMIT` rows unless `all`, with a footer naming the rest.
+ */
+export declare function formatSessionsTable(rows: SessionRecord[], opts: {
+    all?: boolean;
+}): string[];
+/** `turns 3/10 (crossed)` — value against its ceiling (none ⇒ just the value). */
+export declare function gauge(label: string, value: number, ceiling: number | null, fired: boolean | undefined): string;
+/**
+ * The human view for `mnemom agent show`: the local record, then the live
+ * gateway state (or a dim "live state unavailable (<reason>)" line when
+ * `remote` is null).
+ */
+export declare function buildShowView(local: SessionRecord, remote: AgentSessionResponse | null, reason?: string): string[];
+/** The `--json` shape: the local record and the live section each tagged with its source. */
+export interface ShowJson {
+    session: SessionRecord & {
+        source: "local";
+    };
+    goal_alignment: "on" | "off";
+    live: {
+        source: "gateway";
+        available: true;
+        sealed: AgentSessionResponse["sealed"];
+        verdict: AgentSessionResponse["verdict"];
+        turn: AgentSessionResponse["turn"];
+        guardrails: AgentSessionResponse["guardrails"];
+    } | {
+        source: "gateway";
+        available: false;
+        reason: string;
+    };
+}
+export declare function buildShowJson(local: SessionRecord, remote: AgentSessionResponse | null, reason?: string): ShowJson;
+export interface AgentSessionsOptions {
+    all?: boolean;
+    json?: boolean;
+}
+/** `mnemom agent sessions [--all] [--json]` */
+export declare function agentSessionsCommand(opts: AgentSessionsOptions, deps: SessionCommandDeps): Promise<void>;
+export interface AgentShowOptions {
+    json?: boolean;
+}
+/** Why the live read could not happen, from the thrown error. */
+export declare function unavailableReason(err: unknown): string;
+/** `mnemom agent show [ref] [--json]` */
+export declare function agentShowCommand(ref: string | undefined, opts: AgentShowOptions, deps: SessionCommandDeps): Promise<void>;

package/dist/commands/agent-sessions.js

@@ -0,0 +1,271 @@
+/**
+ * `mnemom agent sessions [--all] [--json]` and `mnemom agent show [ref] [--json]`
+ * — the read side of the local session ledger (`~/.mnemom/sessions.jsonl`, one
+ * line per real launch) merged with the gateway's live goal state for one
+ * session (`GET /v1/agent/sessions/{conversationId}` via mnemom-api).
+ *
+ * Pure apart from the injected deps (`readRecords`, `fetchSession`, `out`,
+ * `err`), so every arm is unit-tested; `liveSessionDeps` is the thin driver
+ * index.ts wires in.
+ *
+ * Hash note: the CLI's launch-time envelope sha will NOT equal the gateway's
+ * sealed hash in general (the gateway normalises absent arrays to `[]`), so the
+ * local sha is never printed as "the sealed hash" and no mismatch is flagged —
+ * only the server's hash is shown, labelled "sealed hash".
+ */
+import { readSessionRecords } from "../lib/agent-ledger.js";
+import { MNEMOM_DIR } from "../lib/config.js";
+import { getAgentSession, MnemomApiError } from "../lib/api.js";
+import { fmt, formatRelativeAge } from "../lib/format.js";
+/** The production wiring (index.ts). Lazy so a test that mocks lib/api without
+ *  this export can still import index.ts. */
+export const liveSessionDeps = {
+    // The ledger is oldest-first on disk; every consumer here wants newest-first.
+    readRecords: () => readSessionRecords({ dir: MNEMOM_DIR }).reverse(),
+    fetchSession: (conversationId, agentId, orgId) => getAgentSession(conversationId, agentId, orgId),
+    out: (line) => console.log(line),
+    err: (line) => console.error(line),
+};
+export const NO_SESSIONS_MESSAGE = "No sessions yet — run `mnemom agent` to start one.";
+export const DEFAULT_SESSIONS_LIMIT = 20;
+/**
+ * Resolve `[ref]` against the ledger (newest first):
+ *   - no ref → the newest record;
+ *   - an exact session name → the newest record with that name, older ones in `others`;
+ *   - else a conversation-id prefix → the unique match, or `{record: null, candidates}`
+ *     when several share the prefix;
+ *   - nothing matches (or the ledger is empty) → null.
+ */
+export function resolveSessionRef(records, ref) {
+    const needle = ref?.trim() ?? "";
+    if (needle === "") {
+        const newest = records[0];
+        return newest ? { record: newest, others: [] } : null;
+    }
+    const newestByName = records.find((r) => r.session === needle);
+    if (newestByName) {
+        const others = records.filter((r) => r !== newestByName && r.session === needle);
+        return { record: newestByName, others };
+    }
+    const byConv = records.filter((r) => r.conversation_id.startsWith(needle));
+    if (byConv.length === 1)
+        return { record: byConv[0], others: [] };
+    if (byConv.length > 1)
+        return { record: null, candidates: byConv };
+    return null;
+}
+// ─── sessions table ───────────────────────────────────────────────────────────
+const COL = { session: 26, started: 16, agent: 22, goal: 6, conv: 8 };
+function cell(text, width) {
+    const max = width - 2;
+    const shown = text.length > max ? `${text.slice(0, max - 1)}…` : text;
+    return shown.padEnd(width);
+}
+/** Goal alignment as the ledger recorded it: a contract at launch ⇒ on. */
+export function localGoalFlag(record) {
+    return record.contract ? "on" : "off";
+}
+/**
+ * Render the ledger as a table, newest first — the newest
+ * `DEFAULT_SESSIONS_LIMIT` rows unless `all`, with a footer naming the rest.
+ */
+export function formatSessionsTable(rows, opts) {
+    const shown = opts.all ? rows : rows.slice(0, DEFAULT_SESSIONS_LIMIT);
+    const lines = [];
+    lines.push("  " +
+        cell("Session", COL.session) +
+        cell("Started", COL.started) +
+        cell("Agent", COL.agent) +
+        cell("Goal", COL.goal) +
+        "Conv");
+    lines.push("  " + "─".repeat(COL.session + COL.started + COL.agent + COL.goal + COL.conv));
+    for (const r of shown) {
+        lines.push("  " +
+            cell(r.session, COL.session) +
+            cell(formatRelativeAge(r.started_at), COL.started) +
+            cell(r.agent_slug, COL.agent) +
+            cell(localGoalFlag(r), COL.goal) +
+            r.conversation_id.slice(0, 8));
+    }
+    if (shown.length < rows.length) {
+        lines.push(fmt.dim(`  showing ${shown.length} of ${rows.length} sessions — pass --all for every session`));
+    }
+    return lines;
+}
+// ─── show view ────────────────────────────────────────────────────────────────
+function listOrDash(items) {
+    return items && items.length > 0 ? items.join(", ") : "—";
+}
+function numOrDash(n) {
+    return n === null || n === undefined ? "—" : String(n);
+}
+/** `turns 3/10 (crossed)` — value against its ceiling (none ⇒ just the value). */
+export function gauge(label, value, ceiling, fired) {
+    const ratio = ceiling === null ? String(value) : `${value}/${ceiling}`;
+    return `${label} ${ratio}${fired ? " (crossed)" : ""}`;
+}
+/**
+ * The human view for `mnemom agent show`: the local record, then the live
+ * gateway state (or a dim "live state unavailable (<reason>)" line when
+ * `remote` is null).
+ */
+export function buildShowView(local, remote, reason) {
+    const L = [];
+    L.push(fmt.header(`Session ${local.session}`));
+    L.push(fmt.label("started:      ", `${local.started_at} (${formatRelativeAge(local.started_at)})`));
+    L.push(fmt.label("agent:        ", `${local.agent_slug} ${local.agent_id ? `(${local.agent_id})` : fmt.dim("(id unresolved at launch)")}`));
+    L.push(fmt.label("org:          ", `${local.org_label} (${local.org_id})`));
+    L.push(fmt.label("gateway:      ", local.gateway_host));
+    const launchBits = [local.launch_shape, `cli ${local.cli}`];
+    if (local.model)
+        launchBits.push(`model ${local.model}`);
+    if (local.effort)
+        launchBits.push(`effort ${local.effort}`);
+    L.push(fmt.label("launch:       ", launchBits.join(" · ")));
+    L.push(fmt.label("conversation: ", local.conversation_id));
+    const goalOn = remote ? remote.sealed !== null : local.contract !== null;
+    L.push(fmt.label("goal alignment:", goalOn ? fmt.badge("ON", "green") : fmt.badge("OFF", "yellow")));
+    if (local.contract) {
+        L.push(fmt.label("goal (at launch):", local.contract.statement));
+    }
+    L.push(fmt.section("Live state (gateway)"));
+    if (!remote) {
+        L.push(fmt.dim(`  live state unavailable (${reason ?? "unknown"})`));
+        return L;
+    }
+    if (remote.sealed) {
+        const c = remote.sealed.contract;
+        L.push(fmt.label("statement:      ", c.statement));
+        L.push(fmt.label("requirements:   ", listOrDash(c.requirements)));
+        L.push(fmt.label("allowed paths:  ", listOrDash(c.allowed_paths)));
+        L.push(fmt.label("forbidden paths:", listOrDash(c.forbidden_paths)));
+        L.push(fmt.label("ceilings:       ", `max_turns ${numOrDash(c.max_turns)} · budget_usd ${numOrDash(c.budget_usd)} · stall_turns ${numOrDash(c.stall_turns)}`));
+        L.push(fmt.label("sealed hash:    ", remote.sealed.hash));
+        L.push(fmt.label("sealed at:      ", remote.sealed.sealed_at));
+    }
+    else {
+        L.push(fmt.dim("  no sealed contract on the gateway for this conversation"));
+    }
+    if (remote.verdict) {
+        const v = remote.verdict;
+        L.push(fmt.label("verdict:        ", `${v.verdict.toUpperCase()} at turn ${v.turn} — ${v.reason}`));
+    }
+    else {
+        L.push(fmt.label("verdict:        ", fmt.dim("none yet")));
+    }
+    if (remote.guardrails) {
+        const { ceilings, state } = remote.guardrails;
+        if (state) {
+            const parts = [
+                gauge("turns", state.turns, ceilings.max_turns, state.fired.turns),
+                gauge("spend $", state.spend_usd, ceilings.budget_usd, state.fired.budget),
+                gauge("stall", state.stall_run, ceilings.stall_turns, state.fired.stall),
+            ];
+            L.push(fmt.label("guardrails:     ", parts.join(" · ")));
+        }
+        else {
+            L.push(fmt.label("guardrails:     ", `ceilings max_turns ${numOrDash(ceilings.max_turns)} · budget_usd ${numOrDash(ceilings.budget_usd)} · stall_turns ${numOrDash(ceilings.stall_turns)} ${fmt.dim("(no turns counted yet)")}`));
+        }
+    }
+    else {
+        L.push(fmt.label("guardrails:     ", fmt.dim("none")));
+    }
+    if (remote.turn !== null) {
+        L.push(fmt.label("turn:           ", String(remote.turn)));
+    }
+    return L;
+}
+export function buildShowJson(local, remote, reason) {
+    const goalOn = remote ? remote.sealed !== null : local.contract !== null;
+    return {
+        session: { ...local, source: "local" },
+        goal_alignment: goalOn ? "on" : "off",
+        live: remote
+            ? {
+                source: "gateway",
+                available: true,
+                sealed: remote.sealed,
+                verdict: remote.verdict,
+                turn: remote.turn,
+                guardrails: remote.guardrails,
+            }
+            : { source: "gateway", available: false, reason: reason ?? "unknown" },
+    };
+}
+/** `mnemom agent sessions [--all] [--json]` */
+export async function agentSessionsCommand(opts, deps) {
+    const records = deps.readRecords();
+    const rows = opts.all ? records : records.slice(0, DEFAULT_SESSIONS_LIMIT);
+    if (opts.json) {
+        deps.out(JSON.stringify(rows, null, 2));
+        return;
+    }
+    if (records.length === 0) {
+        deps.out(NO_SESSIONS_MESSAGE);
+        return;
+    }
+    deps.out(fmt.header("Mnemom Agent sessions"));
+    deps.out("");
+    for (const line of formatSessionsTable(records, { all: opts.all }))
+        deps.out(line);
+    deps.out("");
+}
+/** Why the live read could not happen, from the thrown error. */
+export function unavailableReason(err) {
+    if (err instanceof MnemomApiError && err.code)
+        return `${err.code}: ${err.message}`;
+    return err instanceof Error ? err.message : String(err);
+}
+/** `mnemom agent show [ref] [--json]` */
+export async function agentShowCommand(ref, opts, deps) {
+    const records = deps.readRecords();
+    if (records.length === 0) {
+        if (opts.json)
+            deps.out(JSON.stringify(null));
+        else
+            deps.out(NO_SESSIONS_MESSAGE);
+        return;
+    }
+    const resolved = resolveSessionRef(records, ref);
+    if (resolved === null) {
+        deps.err(fmt.error(`No session matches '${ref ?? ""}' — try \`mnemom agent sessions\`.`));
+        process.exitCode = 1;
+        return;
+    }
+    if (resolved.record === null) {
+        deps.err(fmt.error(`'${ref ?? ""}' matches ${resolved.candidates.length} sessions — give more of the conversation id:`));
+        for (const c of resolved.candidates) {
+            deps.err(`  ${c.conversation_id}  ${c.session}  ${formatRelativeAge(c.started_at)}`);
+        }
+        process.exitCode = 1;
+        return;
+    }
+    const { record, others } = resolved;
+    let remote = null;
+    let reason;
+    if (record.agent_id === null) {
+        reason = "agent id was not resolved at launch";
+    }
+    else {
+        try {
+            remote = await deps.fetchSession(record.conversation_id, record.agent_id, record.org_id);
+        }
+        catch (e) {
+            reason = unavailableReason(e);
+        }
+    }
+    if (opts.json) {
+        deps.out(JSON.stringify(buildShowJson(record, remote, reason), null, 2));
+        return;
+    }
+    for (const line of buildShowView(record, remote, reason))
+        deps.out(line);
+    if (others.length > 0) {
+        deps.out("");
+        deps.out(fmt.dim(`  ${others.length} older session(s) share this name — \`mnemom agent show <conv-id prefix>\` picks one:`));
+        for (const o of others) {
+            deps.out(fmt.dim(`    ${o.conversation_id.slice(0, 8)}  ${formatRelativeAge(o.started_at)}`));
+        }
+    }
+    deps.out("");
+}

package/dist/commands/agent.d.ts

@@ -73,6 +73,25 @@ export interface AgentOptions {
 }
 /** Entry point for `mnemom agent [scenario]`. Throws on fatal misconfig. */
 export declare function agentCommand(scenarioArg: string | undefined, options?: AgentOptions): Promise<void>;
+/**
+ * Record this launch in ~/.mnemom/sessions.jsonl. The agent record id is
+ * resolved best-effort (a lookup failure or an unknown slug records null); a
+ * ledger write failure warns to stderr and the launch proceeds regardless.
+ */
+export declare function recordSessionLaunch(ctx: {
+    session: string;
+    conversationId: string;
+    agent: string;
+    account: {
+        orgId: string;
+        orgLabel: string;
+    };
+    gatewayHost: string;
+    shape: LaunchShape;
+    options: AgentOptions;
+    cli: ResolvedCli;
+    envelope: SealedContractEnvelope | null;
+}): Promise<void>;
 /**
  * Resolve the Anthropic key with NO 1Password dependency (built for external
  * customer adoption), in order:

package/dist/commands/agent.js

@@ -31,6 +31,8 @@ import { tmpdir, homedir } from "node:os";
 import { basename, join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { MNEMOM_DIR } from "../lib/config.js";
+import { getAgentByName } from "../lib/api.js";
+import { LEDGER_FILE, appendSessionRecord, toLedgerContract } from "../lib/agent-ledger.js";
 import { configKeySpec, loadLauncherConfig, writeLauncherConfig } from "../lib/launcher-config.js";
 import { fmt } from "../lib/format.js";
 import { askInput, askSelect, askYesNo, isInteractive } from "../lib/prompt.js";
@@ -160,8 +162,9 @@ export async function agentCommand(scenarioArg, options = {}) {
     // there isn't one — and (2) enforce a positive µ balance on the org the agent
     // lives in (default: the user's personal org). No µ ⇒ blocked with a
     // portal-style top-up message. Skipped only on --dry-run (handled above).
+    let account;
     try {
-        await ensureSessionAndBalance({ interactive: isInteractive() });
+        account = await ensureSessionAndBalance({ interactive: isInteractive() });
     }
     catch (err) {
         if (isQuietPreambleExit(err))
@@ -195,6 +198,21 @@ export async function agentCommand(scenarioArg, options = {}) {
             say(fmt.warn(`mnemom agent: agent setup did not complete (${msg}) — launching with the unclaimed identity.`));
         }
     }
+    // ── local session ledger (~/.mnemom/sessions.jsonl) ── one line per real
+    // launch so `mnemom agent sessions` / `show` can find this conversation later.
+    // Written after provisioning so a freshly claimed agent's id resolves. Holds
+    // NO secret (never the key, the headers, or the child env); best-effort.
+    await recordSessionLaunch({
+        session: scenario,
+        conversationId,
+        agent,
+        account,
+        gatewayHost,
+        shape,
+        options,
+        cli,
+        envelope,
+    });
     logLaunch({ shape, door, agent, conversationId, cellNote, envelope, goalMode, cli });
     say(goalAlignmentLine(goalAlignmentMode(envelope, goalMode)));
     if (shape === "terminal") {
@@ -227,6 +245,40 @@ export async function agentCommand(scenarioArg, options = {}) {
     });
 }
 // ───────────────────────────────────────────────────────────────────────────
+// Session ledger (thin driver over lib/agent-ledger.ts)
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * Record this launch in ~/.mnemom/sessions.jsonl. The agent record id is
+ * resolved best-effort (a lookup failure or an unknown slug records null); a
+ * ledger write failure warns to stderr and the launch proceeds regardless.
+ */
+export async function recordSessionLaunch(ctx) {
+    let agentId;
+    try {
+        agentId = (await getAgentByName(ctx.agent))?.id ?? null;
+    }
+    catch {
+        agentId = null; // unresolvable right now — the ledger still records the launch
+    }
+    const result = appendSessionRecord({
+        session: ctx.session,
+        conversation_id: ctx.conversationId,
+        agent_slug: ctx.agent,
+        agent_id: agentId,
+        org_id: ctx.account.orgId,
+        org_label: ctx.account.orgLabel,
+        gateway_host: ctx.gatewayHost,
+        launch_shape: ctx.shape,
+        model: ctx.options.model?.trim() || null,
+        effort: ctx.options.effort?.trim() || null,
+        cli: ctx.cli.name,
+        contract: toLedgerContract(ctx.envelope?.contract ?? null),
+    }, { dir: MNEMOM_DIR, now: () => new Date(), pid: process.pid });
+    if (!result.ok) {
+        say(fmt.warn(`mnemom agent: could not record this session in ~/.mnemom/${LEDGER_FILE} (${result.error}) — launching anyway.`));
+    }
+}
+// ───────────────────────────────────────────────────────────────────────────
 // Credential resolution (zero 1Password)
 // ───────────────────────────────────────────────────────────────────────────
 /**

package/dist/commands/validate.js

@@ -12,7 +12,7 @@
  * green — useful for shell scripts and the `mnemom/deploy` gate-guard
  * workflow which can call the CLI rather than parse the JSON itself.
  */
-import { fmt } from "../lib/format.js";
+import { fmt, formatRelativeAge } from "../lib/format.js";
 import { requireAuth } from "../lib/auth.js";
 import { getSafeHouseHarnessState } from "../lib/api.js";
 /**
@@ -32,21 +32,6 @@ function parseMaxAge(input) {
     const ms = n * { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[unit];
     return ms;
 }
-function formatRelativeAge(startedAt) {
-    const ageMs = Date.now() - Date.parse(startedAt);
-    if (ageMs < 0)
-        return "in the future?";
-    const m = Math.floor(ageMs / 60_000);
-    if (m < 1)
-        return "<1m ago";
-    if (m < 60)
-        return `${m}m ago`;
-    const h = Math.floor(m / 60);
-    if (h < 24)
-        return `${h}h ${m % 60}m ago`;
-    const d = Math.floor(h / 24);
-    return `${d}d ${h % 24}h ago`;
-}
 function evaluateLane(lane, run, maxAgeMs) {
     if (!run) {
         return {

package/dist/index.js

@@ -10,6 +10,7 @@ import { cardShowCommand, cardPublishCommand, cardValidateCommand, cardEditComma
 import { policyInitCommand, policyValidateCommand, policyPublishCommand, policyListCommand, policyTestCommand, policyEvaluateCommand, } from "./commands/policy.js";
 import { protectionShowCommand, protectionPublishCommand, protectionValidateCommand, protectionEditCommand, protectionDriftCommand, } from "./commands/protection.js";
 import { agentsListCommand, agentsClaimCommand, agentsMoveCommand } from "./commands/agents.js";
+import { agentSessionsCommand, agentShowCommand, liveSessionDeps, } from "./commands/agent-sessions.js";
 import { orgListCommand, orgShowCommand, orgUseCommand } from "./commands/org.js";
 import { teamListCommand, teamShowCommand, teamTemplateCommand, teamPreviewComposeCommand, teamAdminGrantCommand, teamAdminRevokeCommand, teamAdminListCommand, teamCoverageCommand, } from "./commands/team.js";
 import { advisoriesListCommand, advisoriesShowCommand } from "./commands/advisories.js";
@@ -103,7 +104,7 @@ const collectRepeatable = (value, previous) => {
 const agentCmd = program
     .command("agent [session] [passthrough...]")
     .description("Launch your governed agent (Claude Code in v1) through the Mnemom gateway — governed identity + optional sealed goal contract. Plain `mnemom agent` asks for a session name and an optional goal. " +
-    "Sub-verbs: `setup` provisions your governed agent; `doctor` preflights prerequisites; `config …` manages persistent settings (~/.mnemom/launcher.toml); `invite <token>` redeems a Mnemom Agent invitation; `list` / `claim` / `move` manage the agents in your orgs.")
+    "Sub-verbs: `setup` provisions your governed agent; `doctor` preflights prerequisites; `config …` manages persistent settings (~/.mnemom/launcher.toml); `invite <token>` redeems a Mnemom Agent invitation; `list` / `claim` / `move` manage the agents in your orgs; `sessions` lists your past launches and `show [ref]` merges one with its live goal state.")
     .option("--goal <statement>", "Contract goal statement (required if any contract flag is given)")
     .option("--requirement <text>", "Contract requirement (repeatable)", collectRepeatable, [])
     .option("--allow <glob>", "Allowed path/glob (repeatable)", collectRepeatable, [])
@@ -698,6 +699,34 @@ agentCmd
         process.exit(1);
     }
 });
+agentCmd
+    .command("sessions")
+    .description("List your Mnemom Agent sessions from the local ledger (~/.mnemom/sessions.jsonl), newest first — the last 20 unless --all")
+    .option("--all", "Every session, not just the newest 20")
+    .option("--json", "Output the rows as JSON instead of a table")
+    .action(async (opts) => {
+    try {
+        await agentSessionsCommand({ all: opts.all, json: opts.json }, liveSessionDeps);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+agentCmd
+    .command("show [ref]")
+    .description("Show one session — the local launch record merged with the gateway's live goal state (sealed contract, latest verdict, guardrails). " +
+    "`ref` is a session name (newest match wins) or a unique conversation-id prefix; omitted = the newest session")
+    .option("--json", "Output the merged view as JSON (each section tagged with its source)")
+    .action(async (ref, opts) => {
+    try {
+        await agentShowCommand(ref, { json: opts.json }, liveSessionDeps);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
 // ============================================================================
 // Organization management (ADR-044, Piece 1 of T1-3.1)
 // ============================================================================

package/dist/lib/agent-ledger.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The local session ledger for `mnemom agent` — `~/.mnemom/sessions.jsonl`, one
+ * JSON line per REAL launch (never `--dry-run`), newest last.
+ *
+ * Pure module: the directory, the clock and the pid are injected so the append
+ * and the read are unit-testable with a temp dir. The record is deliberately a
+ * closed shape — the Anthropic key, the custom-headers line and the child env
+ * are never part of it (see `SessionRecord`), so nothing secret can ride along.
+ *
+ * Writes are best-effort: `appendSessionRecord` never throws — a failure comes
+ * back as `{ ok: false, error }` and the caller decides how loudly to warn.
+ */
+import type { LaunchShape, SealedContract } from "./agent.js";
+/** The ledger's file name under MNEMOM_DIR. */
+export declare const LEDGER_FILE = "sessions.jsonl";
+/** The ledger keeps only the newest this-many launches. */
+export declare const LEDGER_CAP = 200;
+/** The sealed-contract fields the ledger keeps (no goal_id — the statement is the identity). */
+export interface SessionRecordContract {
+    statement: string;
+    requirements?: string[];
+    allowed_paths?: string[];
+    forbidden_paths?: string[];
+    max_turns?: number;
+    budget_usd?: number;
+    stall_turns?: number;
+}
+/** One launch, as written to the ledger. */
+export interface SessionRecord {
+    v: 1;
+    /** ISO-8601 UTC. */
+    started_at: string;
+    /** The session (scenario) name. */
+    session: string;
+    conversation_id: string;
+    /** The x-mnemom-agent slug the launch ran under. */
+    agent_slug: string;
+    /** The agent record id when it resolved at launch, else null. */
+    agent_id: string | null;
+    org_id: string;
+    org_label: string;
+    gateway_host: string;
+    launch_shape: LaunchShape;
+    model: string | null;
+    effort: string | null;
+    /** The coding-agent CLI's basename, e.g. "claude". */
+    cli: string;
+    contract: SessionRecordContract | null;
+}
+/** What the call site supplies — the ledger stamps `v` and `started_at`. */
+export type SessionRecordInput = Omit<SessionRecord, "v" | "started_at">;
+/** The injected environment of the ledger. */
+export interface LedgerDeps {
+    /** The directory holding the ledger (MNEMOM_DIR in production). */
+    dir: string;
+    /** The clock (stamps `started_at` and names the rewrite temp file). */
+    now: () => Date;
+    /** The writing process's pid (names the rewrite temp file). */
+    pid: number;
+}
+export type AppendResult = {
+    ok: true;
+    record: SessionRecord;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Project a sealed contract onto the ledger's contract shape (drops `goal_id`,
+ * keeps only defined fields). `null` in, `null` out.
+ */
+export declare function toLedgerContract(sealed: SealedContract | null): SessionRecordContract | null;
+/** The ledger's path under `dir`. */
+export declare function ledgerPath(dir: string): string;
+/**
+ * Append one launch to the ledger, atomically and capped:
+ *   - `dir` is created 0o700 when missing; the file is created 0o600;
+ *   - the new line is appended when the ledger stays within LEDGER_CAP lines,
+ *     otherwise the newest LEDGER_CAP lines (this one included) are rewritten
+ *     via a temp file + rename, so a reader never sees a torn file.
+ * Never throws — a failure is returned as `{ ok: false, error }`.
+ */
+export declare function appendSessionRecord(input: SessionRecordInput, deps: LedgerDeps): AppendResult;
+/**
+ * Read the ledger, oldest first (file order). A missing file is an empty
+ * ledger; a line that is not a v1 record object is skipped, never fatal.
+ */
+export declare function readSessionRecords(deps: Pick<LedgerDeps, "dir">): SessionRecord[];
+/** One ledger line → a record, or null when it is not a v1 record object. */
+export declare function parseRecord(line: string): SessionRecord | null;

package/dist/lib/agent-ledger.js

@@ -0,0 +1,126 @@
+/**
+ * The local session ledger for `mnemom agent` — `~/.mnemom/sessions.jsonl`, one
+ * JSON line per REAL launch (never `--dry-run`), newest last.
+ *
+ * Pure module: the directory, the clock and the pid are injected so the append
+ * and the read are unit-testable with a temp dir. The record is deliberately a
+ * closed shape — the Anthropic key, the custom-headers line and the child env
+ * are never part of it (see `SessionRecord`), so nothing secret can ride along.
+ *
+ * Writes are best-effort: `appendSessionRecord` never throws — a failure comes
+ * back as `{ ok: false, error }` and the caller decides how loudly to warn.
+ */
+import { appendFileSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/** The ledger's file name under MNEMOM_DIR. */
+export const LEDGER_FILE = "sessions.jsonl";
+/** The ledger keeps only the newest this-many launches. */
+export const LEDGER_CAP = 200;
+/**
+ * Project a sealed contract onto the ledger's contract shape (drops `goal_id`,
+ * keeps only defined fields). `null` in, `null` out.
+ */
+export function toLedgerContract(sealed) {
+    if (!sealed)
+        return null;
+    const out = { statement: sealed.statement };
+    if (sealed.requirements !== undefined)
+        out.requirements = sealed.requirements;
+    if (sealed.allowed_paths !== undefined)
+        out.allowed_paths = sealed.allowed_paths;
+    if (sealed.forbidden_paths !== undefined)
+        out.forbidden_paths = sealed.forbidden_paths;
+    if (sealed.max_turns !== undefined)
+        out.max_turns = sealed.max_turns;
+    if (sealed.budget_usd !== undefined)
+        out.budget_usd = sealed.budget_usd;
+    if (sealed.stall_turns !== undefined)
+        out.stall_turns = sealed.stall_turns;
+    return out;
+}
+/** The ledger's path under `dir`. */
+export function ledgerPath(dir) {
+    return join(dir, LEDGER_FILE);
+}
+/**
+ * Read the ledger text, or null when the file does not exist. Read-and-catch
+ * rather than exists-then-read so there is no window in which the file can
+ * change between the check and the read (CodeQL js/file-system-race).
+ */
+function readLedgerText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+/**
+ * Append one launch to the ledger, atomically and capped:
+ *   - `dir` is created 0o700 when missing; the file is created 0o600;
+ *   - the new line is appended when the ledger stays within LEDGER_CAP lines,
+ *     otherwise the newest LEDGER_CAP lines (this one included) are rewritten
+ *     via a temp file + rename, so a reader never sees a torn file.
+ * Never throws — a failure is returned as `{ ok: false, error }`.
+ */
+export function appendSessionRecord(input, deps) {
+    const path = ledgerPath(deps.dir);
+    try {
+        const record = { v: 1, started_at: deps.now().toISOString(), ...input };
+        mkdirSync(deps.dir, { recursive: true, mode: 0o700 });
+        const line = `${JSON.stringify(record)}\n`;
+        const text = readLedgerText(path);
+        const existing = text === null ? [] : nonEmptyLines(text);
+        if (existing.length + 1 > LEDGER_CAP) {
+            const kept = [...existing, JSON.stringify(record)].slice(-LEDGER_CAP);
+            const tmp = join(deps.dir, `.${LEDGER_FILE}.tmp-${deps.pid}-${deps.now().getTime()}`);
+            writeFileSync(tmp, `${kept.join("\n")}\n`, { mode: 0o600 });
+            renameSync(tmp, path);
+        }
+        else {
+            appendFileSync(path, line, { mode: 0o600 });
+        }
+        return { ok: true, record, path };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Read the ledger, oldest first (file order). A missing file is an empty
+ * ledger; a line that is not a v1 record object is skipped, never fatal.
+ */
+export function readSessionRecords(deps) {
+    const path = ledgerPath(deps.dir);
+    const text = readLedgerText(path);
+    if (text === null)
+        return [];
+    const out = [];
+    for (const line of nonEmptyLines(text)) {
+        const parsed = parseRecord(line);
+        if (parsed)
+            out.push(parsed);
+    }
+    return out;
+}
+/** One ledger line → a record, or null when it is not a v1 record object. */
+export function parseRecord(line) {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const rec = value;
+    if (rec.v !== 1)
+        return null;
+    return rec;
+}
+function nonEmptyLines(text) {
+    return text.split("\n").filter((l) => l.trim().length > 0);
+}

package/dist/lib/api.d.ts

@@ -1219,6 +1219,68 @@ export declare const CODE_NOT_ENABLED = "code_not_enabled";
  * for membership/transport failures.
  */
 export declare function getCodeEntitlement(orgId?: string): Promise<CodeEntitlement>;
+/** The gateway's sealed contract for a conversation (absent arrays are `[]`). */
+export interface AgentSessionSealed {
+    contract: {
+        goal_id?: string;
+        statement: string;
+        requirements: string[];
+        allowed_paths: string[];
+        forbidden_paths: string[];
+        max_turns?: number;
+        budget_usd?: number;
+        stall_turns?: number;
+    };
+    /** The gateway's hash of the sealed contract — NOT the CLI's launch-time sha. */
+    hash: string;
+    sealed_at: string;
+}
+/** The latest goal-judge verdict stored for the conversation. */
+export interface AgentSessionVerdict {
+    turn: number;
+    verdict: "aligned" | "drifting" | "violation";
+    reason: string;
+    at: string;
+    streak_start?: number;
+}
+export interface AgentSessionGuardrails {
+    ceilings: {
+        /** null = inactive */
+        max_turns: number | null;
+        budget_usd: number | null;
+        stall_turns: number | null;
+    };
+    state: {
+        turns: number;
+        spend_usd: number;
+        stall_run: number;
+        fired: {
+            turns?: boolean;
+            budget?: boolean;
+            stall?: boolean;
+        };
+    } | null;
+}
+/** `GET /v1/agent/sessions/{conversationId}` 200 body. Nulls mean "nothing stored" — absence is data. */
+export interface AgentSessionResponse {
+    conversation_id: string;
+    agent: {
+        id: string;
+        name: string | null;
+    };
+    org_id: string;
+    sealed: AgentSessionSealed | null;
+    verdict: AgentSessionVerdict | null;
+    turn: number | null;
+    guardrails: AgentSessionGuardrails | null;
+}
+/**
+ * The live goal state of one `mnemom agent` session, read through mnemom-api
+ * (org-scoped; the api proxies the gateway's internal read). Non-OK responses
+ * keep the server's `code` + `details` (`agent_not_found`, `gateway_unavailable`)
+ * so `mnemom agent show` can name the reason.
+ */
+export declare function getAgentSession(conversationId: string, agentId: string, orgId: string): Promise<AgentSessionResponse>;
 /** `POST /v1/invites/accept` 200 body. Never carries an amount — only whether the
  *  starter grant fired or was deferred for a later backfill. */
 export interface AcceptProductInviteResult {

package/dist/lib/api.js

@@ -1538,6 +1538,17 @@ export async function getCodeEntitlement(orgId) {
     const q = orgId ? `?org_id=${encodeURIComponent(orgId)}` : "";
     return codeFetch(`/v1/code/entitlement${q}`, {}, "Could not check Mnemom Agent access");
 }
+/**
+ * The live goal state of one `mnemom agent` session, read through mnemom-api
+ * (org-scoped; the api proxies the gateway's internal read). Non-OK responses
+ * keep the server's `code` + `details` (`agent_not_found`, `gateway_unavailable`)
+ * so `mnemom agent show` can name the reason.
+ */
+export async function getAgentSession(conversationId, agentId, orgId) {
+    // `org_id` is the org the launch resolved (the ledger record's), so an agent that
+    // lives in a non-primary org resolves instead of 404ing against the caller's primary org.
+    return codeFetch(`/v1/agent/sessions/${encodeURIComponent(conversationId)}?agent_id=${encodeURIComponent(agentId)}&org_id=${encodeURIComponent(orgId)}`, {}, "Could not read the session's live state");
+}
 /** Redeem a `pinv_…` product invite (a Mnemom Agent invitation) for the signed-in user. */
 export async function acceptProductInvite(token) {
     return codeFetch("/v1/invites/accept", { method: "POST", body: JSON.stringify({ token }) }, "Could not redeem the invitation");

package/dist/lib/format.d.ts

@@ -37,3 +37,9 @@ export declare const fmt: {
      */
     badge(text: string, color?: BadgeColor): string;
 };
+/**
+ * Human-friendly age of an ISO timestamp relative to now — "<1m ago", "42m ago",
+ * "3h 5m ago", "2d 4h ago"; a timestamp ahead of the clock reads "in the future?".
+ * Shared by `mnemom validate` and `mnemom agent sessions` / `show`.
+ */
+export declare function formatRelativeAge(startedAt: string): string;

package/dist/lib/format.js

@@ -64,3 +64,23 @@ export const fmt = {
         return colorFn(`[${text}]`);
     },
 };
+/**
+ * Human-friendly age of an ISO timestamp relative to now — "<1m ago", "42m ago",
+ * "3h 5m ago", "2d 4h ago"; a timestamp ahead of the clock reads "in the future?".
+ * Shared by `mnemom validate` and `mnemom agent sessions` / `show`.
+ */
+export function formatRelativeAge(startedAt) {
+    const ageMs = Date.now() - Date.parse(startedAt);
+    if (ageMs < 0)
+        return "in the future?";
+    const m = Math.floor(ageMs / 60_000);
+    if (m < 1)
+        return "<1m ago";
+    if (m < 60)
+        return `${m}m ago`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}h ${m % 60}m ago`;
+    const d = Math.floor(h / 24);
+    return `${d}d ${h % 24}h ago`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.17.0-next.8",
+  "version": "0.17.0",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {