flowviant 0.117.0 → 0.124.1

package/bin/lib/claudeSessions.mjs

@@ -111,6 +111,26 @@ export function titleForSession(cwd, sessionId) {
   return null;
 }
 
+/** Native user UUIDs are delivery evidence after a crash before the replay
+ * receipt reached the API. Unknown/unreadable is null, never an empty claim. */
+export function messageIdsForSession(cwd, sessionId) {
+  if (!cwd || !CLAUDE_SESSION_RE.test(sessionId ?? '')) return null;
+  const dirs = [String(cwd)];
+  try { const real = realpathSync(cwd); if (real !== cwd) dirs.push(real); } catch { /* gone */ }
+  for (const dir of dirs) {
+    const file = join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), 'projects', claudeProjectDir(dir), `${sessionId}.jsonl`);
+    try {
+      if (statSync(file).size > 64 * 1024 * 1024) continue;
+      const ids = new Set();
+      for (const line of readFileSync(file, 'utf8').split('\n')) {
+        try { const row = JSON.parse(line); if (row.type === 'user' && typeof row.uuid === 'string') ids.add(row.uuid); } catch { /* torn tail */ }
+      }
+      return ids;
+    } catch { /* try real cwd */ }
+  }
+  return null;
+}
+
 /**
  * THE DIRECTORY CLAUDE CODE FILES A CWD'S TRANSCRIPTS UNDER — its own rule,
  * copied exactly (2.1.281): every character that is not an ASCII letter or

package/bin/lib/claudeStream.mjs

@@ -93,7 +93,16 @@ export function handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, app
     emit(a.label + '\n');
     onActivity?.(a);
   };
-  if (ev.type === 'assistant' && Array.isArray(ev.message?.content)) {
+  if (ev.type === 'stream_event') {
+    // Partial messages announce reasoning before the completed assistant
+    // block. Relay only that measured start here: text and tool inputs still
+    // come from the complete blocks below, once, with their full contents.
+    const block = ev.event?.content_block;
+    if (ev.event?.type === 'content_block_start' &&
+        (block?.type === 'thinking' || block?.type === 'redacted_thinking')) {
+      push({ kind: 'think', label: THINK_MARKER });
+    }
+  } else if (ev.type === 'assistant' && Array.isArray(ev.message?.content)) {
     // THE MODEL THAT ANSWERED (2026-09-29, turnModel.mjs) — the fallback for an
     // init that named none. The turn's own messages only: a subagent's carry
     // `parent_tool_use_id`, and its model is not the turn's.
@@ -141,9 +150,17 @@ export function handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, app
         // The STRUCTURED form of the same event, for the transcript's tool
         // cards — raw name + input, so the collector can keep what the
         // one-line humanizer drops (an Edit's counts, the plan's items).
-        onToolEvent?.(b.name, b.input || {});
+        onToolEvent?.(b.name, b.input || {}, { id: b.id });
       }
     }
+  } else if (ev.type === 'user' && Array.isArray(ev.message?.content)) {
+    for (const b of ev.message.content) {
+      if (b.type === 'tool_result') onToolEvent?.(null, {}, {
+        id: b.tool_use_id, result: true, isError: b.is_error === true,
+        output: typeof b.content === 'string' ? b.content : Array.isArray(b.content) ? b.content.slice(0, 8).filter(x => x?.type === 'text' && typeof x.text === 'string').map(x => x.text).join('\n') : '',
+        exitCode: ev.tool_use_result?.exit_code ?? ev.tool_use_result?.exitCode,
+      });
+    }
   } else if (ev.type === 'system' && ev.subtype === 'init') {
     // WHAT THIS MACHINE'S CLI CAN BE ASKED FOR BY NAME. The init event is the
     // CLI's OWN answer — it has already resolved personal skills, this repo's
@@ -177,6 +194,7 @@ export function handleStreamLine(line, { cwd, emit, onActivity, onToolEvent, app
         skills: Array.isArray(ev.skills) ? ev.skills.map(String) : undefined,
         sessionId: typeof ev.session_id === 'string' ? ev.session_id : undefined,
         mcpServers: Array.isArray(ev.mcp_servers) ? ev.mcp_servers : undefined,
+        tools: Array.isArray(ev.tools) ? ev.tools : undefined,
       });
     }
   } else if (ev.type === 'result') {

package/bin/lib/codexProjectRead.mjs

@@ -0,0 +1,63 @@
+/** Actual project files and Git history, with no host-wide read fallback.
+ * The CLI retains its provider/MCP login outside the tool sandbox. Shells
+ * receive neither that environment nor native image reads/shell snapshots.
+ */
+import { execFileSync } from 'node:child_process';
+import { lstatSync, readdirSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, dirname } from 'node:path';
+import { git } from './git.mjs';
+import { codexResearchHelper } from './codexResearch.mjs';
+import { unattendedEnv } from './noWindowEnv.mjs';
+
+export function projectReadBoundary({ cwd, knowledgeDir, env = process.env }) {
+  if (process.platform !== 'linux') throw new Error('Project-scoped Codex reads require Linux or WSL.');
+  if (!isAbsolute(cwd ?? '')) throw new Error('Project-scoped Codex reads require an absolute project directory.');
+  const helper = codexResearchHelper(env);
+  const version = execFileSync(helper, ['--version'], { encoding: 'utf8', timeout: 10000, env: unattendedEnv(env) }).match(/^codex-cli (\d+)\.(\d+)\.(\d+)/);
+  if (!version || version.slice(1).map(Number).reduce((n, v) => n * 1000 + v, 0) < 159002)
+    throw new Error('Project-scoped reads need Codex CLI 0.159.2 or newer. Update Codex before retrying.');
+  const project = realpathSync(cwd);
+  // Resolve both: linked worktrees have their own HEAD/index and shared
+  // objects/refs in the common directory. Never grant the parent checkout.
+  const gitOpts = { timeout: 10000, env: { PATH: env.PATH, HOME: '/nonexistent', GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null' } };
+  const local = realpathSync(git(['rev-parse', '--absolute-git-dir'], project, gitOpts));
+  const common = realpathSync(git(['rev-parse', '--path-format=absolute', '--git-common-dir'], project, gitOpts));
+  const paths = [project, local, common];
+  // Git directories also hold daemon login/thread/browser stores. They are
+  // not history. Mask non-Git directories, including other worktree stores.
+  const metadata = new Set(['HEAD', 'index', 'commondir', 'gitdir', 'config', 'config.worktree', 'objects', 'refs', 'logs', 'packed-refs', 'shallow', 'description', 'info', 'branches']);
+  const denied = [];
+  for (const dir of new Set([local, common])) {
+    for (const name of readdirSync(dir)) {
+      if (dir === common && name === 'worktrees' && local !== common) {
+        for (const sibling of readdirSync(join(common, name))) {
+          const path = join(common, name, sibling);
+          if (path !== local && path !== dirname(local)) denied.push(path);
+        }
+      } else if (!metadata.has(name) && lstatSync(join(dir, name)).isDirectory()) denied.push(join(dir, name));
+    }
+  }
+  if (knowledgeDir) paths.push(realpathSync(knowledgeDir));
+  return { paths: [...new Set(paths)], denied, helper };
+}
+
+export function projectReadFence({ paths, denied = [], helper }) {
+  const rules = { ':root': 'deny', ':minimal': 'read', [helper]: 'read' };
+  for (const path of paths) {
+    if (!isAbsolute(path) || path === '/') throw new Error('Invalid project read boundary.');
+    rules[path] = 'read';
+  }
+  for (const path of denied) rules[path] = 'deny';
+  const table = '{' + Object.entries(rules).map(([path, access]) => `${JSON.stringify(path)}=${JSON.stringify(access)}`).join(',') + '}';
+  return [
+    '-c', `permissions.flowviantproject.filesystem=${table}`,
+    '-c', 'permissions.flowviantproject.network.enabled=false',
+    '-c', 'default_permissions="flowviantproject"',
+    '-c', 'approval_policy="never"',
+    '-c', 'project_doc_max_bytes=0',
+    '-c', 'features.shell_snapshot=false', '-c', 'allow_login_shell=false',
+    '-c', 'shell_environment_policy.inherit="none"',
+    '-c', 'shell_environment_policy.set={PATH="/usr/bin:/bin",HOME="/nonexistent",GIT_CONFIG_NOSYSTEM="1",GIT_CONFIG_GLOBAL="/dev/null",GIT_PAGER="cat",BROWSER="none"}',
+    '--disable', 'view_image',
+  ];
+}

package/bin/lib/codexResearch.mjs

@@ -4,6 +4,7 @@
  * Web search is a CLI tool, not direct shell network access.
  */
 import { execFileSync } from 'node:child_process';
+import { codexHome } from './codexHome.mjs';
 import { git } from './git.mjs';
 import { ensureRealSubdir, realDirState } from './ownedDirs.mjs';
 import { closeSync, constants, copyFileSync, existsSync, fstatSync, openSync, readFileSync, readSync, lstatSync, mkdirSync, readdirSync, realpathSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
@@ -77,12 +78,16 @@ export function codexResearchHelper(env = process.env) {
  * in the shared fenced tail (sub-agents, browser, image generation, the
  * person's config and rules), with the web left on: it is this posture's tool.
  */
-export function researchFence({ cwd, helper }) {
+export function researchFence({ cwd, helper, generatedImages }) {
   if (process.platform !== 'linux' || !isAbsolute(cwd ?? '') || !isAbsolute(helper ?? ''))
     throw new Error('Isolated Codex research requires Linux or WSL and absolute sandbox paths.');
   const artifacts = join(cwd, '.flowviant/artifacts');
   const scratch = join(cwd, '.flowviant/tmp');
   const rules = { ':root': 'deny', ':minimal': 'read', [helper]: 'read', [cwd]: 'read', [artifacts]: 'write', [scratch]: 'write' };
+  if (generatedImages) {
+    if (!isAbsolute(generatedImages)) throw new Error('Generated image directory must be absolute.');
+    rules[generatedImages] = 'read';
+  }
   const table = '{' + Object.entries(rules).map(([path, access]) => `${JSON.stringify(path)}=${JSON.stringify(access)}`).join(',') + '}';
   return [
     '-c', `permissions.flowviantresearch.filesystem=${table}`,
@@ -93,7 +98,7 @@ export function researchFence({ cwd, helper }) {
     '-c', 'features.shell_snapshot=false', '-c', 'allow_login_shell=false',
     '-c', 'shell_environment_policy.inherit="none"',
     '-c', `shell_environment_policy.set={PATH="/usr/bin:/bin",HOME=${JSON.stringify(scratch)},TMPDIR=${JSON.stringify(scratch)},BROWSER="none"}`,
-    '--disable', 'view_image',
+    '--disable', 'view_image', // native host-file reads bypass the tool fence
     '--skip-git-repo-check',
   ];
 }
@@ -168,9 +173,17 @@ export async function runIsolatedResearch(opts, run, {
     const rewrite = (text) => typeof text === 'string'
       ? text.replaceAll(original, snapshot).replaceAll(opts.knowledgeDir || '\0', knowledge || '\0') : text;
     const intro = 'This fresh research turn uses an isolated read-only copy. Prior reports are available under .flowviant/artifacts/; previous CLI conversations are not resumed because they may contain host secrets. Git metadata, .env files, credential files, symlinks and personal CLI settings are omitted. Write the Markdown report only under .flowviant/artifacts/. Web search is available; shell networking is disabled. Use exec_command with shell=/bin/bash and login=false; personal shells are outside the fence.\n\n';
+    // Only native output pixels, never the surrounding login/config home.
+    let generatedImages;
+    if (opts.mcpEnv?.CODEX_HOME) {
+      const imageHome = realpathSync(codexHome({ ...process.env, ...opts.mcpEnv }));
+      if (!ensureRealSubdir(imageHome, 'generated_images'))
+        throw new Error('The native generated image directory is not a real directory.');
+      generatedImages = join(imageHome, 'generated_images');
+    }
     const result = await run({ ...opts, resume: false, resumeThreadId: null, resumeConversationId: null, cwd: snapshot, knowledgeDir: knowledge,
       prompt: intro + rewrite(opts.prompt), system: rewrite(opts.system),
-      researchIsolation: { cwd: snapshot, helper } });
+      researchIsolation: { cwd: snapshot, helper, generatedImages } });
     // Made, or found, real at publication too: every component checked again.
     if (!ensureRealSubdir(original, '.flowviant/artifacts'))
       throw new Error('The research artifact destination is not a real directory.');

package/bin/lib/commandSpecs.mjs

@@ -21,6 +21,12 @@
  */
 
 export const COMMANDS = [
+  {
+    name: 'maintenance', usesCheckout: false, hidden: true,
+    usage: 'flowviant maintenance <request|release> <token>',
+    summary: 'Hold new runs for a manual WSL restart; existing work finishes.',
+    group: 'manage',
+  },
   {
     name: 'start',
     usesCheckout: true,

package/bin/lib/credentials.mjs

@@ -15,7 +15,9 @@
  *   {
  *     fleetToken, projectId, mcpUrl,          // the LEGACY MIRROR
  *     projects: {                             // v2: every connected project
- *       [projectId]: { fleetToken, mcpUrl, name, repoRoot, savedAt }
+ *       [projectId]: { fleetToken, mcpUrl, name, repoRoot,
+ *                      repositories: { app: '/code/app', cli: '/code/cli' },
+ *                      repositoriesRegistered, savedAt }
  *     }
  *   }
  *
@@ -27,7 +29,7 @@
  * WHICH CREDENTIAL A START USES — resolution, in order:
  *   --fleet / FLOWVIANT_FLEET     the operator said, verbatim (config.mjs).
  *   --project <name|id>           an entry, named without a prompt.
- *   the entry BOUND to this repo  repoRoot recorded at login/confirm, compared
+ *   the entry BOUND to this repo  any named root recorded at login/confirm, compared
  *                                 by realpath — the no-ambiguity path.
  *   one unbound entry             served, with a one-time TTY confirm that
  *                                 binds it (headless keeps the old behaviour —
@@ -36,7 +38,7 @@
  *                                 stored project and asks (startProject.mjs), or — with
  *                                 no TTY — refuses in words that name them all.
  *
- * The repoRoot binding is a SAFETY line, not bookkeeping: serving project X
+ * Each repository binding is a SAFETY line, not bookkeeping: serving project X
  * from a repo that is not X's checkout materializes X's session worktrees and
  * decrypted env inside the wrong repository. Binding happens only at moments a
  * HUMAN was present (login, an answered confirm, an explicit pick) — never
@@ -46,7 +48,7 @@
 
 import { mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { printable } from './printable.mjs';
 import { connectedOn } from './credentialDate.mjs';
 import { terminalCommand } from './launchCommand.mjs';
@@ -101,6 +103,8 @@ export function listStoredProjects() {
       mcpUrl: e.mcpUrl ?? null,
       name: typeof e.name === 'string' && e.name ? e.name : null,
       repoRoot: typeof e.repoRoot === 'string' && e.repoRoot ? e.repoRoot : null,
+      repositories: storedRepositories(e),
+      repositoriesRegistered: e.repositoriesRegistered === true,
       savedAt: e.savedAt ?? null,
     });
   }
@@ -111,6 +115,7 @@ export function listStoredProjects() {
       mcpUrl: f.mcpUrl ?? null,
       name: null,
       repoRoot: null,
+      repositories: {},
       savedAt: null,
     });
   }
@@ -202,10 +207,11 @@ export function projectRowLabel(e, entries) {
 export function repoCollisions(entries) {
   const groups = [];
   for (const e of entries) {
-    if (!e?.repoRoot) continue;
-    const g = groups.find((x) => samePath(x.repoRoot, e.repoRoot));
-    if (g) g.entries.push(e);
-    else groups.push({ repoRoot: e.repoRoot, entries: [e] });
+    for (const repoRoot of Object.values(storedRepositories(e))) {
+      const g = groups.find((x) => samePath(x.repoRoot, repoRoot));
+      if (g) { if (!g.entries.includes(e)) g.entries.push(e); }
+      else groups.push({ repoRoot, entries: [e] });
+    }
   }
   return groups.filter((g) => g.entries.length > 1);
 }
@@ -228,7 +234,7 @@ export function repoCollisions(entries) {
  */
 export function boundElsewhere(entries, repoRoot, projectId) {
   if (!repoRoot) return [];
-  return entries.filter((e) => e.projectId !== projectId && samePath(e.repoRoot, repoRoot));
+  return entries.filter((e) => e.projectId !== projectId && isStoredRepo(e, repoRoot));
 }
 
 /**
@@ -313,17 +319,45 @@ function mutate(fn) {
   return f;
 }
 
+/** v2 repoRoot remains the primary mirror; v3 retains every named checkout. */
+function storedRepositories(e) {
+  const entries = e?.repositories && typeof e.repositories === 'object' && !Array.isArray(e.repositories)
+    ? Object.entries(e.repositories).filter(([name, root]) => /^[a-z0-9][a-z0-9_-]*$/.test(name) && typeof root === 'string' && root)
+    : [];
+  if (e?.repoRoot && !entries.some(([, root]) => samePath(root, e.repoRoot))) entries.push(['app', e.repoRoot]);
+  return Object.fromEntries(entries);
+}
+
+export function isStoredRepo(entry, repoRoot) {
+  return Boolean(repoRoot && Object.values(storedRepositories(entry)).some((root) => samePath(root, repoRoot)));
+}
+
+function bindEntry(entry, repoRoot, repositoryName, isPrimary = false) {
+  const repos = storedRepositories(entry);
+  const existing = Object.entries(repos).find(([, root]) => samePath(root, repoRoot));
+  const name = repositoryName ?? existing?.[0] ?? (Object.keys(repos).length ? basename(repoRoot).toLowerCase().replace(/[^a-z0-9_-]/g, '-') : 'app');
+  if (Object.hasOwn(repos, name) && !samePath(repos[name], repoRoot)) {
+    throw new Error(`Repository ${name} is already connected at ${repos[name]}.`);
+  }
+  // A settings rename keeps the path while replacing the old name.
+  if (existing && existing[0] !== name) delete repos[existing[0]];
+  entry.repositories = { ...repos, [name]: repoRoot };
+  if (!entry.repoRoot || isPrimary) entry.repoRoot = repoRoot;
+}
+
 /** A fresh login: upsert the entry AND point the legacy mirror at it. */
-export function saveLogin({ fleetToken, projectId, mcpUrl, name, repoRoot }) {
+export function saveLogin({ fleetToken, projectId, mcpUrl, name, repoRoot, repositoryName, isPrimary, repositoryBindings = [], repositoriesRegistered }) {
   mutate((f) => {
     f.projects[projectId] = {
       ...(f.projects[projectId] ?? {}),
       fleetToken,
       mcpUrl: mcpUrl ?? null,
       ...(safeName(name) ? { name: safeName(name) } : {}),
-      ...(repoRoot ? { repoRoot } : {}),
       savedAt: new Date().toISOString(),
+      ...(repositoriesRegistered !== undefined ? { repositoriesRegistered } : {}),
     };
+    for (const binding of repositoryBindings) bindEntry(f.projects[projectId], binding.repoRoot, binding.name, binding.isPrimary);
+    if (repoRoot) bindEntry(f.projects[projectId], repoRoot, repositoryName, isPrimary);
     f.fleetToken = fleetToken;
     f.projectId = projectId;
     f.mcpUrl = mcpUrl ?? null;
@@ -337,7 +371,7 @@ export function selectStoredProject(projectId, { bindRepoRoot } = {}) {
   mutate((f) => {
     const e = f.projects[projectId];
     if (!e) return;
-    if (bindRepoRoot) e.repoRoot = bindRepoRoot;
+    if (bindRepoRoot) bindEntry(e, bindRepoRoot);
     f.fleetToken = e.fleetToken;
     f.projectId = projectId;
     f.mcpUrl = e.mcpUrl ?? null;
@@ -397,10 +431,10 @@ export function forgetStoredProject(ref) {
   return { entry: gone };
 }
 
-export function bindStoredRepo(projectId, repoRoot) {
+export function bindStoredRepo(projectId, repoRoot, repositoryName) {
   if (!repoRoot) return;
   mutate((f) => {
-    if (f.projects[projectId]) f.projects[projectId].repoRoot = repoRoot;
+    if (f.projects[projectId]) bindEntry(f.projects[projectId], repoRoot, repositoryName);
   });
 }
 
@@ -454,15 +488,16 @@ export function resolveStoredCredential(argv = process.argv, cwd = process.cwd()
   const projectArg = i >= 0 ? argv[i + 1] : undefined;
   if (projectArg !== undefined) {
     const m = matchStoredProject(projectArg);
-    return m.entry ? { entry: m.entry, source: 'project-flag' } : { error: m.error };
+    const repoRoot = detectRepoRoot(cwd);
+    return m.entry ? { entry: isStoredRepo(m.entry, repoRoot) ? { ...m.entry, repoRoot } : m.entry, source: 'project-flag' } : { error: m.error };
   }
   const entries = listStoredProjects();
   if (entries.length === 0) return { none: true };
   const repoRoot = detectRepoRoot(cwd);
 
   if (repoRoot) {
-    const bound = entries.filter((e) => samePath(e.repoRoot, repoRoot));
-    if (bound.length === 1) return { entry: bound[0], source: 'repo', repoRoot };
+    const bound = entries.filter((e) => isStoredRepo(e, repoRoot));
+    if (bound.length === 1) return { entry: { ...bound[0], repoRoot }, source: 'repo', repoRoot };
     if (bound.length > 1) return { choices: bound, reason: 'multiple-bound', repoRoot };
   }
 

package/bin/lib/daemonLocks.mjs

@@ -22,12 +22,28 @@ import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-/** Every daemon lock's file name: `daemon-` + 12 hex of the credential's hash. */
+/** Every daemon lock's file name: `daemon-` + 12 hex of its identity hash. */
 export const DAEMON_LOCK_RE = /^daemon-[0-9a-f]{12}\.lock$/;
 
 /** Deliberately a HASH: a credential must never become a filename. */
 export function instanceLockPath(fleetToken, home = homedir()) {
-  const key = createHash('sha256').update(String(fleetToken || 'anon')).digest('hex').slice(0, 12);
+  const projectId = projectForCredential(fleetToken, home);
+  const key = createHash('sha256').update(projectId ? `project:${projectId}` : String(fleetToken || 'anon')).digest('hex').slice(0, 12);
+  return join(home, '.flowviant', `daemon-${key}.lock`);
+}
+
+/** Keep status, stop, draining and startup on the same project identity. */
+export function projectForCredential(token, home = homedir()) {
+  try {
+    const stored = JSON.parse(nodeFs.readFileSync(join(home, '.flowviant', 'credentials.json'), 'utf8'));
+    return Object.entries(stored.projects ?? {}).find(([, entry]) => entry?.fleetToken === token)?.[0] ??
+      (stored.fleetToken === token ? stored.projectId : null);
+  } catch { return null; }
+}
+
+/** An old daemon may still hold the credential-keyed lock. */
+export function legacyInstanceLockPath(token, home = homedir()) {
+  const key = createHash('sha256').update(String(token || 'anon')).digest('hex').slice(0, 12);
   return join(home, '.flowviant', `daemon-${key}.lock`);
 }
 
@@ -57,7 +73,9 @@ export function readLockFile(path, { fs = nodeFs } = {}) {
 
 /** The record in this credential's lock, or null. */
 export function readLockHolder(fleetToken) {
-  return readLockFile(instanceLockPath(fleetToken));
+  const current = readLockFile(instanceLockPath(fleetToken));
+  const legacy = readLockFile(legacyInstanceLockPath(fleetToken));
+  return current && legacy?.pid === current.pid && legacy.draining ? legacy : current ?? legacy;
 }
 
 /**
@@ -68,14 +86,16 @@ export function readLockHolder(fleetToken) {
  * neighbour in the same repo, `flowviant stop` sweeping the lot, uninstall
  * protecting the copy a live daemon runs from. An unreadable (or absent)
  * directory is not an error here, it is an empty machine. `fs` and `home` are
- * injectable for uninstall's test seams.
+ * injectable for uninstall's test seams. The manual WSL restart asks for
+ * `strict`: only a missing directory is empty; other scan failures throw.
  */
-export function listDaemonLocks({ fs = nodeFs, home = homedir() } = {}) {
+export function listDaemonLocks({ fs = nodeFs, home = homedir(), strict = false } = {}) {
   const dir = join(home, '.flowviant');
   let names;
   try {
     names = fs.readdirSync(dir);
-  } catch {
+  } catch (error) {
+    if (strict && error.code !== 'ENOENT') throw error;
     return [];
   }
   return names

package/bin/lib/desktopContract.mjs

@@ -64,6 +64,9 @@ export function desktopStatus({ entries = listStoredProjects(), runtimes = detec
         holder: liveState?.holder ?? null,
         // Measured by the daemon; null = unknown, never idle (see `busyOf`).
         busy: busyOf(liveState, nowMs),
+        maintenance: busyOf(liveState, nowMs) !== null && typeof liveState?.maintenance === 'string' ? liveState.maintenance : null,
+        maintenanceEpoch: busyOf(liveState, nowMs) !== null && typeof liveState?.maintenanceEpoch === 'string' ? liveState.maintenanceEpoch : null,
+        liveAgents: busyOf(liveState, nowMs) !== null && Number.isInteger(liveState?.liveAgents) && liveState.liveAgents >= 0 ? liveState.liveAgents : null,
         // What a standing-down daemon is finishing (`web → prod`), from its
         // lock's draining mark; null when it is not draining or unknown. A
         // daemon→desktop report field: an older tray ignores it.

package/bin/lib/discoveryContract.mjs

@@ -0,0 +1,19 @@
+/** A discovery contract for the person's CLI, never a server-side diagnosis. */
+export const REGRESSION_INVESTIGATION = `REGRESSION INVESTIGATION — for "this existed before and now is gone", restoration requests, and bugs that persist after Done:
+1. Keep the REQUESTED OUTCOME separate from a proposed cause. The runtime baseline names cwd, HEAD, execution base and dirty state; it does not prove you inspected relevant code. Reconcile differing or dirty baselines before relying on them.
+2. Before naming a cause, formula or restoration location, trace current rendering and data flow: locate the UI label/symbol, its render conditions and formatting, the calculation, its data provider, missing/loading inputs, and relevant tests. Reading tests is not running them; never claim tests passed merely because you read them. Do not run write-producing tests or builds under this read-only profile.
+3. Inspect available local Git history with supported plain readers: git log --oneline -- <relative-path>, git log -p --follow -- <relative-path>, git log -S delta -- <relative-path>, git show <commit>:<relative-path>, and relevant diffs. Compare the previous implementation with current code. Missing/shallow history or an unavailable deployed version limits the comparison; say exactly which comparison remains unverified.
+4. Explain only supported evidence. A surviving hidden display needs its render condition investigated, not an invented replacement formula. A missing input needs its provider/comparison data traced, not a claim that the display was deleted. A removed implementation needs a verified historical file/commit and a compatibility check against current code before proposing restoration.
+5. A board card marked Done is history, not proof that an implementation shipped or that the reported behavior works in the deployed version. In capture, dedupe with list_cards and list_staged; use find_cards/read_card for held or completed matches. Refine a pending/staged match in place. A recurrence after Done is new work with followUpOf, never proof of its cause. Scratch planning instead compares the supplied cards and live-agent context; it has no staging MCP.
+6. A failed read requires supported recovery before claiming repository discovery is unavailable. Preserve the actual failure and each attempted alternative; distinguish syntax refusal, permission denial, missing path/history and absent tool. Runtime outcomes are observations; model-authored path/line/commit citations and causal explanations remain separate claims. A request alone proves no successful read.
+7. In capture, still STAGE FIRST: if discovery remains unresolved, stage an investigation-first fix for the requested outcome, requiring reproduction and cause establishment before implementation. State unverified causes in assumed, explicit discovery limits and failures/attempts in the brief, and do not invent a formula or restoration path. Use optional grounding when the served staging tool advertises it; otherwise put requested outcome, observed code/history, discovery limits and recovery attempts in clearly separate description sections. Stage before asking the one remaining person-only question, and edit_staged after its answer rather than creating a twin. In scratch planning, retain that investigation-first ordering in the proposal; do not turn an unverified explanation into implementation instructions.`;
+
+export function discoveryGuide(runtime, lane) {
+  const readers = runtime === 'claude'
+    ? `Claude: scoped Read and Glob, in-workspace Grep, and approved plain shell readers (cat/head/ls/wc and git log/show/diff/rev-parse). The read guard rejects shell composition, expansions/globs and unsafe paths; quoted pipes and bracket Git paths can still be refused. Quotes/escaping do not bypass the guard. Prefer native Read/Grep/Glob after such a refusal. Replace git log -G 'delta|change' with separate plain git log -S delta and git log -S change calls. For a bracket working-tree path use native Read with the literal path; for history use a supported parent-relative Git path or a scoped commit diff and inspect the relevant entry. Never disable the guard or request unrestricted Bash.`
+    : runtime === 'codex'
+      ? `Codex: this profile uses a read-only sandbox with shell discovery such as cat, head, rg and plain Git readers; Claude's dedicated Read/Grep/Glob and read guard are not guaranteed here. Use only tools advertised this turn. No native web, subagents, browser/apps or unrestricted shell are granted. Read only the repository and explicitly supplied project knowledge.`
+      : `This runtime: use the native file/list/search readers actually advertised this turn. Shell availability is unverified and may be denied; do not claim all reading is blocked after one shell refusal. Keep the read-only profile.`;
+  return `DISCOVERY CAPABILITIES (${runtime}, ${lane}):\n${readers}\n` +
+    `Recovery order: use a cwd-relative path; use one plain reader rather than a composed command; use native Read/Grep/Glob where supported, or shell cat/head/rg where permitted; use git show <commit>:<relative-path> when a working-tree file is missing and history is available. If a utility is absent, switch to an advertised reader. Do not try to evade a secret/path denial. Re-read the actual result after each attempt. Preserve the first failure and subsequent recovery attempts, including an unresolved result; then state the remaining limit rather than asking the person to disable protections. ${lane === 'capture' ? 'Only the scoped Flowviant staging tools write records; never change repository files.' : 'Scratch planning has no Flowviant MCP; return a proposal only.'}`;
+}