@mnemom/mnemom 0.17.2-next.3 → 0.17.2-next.4

package/README.md

@@ -84,6 +84,26 @@ An explicit launch shape (`--remote-control`, `--server`, `MNEMOM_AGENT_REMOTE_C
 or `launch` in `launcher.toml`) also skips the Remote Control capability probe
 (`claude --help`), which only feeds the automatic upgrade to Remote Control.
 
+#### Context handoff (experimental, off by default)
+
+**Off by default.** `--context-handoff` (or the standing default `mnemom agent config set
+context_handoff on`) registers one extra MCP tool, `handoff(note)`, that the agent can call
+itself — at a natural stopping point, or as soon as it sees a `[mnemom context warning]` line
+from the gateway — to hand a short note (goal, what's done, next action, open questions) to
+its own successor context ahead of the gateway's next fold. It also tells the gateway to turn
+the context-handoff capability on for that one session. Leaving the setting off (the default)
+sends neither the tool nor the header, and the launch is unaffected.
+
+Turn it on for a single launch with `--context-handoff`, or set the standing default:
+
+```bash
+mnemom agent config set context_handoff on   # persists in ~/.mnemom/launcher.toml
+mnemom agent config set context_handoff off  # back to the default
+```
+
+This is experimental: it only ever ADDS the one tool (no gateway behavior changes for a
+session that leaves the setting off, and no change to Claude Code's own `/compact`).
+
 ## How It Works
 
 ```

package/dist/commands/agent-config.js

@@ -187,6 +187,9 @@ function deleteKey(cfg, key) {
         case "key_source":
             delete cfg.keySource;
             break;
+        case "context_handoff":
+            delete cfg.contextHandoff;
+            break;
         default:
             requireSpec(key); // throws the known-keys message for anything unknown
     }

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

@@ -0,0 +1,79 @@
+/**
+ * `mnemom agent goal show|pin|reset` (implicit-goal CLI, cli-telemetry §1.4): read and steer the
+ * goal the gateway INFERRED for an implicit-mode session, through the gateway's control route
+ * (lib/goal-api.ts). The session is picked from the local ledger exactly like `mnemom agent show`
+ * (a name, newest match wins, or a unique conversation-id prefix; omitted = the newest session).
+ *
+ *   mnemom agent goal show  [ref] [--thread <id>|--all-threads] [--history] [--json]
+ *   mnemom agent goal pin   [ref] [--thread <id>] [--off] [--json]
+ *   mnemom agent goal reset [ref] [--thread <id>] [--statement <s>] [--requirement <r>...] [--yes] [--json]
+ *
+ * Exit codes: 0 ok; 1 no such session / auth or agent not found / gateway or network failure /
+ * reset declined at the prompt; 2 a usage error (not implicit mode, a bad --thread, --requirement
+ * without --statement, reset without --yes off a TTY) or a 409 from the gateway (sealed contract,
+ * nothing to pin).
+ *
+ * Pure apart from the injected deps, so every arm is unit-tested; `liveGoalDeps` is the driver
+ * index.ts wires in. Key material is never printed.
+ */
+import { type SessionRecord } from "../lib/agent-ledger.js";
+import { type FetchLike, type GoalControlCreds, type GoalShowResponse } from "../lib/goal-api.js";
+export interface GoalCommandDeps {
+    /** The ledger, newest first. */
+    readRecords: () => SessionRecord[];
+    fetch: FetchLike;
+    /** The launch's credential; rejects when no key resolves. */
+    resolveCreds: () => Promise<GoalControlCreds>;
+    isTTY: () => boolean;
+    confirm: (question: string) => Promise<boolean>;
+    out: (line: string) => void;
+    err: (line: string) => void;
+}
+/**
+ * The Anthropic key the launch would resolve (env, then ~/.mnemom/launcher.json), never prompted
+ * for. Lazy import: commands/agent.ts is the launcher and carries a heavy import graph.
+ */
+export declare function resolveLaunchCreds(): Promise<GoalControlCreds>;
+export declare const liveGoalDeps: GoalCommandDeps;
+export interface GoalShowOptions {
+    thread?: string;
+    allThreads?: boolean;
+    history?: boolean;
+    json?: boolean;
+}
+export interface GoalPinOptions {
+    thread?: string;
+    off?: boolean;
+    json?: boolean;
+}
+export interface GoalResetOptions {
+    thread?: string;
+    statement?: string;
+    requirement?: string[];
+    yes?: boolean;
+    json?: boolean;
+}
+/** A failed command: the message and the exit code. */
+declare class Exit extends Error {
+    readonly code: 1 | 2;
+    constructor(code: 1 | 2, message: string);
+}
+/** Validate `--thread` locally (same regex as the gateway); `all` only where `allowAll`. */
+export declare function parseThreadOption(raw: string | undefined, allowAll: boolean): string;
+/** The ledger record for `ref`, refusing anything that is not an implicit-mode session. */
+export declare function pickImplicitSession(records: SessionRecord[], ref: string | undefined): SessionRecord;
+/** A gateway / transport failure → the exit code and a message that never names the key. */
+export declare function mapGoalError(e: unknown, host: string): Exit;
+/** `rev 3 · pinned@3 · class refine · 2 pending`, or `rev 0 (no goal yet)`. */
+export declare function revisionLine(body: Pick<GoalShowResponse, "intent" | "last_revision">): string;
+/** The human view of one show body. */
+export declare function buildGoalShowView(record: SessionRecord, body: GoalShowResponse, opts: {
+    history?: boolean;
+}): string[];
+/** `mnemom agent goal show [ref] [--thread <id>|--all-threads] [--history] [--json]` */
+export declare function agentGoalShowCommand(ref: string | undefined, opts: GoalShowOptions, deps: GoalCommandDeps): Promise<number>;
+/** `mnemom agent goal pin [ref] [--thread <id>] [--off] [--json]` */
+export declare function agentGoalPinCommand(ref: string | undefined, opts: GoalPinOptions, deps: GoalCommandDeps): Promise<number>;
+/** `mnemom agent goal reset [ref] [--thread <id>] [--statement <s>] [--requirement <r>...] [--yes] [--json]` */
+export declare function agentGoalResetCommand(ref: string | undefined, opts: GoalResetOptions, deps: GoalCommandDeps): Promise<number>;
+export {};

package/dist/commands/agent-goal.js

@@ -0,0 +1,276 @@
+/**
+ * `mnemom agent goal show|pin|reset` (implicit-goal CLI, cli-telemetry §1.4): read and steer the
+ * goal the gateway INFERRED for an implicit-mode session, through the gateway's control route
+ * (lib/goal-api.ts). The session is picked from the local ledger exactly like `mnemom agent show`
+ * (a name, newest match wins, or a unique conversation-id prefix; omitted = the newest session).
+ *
+ *   mnemom agent goal show  [ref] [--thread <id>|--all-threads] [--history] [--json]
+ *   mnemom agent goal pin   [ref] [--thread <id>] [--off] [--json]
+ *   mnemom agent goal reset [ref] [--thread <id>] [--statement <s>] [--requirement <r>...] [--yes] [--json]
+ *
+ * Exit codes: 0 ok; 1 no such session / auth or agent not found / gateway or network failure /
+ * reset declined at the prompt; 2 a usage error (not implicit mode, a bad --thread, --requirement
+ * without --statement, reset without --yes off a TTY) or a 409 from the gateway (sealed contract,
+ * nothing to pin).
+ *
+ * Pure apart from the injected deps, so every arm is unit-tested; `liveGoalDeps` is the driver
+ * index.ts wires in. Key material is never printed.
+ */
+import { readSessionRecords } from "../lib/agent-ledger.js";
+import { MNEMOM_DIR } from "../lib/config.js";
+import { fmt, formatRelativeAge } from "../lib/format.js";
+import { GoalControlError, goalControlFetch, isValidGoalThread, } from "../lib/goal-api.js";
+import { askYesNo, isInteractive } from "../lib/prompt.js";
+import { localGoalFlag, resolveSessionRef } from "./agent-sessions.js";
+/**
+ * The Anthropic key the launch would resolve (env, then ~/.mnemom/launcher.json), never prompted
+ * for. Lazy import: commands/agent.ts is the launcher and carries a heavy import graph.
+ */
+export async function resolveLaunchCreds() {
+    const { resolveAnthropicKey } = await import("./agent.js");
+    try {
+        return { anthropicKey: await resolveAnthropicKey(process.env, { allowPrompt: false }) };
+    }
+    catch {
+        throw new Error("no Anthropic key in env (MNEMOM_AGENT_ANTHROPIC_KEY / ANTHROPIC_API_KEY) or ~/.mnemom/launcher.json — " +
+            "the goal commands authenticate with the same key the session launched with");
+    }
+}
+export const liveGoalDeps = {
+    readRecords: () => readSessionRecords({ dir: MNEMOM_DIR }).reverse(),
+    fetch: (url, init) => fetch(url, init),
+    resolveCreds: resolveLaunchCreds,
+    isTTY: () => isInteractive(),
+    confirm: (q) => askYesNo(q, false),
+    out: (line) => console.log(line),
+    err: (line) => console.error(line),
+};
+/** A failed command: the message and the exit code. */
+class Exit extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/** Validate `--thread` locally (same regex as the gateway); `all` only where `allowAll`. */
+export function parseThreadOption(raw, allowAll) {
+    const thread = raw?.trim() || "main";
+    if (!isValidGoalThread(thread)) {
+        throw new Exit(2, `invalid --thread '${raw}': use main, or a thread id such as a.<agent-id> (see \`mnemom agent goal show --all-threads\`)`);
+    }
+    if (thread === "all" && !allowAll) {
+        throw new Exit(2, "--thread all is read-only; pin and reset take one thread");
+    }
+    return thread;
+}
+/** The ledger record for `ref`, refusing anything that is not an implicit-mode session. */
+export function pickImplicitSession(records, ref) {
+    if (records.length === 0) {
+        throw new Exit(1, "No sessions yet — run `mnemom agent` to start one.");
+    }
+    const resolved = resolveSessionRef(records, ref);
+    if (resolved === null) {
+        throw new Exit(1, `No session matches '${ref ?? ""}' — try \`mnemom agent sessions\`.`);
+    }
+    if (resolved.record === null) {
+        const ids = resolved.candidates.map((c) => c.conversation_id.slice(0, 12)).join(", ");
+        throw new Exit(1, `'${ref ?? ""}' matches ${resolved.candidates.length} sessions (${ids}) — give more of the conversation id.`);
+    }
+    const mode = localGoalFlag(resolved.record);
+    if (mode !== "implicit") {
+        throw new Exit(2, `session is not in implicit goal mode (goal_mode=${mode})`);
+    }
+    return resolved.record;
+}
+/** A gateway / transport failure → the exit code and a message that never names the key. */
+export function mapGoalError(e, host) {
+    if (e instanceof Exit)
+        return e;
+    if (e instanceof GoalControlError) {
+        if (e.status === 409) {
+            if (e.code === "sealed_contract") {
+                return new Exit(2, "this conversation runs a sealed goal contract, not an implicit goal");
+            }
+            if (e.code === "nothing_to_pin") {
+                return new Exit(2, "this thread has no live goal to pin yet (rev 0)");
+            }
+            return new Exit(2, `the gateway refused: ${e.message}`);
+        }
+        if (e.status === 401) {
+            return new Exit(1, `the gateway on ${host} rejected the credential: ${e.message}`);
+        }
+        if (e.status === 404) {
+            if (e.code === "agent_not_found") {
+                return new Exit(1, `agent not found for this key on ${host}: was the session launched with a different key or agent?`);
+            }
+            if (e.code === "goal_intent_disabled") {
+                return new Exit(1, `implicit goal alignment is not enabled on ${host}`);
+            }
+            return new Exit(1, `${host} has no goal control route yet (HTTP 404)`);
+        }
+        if (e.status === 400)
+            return new Exit(2, `the gateway rejected the request: ${e.message}`);
+        if (e.status === 0)
+            return new Exit(1, e.message);
+        return new Exit(1, `the gateway on ${host} failed (HTTP ${e.status}): ${e.message}`);
+    }
+    return new Exit(1, e instanceof Error ? e.message : String(e));
+}
+async function run(deps, body) {
+    try {
+        await body();
+        return 0;
+    }
+    catch (e) {
+        const exit = mapGoalError(e, "the gateway");
+        deps.err(fmt.error(`mnemom agent goal: ${exit.message}`));
+        process.exitCode = exit.code;
+        return exit.code;
+    }
+}
+async function call(host, fn) {
+    try {
+        return await fn();
+    }
+    catch (e) {
+        throw mapGoalError(e, host);
+    }
+}
+// ─── show ─────────────────────────────────────────────────────────────────────
+function listOrDash(items) {
+    return items.length > 0 ? items.join(", ") : "—";
+}
+/** `rev 3 · pinned@3 · class refine · 2 pending`, or `rev 0 (no goal yet)`. */
+export function revisionLine(body) {
+    const i = body.intent;
+    if (!i) {
+        return body.last_revision > 0
+            ? `rev 0 (no goal yet; last revision ${body.last_revision})`
+            : "rev 0 (no goal yet)";
+    }
+    const bits = [`rev ${i.revision}`];
+    if (i.pinned)
+        bits.push(`pinned@${i.pinned.revision}`);
+    const last = i.history[i.history.length - 1];
+    if (last)
+        bits.push(`class ${last.class}`);
+    bits.push(`${i.pending_count} pending`);
+    return bits.join(" · ");
+}
+function intentLines(i, history) {
+    const L = [];
+    L.push(fmt.label("statement:      ", i.statement));
+    if (i.requirements.length === 0) {
+        L.push(fmt.label("requirements:   ", "—"));
+    }
+    else {
+        L.push(fmt.label("requirements:", ""));
+        for (const r of i.requirements)
+            L.push(`  - ${r}`);
+    }
+    L.push(fmt.label("allowed paths:  ", listOrDash(i.allowed_paths)));
+    L.push(fmt.label("forbidden paths:", listOrDash(i.forbidden_paths)));
+    if (history) {
+        L.push(fmt.label("history:", ""));
+        for (const h of i.history) {
+            L.push(`  r${h.revision}  ${h.class.padEnd(10)} ${String(h.ops).padStart(2)} ops  ${h.at}  ${h.source ?? "—"}`);
+        }
+    }
+    return L;
+}
+/** The human view of one show body. */
+export function buildGoalShowView(record, body, opts) {
+    const L = [];
+    L.push(fmt.label("session:        ", `${record.session} (${record.conversation_id.slice(0, 8)}, ${formatRelativeAge(record.started_at)})`));
+    L.push(fmt.label("thread:         ", body.thread));
+    if (body.mode === "sealed") {
+        L.push(fmt.dim(`  this conversation runs a sealed goal contract (hash ${body.sealed_hash ?? "?"})`));
+        return L;
+    }
+    L.push(revisionLine(body));
+    if (body.intent)
+        L.push(...intentLines(body.intent, opts.history === true));
+    const v = body.verdict;
+    L.push(fmt.label("verdict:        ", v
+        ? `${v.verdict.toUpperCase()} at turn ${v.turn}${v.superseded ? " (superseded)" : ""}`
+        : fmt.dim("none yet")));
+    if (body.threads) {
+        L.push(fmt.label("threads:", ""));
+        for (const t of body.threads) {
+            L.push(`  ${t.thread.padEnd(22)} ${t.role.padEnd(9)} rev ${t.revision}${t.pinned ? " · pinned" : ""}  ${t.statement ?? fmt.dim("(no goal)")}`);
+        }
+    }
+    return L;
+}
+/** `mnemom agent goal show [ref] [--thread <id>|--all-threads] [--history] [--json]` */
+export function agentGoalShowCommand(ref, opts, deps) {
+    return run(deps, async () => {
+        if (opts.allThreads && opts.thread && opts.thread.trim() !== "all") {
+            throw new Exit(2, "--thread and --all-threads are exclusive");
+        }
+        const thread = opts.allThreads ? "all" : parseThreadOption(opts.thread, true);
+        const record = pickImplicitSession(deps.readRecords(), ref);
+        const creds = await deps.resolveCreds();
+        const body = await call(record.gateway_host, () => goalControlFetch(record, "show", { thread }, { fetch: deps.fetch, creds }));
+        if (opts.json) {
+            deps.out(JSON.stringify({ gateway: { ...body, source: "gateway" }, ledger: { ...record, source: "ledger" } }, null, 2));
+            return;
+        }
+        for (const line of buildGoalShowView(record, body, { history: opts.history }))
+            deps.out(line);
+    });
+}
+// ─── pin ──────────────────────────────────────────────────────────────────────
+/** `mnemom agent goal pin [ref] [--thread <id>] [--off] [--json]` */
+export function agentGoalPinCommand(ref, opts, deps) {
+    return run(deps, async () => {
+        const thread = parseThreadOption(opts.thread, false);
+        const record = pickImplicitSession(deps.readRecords(), ref);
+        const creds = await deps.resolveCreds();
+        const pinned = opts.off !== true;
+        const body = await call(record.gateway_host, () => goalControlFetch(record, "pin", { thread, pinned }, { fetch: deps.fetch, creds }));
+        if (opts.json) {
+            deps.out(JSON.stringify({ ...body, source: "gateway" }, null, 2));
+            return;
+        }
+        deps.out(fmt.success(body.pinned
+            ? `pinned ${thread} at rev ${body.pinned.revision} — the gateway keeps this goal until \`mnemom agent goal pin --off\``
+            : `unpinned ${thread} (rev ${body.revision}) — new directions revise the goal again`));
+    });
+}
+// ─── reset ────────────────────────────────────────────────────────────────────
+/** `mnemom agent goal reset [ref] [--thread <id>] [--statement <s>] [--requirement <r>...] [--yes] [--json]` */
+export function agentGoalResetCommand(ref, opts, deps) {
+    return run(deps, async () => {
+        const thread = parseThreadOption(opts.thread, false);
+        const statement = opts.statement?.trim() || undefined;
+        const requirements = (opts.requirement ?? []).map((r) => r.trim()).filter((r) => r !== "");
+        if (requirements.length > 0 && statement === undefined) {
+            throw new Exit(2, "--requirement needs --statement (requirements belong to a stated goal)");
+        }
+        const record = pickImplicitSession(deps.readRecords(), ref);
+        if (!opts.yes) {
+            if (!deps.isTTY())
+                throw new Exit(2, "refusing to reset without --yes (no TTY to confirm on)");
+            const what = statement
+                ? `replace the ${thread} goal of '${record.session}' with your statement`
+                : `clear the ${thread} goal of '${record.session}' (the next message re-infers it)`;
+            if (!(await deps.confirm(`Reset: ${what}?`)))
+                throw new Exit(1, "reset cancelled");
+        }
+        const creds = await deps.resolveCreds();
+        const body = await call(record.gateway_host, () => goalControlFetch(record, "reset", {
+            thread,
+            ...(statement !== undefined ? { statement } : {}),
+            ...(requirements.length > 0 ? { requirements } : {}),
+        }, { fetch: deps.fetch, creds }));
+        if (opts.json) {
+            deps.out(JSON.stringify({ ...body, source: "gateway" }, null, 2));
+            return;
+        }
+        deps.out(fmt.success(body.intent
+            ? `reset ${thread} to your goal at rev ${body.revision} (was rev ${body.prior_revision})`
+            : `reset ${thread}: rev 0 (no goal yet) — the next message re-infers the goal as rev ${body.prior_revision + 1}`));
+    });
+}

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

@@ -15,11 +15,17 @@
  */
 import { type GoalMode, type SessionRecord } from "../lib/agent-ledger.js";
 import { type AgentSessionResponse } from "../lib/api.js";
+import { type GoalShowResponse } from "../lib/goal-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>;
+    /**
+     * The live implicit goal from the gateway's control route (`GET /mnemom/goal/intent`), for the
+     * one `live goal` line an implicit session gets. Optional: absent ⇒ no line.
+     */
+    fetchGoal?: (record: SessionRecord) => Promise<GoalShowResponse>;
     out: (line: string) => void;
     err: (line: string) => void;
 }
@@ -35,15 +41,17 @@ export interface SessionRefMatch {
 }
 export interface SessionRefAmbiguous {
     record: null;
-    /** Every record whose conversation id starts with the ref. */
+    /** The newest record of each distinct conversation whose 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;
+ *   - else a conversation-id prefix → the newest record of the one conversation it names
+ *     (a relaunch / `--resume` appends another row for the same conversation id, which is not
+ *     ambiguity), or `{record: null, candidates}` — newest row per conversation — when several
+ *     distinct conversations share the prefix (an exact full id among them wins);
  *   - nothing matches (or the ledger is empty) → null.
  */
 export declare function resolveSessionRef(records: SessionRecord[], ref?: string): SessionRefMatch | SessionRefAmbiguous | null;
@@ -106,5 +114,7 @@ export interface AgentShowOptions {
 }
 /** Why the live read could not happen, from the thrown error. */
 export declare function unavailableReason(err: unknown): string;
+/** `rev N[ · pinned]` from a live show body, or `rev 0 (no goal yet)`. */
+export declare function liveGoalLine(body: GoalShowResponse): 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

@@ -17,12 +17,20 @@ 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";
+import { goalControlFetch } from "../lib/goal-api.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),
+    fetchGoal: async (record) => {
+        // Lazy: agent-goal.ts imports this module (ref resolution), and the key resolver behind it
+        // pulls in the launcher.
+        const { resolveLaunchCreds } = await import("./agent-goal.js");
+        const creds = await resolveLaunchCreds();
+        return goalControlFetch(record, "show", { thread: "main" }, { fetch, creds });
+    },
     out: (line) => console.log(line),
     err: (line) => console.error(line),
 };
@@ -32,8 +40,10 @@ 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;
+ *   - else a conversation-id prefix → the newest record of the one conversation it names
+ *     (a relaunch / `--resume` appends another row for the same conversation id, which is not
+ *     ambiguity), or `{record: null, candidates}` — newest row per conversation — when several
+ *     distinct conversations share the prefix (an exact full id among them wins);
  *   - nothing matches (or the ledger is empty) → null.
  */
 export function resolveSessionRef(records, ref) {
@@ -47,11 +57,26 @@ export function resolveSessionRef(records, ref) {
         const others = records.filter((r) => r !== newestByName && r.session === needle);
         return { record: newestByName, others };
     }
-    const byConv = records.filter((r) => r.conversation_id.startsWith(needle));
+    // The ledger appends a row per launch, so a relaunch or `--resume` with the same
+    // `--conversation-id` leaves several rows for ONE conversation. Collapse to the newest row
+    // per conversation id (records are newest first) before deciding ambiguity: only distinct
+    // conversations are ambiguous.
+    const seen = new Set();
+    const byConv = records.filter((r) => {
+        if (!r.conversation_id.startsWith(needle) || seen.has(r.conversation_id))
+            return false;
+        seen.add(r.conversation_id);
+        return true;
+    });
     if (byConv.length === 1)
         return { record: byConv[0], others: [] };
-    if (byConv.length > 1)
+    if (byConv.length > 1) {
+        // A full conversation id that also prefixes a longer one still names exactly one.
+        const exact = byConv.find((r) => r.conversation_id === needle);
+        if (exact)
+            return { record: exact, others: [] };
         return { record: null, candidates: byConv };
+    }
     return null;
 }
 // ─── sessions table ───────────────────────────────────────────────────────────
@@ -246,6 +271,12 @@ export function unavailableReason(err) {
         return `${err.code}: ${err.message}`;
     return err instanceof Error ? err.message : String(err);
 }
+/** `rev N[ · pinned]` from a live show body, or `rev 0 (no goal yet)`. */
+export function liveGoalLine(body) {
+    if (!body.intent)
+        return "rev 0 (no goal yet)";
+    return `rev ${body.intent.revision}${body.intent.pinned ? " · pinned" : ""}`;
+}
 /** `mnemom agent show [ref] [--json]` */
 export async function agentShowCommand(ref, opts, deps) {
     const records = deps.readRecords();
@@ -290,6 +321,17 @@ export async function agentShowCommand(ref, opts, deps) {
     }
     for (const line of buildShowView(record, remote, reason))
         deps.out(line);
+    if (deps.fetchGoal && resolveGoalMode(record, remote) === "implicit") {
+        // Best effort: any failure (no key, gateway without the route, agent not found) is one dim line.
+        let line;
+        try {
+            line = liveGoalLine(await deps.fetchGoal(record));
+        }
+        catch {
+            line = fmt.dim("(live goal unavailable)");
+        }
+        deps.out(fmt.label("live goal:      ", 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:`));

package/dist/commands/agent.d.ts

@@ -60,6 +60,12 @@ export interface AgentOptions {
     context?: boolean;
     /** context-hint seed default: commander `--no-context-hint` sets this false. */
     contextHint?: boolean;
+    /**
+     * EXPERIMENTAL, off by default (operator directive, MNE-7564): registers the `handoff` MCP
+     * tool and tells the gateway `CONTEXT_HANDOFF_ENABLED=true` for this session only. Absent/false
+     * ⇒ no header key, no MCP server — the launch is byte-identical to a build without this flag.
+     */
+    contextHandoff?: boolean;
     /**
      * Governed-agent provisioning: undefined = AUTO (provision-with-confirm when
      * interactive, warn-and-continue otherwise), true = force (`--setup`), false =
@@ -98,6 +104,8 @@ export declare function recordSessionLaunch(ctx: {
     cli: ResolvedCli;
     envelope: SealedContractEnvelope | null;
     goalMode: string | null;
+    /** The Claude Code session id (pickCcSessionId); null/absent when Claude Code picks it. */
+    ccSessionId?: string | null;
 }): Promise<void>;
 /**
  * Resolve the Anthropic key with NO 1Password dependency (built for external
@@ -153,17 +161,48 @@ export interface RcCapability {
  * and by the auto-default selection (a bare launch prefers RC when capable).
  */
 export declare function checkRcCapability(cli: ResolvedCli): RcCapability;
+/**
+ * Locates the `handoff` MCP server (src/mcp/handoff-server.mjs in dev, dist/mcp/handoff-server.mjs
+ * once built — a raw, uncompiled `.mjs` file that `copy-assets.mjs` copies verbatim, exactly like
+ * `resolveProxyScript`'s `rc-proxy.mjs`, so the SAME relative path resolves in both trees).
+ *
+ * `baseDirOverride` exists ONLY so a test can exercise the missing-file throw deterministically
+ * (point it at a directory with no `../mcp/handoff-server.mjs` beside it) without touching the
+ * real installed tree; every real caller omits it and gets `import.meta.url`'s own directory.
+ */
+export declare function resolveHandoffServerScript(baseDirOverride?: string): string;
 /**
  * Build the coding-agent CLI args from the model/effort/trim-mcp/yolo knobs plus
  * the caller's passthrough. `--model`/`--effort` are injected only when given (no
- * silent default). yolo appends `--dangerously-skip-permissions`. `--trim-mcp`
+ * silent default). yolo appends `--dangerously-skip-permissions`. A `ccSessionId`
+ * (pickCcSessionId, inject arm) appends `--session-id <id>`. `--trim-mcp`
  * appends `--strict-mcp-config --mcp-config {}` LAST so it wins over any
- * caller-supplied --mcp-config.
+ * caller-supplied --mcp-config — UNLESS `handoffMcpConfigPath` is set (context
+ * handoff ON, MNE-7564), in which case that file (which already declares only the
+ * `mnemom-handoff` server) is what `--strict-mcp-config` points at, so trimming
+ * strips every OTHER server but the handoff tool survives. Without `--trim-mcp`,
+ * the same path is passed WITHOUT `--strict-mcp-config` so it only ADDS the tool
+ * on top of the caller's/CLI's own MCP config rather than replacing it.
  */
 export declare function buildCliArgs(options: AgentOptions, ctx: {
     yolo: boolean;
     allowCliFlags: boolean;
+    ccSessionId?: string;
+    handoffMcpConfigPath?: string;
 }): string[];
+/**
+ * The Claude Code session id a launch runs under, from the caller's passthrough (implicit-goal
+ * CLI, cli-telemetry §1.5):
+ *   - `--session-id <uuid>` (or `=<uuid>`) → that id; the caller's own flag, nothing injected;
+ *   - `--fork-session` → null (Claude Code mints the fork's id);
+ *   - `--resume <id>` / `-r <id>` (or `--resume=<id>`) → that id, nothing injected;
+ *   - a bare `--resume` / `-r`, `--continue` / `-c` → null (Claude Code picks the session);
+ *   - otherwise → a fresh UUID the launcher injects as `--session-id`.
+ */
+export declare function pickCcSessionId(passthrough: string[], newId?: () => string): {
+    id: string | null;
+    inject: boolean;
+};
 /**
  * Which goal-alignment mode the launch status line names: a sealed contract →
  * "on"; `--implicit` (mode header, no contract) → "implicit"; neither → "off".