@meetless/mla 0.1.4

package/dist/commands/kb_promote.js

@@ -0,0 +1,188 @@
+"use strict";
+// `mla kb promote <doc-id>` / `mla kb promote --reject <doc-id>` (Personal-KB
+// posture promotion, Phase 3).
+//
+// Renamed from `kb share`: "share" read as "invite a teammate", but this verb
+// has nothing to do with membership. It flips a SHADOW Personal-KB doc to LIVE,
+// i.e. it PROMOTES the doc into the workspace's grounded, agent-visible corpus.
+// `kb share` survives as a hidden, deprecated alias in kb.ts (see the dispatch).
+//
+//   promote <doc-id>          -> PATCH /internal/v1/kb/documents/<id>/posture with
+//                                { workspaceId, actorUserId, posture: "LIVE" }. This
+//                                promotes the owner's Personal-KB doc from SHADOW to
+//                                LIVE: the "promote into the workspace corpus" action.
+//   promote --reject <doc-id> -> the owner declines to promote. Makes NO posture call
+//                                and NO delete call, so the personal doc survives
+//                                untouched at SHADOW. Records the decline locally so
+//                                the agent can avoid re-proposing it later (test 16).
+//
+// Mirrors the kb_personal.ts deps-injection shape: a thin public `runKbPromote`
+// that loads the real config (readKbConfig) and wires the real intelPatch +
+// rejection recorder, while every collaborator is injectable so the unit test
+// drives it offline without touching the network, config, or disk.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseKbPromoteArgs = parseKbPromoteArgs;
+exports.runKbPromote = runKbPromote;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("../lib/config");
+const http_1 = require("../lib/http");
+const USAGE = "Usage: mla kb promote <doc-id> | mla kb promote --reject <doc-id>";
+// Parse a single positional <doc-id> plus an optional --reject flag. The flag may
+// appear before or after the id (`--reject doc_1` or `doc_1 --reject`). Unknown
+// flags, a missing id, or a second positional are usage errors.
+function parseKbPromoteArgs(argv) {
+    let docId = null;
+    let reject = false;
+    for (const a of argv) {
+        if (a === "--reject") {
+            reject = true;
+        }
+        else if (a.startsWith("-")) {
+            throw new Error(`Unknown flag: ${a}. ${USAGE}`);
+        }
+        else if (docId === null) {
+            docId = a;
+        }
+        else {
+            throw new Error(`Unexpected argument: ${a}. ${USAGE}`);
+        }
+    }
+    if (docId === null) {
+        throw new Error(`mla kb promote requires a document id. ${USAGE}`);
+    }
+    // `kb add` / `kb reingest` receipts print the id as `kbdoc:<cuid>`, so
+    // operators paste that exact token. The posture route keys on the bare cuid;
+    // a `kbdoc:` prefix flowed verbatim into the URL used to 404 with a
+    // misleading "intel does not expose the posture endpoint" message. Strip it
+    // (mirrors the kb_reingest `kbdoc:` input handling) so both spellings work.
+    if (docId.startsWith("kbdoc:")) {
+        docId = docId.slice("kbdoc:".length);
+        if (docId.length === 0) {
+            throw new Error(`mla kb promote requires a document id after 'kbdoc:'. ${USAGE}`);
+        }
+    }
+    return { docId, reject };
+}
+// The local rejections spool. Path + filename live under the SAME logs directory
+// the Phase 1 Active Review store uses (HOME/logs), so both the agent and this
+// command resolve their state under one MEETLESS_HOME. Forward-looking plumbing:
+// the agent reads this to avoid re-proposing a doc the owner already declined.
+//
+// The filename + event string keep the legacy `kb-share` spelling on purpose:
+// this is an append-only on-disk contract, not a user-facing surface. Renaming it
+// would orphan any already-spooled declines for zero operator benefit. The command
+// was renamed promote; the durable record name stays stable.
+function rejectionsLogPath() {
+    return path.join(config_1.HOME, "logs", "kb-share-rejections.jsonl");
+}
+// Append one JSON line recording the decline. Best-effort by contract: every
+// failure (unwritable dir, EACCES, full disk) is swallowed so the command outcome
+// is never affected and the function NEVER throws (the unit test relies on this).
+function recordRejectDefault(cfg, docId) {
+    try {
+        const file = rejectionsLogPath();
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const line = JSON.stringify({
+            ts: new Date().toISOString(),
+            event: "kb_share_rejected",
+            workspaceId: cfg?.workspaceId ?? null,
+            ownerUserId: cfg?.actorUserId ?? null,
+            docId,
+        }) + "\n";
+        fs.appendFileSync(file, line);
+    }
+    catch {
+        // best-effort: never throw, never affect the command outcome.
+    }
+}
+// Surface an intel HTTP failure helpfully, mirroring kb.ts's explainIntelError
+// for the postures most likely on a posture flip; falls back to the raw message.
+function explainPromoteError(err, intelUrl) {
+    if (err.status === 404) {
+        return `intel returned 404 for the posture route. Document not found, or this intel does not expose the KB posture endpoint.`;
+    }
+    if (err.status === 401 || err.status === 403) {
+        return `intel rejected the token (HTTP ${err.status}). Check controlToken in cli-config.json.`;
+    }
+    if (err.status === undefined) {
+        return `intel not reachable at ${intelUrl}. Is it running? Try \`mla doctor\`.`;
+    }
+    return err.message;
+}
+async function runKbPromote(argv, deps) {
+    let cfg;
+    try {
+        cfg = deps?.cfg ?? (0, config_1.readKbConfig)();
+    }
+    catch (e) {
+        console.error(e.message);
+        return { rejected: false, code: 2 };
+    }
+    let parsed;
+    try {
+        parsed = parseKbPromoteArgs(argv);
+    }
+    catch (e) {
+        console.error(e.message);
+        return { rejected: false, code: 2 };
+    }
+    const patch = deps?.http?.intelPatch ?? http_1.intelPatch;
+    const recordReject = deps?.recordReject ?? recordRejectDefault;
+    // REJECT path: no posture call, no delete. Record the decline and confirm the
+    // personal doc is unchanged.
+    if (parsed.reject) {
+        recordReject(cfg, parsed.docId);
+        console.log(`Declined to promote ${parsed.docId}. Your personal copy is unchanged (still SHADOW, not deleted).`);
+        return { rejected: true, code: 0 };
+    }
+    // PROMOTE path: flip the posture to LIVE.
+    const body = {
+        workspaceId: cfg.workspaceId,
+        actorUserId: cfg.actorUserId,
+        posture: "LIVE",
+    };
+    try {
+        await patch(cfg, `/internal/v1/kb/documents/${parsed.docId}/posture`, body);
+    }
+    catch (e) {
+        const intelUrl = cfg.intelUrl || http_1.DEFAULT_INTEL_URL;
+        console.error(explainPromoteError(e, intelUrl));
+        return { rejected: false, code: 1 };
+    }
+    console.log(`Promoted ${parsed.docId} to the workspace corpus (posture is now LIVE).`);
+    return { rejected: false, code: 0 };
+}

package/dist/commands/kb_purge.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseKbPurgeArgs = parseKbPurgeArgs;
+exports.runKbPurge = runKbPurge;
+const config_1 = require("../lib/config");
+const kb_acl_1 = require("../lib/kb_acl");
+const render_1 = require("../lib/render");
+const http_1 = require("../lib/http");
+const kb_forget_1 = require("./kb_forget");
+const kb_reingest_1 = require("./kb_reingest");
+const VALUE_FLAGS = new Set(["--workspace", "--reason"]);
+const MIN_REASON_CHARS = 16;
+const PURGE_TIMEOUT_MS = 30_000;
+function parseKbPurgeArgs(argv) {
+    const out = {};
+    let positional = null;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (VALUE_FLAGS.has(a)) {
+            const v = argv[i + 1];
+            if (v === undefined) {
+                throw new Error(`Missing value for ${a}`);
+            }
+            if (v.startsWith("--") || v.startsWith("-")) {
+                throw new Error(`Missing value for ${a} (got the next flag ${v} instead)`);
+            }
+            switch (a) {
+                case "--workspace":
+                    out.workspace = v;
+                    break;
+                case "--reason":
+                    out.reason = v;
+                    break;
+            }
+            i += 1;
+            continue;
+        }
+        if (a.startsWith("--") || a.startsWith("-")) {
+            throw new Error(`Unknown flag: ${a}. Supported flags: ${[...VALUE_FLAGS].sort().join(", ")}`);
+        }
+        if (positional !== null) {
+            throw new Error(`\`mla kb purge\` takes exactly one positional input (got '${positional}' and '${a}')`);
+        }
+        positional = a;
+    }
+    if (positional === null) {
+        throw new Error("`mla kb purge` requires a positional input: kbdoc:<id>, note:<path>, or a bare note path");
+    }
+    if (!out.reason || !out.reason.trim()) {
+        throw new Error("--reason \"...\" is required: purge redacts every revision, which is irreversible in slice A");
+    }
+    if (out.reason.trim().length < MIN_REASON_CHARS) {
+        throw new Error(`--reason must be at least ${MIN_REASON_CHARS} characters of rationale (purge is irreversible)`);
+    }
+    return {
+        input: positional,
+        workspace: out.workspace,
+        reason: out.reason,
+    };
+}
+function printPreflight(flags, cfg) {
+    const ws = flags.workspace || cfg.workspaceId;
+    console.log(`mla kb purge workspace=${ws} input=${flags.input} reason=${JSON.stringify(flags.reason)}`);
+}
+// Map an HTTP/network failure to the worker's exit semantics: a 404 (unknown
+// doc), 409 (PURGED terminal), or 422 (bad args / short reason) is a precondition
+// -> 2; a network error (no status), a 5xx, or the 500 write-time state race is an
+// operational failure -> 1. Identical to forget's mapping.
+function exitForHttpError(e) {
+    const status = e?.status;
+    if (status === 404 || status === 409 || status === 422)
+        return 2;
+    return 1;
+}
+async function runKbPurge(argv) {
+    // Parse flags BEFORE loading config so `--workspace <id>` can override the
+    // marker-resolved workspace (T1.1 folder = workspace) without requiring the
+    // current directory to be activated.
+    let flags;
+    try {
+        flags = parseKbPurgeArgs(argv);
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    let cfg;
+    try {
+        cfg = (0, config_1.readKbConfig)(flags.workspace);
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    // §13.14 owner-only ACL: purge is the most destructive KB write; the gate runs
+    // before the route so a non-owner cannot trigger redact-all + tombstone.
+    try {
+        await (0, kb_acl_1.verifyKbActorIsOwner)(cfg);
+    }
+    catch (e) {
+        if (e instanceof kb_acl_1.KbOwnerCheckError) {
+            console.error(e.message);
+            return 2;
+        }
+        throw e;
+    }
+    const workspaceId = flags.workspace || cfg.workspaceId;
+    printPreflight(flags, cfg);
+    // Pick the server-resolvable handle, SHARED with forget so `purge X` and
+    // `forget X` produce the same handle. A real local file maps to its
+    // vault-relative path (vault root resolved client-side); an unresolved vault
+    // root for a real file is a precondition (-> 2).
+    let handle;
+    try {
+        handle = (0, kb_forget_1.resolveForgetHandle)(flags.input);
+    }
+    catch (e) {
+        if (e instanceof kb_reingest_1.ReingestPreconditionError) {
+            console.error(e.message);
+            return 2;
+        }
+        throw e;
+    }
+    const body = {
+        workspaceId,
+        actor: cfg.actorUserId,
+        reason: flags.reason,
+        ...handle,
+    };
+    let receipt;
+    try {
+        const res = await (0, http_1.intelPost)(cfg, "/internal/v1/kb/purge", body, PURGE_TIMEOUT_MS);
+        receipt = res.receipt;
+    }
+    catch (e) {
+        console.error(`kb purge failed: ${e.message}`);
+        return exitForHttpError(e);
+    }
+    if (!receipt) {
+        console.error("kb purge: the route returned no receipt.");
+        return 1;
+    }
+    console.log((0, render_1.renderKbPurgeReceipt)(receipt));
+    console.log("");
+    // Cascade: a purged doc is dead the same way a forgotten one is, so its PENDING
+    // relationship candidates point at a dead artifact and should not linger in the
+    // review queue. Only a fresh purge needs it; an already_purged doc's candidates
+    // were cleared on the first purge/forget. Reuse forget's best-effort cascade.
+    if (receipt.outcome === "purged") {
+        const cascadeDeps = {
+            fetchPending: (qs) => (0, http_1.get)(cfg, `/internal/v1/relationship-candidates?${qs}`, 12000),
+            submitReject: async (id, rejectBody) => {
+                await (0, http_1.post)(cfg, `/internal/v1/relationship-candidates/${encodeURIComponent(id)}/reject`, rejectBody, 12000);
+            },
+        };
+        const c = await (0, kb_forget_1.cascadeRejectForDoc)(receipt.canonicalPath, { workspaceId: cfg.workspaceId, actorUserId: cfg.actorUserId }, cascadeDeps);
+        if (c.rejected > 0) {
+            console.log(`Also cleared ${c.rejected} orphaned relationship candidate${c.rejected === 1 ? "" : "s"} that referenced this doc.`);
+        }
+        if (c.fetchFailed) {
+            console.error("Warning: could not check for orphaned relationship candidates; some may remain in the review queue.");
+        }
+        else if (c.failed > 0) {
+            console.error(`Warning: ${c.failed} orphaned relationship candidate${c.failed === 1 ? "" : "s"} could not be cleared; clear them with mla kb review <id> --reject.`);
+        }
+    }
+    return 0;
+}

package/dist/commands/kb_reingest.js

@@ -0,0 +1,335 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReingestPreconditionError = void 0;
+exports.parseKbReingestArgs = parseKbReingestArgs;
+exports.resolveReingestVaultRoot = resolveReingestVaultRoot;
+exports.reverseMapEoidToFile = reverseMapEoidToFile;
+exports.runKbReingest = runKbReingest;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const config_1 = require("../lib/config");
+const http_1 = require("../lib/http");
+const kb_acl_1 = require("../lib/kb_acl");
+const observability_1 = require("../lib/observability");
+const render_1 = require("../lib/render");
+const kb_add_1 = require("./kb_add");
+const VALUE_FLAGS = new Set([
+    "--workspace",
+    "--profile",
+    "--ingest-run-id",
+    "--reason",
+    "--agent-session",
+]);
+const DEFAULT_PROFILE = "markdown_atomic_v1";
+const NOTES_IDENTITY_ROOT = "notes";
+const KBDOC_PREFIX = "kbdoc:";
+const NOTE_PREFIX = "note:";
+// RESOLVE mints nothing (a DB lookup + guards), so it is fast. APPLY runs the
+// heavy inline LDM body + embeds for a body change, so it gets the kb-add
+// single-file floor.
+const RESOLVE_TIMEOUT_MS = 15_000;
+const REINGEST_TIMEOUT_MS = 120_000;
+function parseKbReingestArgs(argv) {
+    const out = {};
+    let positional = null;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (VALUE_FLAGS.has(a)) {
+            const v = argv[i + 1];
+            if (v === undefined) {
+                throw new Error(`Missing value for ${a}`);
+            }
+            if (v.startsWith("--") || v.startsWith("-")) {
+                throw new Error(`Missing value for ${a} (got the next flag ${v} instead)`);
+            }
+            switch (a) {
+                case "--workspace":
+                    out.workspace = v;
+                    break;
+                case "--profile":
+                    out.profile = v;
+                    break;
+                case "--ingest-run-id":
+                    out.ingestRunId = v;
+                    break;
+                case "--reason":
+                    out.reason = v;
+                    break;
+                case "--agent-session":
+                    out.agentSession = v;
+                    break;
+            }
+            i += 1;
+            continue;
+        }
+        if (a.startsWith("--") || a.startsWith("-")) {
+            throw new Error(`Unknown flag: ${a}. Supported flags: ${[...VALUE_FLAGS].sort().join(", ")}`);
+        }
+        if (positional !== null) {
+            throw new Error(`\`mla kb reingest\` takes exactly one positional input (got '${positional}' and '${a}')`);
+        }
+        positional = a;
+    }
+    if (positional === null) {
+        throw new Error("`mla kb reingest` requires a positional input: kbdoc:<id>, note:<externalObjectId>, or a bare note path");
+    }
+    return {
+        input: positional,
+        workspace: out.workspace,
+        profile: out.profile,
+        ingestRunId: out.ingestRunId,
+        reason: out.reason,
+        agentSession: out.agentSession,
+    };
+}
+// ---------------------------------------------------------------------------
+// Client-side source resolution (was tools/mla_kb_reingest.py)
+//
+// The governed identity is the vault-relative POSIX path under a single
+// `notes/` root. The CLIENT alone holds the filesystem, so it resolves the
+// vault root and reverse-maps the stored externalObjectId to a file here,
+// exactly mirroring the python worker's `_resolve_vault_root` /
+// `_abs_path_from_external_object_id`.
+// ---------------------------------------------------------------------------
+// A client-side precondition (unresolved vault root, missing source file, a
+// malformed identity). Maps to exit code 2, distinct from an HTTP failure.
+class ReingestPreconditionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ReingestPreconditionError";
+    }
+}
+exports.ReingestPreconditionError = ReingestPreconditionError;
+function expandHome(p) {
+    if (p === "~")
+        return os.homedir();
+    if (p.startsWith("~/"))
+        return path.join(os.homedir(), p.slice(2));
+    return p;
+}
+// Resolve the notes vault root the governed identity is relative to. Order
+// (mirrors the worker, minus the removed `--vault-root` flag): MEETLESS_NOTES_ROOT,
+// else a git-repo-root walk-up from `anchor` (the source file's directory for a
+// path input, else cwd). Throws a precondition when neither resolves: reingest
+// cannot read the source otherwise.
+function resolveReingestVaultRoot(anchor) {
+    const envRoot = process.env.MEETLESS_NOTES_ROOT;
+    if (envRoot) {
+        const expanded = path.resolve(expandHome(envRoot));
+        if (!fs.existsSync(expanded) || !fs.statSync(expanded).isDirectory()) {
+            throw new ReingestPreconditionError(`MEETLESS_NOTES_ROOT=${envRoot} is not a directory`);
+        }
+        return fs.realpathSync(expanded);
+    }
+    const gitRoot = (0, kb_add_1.gitRootForVault)(anchor);
+    if (gitRoot)
+        return gitRoot;
+    throw new ReingestPreconditionError("could not resolve a notes vault root to read the source file; set MEETLESS_NOTES_ROOT or run inside a git repo");
+}
+// Reverse the governed identity mapping: `notes/<rel>` -> <vaultRoot>/<rel>.
+// Mirrors the worker's `_abs_path_from_external_object_id`. The stored id is
+// NFC + (case-insensitive fs) casefolded; lookup on such a fs is case-
+// insensitive, so the reverse-mapped path still reads the real file. Guards a
+// non-notes-rooted id and a `..` escape, and that the target is a real file.
+function reverseMapEoidToFile(externalObjectId, vaultRoot) {
+    const prefix = `${NOTES_IDENTITY_ROOT}/`;
+    if (!externalObjectId.startsWith(prefix)) {
+        throw new ReingestPreconditionError(`externalObjectId ${JSON.stringify(externalObjectId)} is not under the '${NOTES_IDENTITY_ROOT}/' identity root; reingest only supports notes-sourced documents`);
+    }
+    const rel = externalObjectId.slice(prefix.length);
+    if (!rel) {
+        throw new ReingestPreconditionError(`externalObjectId ${JSON.stringify(externalObjectId)} has an empty relative path`);
+    }
+    const root = fs.realpathSync(vaultRoot);
+    const abs = path.resolve(root, rel);
+    const relCheck = path.relative(root, abs);
+    if (relCheck.startsWith("..") || path.isAbsolute(relCheck)) {
+        throw new ReingestPreconditionError(`resolved source path ${abs} escapes vault root ${root}`);
+    }
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
+        throw new ReingestPreconditionError(`source file for ${JSON.stringify(externalObjectId)} does not resolve to a readable file at ${abs}. Set MEETLESS_NOTES_ROOT, or re-add it with \`mla kb add\`.`);
+    }
+    return abs;
+}
+// RESOLVE an identity reference (kbdoc:<id> or a stored note:<eoid>) server-side
+// -- the SAME canonicalize + guards the worker ran -- then reverse-map the
+// returned externalObjectId to a file and read its bytes for an APPLY-by-id.
+async function resolveViaServer(cfg, workspaceId, ref, anchor) {
+    const resolved = await (0, http_1.intelPost)(cfg, "/internal/v1/kb/reingest", { workspaceId, actor: cfg.actorUserId, ref }, RESOLVE_TIMEOUT_MS);
+    // RESOLVE already ran the PURGED/TOMBSTONED guards (409) and unknown-doc (404),
+    // so a terminal/missing doc threw before we touch the filesystem.
+    const vaultRoot = resolveReingestVaultRoot(anchor);
+    const file = reverseMapEoidToFile(resolved.externalObjectId, vaultRoot);
+    const content = fs.readFileSync(file, "utf8");
+    return { documentId: resolved.documentId, content };
+}
+// Map the operator's input to an APPLY target. A real local file is read
+// directly (APPLY by relPath); an opaque/identity reference round-trips through
+// RESOLVE (APPLY by documentId). This mirrors the worker's two resolution
+// candidates (filesystem form vs identity form), split across the wire.
+async function resolveApplyTarget(cfg, flags, workspaceId) {
+    const raw = flags.input.trim();
+    if (!raw) {
+        throw new ReingestPreconditionError("`mla kb reingest` requires a non-empty input");
+    }
+    // kbdoc:<id>: opaque, never a file. Resolve server-side, anchored on cwd.
+    if (raw.startsWith(KBDOC_PREFIX)) {
+        const id = raw.slice(KBDOC_PREFIX.length).trim();
+        if (!id) {
+            throw new ReingestPreconditionError("kbdoc: prefix requires an id");
+        }
+        return resolveViaServer(cfg, workspaceId, raw, process.cwd());
+    }
+    // note:<X> or bare <X>. If X is a real local file, the client holds it: read
+    // it and APPLY by relPath. Otherwise it is a stored externalObjectId string;
+    // resolve it server-side (anchored on cwd) and APPLY by documentId.
+    const rawPath = raw.startsWith(NOTE_PREFIX)
+        ? raw.slice(NOTE_PREFIX.length)
+        : raw;
+    const abs = path.resolve(expandHome(rawPath));
+    let isFile = false;
+    try {
+        isFile = fs.existsSync(abs) && fs.statSync(abs).isFile();
+    }
+    catch {
+        isFile = false;
+    }
+    if (isFile) {
+        const vaultRoot = resolveReingestVaultRoot(path.dirname(abs));
+        const relPath = (0, kb_add_1.vaultRelPath)(vaultRoot, abs);
+        const content = fs.readFileSync(abs, "utf8");
+        return { relPath, content };
+    }
+    return resolveViaServer(cfg, workspaceId, raw, process.cwd());
+}
+function printPreflight(flags, cfg) {
+    const ws = flags.workspace || cfg.workspaceId;
+    const reasonHint = flags.reason ? ` reason=${JSON.stringify(flags.reason)}` : "";
+    console.log(`mla kb reingest workspace=${ws} input=${flags.input}${reasonHint}`);
+}
+// Map an HTTP/network failure to the worker's exit semantics: a 404 (unknown
+// doc), 409 (terminal state), or 422 (bad args) is a precondition -> 2; a
+// network error (no status) or a 5xx is an operational failure -> 1.
+function exitForHttpError(e) {
+    const status = e?.status;
+    if (status === 404 || status === 409 || status === 422)
+        return 2;
+    return 1;
+}
+async function runKbReingest(argv) {
+    // Parse flags BEFORE loading config so `--workspace <id>` can override the
+    // marker-resolved workspace (T1.1 folder = workspace) without requiring the
+    // current directory to be activated.
+    let flags;
+    try {
+        flags = parseKbReingestArgs(argv);
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    let cfg;
+    try {
+        cfg = (0, config_1.readKbConfig)(flags.workspace);
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    // §13.14 owner-only ACL: reingest mints new revisions and activates them.
+    try {
+        await (0, kb_acl_1.verifyKbActorIsOwner)(cfg);
+    }
+    catch (e) {
+        if (e instanceof kb_acl_1.KbOwnerCheckError) {
+            console.error(e.message);
+            return 2;
+        }
+        throw e;
+    }
+    const workspaceId = flags.workspace || cfg.workspaceId;
+    printPreflight(flags, cfg);
+    // Resolve the source file + the document handle. A RESOLVE round-trip (for an
+    // opaque/identity reference) can fail with an HTTP status; a client-side
+    // precondition (vault root, missing file) throws ReingestPreconditionError.
+    let target;
+    try {
+        target = await resolveApplyTarget(cfg, flags, workspaceId);
+    }
+    catch (e) {
+        if (e instanceof ReingestPreconditionError) {
+            console.error(e.message);
+            return 2;
+        }
+        console.error(`kb reingest failed: ${e.message}`);
+        return exitForHttpError(e);
+    }
+    // Relay the session UUID, canonicalized (defense in depth: a direct
+    // `mla kb reingest --agent-session X` may carry a non-canonical value). The
+    // server canonicalizes again and is the authoritative gate; an invalid value
+    // yields no session, never a composed value.
+    const agentSession = (0, observability_1.canonicalizeSessionId)(flags.agentSession ?? null);
+    const body = {
+        workspaceId,
+        actor: cfg.actorUserId,
+        profile: flags.profile || DEFAULT_PROFILE,
+        reason: flags.reason ?? undefined,
+        agentSession: agentSession ?? undefined,
+        content: target.content,
+        ...(target.documentId
+            ? { documentId: target.documentId }
+            : { relPath: target.relPath }),
+    };
+    let receipt;
+    try {
+        const res = await (0, http_1.intelPost)(cfg, "/internal/v1/kb/reingest", body, REINGEST_TIMEOUT_MS);
+        receipt = res.receipt;
+    }
+    catch (e) {
+        console.error(`kb reingest failed: ${e.message}`);
+        return exitForHttpError(e);
+    }
+    if (!receipt) {
+        console.error("kb reingest: the route returned no receipt.");
+        return 1;
+    }
+    console.log((0, render_1.renderKbReingestReceipt)(receipt));
+    console.log("");
+    // A per-doc intake failure is reported in the receipt, not the HTTP status;
+    // mirror the worker's exit (failed -> 1, ingested / noop_unchanged -> 0).
+    return receipt.outcome === "failed" ? 1 : 0;
+}