litmus-cli 1.4.11 → 1.4.12

package/dist/lib/capture-nudge.js

@@ -0,0 +1,341 @@
+/**
+ * Capture-nudge decision logic (ENG-1857) — pure and unit-testable
+ * (watcher.ts is a spawned script, so logic living there can't be imported
+ * by tests; same split as detection.ts).
+ *
+ * The signature this exists to catch: a hook-capturable AI tool is running
+ * but zero prompts have been captured — almost always Codex or the Copilot
+ * CLI sitting behind their silent trust gates (ENG-951/ENG-1323), i.e. a
+ * candidate whose AI work is invisibly not being recorded. The nudge is
+ * CANDIDATE-FACING ONLY: a desktop notification plus a notice file at the
+ * assessment root. It emits NO activity event — the grader renders every
+ * non-response activity event verbatim in the judge-visible timeline
+ * (substrate_sections.py) and merges the in-zip activity.jsonl, so anything
+ * we logged there would leak to reports. Watcher firings go to stderr only
+ * (.litmus/tracker.log, excluded from all grader signals via
+ * substrate.py's _is_capture_artifact).
+ */
+import fs from "fs";
+import path from "path";
+import { REPAIR_FILE_NAME } from "./shadow.js";
+import { clearOwnedNotice, isOwnedNoticeFile, recordOwnedNotice } from "./notice-ownership.js";
+// ── Trigger tools ─────────────────────────────────────────────────
+// In copy-priority order. Sourced from env_detected aiTools labels ONLY
+// (process-list detection) — never network signals, which can't separate a
+// capturable surface from a browser tab. Deliberately NOT included:
+//   cursor         — the watcher labels the Cursor EDITOR as an AI tool
+//                    whenever it is open, so this would nag plain-editor users
+//   claude         — legacy/unattributable label; could be Desktop or a
+//                    bystander string, neither hook-capturable
+//   claude_desktop, claude_web, gemini — no hook exists; nothing to nudge
+export const NUDGE_TRIGGER_TOOLS = ["codex", "copilot", "claude_code"];
+// Fire only after the tool is present on this many CONSECUTIVE scans, so a
+// one-scan blip (a stray process, a tool opened and closed) never nags.
+const CONSECUTIVE_SCANS_TO_FIRE = 2;
+// Re-nudge once if still zero prompts and the tool is still present this
+// long after the first nudge; hard cap below.
+const RENUDGE_AFTER_MS = 30 * 60 * 1000;
+const MAX_NUDGES = 2;
+// Don't nag someone in their final minutes — nothing they do now changes
+// what got captured, and status.ts already warns about the deadline itself.
+const DEADLINE_SUPPRESS_MS = 10 * 60 * 1000;
+// ── State ─────────────────────────────────────────────────────────
+// Serialized to .litmus/nudge-state.json so watcher respawns don't re-nag
+// (litmus status/doctor revive watchers routinely). The file lives in
+// .litmus/, which never reaches the submission zip: zip.ts excludes the
+// directory (via the .gitignore entry init guarantees) and re-includes only
+// its whitelisted diagnostics — plus a ROOT-ANCHORED nudge-state.json
+// exclude (EXCLUDE_ROOT_PATHS) for the case where a candidate stripped
+// their .gitignore.
+export const NUDGE_STATE_FILE_NAME = "nudge-state.json";
+export function initialNudgeState() {
+    return { consecutive: {}, nudgeCount: 0, lastNudgeAt: null, latched: false };
+}
+/**
+ * One decision per env scan. Pure: all inputs explicit, returns the action
+ * plus the next state (the caller persists it).
+ *
+ * @param scanTools    aiTools labels from this scan's env detection
+ * @param promptCount  ai_prompt + ai_response events captured so far
+ * @param now          epoch ms
+ * @param msRemaining  ms to the effective deadline, null when none configured
+ */
+export function decideNudge(state, scanTools, promptCount, now, msRemaining) {
+    if (state.latched)
+        return { action: "none", state };
+    // Capture confirmed: latch off permanently and signal notice removal.
+    // Counters are cleared — they can never matter again this session.
+    if (promptCount > 0) {
+        return { action: "remove_notice", state: { ...state, consecutive: {}, latched: true } };
+    }
+    // Advance the per-tool consecutive counters; absence resets to zero.
+    const present = new Set(scanTools);
+    const consecutive = {};
+    for (const tool of NUDGE_TRIGGER_TOOLS) {
+        consecutive[tool] = present.has(tool) ? (state.consecutive[tool] ?? 0) + 1 : 0;
+    }
+    const next = { ...state, consecutive };
+    // First trigger tool (in copy-priority order) that has been present long
+    // enough to be a real session rather than a blip.
+    const tool = NUDGE_TRIGGER_TOOLS.find((t) => (consecutive[t] ?? 0) >= CONSECUTIVE_SCANS_TO_FIRE);
+    if (!tool)
+        return { action: "none", state: next };
+    if (msRemaining !== null && msRemaining < DEADLINE_SUPPRESS_MS) {
+        return { action: "none", state: next };
+    }
+    if (next.nudgeCount >= MAX_NUDGES)
+        return { action: "none", state: next };
+    if (next.nudgeCount > 0 && (next.lastNudgeAt === null || now - next.lastNudgeAt < RENUDGE_AFTER_MS)) {
+        return { action: "none", state: next };
+    }
+    return {
+        action: "nudge",
+        tool,
+        state: { ...next, nudgeCount: next.nudgeCount + 1, lastNudgeAt: now },
+    };
+}
+// ── State persistence ─────────────────────────────────────────────
+function nudgeStatePath(projectDir) {
+    return path.join(projectDir, ".litmus", NUDGE_STATE_FILE_NAME);
+}
+/** Tolerant load: anything unreadable or malformed means a fresh state. */
+export function loadNudgeState(projectDir) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(nudgeStatePath(projectDir), "utf8"));
+        if (typeof raw !== "object" || raw === null)
+            return initialNudgeState();
+        const consecutive = {};
+        for (const tool of NUDGE_TRIGGER_TOOLS) {
+            const n = raw.consecutive?.[tool];
+            if (typeof n === "number" && Number.isFinite(n) && n >= 0)
+                consecutive[tool] = n;
+        }
+        return {
+            consecutive,
+            nudgeCount: typeof raw.nudgeCount === "number" && raw.nudgeCount >= 0 ? raw.nudgeCount : 0,
+            lastNudgeAt: typeof raw.lastNudgeAt === "number" ? raw.lastNudgeAt : null,
+            latched: raw.latched === true,
+        };
+    }
+    catch {
+        return initialNudgeState();
+    }
+}
+export function saveNudgeState(projectDir, state) {
+    try {
+        fs.mkdirSync(path.dirname(nudgeStatePath(projectDir)), { recursive: true });
+        fs.writeFileSync(nudgeStatePath(projectDir), JSON.stringify(state), "utf8");
+    }
+    catch { /* best effort — worst case a respawn re-nags once */ }
+}
+export function initialPromptCursor() {
+    return { offset: 0, remainder: "", count: 0 };
+}
+function countCaptureEvents(text) {
+    let count = 0;
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const event = JSON.parse(trimmed);
+            if (event && (event.type === "ai_prompt" || event.type === "ai_response"))
+                count++;
+        }
+        catch { /* malformed line — skip, same tolerance as status.ts */ }
+    }
+    return count;
+}
+/**
+ * Scan any bytes appended to `logPath` since `cursor` and return the
+ * advanced cursor. Never throws; a missing/unreadable log leaves the cursor
+ * unchanged. A log SMALLER than the cursor's offset (wiped/rotated) rescans
+ * from zero.
+ */
+export function scanPromptCount(logPath, cursor) {
+    try {
+        let { offset, remainder } = cursor;
+        const size = fs.statSync(logPath).size;
+        if (size < offset) {
+            offset = 0;
+            remainder = "";
+        }
+        if (size === offset)
+            return { ...cursor, offset, remainder };
+        const length = size - offset;
+        const buf = Buffer.alloc(length);
+        const fd = fs.openSync(logPath, "r");
+        let read = 0;
+        try {
+            read = fs.readSync(fd, buf, 0, length, offset);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        const text = remainder + buf.subarray(0, read).toString("utf8");
+        const lastNewline = text.lastIndexOf("\n");
+        const complete = lastNewline === -1 ? "" : text.slice(0, lastNewline + 1);
+        return {
+            offset: offset + read,
+            remainder: lastNewline === -1 ? text : text.slice(lastNewline + 1),
+            count: cursor.count + countCaptureEvents(complete),
+        };
+    }
+    catch {
+        return cursor;
+    }
+}
+// ── Candidate-facing notice file ──────────────────────────────────
+// Modeled on writeRepairFile (shadow.ts): rewritten whenever the condition
+// fires, removed on resolution. Lives at the assessment ROOT so the
+// candidate actually sees it — which is why it must be excluded everywhere:
+// the submission zip (never ships), the watcher's change events (its own
+// write never emits a judge-visible event), and the interview-agent
+// snapshot. All three exclusions go through isCliNoticeArtifact below:
+// root-only AND content-gated on the sentinel, so a candidate's own file
+// that merely shares the name — at the root or nested — is never touched,
+// suppressed, or dropped from their submission.
+export const AI_NOTICE_FILE_NAME = "LITMUS-AI-NOTICE.md";
+/** Human-readable label on every notice this CLI writes. A LABEL ONLY — it is
+ *  world-readable and therefore copyable, so it proves nothing. Ownership is
+ *  decided by the recorded content hash (notice-ownership.ts): only a file
+ *  byte-identical to what we wrote is ever overwritten, deleted, hidden from
+ *  change events, or excluded from the zip; an edited or planted file is the
+ *  candidate's, sentinel or not. */
+export const AI_NOTICE_SENTINEL = "<!-- litmus-cli capture-nudge notice. Auto-generated, removed when capture starts. -->";
+export function aiNoticeContent() {
+    return [
+        AI_NOTICE_SENTINEL,
+        "",
+        "# Your AI usage isn't being recorded yet",
+        "",
+        "An AI coding tool looks like it's running, but no prompts have been captured",
+        "so far. The hiring company reviews your AI use as part of your submission,",
+        "and visible AI usage counts in your favor. A session we can't see just",
+        "looks like you didn't use AI at all.",
+        "",
+        "- **Codex**: accept the one-time trust prompt it shows the first time it",
+        "  runs a hook in this folder. Until then, nothing is recorded.",
+        "- **Copilot CLI**: accept the folder-trust prompt it shows when it starts",
+        "  in this folder. It runs no hooks (and says nothing) until you do. Then",
+        "  run `litmus doctor` here to recover prompts from before you accepted.",
+        "- **Claude Code**: run `litmus doctor` here to check and repair tracking.",
+        "",
+        "Already done this, or not using an AI tool (or using one we can't capture,",
+        "like a browser chat)? Then ignore this. Nothing is wrong with your",
+        "submission. Run `litmus status` any time to see what's being captured.",
+        "This file is not part of your submission and disappears once capture starts.",
+        "",
+    ].join("\n");
+}
+/**
+ * Write (or refresh) our notice at the assessment root. Returns false —
+ * writing nothing — when a candidate-owned file already occupies the path;
+ * the caller falls back to the desktop notification alone.
+ */
+export function writeAiNoticeFile(projectDir) {
+    try {
+        const target = path.join(projectDir, AI_NOTICE_FILE_NAME);
+        if (fs.existsSync(target) && !isOwnedNoticeFile(projectDir, AI_NOTICE_FILE_NAME))
+            return false;
+        const content = aiNoticeContent();
+        fs.writeFileSync(target, content, "utf8");
+        recordOwnedNotice(projectDir, AI_NOTICE_FILE_NAME, content);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Remove the notice — but only one byte-identical to what WE wrote. Returns
+ * whether a file was removed; a candidate-owned file, an edited copy, or no
+ * file is left alone and returns false.
+ */
+export function removeAiNoticeFile(projectDir) {
+    try {
+        const target = path.join(projectDir, AI_NOTICE_FILE_NAME);
+        if (!isOwnedNoticeFile(projectDir, AI_NOTICE_FILE_NAME))
+            return false;
+        fs.rmSync(target, { force: true });
+        clearOwnedNotice(projectDir, AI_NOTICE_FILE_NAME);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ── CLI-notice classification (shared by watcher + zip + status) ──
+// The two notice names are ONLY special as OUR files at the assessment root.
+// Anything nested is candidate work whatever it is called (a basename match
+// there would let a candidate hide arbitrary files from evidence capture and
+// from their own submission), and a root file that isn't byte-identical to
+// content this CLI recorded writing is the candidate's own (suppressing or
+// dropping it would destroy their work — the same file could be silently
+// excluded from the zip AND deleted by cleanup). Content markers can't decide
+// this: they're world-readable and copyable, so ownership is the recorded
+// hash in notice-ownership.ts.
+const NOTICE_FILE_NAMES = new Set([
+    AI_NOTICE_FILE_NAME,
+    REPAIR_FILE_NAME,
+]);
+/**
+ * True only for a notice file THIS CLI generated, sitting at the assessment
+ * root. Root-only (any path separator disqualifies) and gated on the recorded
+ * content hash — an edited or planted file, sentinel included, is never ours.
+ *
+ * `lastKnown`, when supplied, is a caller-owned cache of the most recent
+ * ownership verdict per filename. It is refreshed on every call that can
+ * read the file, and consulted only when the file is GONE — i.e. the caller
+ * is classifying the file's own deletion event, where content can no longer
+ * decide. Without it, our removal of our own notice would emit a
+ * judge-visible rename event. Callers with no deletion events to classify
+ * (zip, status) omit it; a missing file is then simply "not ours".
+ */
+export function isCliNoticeArtifact(projectDir, relPath, lastKnown) {
+    if (/[/\\]/.test(relPath))
+        return false; // nested = candidate work, always
+    if (!NOTICE_FILE_NAMES.has(relPath))
+        return false;
+    const abs = path.join(projectDir, relPath);
+    let exists = false;
+    try {
+        exists = fs.existsSync(abs);
+    }
+    catch { /* treat as missing */ }
+    if (exists) {
+        const ours = isOwnedNoticeFile(projectDir, relPath);
+        lastKnown?.set(relPath, ours);
+        return ours;
+    }
+    return lastKnown?.get(relPath) ?? false;
+}
+// ── Notification copy ─────────────────────────────────────────────
+// Tone matches the ENG-951 init notice: helpful, never accusatory — zero
+// captured prompts makes the grader renormalize the Process dimension out,
+// so the honest pitch is "visible AI use counts in your favor", not a threat.
+const NOTICE_POINTER = `Details: ${AI_NOTICE_FILE_NAME} in your assessment folder.`;
+/**
+ * @param withDetailsPointer false when the notice file could not be written
+ *   (a candidate-owned file occupies the path) — pointing at a file that
+ *   carries THEIR content would misdirect.
+ */
+export function nudgeNotificationCopy(tool, withDetailsPointer = true) {
+    let message;
+    switch (tool) {
+        case "codex":
+            message =
+                "No AI prompts captured yet. If you're using Codex, accept its one-time trust prompt so your AI work is recorded for review by the hiring company.";
+            break;
+        case "copilot":
+            message =
+                `No AI prompts captured yet. If you're using the Copilot CLI, accept its folder-trust prompt so your AI work is recorded for review by the hiring company, then run "litmus doctor" to recover earlier prompts.`;
+            break;
+        default:
+            message =
+                'No AI prompts captured yet. Run "litmus doctor" in your assessment folder to check AI tracking.';
+            break;
+    }
+    return { title: "Litmus", message: withDetailsPointer ? `${message} ${NOTICE_POINTER}` : message };
+}
+//# sourceMappingURL=capture-nudge.js.map

package/dist/lib/capture-nudge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-nudge.js","sourceRoot":"","sources":["../../src/lib/capture-nudge.ts"],"names":[],"mappings":"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"}

package/dist/lib/hook-logger.cjs

@@ -20,10 +20,13 @@
  *           cursor-agent CLI never fires it)
  *   copilot Stop payload -> read transcript_path (JSONL), assistant.message
  *           entries of the final turn (VS Code shape; CLI best-effort)
+ *   gemini  AfterAgent payload -> `prompt_response` directly (arrives inline;
+ *           no transcript read)
  *
  * stdout contract: Cursor is the only tool that expects output back — see
  * emitCursorVerdictIfNeeded. For every other tool stdout MUST stay empty:
- * Claude Code injects hook stdout into the candidate's prompt as context.
+ * Claude Code injects hook stdout into the candidate's prompt as context, and
+ * Gemini surfaces non-empty hook stdout to the candidate as a systemMessage.
  */
 
 const fs = require("fs")
@@ -587,6 +590,17 @@ function extractPrompt(input, toolName) {
           sessionId: data.session_id || null,
         }
       }
+      case "gemini": {
+        // Gemini CLI BeforeAgent: { session_id, transcript_path, cwd,
+        // hook_event_name, prompt } per geminicli.com/docs/hooks. `cwd` is
+        // always sent and rides into sessionDirs via main()'s generic
+        // `parsed.cwd` plumbing, the same way the other CLIs' payloads do.
+        const prompt = data.prompt || null
+        return {
+          prompt: typeof prompt === "string" ? prompt : JSON.stringify(prompt),
+          sessionId: data.session_id || null,
+        }
+      }
       case "cursor": {
         // Cursor beforeSubmitPrompt. session_id and conversation_id carry the
         // same value; prefer session_id to match every other tool here.
@@ -619,11 +633,12 @@ function extractPrompt(input, toolName) {
 
 // The payload event names that mean "the model finished responding".
 // Claude Code and Codex both name theirs `Stop`; Cursor's is
-// `afterAgentResponse`. Anything else is treated as a prompt-submit event,
-// preserving the pre-ENG-1323 behavior for tools/payloads we don't recognize.
+// `afterAgentResponse`; Gemini's is `AfterAgent`. Anything else is treated as
+// a prompt-submit event, preserving the pre-ENG-1323 behavior for
+// tools/payloads we don't recognize.
 // Note the case difference is real, not a typo: Claude Code, Codex and Copilot
 // all name theirs `Stop`; Cursor's is lowercase `stop` (and `afterAgentResponse`).
-const RESPONSE_HOOK_EVENTS = new Set(["Stop", "stop", "afterAgentResponse"])
+const RESPONSE_HOOK_EVENTS = new Set(["Stop", "stop", "afterAgentResponse", "AfterAgent"])
 
 function isResponseEvent(data) {
   if (!data || typeof data !== "object") return false
@@ -927,6 +942,15 @@ function extractResponse(data, toolName) {
         sessionId: data.session_id || null,
       }
     }
+    case "gemini": {
+      // Gemini AfterAgent carries the response INLINE: { session_id, cwd,
+      // hook_event_name: "AfterAgent", prompt_response }. No transcript read.
+      const msg = data.prompt_response
+      return {
+        text: typeof msg === "string" && msg ? msg : null,
+        sessionId: data.session_id || null,
+      }
+    }
     case "cursor": {
       const common = {
         sessionId: data.session_id || data.conversation_id || null,

package/dist/lib/notice-ownership.d.ts

@@ -0,0 +1,13 @@
+/** Record that this CLI just wrote `content` to the root file `fileName`.
+ *  Call immediately after every write of a notice file. */
+export declare function recordOwnedNotice(projectDir: string, fileName: string, content: string): void;
+/** Forget a notice we removed (or gave up on). */
+export declare function clearOwnedNotice(projectDir: string, fileName: string): void;
+/**
+ * True only when the root file `fileName` exists and is byte-identical to
+ * content this CLI recorded writing for this project. Never throws; a missing
+ * file, missing record, unreadable content, oversize file, or hash mismatch
+ * are all "not ours".
+ */
+export declare function isOwnedNoticeFile(projectDir: string, fileName: string): boolean;
+//# sourceMappingURL=notice-ownership.d.ts.map

package/dist/lib/notice-ownership.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notice-ownership.d.ts","sourceRoot":"","sources":["../../src/lib/notice-ownership.ts"],"names":[],"mappings":"AAqFA;2DAC2D;AAC3D,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAK7F;AAED,kDAAkD;AAClD,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAQ3E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAW/E"}

package/dist/lib/notice-ownership.js

@@ -0,0 +1,123 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { createHash } from "crypto";
+// ── Ownership registry for candidate-facing notice files (ENG-1857) ──
+// The notice files (LITMUS-AI-NOTICE.md, LITMUS-REPAIR.md) sit world-readable
+// at the assessment root, so nothing IN a file can prove this CLI wrote it —
+// any sentinel or marker line can be copied into a look-alike, and a
+// candidate's edits to a generated notice would still carry it. Ownership
+// therefore lives OUTSIDE the file: a registry records the sha256 of exactly
+// the content we wrote, and only a byte-identical file is ever treated as
+// ours. The moment a candidate edits our notice — or plants their own — the
+// hash stops matching and the file is theirs: its change events flow, it
+// ships in the submission zip, and no cleanup path may overwrite or remove it.
+//
+// The registry lives in HOME scope (`~/.litmus/notice-owners.json`, keyed by
+// project realpath), not in the project's own `.litmus/`, so it is outside
+// everything that operates on the assessment tree — the candidate's editor
+// and agents, `git clean`, the zip, the watcher. To be explicit about the
+// boundary this does NOT move: everything on a candidate-owned machine is
+// ultimately candidate-writable (activity.jsonl included), so no client-side
+// state can be adversarially trustworthy. This registry's job is preventing
+// ACCIDENTAL destruction or suppression of candidate work; a candidate who
+// deliberately forges an entry can only self-suppress a root file with one of
+// these two fixed names — which gains them nothing over simply keeping that
+// file outside the assessment directory, where it was never evidence at all.
+const OWNERS_FILE_NAME = "notice-owners.json";
+// Same ceiling as the notices themselves (~1KB each): anything larger at one
+// of these paths is candidate work regardless of what the registry says.
+const MAX_NOTICE_BYTES = 64 * 1024;
+// Resolved per call (not at module load): tests fake HOME, and vitest caches
+// modules — a load-time constant would lock the first test's home in place.
+function ownersPath() {
+    return path.join(os.homedir(), ".litmus", OWNERS_FILE_NAME);
+}
+/** Registry keys are project realpaths: `process.cwd()` is realpath-resolved
+ *  but callers may hold raw paths, and on macOS `/var` is a symlink to
+ *  `/private/var` — raw-string keys would silently never match. */
+function projectKey(projectDir) {
+    try {
+        return fs.realpathSync(projectDir);
+    }
+    catch {
+        return projectDir;
+    }
+}
+function contentHash(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}
+/** Tolerant load: unreadable or malformed means an empty registry — doubt is
+ *  always resolved toward "the candidate's file". */
+function loadOwners() {
+    try {
+        const raw = JSON.parse(fs.readFileSync(ownersPath(), "utf8"));
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+            return {};
+        const registry = {};
+        for (const [project, entries] of Object.entries(raw)) {
+            if (typeof entries !== "object" || entries === null || Array.isArray(entries))
+                continue;
+            const owned = {};
+            for (const [name, hash] of Object.entries(entries)) {
+                if (typeof hash === "string" && /^[0-9a-f]{64}$/.test(hash))
+                    owned[name] = hash;
+            }
+            if (Object.keys(owned).length)
+                registry[project] = owned;
+        }
+        return registry;
+    }
+    catch {
+        return {};
+    }
+}
+function saveOwners(registry) {
+    try {
+        fs.mkdirSync(path.dirname(ownersPath()), { recursive: true });
+        fs.writeFileSync(ownersPath(), JSON.stringify(registry), "utf8");
+    }
+    catch { /* best effort — worst case a notice we wrote is treated as the candidate's */ }
+}
+/** Record that this CLI just wrote `content` to the root file `fileName`.
+ *  Call immediately after every write of a notice file. */
+export function recordOwnedNotice(projectDir, fileName, content) {
+    const registry = loadOwners();
+    const key = projectKey(projectDir);
+    registry[key] = { ...registry[key], [fileName]: contentHash(content) };
+    saveOwners(registry);
+}
+/** Forget a notice we removed (or gave up on). */
+export function clearOwnedNotice(projectDir, fileName) {
+    const registry = loadOwners();
+    const key = projectKey(projectDir);
+    const owned = registry[key];
+    if (!owned || !(fileName in owned))
+        return;
+    delete owned[fileName];
+    if (!Object.keys(owned).length)
+        delete registry[key];
+    saveOwners(registry);
+}
+/**
+ * True only when the root file `fileName` exists and is byte-identical to
+ * content this CLI recorded writing for this project. Never throws; a missing
+ * file, missing record, unreadable content, oversize file, or hash mismatch
+ * are all "not ours".
+ */
+export function isOwnedNoticeFile(projectDir, fileName) {
+    const recorded = loadOwners()[projectKey(projectDir)]?.[fileName];
+    if (!recorded)
+        return false;
+    try {
+        const abs = path.join(projectDir, fileName);
+        const stat = fs.statSync(abs);
+        if (!stat.isFile() || stat.size > MAX_NOTICE_BYTES)
+            return false;
+        return contentHash(fs.readFileSync(abs, "utf8")) === recorded;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=notice-ownership.js.map

package/dist/lib/notice-ownership.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notice-ownership.js","sourceRoot":"","sources":["../../src/lib/notice-ownership.ts"],"names":[],"mappings":"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"}

package/dist/lib/notify.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Best-effort desktop notification (ENG-1857) — zero dependencies, silent
+ * failure. Used by the watcher to reach a candidate whose terminal (and
+ * tracker.log) they are not looking at. It must never throw and never block:
+ * every path is a fire-and-forget execFile with a 5s timeout, and a missing
+ * binary (no notify-send, locked-down PowerShell) is simply a no-op.
+ */
+import { execFile } from "child_process";
+/**
+ * The command for this platform, or null when there is nothing sensible to
+ * run. Pure — split out so tests can check construction (quote escaping)
+ * without spawning anything.
+ */
+export declare function buildNotifyCommand(platform: NodeJS.Platform, title: string, message: string): {
+    cmd: string;
+    args: string[];
+} | null;
+/**
+ * Show a desktop notification. Never throws, never blocks the caller;
+ * failure of any kind (missing binary, DE without a notification daemon,
+ * headless session) is silently ignored — the notice file is the durable
+ * fallback surface.
+ */
+export declare function desktopNotify(title: string, message: string, exec?: typeof execFile): void;
+//# sourceMappingURL=notify.d.ts.map

package/dist/lib/notify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../../src/lib/notify.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAYxC;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,CAAC,QAAQ,EACzB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GACd;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CA4BxC;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,OAAO,QAAmB,GAC/B,IAAI,CAaN"}