@mnemonik/shared 7.97.2 → 7.98.0

package/src/index.ts

@@ -10,6 +10,7 @@ export { USAGE_GUIDE } from './usageGuide.js';
 export {
   CodeScanner,
   MAX_SCANNED_FILE_BYTES,
+  MAX_PUSH_CHUNK_CONTENT_LENGTH,
   AUTHORITY_FILE_MATCHERS,
   BUILT_IN_IGNORE_DIRS,
   DEFAULT_INCLUDE_EXTENSIONS,
@@ -72,3 +73,22 @@ export {
 } from './jitDeliveryAck.js';
 export * from './settingsIo.js';
 export * from './claudeProxySettings.js';
+export * from './repositoryFingerprint.js';
+export * from './projectIdentityFile.js';
+export * from './repositoryRoot.js';
+export * from './protectedPaths.js';
+export * from './readiness.js';
+
+export * from './hostAdapter.js';
+export * from './hostBinary.js';
+
+export type {
+  ServiceDefinition,
+  SupervisorStatus,
+  ServiceOperation,
+  ServiceResult,
+} from './scannerSupervisor.js';
+
+export { apiOrigin } from './apiOrigin.js';
+
+export { WINDOWS_SERVICE_BUDGET_MS } from './scannerSupervisor.js';

package/src/instructions.ts

@@ -7,15 +7,15 @@
  * Version: 2.110
  * Updated: 2026-08-27
  *
- * v2.110 — Reordered and compressed the universal instructions to fit the
+ * v2.110 - Reordered and compressed the universal instructions to fit the
  *          2,048-character transport limit. The first 512 characters now carry
  *          the server purpose, self-scoping bootstrap condition, required cwd,
  *          and memory-as-augmentation stance. The retrieval, task pagination,
  *          and tool-floor capabilities remain in a shorter factual form.
  *
- * v2.109 — Compressed the v2.108 memory-search clause. It restated, verbatim,
+ * v2.109 - Compressed the v2.108 memory-search clause. It restated, verbatim,
  *          the same search guidance carried by SESSION_OPENER_INSTRUCTION
- *          (bootstrapDigestRender.ts) — and both co-occur in the same agent
+ *          (bootstrapDigestRender.ts) - and both co-occur in the same agent
  *          session as the bootstrap digest's capabilities.search block, which
  *          already states the memory_search/code_search call signatures in
  *          full. Kept the essential behavior (memory holds the why; search it
@@ -23,11 +23,11 @@
  *          with Grep/Read; reach for code_search when concepts don't share
  *          the user's words), dropped the restated call shapes, and pointed at
  *          the session context's capabilities block for the exact signatures
- *          once it loads — this text fires at `initialize`, before any
+ *          once it loads - this text fires at `initialize`, before any
  *          digest exists, so it cannot point "above" the way the trimmed
  *          SESSION_OPENER clause does. recall-first-class plan, Task A3
  *          rider (reviewer-flagged: character-for-character duplicate).
- * v2.108 — Added front-loaded education that persistent project memory is part
+ * v2.108 - Added front-loaded education that persistent project memory is part
  *          of the agent's working knowledge. A live Config-B fixture rejected
  *          the first generic invitation: the agent searched code, docs, and git
  *          history, then called the rationale undocumented without searching
@@ -38,7 +38,7 @@
  *          wording stays a compact startup floor, not a token-heavy tutorial or
  *          recurring nudge.
  *
- * v2.106 — Added a static "Which tool for what" floor map. Rides the already-
+ * v2.106 - Added a static "Which tool for what" floor map. Rides the already-
  *         cached instructions at near-zero cost and gives every agent a baseline
  *         "which tool for what" for the under-surfaced tools (memory_add,
  *         memory_state, memory_info, memory_links, assist, search_summaries,
@@ -46,55 +46,55 @@
  *         nudges; memory_info in particular has no reactive trigger, so the floor
  *         is its only education.
  *
- * v2.105 — Bootstrap's agent-facing label is generic project context. Use the
+ * v2.105 - Bootstrap's agent-facing label is generic project context. Use the
  *         canonical text body's stable `PROJECT_CONTEXT schemaVersion=` marker
  *         for the self-scoping check instead of teaching agents to call the
  *         user's project "Mnemonik".
  *
- * v2.104 — Disambiguated persistent project task memories from Claude Code's
+ * v2.104 - Disambiguated persistent project task memories from Claude Code's
  *         host-local TaskList and made completeness proactive. A request for a
  *         complete/all list must build cursor continuation into the first Code
  *         Mode program; guidance returned after an incomplete outer call is too
  *         late to preserve the one-round-trip workflow.
  *
- * v2.103 — Added the compact Discover → Select → Hydrate interpretation
+ * v2.103 - Added the compact Discover -> Select -> Hydrate interpretation
  *         fallback for Config-A. Dynamic response orchestration remains
  *         authoritative; this sentence only teaches an un-orchestrated client
  *         how to act on retrieval envelopes without walking full bodies.
  *
- * v2.102 — Strengthened the self-bootstrap trigger to a compelling imperative.
+ * v2.102 - Strengthened the self-bootstrap trigger to a compelling imperative.
  *         The v2.101 phrasing ("At the start of a session, unless ... call ...")
  *         was too soft; agents on a blind first turn skipped it. Real-world hole
  *         it must cover: Cursor's FIRST chat after an IDE open fires no
  *         sessionStart (confirmed by hook-stdin capture), and beforeSubmitPrompt
  *         has NO model-facing output field (only user_message, shown to the
- *         human) — so neither the silent digest nor the hook's
+ *         human) - so neither the silent digest nor the hook's
  *         session_bootstrap_required directive reaches the model. The MCP
  *         instruction is the ONLY model-facing channel left for that turn, so it
  *         now leads with the blind-state check + a hard "FIRST action MUST be
  *         session_bootstrap, before you reply" and an explicit cwd-REQUIRED
  *         clause. Still self-scoping: skips when the "Mnemonik project context"
  *         block is already present (working hook/proxy delivery), so config-B/C
- *         with live delivery don't double-call. cwd stays host-agnostic — the
+ *         with live delivery don't double-call. cwd stays host-agnostic - the
  *         agent passes the project root it is working in (Cursor exposes the
  *         working dir to HOOKS via the stdin `workspace_roots[0]`, which cwdOf
  *         already reads; it is NOT an agent-readable env var, so the instruction
  *         must not name one).
  *
- * v2.101 — Stripped to a single instruction: the session_bootstrap trigger.
+ * v2.101 - Stripped to a single instruction: the session_bootstrap trigger.
  *         MCP instructions are set at Server construction (initialize), before
- *         the server knows the client, so they cannot be scoped per-IDE — and
+ *         the server knows the client, so they cannot be scoped per-IDE - and
  *         IDE != config (a Claude Code user may be config-B or -C). The content
  *         is therefore universal and SELF-SCOPING: it conditions on whether a
  *         "Mnemonik project context" block is already present (config-B/C with
- *         working delivery → skip; config-A and any host where hook/proxy
- *         delivery missed → call). Re-enabled in production
+ *         working delivery -> skip; config-A and any host where hook/proxy
+ *         delivery missed -> call). Re-enabled in production
  *         (MNEMONIK_INSTRUCTIONS_ENABLED=true in both ECS task defs). This is the
- *         reliable trigger that makes the agent self-bootstrap — tool results
+ *         reliable trigger that makes the agent self-bootstrap - tool results
  *         always reach the model, which hook injection cannot guarantee on a
  *         no-tool-call turn (e.g. Cursor "hello").
  *
- * v2.100 — Skill + IDE rule templates retired entirely. They were the
+ * v2.100 - Skill + IDE rule templates retired entirely. They were the
  *         file-written home of the workflow; agents followed them unreliably and
  *         forgot them over long sessions (the same fate these MCP instructions
  *         suffer), so they are gone. `filesToWrite` now carries only
@@ -103,7 +103,7 @@
  *         orchestration layer (host hooks + proxy); these instructions stay lean
  *         and are the Config-A fallback only.
  *
- * v2.99 — Orchestration-aware framing. These static MCP instructions are
+ * v2.99 - Orchestration-aware framing. These static MCP instructions are
  *         delivered at `initialize`, before the server knows the actor's tier
  *         (no project/proxy/hooks state yet), so they cannot be served per-tier.
  *         Instead the CONTENT is now tier-correct: the self-drive calls
@@ -114,29 +114,29 @@
  *         The orchestration layer (proxy + host hooks) is authoritative for
  *         B/C; this block is primarily Config-A's driver.
  *
- * v2.98 — Doc truth contracts are the normal drift surface. linkedDocs and
+ * v2.98 - Doc truth contracts are the normal drift surface. linkedDocs and
  *         doc_code_couplings remain legacy diagnostics only; docs drift
  *         defaults to truth findings and legacy:true is explicit debug.
- * v2.97 — Dropped legacy doc-coupling action guidance. Coupling rows are
+ * v2.97 - Dropped legacy doc-coupling action guidance. Coupling rows are
  *         not truth findings (plan §1).
- * v2.96 — Replace conditional memory_discover guidance with structural fix:
+ * v2.96 - Replace conditional memory_discover guidance with structural fix:
  *         bootstrap now includes _methodCatalog (discoverMemoryTools({})) so
  *         agents have the memory_tools calling convention from turn one.
  *         Instruction updated to reference _methodCatalog directly.
  *         Superseded 2026-07-13: a real Config-B host persisted the expanded
  *         15.1KB hook output instead of injecting it. Bootstrap now carries a
  *         compact discovery bridge; memory_discover({}) owns the full catalog.
- * v2.95 — Drop `augments` from JIT directive verdict list per plan §5 default
+ * v2.95 - Drop `augments` from JIT directive verdict list per plan §5 default
  *         (augments downgrades to ambient via the parallel recall gate, not
  *         the directive lane). See jit-knowledge-injector.md §5 decision note.
- * v2.94 — Add JIT directive teaching (docs/development/jit-knowledge-injector.md §2.3).
+ * v2.94 - Add JIT directive teaching (docs/development/jit-knowledge-injector.md §2.3).
  *
- * Code mode permanent — all memory operations via memory_tools sandbox.
+ * Code mode permanent - all memory operations via memory_tools sandbox.
  *        memory_add, file_context etc. are now mnemonik.* methods, not standalone tools.
  *
  * Zero-cooperation rewrite. Context auto-loads if session_bootstrap is skipped.
  *        Session summaries are auto-saved if agent doesn't call mnemonik.memory_add().
- *        Instructions drastically simplified — the server handles the workflow now.
+ *        Instructions drastically simplified - the server handles the workflow now.
  *
  * Token-optimised rewrite (superseded by later instruction rewrites).
  */

package/src/jitDeliveryAck.ts

@@ -1,3 +1,4 @@
+import { ensureWindowsPrivateDirectorySync } from './runtimeSigners.js';
 import { createHash } from 'node:crypto';
 import {
   chmodSync,
@@ -81,6 +82,7 @@ function ensurePrivateDirectory(path: string): boolean {
   if (!path) return false;
   try {
     if (existsSync(path) && lstatSync(path).isSymbolicLink()) return false;
+    ensureWindowsPrivateDirectorySync(path);
     mkdirSync(path, { recursive: true, mode: 0o700 });
     chmodSync(path, 0o700);
     return lstatSync(path).isDirectory() && !lstatSync(path).isSymbolicLink();

package/src/projectIdentityFile.ts

@@ -0,0 +1,100 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { RepositoryFingerprint } from './repositoryFingerprint.js';
+
+const CANONICAL_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+export const isCanonicalUuid = (value: unknown): value is string =>
+  typeof value === 'string' && CANONICAL_UUID.test(value);
+const IDENTITY_KEYS = new Set([
+  'schemaVersion',
+  'projectId',
+  'projectName',
+  'repositoryFingerprint',
+]);
+const FINGERPRINT_KEYS = new Set(['algorithmVersion', 'hash']);
+
+export interface ProjectIdentityFile {
+  schemaVersion: 1;
+  projectId: string;
+  projectName?: string;
+  repositoryFingerprint?: RepositoryFingerprint;
+}
+
+export type IdentityFileResult =
+  | { kind: 'ok'; identity: ProjectIdentityFile }
+  | { kind: 'unknown_version'; version: unknown }
+  | { kind: 'malformed'; detail: string }
+  | { kind: 'absent' };
+
+export function parseIdentityFile(text: string): Exclude<IdentityFileResult, { kind: 'absent' }> {
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    return { kind: 'malformed', detail: `unparseable JSON: ${(error as Error).message}` };
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return { kind: 'malformed', detail: 'identity file must contain a JSON object' };
+  }
+  const record = value as Record<string, unknown>;
+  if (record.schemaVersion !== 1) {
+    return { kind: 'unknown_version', version: record.schemaVersion };
+  }
+  const unknownKey = Object.keys(record).find((key) => !IDENTITY_KEYS.has(key));
+  if (unknownKey) return { kind: 'malformed', detail: `unknown key "${unknownKey}"` };
+  if (!isCanonicalUuid(record.projectId)) {
+    return { kind: 'malformed', detail: '"projectId" must be a canonical RFC 4122 UUID string' };
+  }
+  if ('projectName' in record && typeof record.projectName !== 'string') {
+    return { kind: 'malformed', detail: '"projectName" must be a string when present' };
+  }
+  if (
+    'repositoryFingerprint' in record &&
+    (!record.repositoryFingerprint ||
+      typeof record.repositoryFingerprint !== 'object' ||
+      Array.isArray(record.repositoryFingerprint))
+  ) {
+    return { kind: 'malformed', detail: '"repositoryFingerprint" must be an object when present' };
+  }
+  const fingerprint = record.repositoryFingerprint as Record<string, unknown> | undefined;
+  const unknownFingerprintKey = fingerprint
+    ? Object.keys(fingerprint).find((key) => !FINGERPRINT_KEYS.has(key))
+    : undefined;
+  if (unknownFingerprintKey) {
+    return {
+      kind: 'malformed',
+      detail: `unknown repositoryFingerprint key "${unknownFingerprintKey}"`,
+    };
+  }
+  if (fingerprint && (fingerprint.algorithmVersion !== 1 || typeof fingerprint.hash !== 'string')) {
+    return {
+      kind: 'malformed',
+      detail: '"repositoryFingerprint" must contain algorithmVersion 1 and a string hash',
+    };
+  }
+  const repositoryFingerprint: RepositoryFingerprint | undefined = fingerprint
+    ? { algorithmVersion: 1, hash: fingerprint.hash as string }
+    : undefined;
+  return {
+    kind: 'ok',
+    identity: {
+      schemaVersion: 1,
+      projectId: record.projectId,
+      ...(record.projectName === undefined ? {} : { projectName: record.projectName as string }),
+      ...(repositoryFingerprint ? { repositoryFingerprint } : {}),
+    },
+  };
+}
+
+export async function readIdentityFile(dir: string): Promise<IdentityFileResult> {
+  const path = join(dir, '.mnemonik.json');
+  try {
+    const stat = await lstat(path);
+    if (stat.isSymbolicLink()) return { kind: 'malformed', detail: 'symlink' };
+    if (!stat.isFile()) return { kind: 'malformed', detail: 'identity path is not a regular file' };
+    return parseIdentityFile(await readFile(path, 'utf8'));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { kind: 'absent' };
+    return { kind: 'malformed', detail: `cannot read identity file: ${(error as Error).message}` };
+  }
+}

package/src/projectSetupHandoff.ts

@@ -0,0 +1,275 @@
+import { protectWindowsDirectory } from './runtimeSigners.js';
+import { execFile } from 'node:child_process';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readdir, realpath, rename, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, relative } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { RuntimeReader, hash } from './runtimeReader.js';
+
+export const PROJECT_SETUP_MANUAL =
+  'Mnemonik project setup needs attention; ask the person to run `mnemonik project init` in this folder.';
+const words = (value: unknown): string =>
+  typeof value === 'string' && /^[a-z][a-z0-9_]{0,79}$/.test(value)
+    ? value.replaceAll('_', ' ')
+    : 'needs attention';
+export function projectSetupActions(value: unknown): string {
+  return Array.isArray(value) ? value.slice(0, 20).map(words).join(', ') : 'retry, cancel';
+}
+export interface ProjectSetupDiagnostic {
+  requestId?: string;
+  outcome: 'done' | 'ACTION_REQUIRED' | 'failed';
+  time: string;
+  rootHash: string | null;
+  action: string;
+  reason?: string;
+}
+const record = (value: unknown): value is Record<string, unknown> =>
+  !!value && typeof value === 'object' && !Array.isArray(value);
+/** Parse the native tool response, never tool arguments or agent-authored command fields. */
+export function setupResponse(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value === 'string') {
+    if (value.length > 64 * 1024) return;
+    try {
+      value = JSON.parse(value);
+    } catch {
+      return;
+    }
+  }
+  if (!record(value)) return;
+  if (record(value.structuredContent)) value = value.structuredContent;
+  else {
+    // Claude supplies the server's tool_response directly, not model-authored text.
+    // Accept only the server envelope; no command/path extensions cross this boundary.
+    const keys = ['status', 'state', 'allowedActions', 'requestId', 'expiresAt'];
+    const envelope = value;
+    if (
+      !keys.every((key) => Object.hasOwn(envelope, key)) ||
+      Object.keys(value).some((key) => ![...keys, 'manualAction'].includes(key)) ||
+      typeof value.state !== 'string' ||
+      !Array.isArray(value.allowedActions) ||
+      !value.allowedActions.every((action) => typeof action === 'string') ||
+      typeof value.requestId !== 'string' ||
+      !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
+        value.requestId
+      ) ||
+      typeof value.expiresAt !== 'string' ||
+      !Number.isFinite(Date.parse(value.expiresAt)) ||
+      (Object.hasOwn(value, 'manualAction') && typeof value.manualAction !== 'string')
+    )
+      return;
+  }
+  if (record(value) && value.status === 'project_setup_required') return value;
+  return;
+}
+async function privateDirectory(path: string, session: string): Promise<void> {
+  const created = await mkdir(path, { recursive: true, mode: 0o700 });
+  const st = await lstat(path);
+  if (
+    !st.isDirectory() ||
+    st.isSymbolicLink() ||
+    (process.getuid && (st.uid !== process.getuid() || st.mode & 0o077))
+  )
+    throw new Error('diagnostic_unavailable');
+  if (process.platform === 'win32') {
+    await protectWindowsDirectory(path, created !== undefined, undefined, session);
+  }
+}
+async function readPrivate(path: string): Promise<string> {
+  const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const st = await file.stat();
+    if (
+      !st.isFile() ||
+      st.size > 64 * 1024 ||
+      (process.getuid && (st.uid !== process.getuid() || st.mode & 0o077))
+    )
+      throw new Error('diagnostic_unavailable');
+    return await file.readFile('utf8');
+  } finally {
+    await file.close();
+  }
+}
+async function writeDiagnostic(path: string, value: ProjectSetupDiagnostic): Promise<void> {
+  await privateDirectory(dirname(dirname(path)), dirname(path));
+  await privateDirectory(dirname(path), dirname(path));
+  const temp = `${path}.${randomUUID()}`;
+  try {
+    const file = await open(temp, 'wx', 0o600);
+    try {
+      await file.writeFile(JSON.stringify(value) + '\n');
+    } finally {
+      await file.close();
+    }
+    await rename(temp, path);
+  } finally {
+    await rm(temp, { force: true });
+  }
+}
+
+export async function handoffProjectSetup(input: {
+  response: unknown;
+  cwd: string | undefined;
+  host: 'claude_code' | 'cursor' | 'grok';
+  hostSessionId: string;
+  stateFile: string;
+  stateDir: string;
+  familyId: string | undefined;
+}): Promise<string | undefined> {
+  const response = setupResponse(input.response);
+  if (!response) return;
+  let root: string | undefined;
+  let action = PROJECT_SETUP_MANUAL;
+  let outcome: ProjectSetupDiagnostic['outcome'] = 'failed';
+  let reason = 'manual_setup_required';
+  const requestId =
+    typeof response.requestId === 'string' && response.requestId.length <= 4096
+      ? response.requestId
+      : undefined;
+  try {
+    if (!input.cwd) throw new Error('safe_cwd_unavailable');
+    // The binding receipt is private local state. No path from the response is read.
+    const cache = JSON.parse(
+      await readPrivate(join(dirname(input.stateFile), 'bound-context.json'))
+    );
+    const [, family, body] = JSON.parse(cache.key);
+    if (
+      !input.familyId ||
+      family !== input.familyId ||
+      body.host !== input.host ||
+      body.hostSessionId !== input.hostSessionId ||
+      cache.expiresAt <= Date.now() ||
+      !cache.canonicalRoot
+    )
+      throw new Error('bound_context_unavailable');
+    root = await realpath(cache.canonicalRoot);
+    const { findProjectIdentityDetailed } = await import('./hookRuntime.js');
+    const identity = await findProjectIdentityDetailed(await realpath(input.cwd));
+    if (identity.kind === 'git_unavailable' || root !== (await realpath(identity.root)))
+      throw new Error('bound_root_changed');
+    if (!requestId) throw new Error('manual_setup_required');
+    const runtime = await new RuntimeReader(input.stateDir).verifyRuntime('cli').catch(() => {
+      throw new Error('verified_cli_runtime_unavailable');
+    });
+    const bin = join(dirname(runtime.entry), 'bin.js');
+    if (!runtime.manifest.files[relative(runtime.directory, bin).replaceAll('\\', '/')])
+      throw new Error('verified_cli_bin_missing');
+    const result = await new Promise<unknown>((resolve, reject) => {
+      const child = execFile(
+        process.execPath,
+        [bin, 'project', 'ensure', '--agent', '--json'],
+        {
+          cwd: root,
+          shell: false,
+          timeout: 30_000,
+          killSignal: 'SIGKILL',
+          maxBuffer: 64 * 1024,
+          // Runtime injection variables and repository/PATH executables are not inherited.
+          env: Object.fromEntries(
+            [
+              'HOME',
+              'USERPROFILE',
+              'LOCALAPPDATA',
+              'XDG_STATE_HOME',
+              'MNEMONIK_STATE_DIR',
+              'MNEMONIK_SERVER',
+              'MNEMONIK_API_RESOURCE',
+              'MNEMONIK_OAUTH_ISSUER',
+              'SYSTEMROOT',
+              'TEMP',
+              'TMP',
+              'TMPDIR',
+            ].flatMap((key) => (process.env[key] === undefined ? [] : [[key, process.env[key]]]))
+          ),
+        },
+        (error, stdout) => {
+          if (error && (error.killed || error.code !== 3))
+            return reject(new Error('helper_failed'));
+          try {
+            resolve(JSON.parse(stdout));
+          } catch {
+            reject(new Error('helper_invalid_json'));
+          }
+        }
+      );
+      child.stdin?.on('error', () => {});
+      child.stdin?.end(JSON.stringify({ requestId }));
+    });
+    if (!record(result)) throw new Error('helper_invalid_json');
+    if (result.status === 'done') {
+      outcome = 'done';
+      reason = 'complete';
+      action = 'Mnemonik project setup is complete; call session_bootstrap again.';
+    } else if (
+      ['ACTION_REQUIRED', 'action_required', 'project_setup_required'].includes(
+        String(result.status)
+      )
+    ) {
+      outcome = 'ACTION_REQUIRED';
+      reason = 'choice_required';
+      action =
+        result.action === 'mnemonik auth renew' ||
+        (Array.isArray(result.allowedActions) &&
+          result.allowedActions.includes('mnemonik auth renew'))
+          ? 'mnemonik auth renew'
+          : result.allowedActions
+            ? `Mnemonik project setup needs attention; allowed actions: ${projectSetupActions(result.allowedActions)}.`
+            : PROJECT_SETUP_MANUAL;
+    } else throw new Error('helper_invalid_json');
+  } catch (error) {
+    const code = error instanceof Error ? error.message : '';
+    reason = /^[a-z_]+$/.test(code) ? code : 'helper_unavailable';
+    process.stderr.write(`mnemonik-hook: project setup ${reason}; manual action required\n`);
+  }
+  try {
+    await writeDiagnostic(input.stateFile, {
+      requestId,
+      outcome,
+      time: new Date().toISOString(),
+      rootHash: root ? hash(root) : input.cwd ? hash(await realpath(input.cwd)) : null,
+      action,
+      reason,
+    });
+  } catch {
+    process.stderr.write('mnemonik-hook: project setup diagnostic unavailable\n');
+  }
+  return action;
+}
+
+/** Both doctor and status consume private per-session outcomes, scoped by root hash. */
+export async function pendingProjectSetup(root: string): Promise<ProjectSetupDiagnostic[]> {
+  const rootHash = hash(await realpath(root));
+  const results: ProjectSetupDiagnostic[] = [];
+  const uid = process.getuid?.() ?? 'user';
+  for (const host of ['credit', 'cursor', 'grok']) {
+    const directory = join(tmpdir(), `mnemonik-${host}-${uid}`);
+    try {
+      const stat = await lstat(directory);
+      if (stat.isSymbolicLink() || !stat.isDirectory()) continue;
+      for (const name of await readdir(directory)) {
+        if (!/^[a-f0-9]{64}$/.test(name)) continue;
+        try {
+          if ((await lstat(join(directory, name))).isSymbolicLink()) continue;
+          const diagnostic = JSON.parse(
+            await readPrivate(join(directory, name, 'project-setup.json'))
+          );
+          if (
+            (diagnostic.rootHash === rootHash || diagnostic.rootHash === null) &&
+            ['done', 'ACTION_REQUIRED', 'failed'].includes(diagnostic.outcome) &&
+            typeof diagnostic.action === 'string' &&
+            diagnostic.action.length < 2000 &&
+            Date.now() - Date.parse(diagnostic.time) < 24 * 60 * 60 * 1000
+          )
+            results.push(diagnostic);
+        } catch {
+          /* An incomplete or removed session is not a pending action. */
+        }
+      }
+    } catch {
+      /* Host has no local sessions. */
+    }
+  }
+  // A later completion supersedes stale actions from another session in this root.
+  results.sort((a, b) => Date.parse(b.time) - Date.parse(a.time));
+  return results[0]?.outcome === 'done' ? [] : results.slice(0, 1);
+}

package/src/protectedPaths.ts

@@ -0,0 +1,88 @@
+import { homedir } from 'node:os';
+import { posix, win32, type PlatformPath } from 'node:path';
+
+type Platform = NodeJS.Platform;
+
+function pathsFor(platform: Platform): PlatformPath {
+  return platform === 'win32' ? win32 : posix;
+}
+
+/** Local state and credential locations that Mnemonik must never scan. */
+export function protectedLocalPaths(
+  platform: Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+  home: string = homedir()
+): string[] {
+  const path = pathsFor(platform);
+  const localAppData = env.LOCALAPPDATA || win32.join(home, 'AppData', 'Local');
+  const appData = env.APPDATA || win32.join(home, 'AppData', 'Roaming');
+  const state =
+    env.MNEMONIK_STATE_DIR ||
+    (platform === 'win32'
+      ? win32.join(localAppData, 'Mnemonik')
+      : platform === 'darwin'
+        ? posix.join(home, 'Library', 'Application Support', 'Mnemonik')
+        : posix.join(env.XDG_STATE_HOME || posix.join(home, '.local', 'state'), 'mnemonik'));
+  const common = [
+    state,
+    path.join(home, '.mnemonik'),
+    path.join(home, '.claude', '.credentials.json'),
+    path.join(home, '.codex', 'auth.json'),
+    path.join(home, '.cursor', 'mcp.json'),
+    path.join(home, '.grok', 'mcp_credentials.json'),
+  ];
+  const osPaths =
+    platform === 'darwin'
+      ? [path.join(home, 'Library', 'Keychains')]
+      : platform === 'win32'
+        ? [
+            win32.join(appData, 'Microsoft', 'Credentials'),
+            win32.join(localAppData, 'Microsoft', 'Credentials'),
+            win32.join(appData, 'Microsoft', 'Protect'),
+          ]
+        : [
+            path.join(home, '.local', 'share', 'keyrings'),
+            path.join(home, '.gnupg'),
+            path.join(home, '.ssh'),
+            path.join(home, '.aws'),
+            path.join(home, '.config', 'gcloud'),
+            path.join(home, '.docker', 'config.json'),
+            path.join(home, '.npmrc'),
+            path.join(home, '.netrc'),
+            path.join(home, '.pypirc'),
+          ];
+  return [...new Set([...common, ...osPaths])];
+}
+
+function comparable(value: string, platform: Platform): string {
+  const path = pathsFor(platform);
+  const normalized = path.resolve(value);
+  return platform === 'win32' || platform === 'darwin' ? normalized.toLowerCase() : normalized;
+}
+
+/** True when candidate is the protected path itself or lies below it. */
+export function isProtectedLocalPath(
+  candidate: string,
+  protectedPaths: readonly string[] = protectedLocalPaths(),
+  platform: Platform = process.platform
+): boolean {
+  const path = pathsFor(platform);
+  const target = comparable(candidate, platform);
+  return protectedPaths.some((protectedPath) => {
+    const parent = comparable(protectedPath, platform);
+    const relative = path.relative(parent, target);
+    return (
+      relative === '' ||
+      (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative))
+    );
+  });
+}
+
+/** Protected paths equal to or below root, for consent auto-exclusions. */
+export function protectedPathsWithinRoot(
+  root: string,
+  protectedPaths: readonly string[] = protectedLocalPaths(),
+  platform: Platform = process.platform
+): string[] {
+  return protectedPaths.filter((candidate) => isProtectedLocalPath(candidate, [root], platform));
+}