@meetless/mla 0.1.4

package/dist/lib/steer-cache.js

@@ -0,0 +1,87 @@
+"use strict";
+// Cross-session steer transport: the zero-network hand-off between the CLI
+// `_internal steer-sync` hop (which pulls steers from control) and the
+// UserPromptSubmit hook (which injects them).
+//
+// steer-sync writes the deliverable set to steer-<sid>.json; the hook reads it
+// with NO network call (same hot-path constraint as the governance nudge). The
+// hook records which steer ids it injected in inject-<sid>.json; steer-sync reads
+// THAT to mark them injected (PULLED -> INJECTED). Both files live under
+// $MEETLESS_HOME/logs/steer/ and the paths + shapes MUST stay byte-identical to
+// the bash helpers in common.sh (steer_cache_file / steer_inject_file). The
+// session id is opaque (CLAUDE_CODE_SESSION_ID); like governance_inject_file it
+// is used verbatim, no sanitization.
+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.steerCachePath = steerCachePath;
+exports.steerInjectStatePath = steerInjectStatePath;
+exports.writeSteerCache = writeSteerCache;
+exports.readInjectedIds = readInjectedIds;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("./config");
+function steerCachePath(sessionId, home = config_1.HOME) {
+    return path.join(home, "logs", "steer", `steer-${sessionId}.json`);
+}
+function steerInjectStatePath(sessionId, home = config_1.HOME) {
+    return path.join(home, "logs", "steer", `inject-${sessionId}.json`);
+}
+// Best-effort: a failed cache write must never break the steer-sync hop (which is
+// itself best-effort inside flush.sh). Worst case the hook keeps reading the prior
+// cache until the next successful write.
+function writeSteerCache(sessionId, steers, home = config_1.HOME) {
+    try {
+        const file = steerCachePath(sessionId, home);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify({ steers, ts: Math.floor(Date.now() / 1000) }));
+    }
+    catch {
+        /* non-fatal */
+    }
+}
+// Read the ids the hook recorded as injected. Returns [] on any absence/parse
+// failure (the mark-injected loop then simply has nothing to flip this round).
+function readInjectedIds(sessionId, home = config_1.HOME) {
+    try {
+        const file = steerInjectStatePath(sessionId, home);
+        const body = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (!Array.isArray(body.injected))
+            return [];
+        return body.injected.filter((x) => typeof x === "string");
+    }
+    catch {
+        return [];
+    }
+}

package/dist/lib/tagged-reference.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.supersessionAdvisory = supersessionAdvisory;
+function supersessionAdvisory(referencedPaths, facts) {
+    const refs = new Set(referencedPaths);
+    const out = [];
+    for (const f of facts) {
+        if (!refs.has(f.fromPath))
+            continue;
+        if (f.posture !== "LIVE" || f.status !== "ACCEPTED")
+            continue; // approved facts only
+        if (f.relationType === "SUPERSEDED_BY") {
+            out.push({ citedKbId: f.toKbId, message: `${f.fromPath} is superseded by ${f.toPath} (${f.toKbId}); prefer the newer doc.` });
+        }
+        else if (f.relationType === "CONTRADICTS") {
+            out.push({ citedKbId: f.toKbId, message: `${f.fromPath} contradicts ${f.toPath} (${f.toKbId}).` });
+        }
+    }
+    return out;
+}

package/dist/lib/temporal.js

@@ -0,0 +1,109 @@
+"use strict";
+// Shared temporal helpers for the MLA CLI's as-of surfaces (B9).
+//
+// `parseAsOf` normalizes an operator-supplied date into a UTC ISO-8601 instant
+// (a VALID-time cutoff: "what was true as of this instant"). It is the front
+// door for `mla ask --as-of` and `mla kb show --as-of`; the intel side reads it
+// as `AskRequest.as_of` and runs the point-in-time filter. We reject anything
+// malformed so a typo never silently answers as-of "now".
+//
+// Render helpers (renderValidWindow, renderTrustLabel) live here too so every
+// as-of surface formats the bi-temporal window and the clock trust the same
+// way. `kb show` is the first consumer (Task 5.2); the help surfaces (cli.ts
+// USAGE + kb.ts KB_USAGE) teach the same two temporal axes valid-time and
+// observation-time that these helpers render (Task 5.4).
+//
+// Plan: notes/20260605-mla-full-temporal-awareness-implementation-plan.md, Tasks 5.1-5.4.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAsOf = parseAsOf;
+exports.renderTrustLabel = renderTrustLabel;
+exports.renderValidWindow = renderValidWindow;
+const DASHED = /^(\d{4})-(\d{2})-(\d{2})$/;
+const COMPACT = /^(\d{4})(\d{2})(\d{2})$/;
+// Build a midnight-UTC ISO instant from year/month/day, rejecting rolled-over
+// dates: JS `Date` silently turns 2026-02-30 into Mar 2, so we round-trip the
+// components and refuse any that do not survive intact.
+function isoFromYmd(y, mo, d) {
+    if (mo < 1 || mo > 12 || d < 1 || d > 31)
+        return null;
+    const dt = new Date(Date.UTC(y, mo - 1, d));
+    if (dt.getUTCFullYear() !== y || dt.getUTCMonth() !== mo - 1 || dt.getUTCDate() !== d) {
+        return null;
+    }
+    return dt.toISOString();
+}
+// Parse an `--as-of` argument into a UTC ISO-8601 instant. Accepts:
+//   - `YYYY-MM-DD` and compact `YYYYMMDD` -> midnight UTC of that day
+//   - a full ISO-8601 datetime (e.g. 2026-04-10T12:30:00Z) -> normalized instant
+// Throws on anything else.
+function parseAsOf(raw) {
+    const s = (raw ?? "").trim();
+    if (!s) {
+        throw new Error("`--as-of` requires a date (YYYY-MM-DD or YYYYMMDD).");
+    }
+    const m = DASHED.exec(s) ?? COMPACT.exec(s);
+    if (m) {
+        const iso = isoFromYmd(Number(m[1]), Number(m[2]), Number(m[3]));
+        if (!iso) {
+            throw new Error(`Invalid --as-of date: '${raw}'. Use YYYY-MM-DD or YYYYMMDD.`);
+        }
+        return iso;
+    }
+    // Full ISO-8601 datetime: pin a precise instant. Date.parse is lenient, so we
+    // require the string to at least carry a 'T' before trusting it as a datetime,
+    // keeping bare junk ("not-a-date") on the reject path.
+    if (s.includes("T")) {
+        const t = Date.parse(s);
+        if (!Number.isNaN(t)) {
+            return new Date(t).toISOString();
+        }
+    }
+    throw new Error(`Invalid --as-of date: '${raw}'. Use YYYY-MM-DD or YYYYMMDD.`);
+}
+// The clock sources Meetless trusts as VALID-time authority. Mirrors intel's
+// TRUSTED_ASOF_SOURCES (app/graphs/ask/retrieval/asof.py): an explicit author
+// stamp, a document date, a diff audit-log entry, or a source-event time.
+// INGESTION_TIME_PROXY and UNKNOWN are observed-only, never validated.
+const TRUSTED_TIME_SOURCES = new Set([
+    "EXPLICIT_METADATA",
+    "DOCUMENT_DATE",
+    "DIFF_AUDIT_LOG",
+    "SOURCE_EVENT_TIME",
+]);
+// Plain-words trust label for a relation's valid_time_source. Trusted sources
+// read as "trusted"; anything observed-only reads as "approximate (observed,
+// not validated)" so an operator never mistakes an ingestion guess for a
+// validated clock. Two axes, two answers (B17): this is the trust of the
+// VALID-time clock, separate from whether the edge survives an as-of filter.
+function renderTrustLabel(source) {
+    if (source && TRUSTED_TIME_SOURCES.has(source)) {
+        return "trusted";
+    }
+    return "approximate (observed, not validated)";
+}
+// Reduce a stored ISO instant to its calendar date for a compact window line.
+// Falls back to the raw value if it is not an ISO date so we never drop signal.
+function calendarDate(iso) {
+    if (!iso)
+        return null;
+    const m = /^(\d{4}-\d{2}-\d{2})/.exec(iso);
+    return m ? m[1] : iso;
+}
+// Render a bi-temporal VALID-time window in plain words. No double-dash range
+// separators (An's AI-smell rule); the open end is spelled out so an operator
+// reads "still in force" rather than guessing at a blank. Cases:
+//   both bounds   -> "valid from <from> until <until>"
+//   open-ended    -> "valid from <from> (open-ended)"
+//   close-only    -> "valid until <until>" (rare; close recorded, open missing)
+//   neither       -> "validity window not recorded"
+function renderValidWindow(window) {
+    const from = calendarDate(window.validAt);
+    const until = calendarDate(window.invalidAt);
+    if (from && until)
+        return `valid from ${from} until ${until}`;
+    if (from)
+        return `valid from ${from} (open-ended)`;
+    if (until)
+        return `valid until ${until}`;
+    return "validity window not recorded";
+}

package/dist/lib/turn-recap-emit.js

@@ -0,0 +1,67 @@
+"use strict";
+// Layer D emitter (notes/20260609-mla-per-turn-assist-recap-plan.md §4.4).
+//
+// POST a just-finished turn's recap to intel's POST /v1/observability/turn-recap
+// so intel attaches the mla_ran / mla_assist Langfuse scores to that turn's
+// trace. Spawned detached from stop.sh via `mla _internal turn-recap
+// --emit-langfuse`; runInternalTurnRecap wires this as the default emitter.
+//
+// Why not the generic intelPost helper: intelPost stamps X-Trace-ID from the
+// CURRENT run's trace id. Here the trace we score is the JUST-FINISHED turn's
+// (recap.trace_id), which differs from this detached invocation's run id. We pin
+// X-Trace-ID to recap.trace_id so header and body name the same trace and the
+// endpoint's mismatch guard stays satisfied.
+//
+// Best-effort: a missing trace id is a silent no-op (nothing to score); any
+// transport / non-2xx failure throws so the caller can swallow it without ever
+// disturbing the agent. Langfuse keys live in intel, never here, so the
+// soon-to-be-OSS CLI ships no observability credentials.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.postTurnRecapToIntel = postTurnRecapToIntel;
+const http_1 = require("./http");
+const turn_recap_1 = require("./analytics/turn-recap");
+// Detached + best-effort, so a tight deadline: the turn already ended, this only
+// decorates its trace. 1.5s matches the trace-flush HTTP deadline.
+const EMIT_TIMEOUT_MS = 1500;
+async function postTurnRecapToIntel(cfg, recap, deps = {}) {
+    // No trace id -> no Langfuse trace to attach a score to. Silent no-op.
+    if (!recap.trace_id)
+        return;
+    const base = cfg.intelUrl || http_1.DEFAULT_INTEL_URL;
+    const url = `${base}/v1/observability/turn-recap`;
+    const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+    const timeoutMs = deps.timeoutMs ?? EMIT_TIMEOUT_MS;
+    const body = {
+        traceId: recap.trace_id,
+        sessionId: recap.session_id,
+        turnIndex: recap.turn_index,
+        verdict: recap.verdict,
+        // One-line footer rides as the score comment.
+        footer: (0, turn_recap_1.renderFooter)(recap),
+        notRunReason: recap.not_run_reason,
+        // Full recap -> trace metadata for drilldown.
+        recap,
+    };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(url, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${cfg.controlToken}`,
+                "Content-Type": "application/json",
+                // Pinned to the just-finished turn's trace, not this run's.
+                "X-Trace-ID": recap.trace_id,
+            },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`POST ${url} -> HTTP ${res.status}: ${text.slice(0, 200)}`);
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/lib/unwire.js

@@ -0,0 +1,253 @@
+"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.backupFile = backupFile;
+exports.removeDir = removeDir;
+exports.countQueuedSessions = countQueuedSessions;
+exports.countQueuedEvents = countQueuedEvents;
+exports.resolveMlaBinary = resolveMlaBinary;
+exports.removeMeetlessHooks = removeMeetlessHooks;
+exports.removeMeetlessMcp = removeMeetlessMcp;
+exports.detectBinaryRemovalHint = detectBinaryRemovalHint;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("./config");
+const wire_1 = require("./wire");
+// Inverse primitives of lib/wire.ts. Pure-ish and best-effort: a step that
+// cannot complete returns a structured result rather than throwing, so the
+// orchestrator can report every outcome and never abort halfway.
+// Copy `p` to `p.bak.<now>` and return the backup path. Caller writes the new
+// content only after this returns, so a botched edit is always recoverable.
+function backupFile(p) {
+    const backupPath = `${p}.bak.${Date.now()}`;
+    fs.copyFileSync(p, backupPath);
+    return backupPath;
+}
+// rm -rf one directory. removed=false (no error) means "was not there"; an
+// error string means it existed but could not be removed.
+function removeDir(dir) {
+    try {
+        if (!fs.existsSync(dir))
+            return { removed: false };
+        fs.rmSync(dir, { recursive: true, force: true });
+        return { removed: true };
+    }
+    catch (e) {
+        return { removed: false, error: e.message };
+    }
+}
+// Number of capture sessions with a queue file: one `<sid>.jsonl` per session
+// (`.lock` / `.turn` sidecars do not count). A flush drains and truncates the
+// events it sent, so a counted file may hold only a small un-flushed tail (or
+// none) rather than a whole un-flushed session. Missing dir -> 0.
+function countQueuedSessions(queueDir) {
+    try {
+        return fs.readdirSync(queueDir).filter((f) => f.endsWith(".jsonl")).length;
+    }
+    catch {
+        return 0;
+    }
+}
+// Total un-flushed events still sitting in the queue: the sum of event lines
+// across every `<sid>.jsonl` (one JSON object per line; blank lines and `.lock`
+// / `.turn` sidecars do not count). This is the honest measure of what an
+// uninstall discards, since most session files hold only a short tail of events
+// and the file count alone overstates the magnitude. Missing dir -> 0.
+function countQueuedEvents(queueDir) {
+    try {
+        let total = 0;
+        for (const f of fs.readdirSync(queueDir)) {
+            if (!f.endsWith(".jsonl"))
+                continue;
+            const content = fs.readFileSync(path.join(queueDir, f), "utf8");
+            total += content.split("\n").filter((line) => line.trim().length > 0).length;
+        }
+        return total;
+    }
+    catch {
+        return 0;
+    }
+}
+// Best-effort PATH search for the `mla` launcher. Returns the on-PATH path and
+// its resolved realpath (the symlink target, when it is one). Pure over `env`
+// so a test can hand it a synthetic PATH.
+function resolveMlaBinary(env = process.env) {
+    const PATH = env.PATH || "";
+    for (const dir of PATH.split(path.delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = path.join(dir, "mla");
+        try {
+            const st = fs.lstatSync(candidate);
+            if (st.isFile() || st.isSymbolicLink()) {
+                let realPath = null;
+                try {
+                    realPath = fs.realpathSync(candidate);
+                }
+                catch {
+                    realPath = null;
+                }
+                return { binPath: candidate, realPath };
+            }
+        }
+        catch {
+            // not in this dir
+        }
+    }
+    return { binPath: null, realPath: null };
+}
+// Inverse of ensureClaudeSettings. For each managed event, drop entries that are
+// EXCLUSIVELY ours (exactly one hook whose command isManagedHookCommand for that
+// event's script). Operator hooks, and multi-hook entries an operator merged our
+// command into, are never touched (same conservatism install uses). Emptied
+// event arrays are deleted; an emptied `hooks` object is dropped. Best-effort:
+// a missing or unparseable file is a no-op, not an error.
+function removeMeetlessHooks(settingsPath) {
+    const noop = { removed: [], changed: false, backupPath: null, settingsPath };
+    if (!fs.existsSync(settingsPath))
+        return noop;
+    const current = fs.readFileSync(settingsPath, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(current);
+    }
+    catch {
+        return noop;
+    }
+    if (!parsed || typeof parsed.hooks !== "object" || parsed.hooks === null)
+        return noop;
+    const removed = [];
+    for (const { event, script } of wire_1.MANAGED_HOOK_SCRIPTS) {
+        const list = parsed.hooks[event];
+        if (!Array.isArray(list))
+            continue;
+        const cmd = path.join(config_1.HOOKS_DIR, script);
+        const isOurs = (entry) => {
+            const hooks = Array.isArray(entry?.hooks) ? entry.hooks : [];
+            if (hooks.length !== 1)
+                return false;
+            const c = hooks[0];
+            return (c?.type === "command" &&
+                typeof c?.command === "string" &&
+                (0, wire_1.isManagedHookCommand)(c.command, script, cmd));
+        };
+        const kept = list.filter((e) => !isOurs(e));
+        if (kept.length !== list.length) {
+            removed.push(event);
+            if (kept.length === 0)
+                delete parsed.hooks[event];
+            else
+                parsed.hooks[event] = kept;
+        }
+    }
+    if (removed.length === 0)
+        return noop;
+    if (Object.keys(parsed.hooks).length === 0)
+        delete parsed.hooks;
+    const next = JSON.stringify(parsed, null, 2) + "\n";
+    const backupPath = backupFile(settingsPath);
+    fs.writeFileSync(settingsPath, next, "utf8");
+    return { removed, changed: true, backupPath, settingsPath };
+}
+// Delete the single `meetless` server from ~/.claude.json: the top-level
+// mcpServers map plus every projects[*].mcpServers map. Other servers are kept;
+// an emptied mcpServers object is dropped. Best-effort over a missing/unparseable
+// file. The file is re-serialized with 2-space indent (it may have been
+// minified); the timestamped backup preserves the byte-exact original.
+function removeMeetlessMcp(claudeJsonPath) {
+    const noop = { removedFrom: [], changed: false, backupPath: null, claudeJsonPath };
+    if (!fs.existsSync(claudeJsonPath))
+        return noop;
+    const current = fs.readFileSync(claudeJsonPath, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(current);
+    }
+    catch {
+        return noop;
+    }
+    const removedFrom = [];
+    const dropFrom = (container, label) => {
+        const servers = container?.mcpServers;
+        if (servers && typeof servers === "object" && wire_1.MCP_SERVER_KEY in servers) {
+            delete servers[wire_1.MCP_SERVER_KEY];
+            removedFrom.push(label);
+            if (Object.keys(servers).length === 0)
+                delete container.mcpServers;
+        }
+    };
+    dropFrom(parsed, "(top level)");
+    if (parsed && typeof parsed.projects === "object" && parsed.projects !== null) {
+        for (const projPath of Object.keys(parsed.projects)) {
+            dropFrom(parsed.projects[projPath], `projects/${projPath}`);
+        }
+    }
+    if (removedFrom.length === 0)
+        return noop;
+    const next = JSON.stringify(parsed, null, 2) + "\n";
+    const backupPath = backupFile(claudeJsonPath);
+    fs.writeFileSync(claudeJsonPath, next, "utf8");
+    return { removedFrom, changed: true, backupPath, claudeJsonPath };
+}
+// Map (binPath, realPath) to the human removal instruction. Classifies by the
+// realpath shape, no shelling out:
+//   - realpath under node_modules/@meetless/mla  -> a package-manager global
+//     (pnpm if the path mentions pnpm, else npm)
+//   - otherwise a dev symlink into a source checkout -> rm the launcher, and
+//     name the repo root (the segment before /packages/cli/) so the operator
+//     can delete the clone too.
+function detectBinaryRemovalHint(binPath, realPath) {
+    if (!binPath) {
+        return ["Could not find `mla` on your PATH. If a copy remains, remove it manually."];
+    }
+    const probe = realPath ?? "";
+    const pkgMarker = `${path.sep}node_modules${path.sep}@meetless${path.sep}mla`;
+    if (probe.includes(pkgMarker)) {
+        const isPnpm = /pnpm/.test(probe) || /pnpm/.test(binPath);
+        return [
+            "Remove the globally-installed package:",
+            isPnpm ? "  pnpm rm -g @meetless/mla" : "  npm uninstall -g @meetless/mla",
+        ];
+    }
+    const lines = ["Remove the `mla` launcher (a dev symlink):", `  rm ${binPath}`];
+    if (realPath) {
+        const marker = `${path.sep}packages${path.sep}cli${path.sep}`;
+        const idx = realPath.indexOf(marker);
+        if (idx > 0) {
+            lines.push(`If you no longer need the source, delete the checkout at ${realPath.slice(0, idx)}`);
+        }
+    }
+    return lines;
+}