@mnemonik/shared 7.112.1 → 7.112.2

package/src/projectSetupHandoff.ts

@@ -1,9 +1,11 @@
 import { protectWindowsDirectory } from './runtimeSigners.js';
-import { execFile } from 'node:child_process';
+import { spawn } 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 { basename, dirname, join, relative } from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { hookDeadlineMs } from './hookTimeouts.js';
 import { randomUUID } from 'node:crypto';
 import { RuntimeReader, hash } from './runtimeReader.js';
 
@@ -107,6 +109,186 @@ async function writeDiagnostic(path: string, value: ProjectSetupDiagnostic): Pro
   }
 }
 
+/** What the agent is told while `project ensure` is still running detached. */
+export const PROJECT_SETUP_RUNNING =
+  'Mnemonik project setup is still running; call session_bootstrap again in a few seconds.';
+
+/** The CLI helper's own bound, enforced by the detached supervisor below. */
+export const PROJECT_ENSURE_TIMEOUT_MS = 30_000;
+const RUNNING = Symbol('running');
+
+/**
+ * The detached supervisor: runs the verified CLI bin (argv[2], args after it)
+ * with the request on stdin under PROJECT_ENSURE_TIMEOUT_MS, then writes
+ * { code, killed, stdout } to argv[1] through a rename, so a reader sees a
+ * whole result or none. It outlives the hook process: the host may kill the
+ * hook at its timeout (5 s on Claude Code and Grok) while the ensure, which
+ * consumes a single-use setup request and writes .mnemonik.json, finishes.
+ */
+const SUPERVISOR = `
+const { execFile } = require('node:child_process');
+const { writeFileSync, renameSync } = require('node:fs');
+const [out, bin, ...args] = process.argv.slice(1);
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => (input += chunk));
+process.stdin.on('end', () => {
+  const child = execFile(
+    process.execPath,
+    [bin, ...args],
+    { shell: false, timeout: ${PROJECT_ENSURE_TIMEOUT_MS}, killSignal: 'SIGKILL', maxBuffer: 64 * 1024, env: process.env },
+    (error, stdout) => {
+      const result = { code: error ? (typeof error.code === 'number' ? error.code : null) : 0, killed: !!(error && error.killed), stdout: String(stdout) };
+      writeFileSync(out + '.tmp', JSON.stringify(result), { mode: 0o600 });
+      renameSync(out + '.tmp', out);
+    }
+  );
+  child.stdin.on('error', () => {});
+  child.stdin.end(input);
+});
+`;
+
+interface EnsureRun {
+  requestId: string;
+  root: string;
+  result: string;
+  startedAt: number;
+}
+
+/** A run older than this is no longer waited for (the helper's bound plus slack). */
+const RUN_STALE_MS = PROJECT_ENSURE_TIMEOUT_MS + 10_000;
+
+async function readResult(path: string): Promise<unknown | undefined> {
+  let raw: string;
+  try {
+    raw = await readPrivate(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  }
+  const result = JSON.parse(raw) as { code?: unknown; killed?: unknown; stdout?: unknown };
+  // Exit 3 is the helper's "action required", with its JSON on stdout.
+  if (result.killed || (result.code !== 0 && result.code !== 3)) throw new Error('helper_failed');
+  try {
+    return JSON.parse(String(result.stdout));
+  } catch {
+    throw new Error('helper_invalid_json');
+  }
+}
+
+async function waitForResult(path: string, waitMs: number): Promise<unknown | typeof RUNNING> {
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    const result = await readResult(path);
+    if (result !== undefined) return result;
+    if (Date.now() >= deadline) return RUNNING;
+    await new Promise((resolve) => setTimeout(resolve, Math.min(50, deadline - Date.now())));
+  }
+}
+
+/**
+ * Run `project ensure` for this setup request, waiting at most `waitMs`.
+ *
+ * The helper runs detached (under SUPERVISOR) and its result lands in the
+ * session's private directory, so a hook the host kills at its timeout loses
+ * neither the setup nor its outcome. One run per session: while it is
+ * running, a later handoff (the agent calls session_bootstrap again and gets a
+ * fresh request id) waits for that run instead of starting another; a
+ * finished run whose setup completed answers for the new request too.
+ */
+async function runEnsure(options: {
+  bin: string;
+  root: string;
+  requestId: string;
+  directory: string;
+  waitMs: number;
+}): Promise<unknown | typeof RUNNING> {
+  await privateDirectory(dirname(options.directory), options.directory);
+  await privateDirectory(options.directory, options.directory);
+  const runFile = join(options.directory, 'project-setup-run.json');
+  let previous: EnsureRun | undefined;
+  try {
+    previous = JSON.parse(await readPrivate(runFile)) as EnsureRun;
+  } catch {
+    previous = undefined;
+  }
+  if (previous && previous.root === options.root && typeof previous.result === 'string') {
+    const result = join(options.directory, basename(previous.result));
+    const finished = await readResult(result).catch(() => ({ status: 'failed' }));
+    if (finished === undefined && Date.now() - previous.startedAt < RUN_STALE_MS) {
+      const outcome = await waitForResult(result, options.waitMs);
+      if (outcome !== RUNNING) await rm(runFile, { force: true });
+      return outcome;
+    }
+    await rm(runFile, { force: true });
+    await rm(result, { force: true });
+    if (record(finished) && finished.status === 'done') return finished;
+  }
+  const result = join(options.directory, `project-setup-${randomUUID()}.result.json`);
+  const run: EnsureRun = {
+    requestId: options.requestId,
+    root: options.root,
+    result: basename(result),
+    startedAt: Date.now(),
+  };
+  await writeFileAtomic(runFile, JSON.stringify(run));
+  const child = spawn(
+    process.execPath,
+    ['-e', SUPERVISOR, result, options.bin, 'project', 'ensure', '--agent', '--json'],
+    {
+      cwd: options.root,
+      shell: false,
+      detached: true,
+      windowsHide: true,
+      stdio: ['pipe', 'ignore', 'ignore'],
+      // 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]]]))
+      ),
+    }
+  );
+  const spawnFailed = new Promise<never>((_, reject) =>
+    child.once('error', () => reject(new Error('helper_failed')))
+  );
+  child.stdin?.on('error', () => {});
+  child.stdin?.end(JSON.stringify({ requestId: options.requestId }));
+  child.unref();
+  const outcome = await Promise.race([waitForResult(result, options.waitMs), spawnFailed]);
+  if (outcome !== RUNNING) {
+    await rm(runFile, { force: true });
+    await rm(result, { force: true });
+  }
+  return outcome;
+}
+
+async function writeFileAtomic(path: string, data: string): Promise<void> {
+  const temp = `${path}.${randomUUID()}`;
+  try {
+    const file = await open(temp, 'wx', 0o600);
+    try {
+      await file.writeFile(data);
+    } finally {
+      await file.close();
+    }
+    await rename(temp, path);
+  } finally {
+    await rm(temp, { force: true });
+  }
+}
+
 export async function handoffProjectSetup(input: {
   response: unknown;
   cwd: string | undefined;
@@ -115,6 +297,11 @@ export async function handoffProjectSetup(input: {
   stateFile: string;
   stateDir: string;
   familyId: string | undefined;
+  /**
+   * How long this hook may wait for `project ensure`; defaults to what the
+   * host's hook timeout leaves (hookDeadlineMs less the time since start).
+   */
+  waitMs?: number;
 }): Promise<string | undefined> {
   const response = setupResponse(input.response);
   if (!response) return;
@@ -154,47 +341,20 @@ export async function handoffProjectSetup(input: {
     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 }));
+    const result = await runEnsure({
+      bin,
+      root,
+      requestId,
+      directory: dirname(input.stateFile),
+      waitMs: input.waitMs ?? Math.max(0, hookDeadlineMs(input.host) - performance.now()),
     });
+    if (result === RUNNING) {
+      // Still running detached (runEnsure); the next session_bootstrap's hook
+      // waits for it or collects its result, and never starts a second one.
+      return PROJECT_SETUP_RUNNING;
+    }
+    // The helper may have written this folder's identity.
+    (await import('./hookRuntime.js')).clearProjectIdentityCache();
     if (!record(result)) throw new Error('helper_invalid_json');
     if (result.status === 'done') {
       outcome = 'done';

package/src/usageGuide.ts

@@ -21,7 +21,7 @@ session_bootstrap -> memory_search -> file_context -> [work] -> memory_add -> me
 
 ### Session start
 - session_bootstrap: loads context, policies, pending tasks (call once, first thing)
-- memory_search: search by task domain; set workflowContext (feature_implementation, debugging, exploration, policy_review)
+- memory_search: search by task domain
 - projects: resolve project IDs if context unclear
 - policy: review safety rules
 
@@ -65,7 +65,6 @@ Never tell the user significant work is done without calling memory_add first in
 ## Memory search tips
 
 - Query should include task intent + key entities
-- Set workflowContext when you know the phase
 - Use currentFile to boost file-linked memories
 - Use filterOnly:true only for narrow filters (no embedding, requires >=1 filter)
 

package/tests/projectIdentity.test.ts

@@ -71,6 +71,15 @@ test('only a selected regular JSON object without a project id is treated as una
       await writeFile(path, text);
       assert.notEqual((await readIdentityFile(root, { selectedRoot: true })).kind, 'absent');
     }
+    for (const text of [
+      '{"schemaVersion":2,"futureIdentity":"proj_future_0001"}',
+      '{"schemaVersion":0}',
+      '{"schemaVersion":null}',
+      '{"schemaVersion":"1"}',
+    ]) {
+      await writeFile(path, text);
+      assert.equal((await readIdentityFile(root, { selectedRoot: true })).kind, 'unknown_version');
+    }
     if (process.platform !== 'win32') {
       await rm(path);
       const target = join(root, 'other.json');