machine-bridge-mcp 0.16.2 → 0.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "machine-bridge-mcp",
-  "version": "0.16.2",
+  "version": "0.17.1",
   "description": "Cross-client MCP bridge for local agent context, structured browser and application automation, files, Git, processes, resources, and durable jobs over stdio or OAuth relay.",
   "type": "module",
   "license": "MIT",
@@ -40,10 +40,10 @@
     "version": "node scripts/sync-worker-version.mjs && git add package.json package-lock.json src/worker/index.ts browser-extension/manifest.json",
     "prepack": "npm run version:check && npm run privacy:check && npm run release-impact:check",
     "prepublishOnly": "npm run check && npm run version:check && npm run release:check",
-    "worker:types": "wrangler types src/worker/worker-configuration.d.ts",
+    "worker:types": "node scripts/generate-worker-types.mjs",
     "typecheck": "npm run worker:types && tsc -p tsconfig.json --noEmit",
     "syntax": "node scripts/syntax-check.mjs",
-    "check": "npm run privacy:check && npm run privacy:test && npm run release-impact:check && npm run release-impact:test && npm run release-state:test && npm run release-ci:test && npm run network-retry:test && npm run relay:test && npm run secure-file:test && npm run architecture:test && npm run policy:test && npm run policy-docs:check && npm run runtime-infrastructure:test && npm run runtime-handlers:test && npm run cli-entrypoint:test && npm run lifecycle:test && npm run logging-structure:test && npm run coverage:test && npm run worker-runtime-infrastructure:test && npm run typecheck && npm run syntax && npm run process-lock:test && npm run service-lifecycle:test && npm run service-platform:test && npm run catalog:test && npm run agent-context:test && npm run capability-ranking:test && npm run browser-command:test && npm run browser-devtools-input:test && npm run browser-service-worker:test && npm run browser-page-automation:test && npm run browser-bridge:test && npm run app-automation:test && npm run self-test && npm run atomic-fs:test && npm run package:test && npm run ssh-key:test && npm run full-access:test && npm run managed-jobs:test && npm run stdio:integration-test && npm run worker:integration-test",
+    "check": "npm run privacy:check && npm run privacy:test && npm run release-impact:check && npm run release-impact:test && npm run release-state:test && npm run release-ci:test && npm run network-retry:test && npm run relay:test && npm run secure-file:test && npm run architecture:test && npm run markdown:test && npm run project-metadata:test && npm run numbers:test && npm run records:test && npm run state-inventory:test && npm run commit-message:test && npm run policy:test && npm run policy-docs:check && npm run tool-docs:check && npm run runtime-infrastructure:test && npm run runtime-handlers:test && npm run cli-entrypoint:test && npm run lifecycle:test && npm run logging-structure:test && npm run coverage:test && npm run worker-runtime-infrastructure:test && npm run typecheck && npm run syntax && npm run process-lock:test && npm run service-lifecycle:test && npm run service-platform:test && npm run catalog:test && npm run agent-context:test && npm run capability-ranking:test && npm run browser-command:test && npm run browser-devtools-input:test && npm run browser-service-worker:test && npm run browser-page-automation:test && npm run browser-bridge:test && npm run app-automation:test && npm run self-test && npm run atomic-fs:test && npm run package:test && npm run ssh-key:test && npm run full-access:test && npm run managed-jobs:test && npm run stdio:integration-test && npm run worker:integration-test",
     "worker:dry-run": "wrangler deploy --dry-run",
     "worker:integration-test": "node tests/worker-integration-test.mjs",
     "release:check": "node scripts/github-release.mjs --check",
@@ -66,6 +66,11 @@
     "install:test": "node tests/install-smoke-test.mjs",
     "secure-file:test": "node tests/secure-file-test.mjs",
     "architecture:test": "node tests/architecture-test.mjs",
+    "markdown:test": "node tests/markdown-test.mjs",
+    "project-metadata:test": "node tests/project-metadata-test.mjs",
+    "numbers:test": "node tests/numbers-test.mjs",
+    "records:test": "node tests/records-test.mjs",
+    "state-inventory:test": "node tests/state-inventory-test.mjs",
     "release-state:test": "node tests/release-state-test.mjs",
     "release-ci:test": "node tests/release-ci-test.mjs",
     "agent-context:test": "node tests/agent-context-test.mjs",
@@ -89,7 +94,11 @@
     "capability-ranking:test": "node tests/capability-ranking-test.mjs",
     "lifecycle:test": "node tests/lifecycle-test.mjs",
     "runtime-handlers:test": "node tests/runtime-handler-matrix-test.mjs",
-    "cli-entrypoint:test": "node tests/cli-entrypoint-test.mjs"
+    "cli-entrypoint:test": "node tests/cli-entrypoint-test.mjs",
+    "commit-message:check": "node scripts/commit-message-check.mjs",
+    "commit-message:test": "node tests/commit-message-test.mjs",
+    "tool-docs:generate": "node scripts/generate-tool-reference.mjs",
+    "tool-docs:check": "node scripts/generate-tool-reference.mjs --check"
   },
   "dependencies": {
     "https-proxy-agent": "9.1.0",

package/scripts/commit-message-check.mjs

@@ -0,0 +1,63 @@
+import { execFileSync } from "node:child_process";
+import process from "node:process";
+
+const allowedTypes = Object.freeze([
+  "feat",
+  "fix",
+  "docs",
+  "refactor",
+  "perf",
+  "test",
+  "build",
+  "ci",
+  "chore",
+  "security",
+  "release",
+  "revert",
+]);
+const subjectPattern = new RegExp(`^(?:${allowedTypes.join("|")})(?:\\([a-z0-9][a-z0-9._/-]*\\))?!?: [^\\s].*$`);
+const titles = readTitles(process.argv.slice(2));
+const failures = [];
+
+for (const title of titles) {
+  const normalized = String(title).trim();
+  if (!normalized) {
+    failures.push("commit or pull-request title is empty");
+    continue;
+  }
+  if (normalized.length > 120) failures.push(`title exceeds 120 characters: ${normalized}`);
+  if (!subjectPattern.test(normalized)) {
+    failures.push(`invalid Conventional Commit title: ${normalized}`);
+  }
+}
+
+if (failures.length) {
+  console.error([
+    ...failures,
+    "Expected: <type>[optional scope][optional !]: <imperative description>",
+    `Allowed types: ${allowedTypes.join(", ")}`,
+  ].join("\n"));
+  process.exitCode = 1;
+} else {
+  console.log(`commit message check ok (${titles.length} title${titles.length === 1 ? "" : "s"})`);
+}
+
+function readTitles(args) {
+  const titleIndex = args.indexOf("--title");
+  if (titleIndex !== -1) {
+    const title = args[titleIndex + 1];
+    if (title === undefined) throw new Error("--title requires a value");
+    return [title];
+  }
+
+  const rangeIndex = args.indexOf("--range");
+  if (rangeIndex !== -1) {
+    const range = args[rangeIndex + 1];
+    if (!range) throw new Error("--range requires a Git revision range");
+    return execFileSync("git", ["log", "--format=%s", range], { encoding: "utf8" })
+      .split(/\r?\n/)
+      .filter(Boolean);
+  }
+
+  return [execFileSync("git", ["log", "-1", "--format=%s"], { encoding: "utf8" }).trim()];
+}

package/scripts/coverage-check.mjs

@@ -14,6 +14,10 @@ const tests = [
   "tests/runtime-handler-matrix-test.mjs",
   "tests/cli-entrypoint-test.mjs",
   "tests/local-self-test.mjs",
+  "tests/numbers-test.mjs",
+  "tests/records-test.mjs",
+  "tests/project-metadata-test.mjs",
+  "tests/state-inventory-test.mjs",
 ];
 
 try {
@@ -41,9 +45,13 @@ try {
     "src/local/process-tracker.mjs": [65, 35],
     "src/local/log.mjs": [60, 40],
     "src/local/runtime.mjs": [60, 35],
-    "src/local/cli.mjs": [40, 5],
+    "src/local/cli.mjs": [40, 10],
     "src/local/cli-options.mjs": [65, 35],
     "src/local/cli-policy.mjs": [70, 35],
+    "src/local/numbers.mjs": [100, 100],
+    "src/local/records.mjs": [100, 100],
+    "src/local/project-metadata.mjs": [85, 55],
+    "src/local/state-inventory.mjs": [80, 50],
     "src/worker/pending-calls.ts": [85, null],
     "src/worker/policy.ts": [90, null],
     "src/worker/errors.ts": [100, null],

package/scripts/generate-policy-reference.mjs

@@ -1,5 +1,6 @@
 import { readFile, writeFile } from "node:fs/promises";
 import process from "node:process";
+import { normalizeLineEndings } from "./markdown.mjs";
 
 const root = new URL("../", import.meta.url);
 const contract = JSON.parse(await readFile(new URL("src/shared/policy-contract.json", root), "utf8"));
@@ -89,7 +90,3 @@ function display(value) {
   if (typeof value === "boolean") return value ? "yes" : "no";
   return String(value);
 }
-
-function normalizeLineEndings(value) {
-  return String(value).replace(/\r\n/g, "\n");
-}

package/scripts/generate-tool-reference.mjs

@@ -0,0 +1,87 @@
+import { readFile, writeFile } from "node:fs/promises";
+import process from "node:process";
+import { escapeMarkdownTableCell, normalizeLineEndings } from "./markdown.mjs";
+
+const root = new URL("../", import.meta.url);
+const catalogUrl = new URL("src/shared/tool-catalog.json", root);
+const targetUrl = new URL("docs/TOOL_REFERENCE.md", root);
+const catalog = JSON.parse(await readFile(catalogUrl, "utf8"));
+const generated = renderToolReference(catalog);
+
+if (process.argv.includes("--check")) {
+  const current = await readFile(targetUrl, "utf8").catch(() => "");
+  if (normalizeLineEndings(current) !== generated) {
+    console.error("docs/TOOL_REFERENCE.md is stale; run npm run tool-docs:generate");
+    process.exitCode = 1;
+  } else {
+    console.log(`tool reference is up to date (${catalog.length} tools)`);
+  }
+} else {
+  await writeFile(targetUrl, generated, "utf8");
+  console.log(`generated docs/TOOL_REFERENCE.md (${catalog.length} tools)`);
+}
+
+function renderToolReference(tools) {
+  const lines = [
+    "# MCP tool reference",
+    "",
+    "> Generated from `src/shared/tool-catalog.json`. Do not edit this file manually.",
+    "",
+    "This catalog is the authoritative public tool contract for names, availability classes, behavior annotations, and JSON input schemas. Runtime authorization is additionally determined by the active policy described in [POLICY_REFERENCE.md](POLICY_REFERENCE.md).",
+    "",
+    `Tool count: **${tools.length}**.`,
+    "",
+    "## Index",
+    "",
+    "| Tool | Availability | Read only | Destructive | Idempotent | Open world |",
+    "|---|---|---:|---:|---:|---:|",
+  ];
+
+  for (const tool of tools) {
+    const annotations = tool.annotations || {};
+    lines.push(`| [\`${escapeMarkdownTableCell(tool.name)}\`](#${anchor(tool.name)}) | \`${escapeMarkdownTableCell(tool.availability)}\` | ${yesNo(annotations.readOnlyHint)} | ${yesNo(annotations.destructiveHint)} | ${yesNo(annotations.idempotentHint)} | ${yesNo(annotations.openWorldHint)} |`);
+  }
+
+  for (const tool of tools) {
+    const annotations = tool.annotations || {};
+    lines.push(
+      "",
+      `## \`${tool.name}\``,
+      "",
+      `**${tool.title}**`,
+      "",
+      tool.description,
+      "",
+      "| Contract field | Value |",
+      "|---|---|",
+      `| Availability | \`${tool.availability}\` |`,
+      `| Read-only hint | ${yesNo(annotations.readOnlyHint)} |`,
+      `| Destructive hint | ${yesNo(annotations.destructiveHint)} |`,
+      `| Idempotent hint | ${yesNo(annotations.idempotentHint)} |`,
+      `| Open-world hint | ${yesNo(annotations.openWorldHint)} |`,
+      "",
+      "### Input schema",
+      "",
+      "```json",
+      JSON.stringify(tool.inputSchema || { type: "object", additionalProperties: false }, null, 2),
+      "```",
+    );
+  }
+
+  lines.push(
+    "",
+    "## Change discipline",
+    "",
+    "A catalog change must update its runtime handler and protocol tests in the same pull request. CI verifies catalog uniqueness, local/Worker use of the shared catalog, handler parity, generated policy documentation, and this generated reference.",
+    "",
+  );
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+function anchor(name) {
+  return name.toLowerCase().replace(/[^a-z0-9_-]+/g, "-");
+}
+
+function yesNo(value) {
+  return value === true ? "yes" : "no";
+}

package/scripts/generate-worker-types.mjs

@@ -0,0 +1,19 @@
+import { spawnSync } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const target = resolve(root, ".wrangler", "worker-configuration.d.ts");
+const wrangler = resolve(root, "node_modules", "wrangler", "bin", "wrangler.js");
+
+mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+const result = spawnSync(process.execPath, [wrangler, "types", target], {
+  cwd: root,
+  env: process.env,
+  stdio: "inherit",
+  windowsHide: true,
+});
+if (result.error) throw result.error;
+if (result.status !== 0) process.exit(result.status ?? 1);

package/scripts/markdown.mjs

@@ -0,0 +1,9 @@
+export function escapeMarkdownTableCell(value) {
+  return String(value)
+    .replace(/\\/g, "\\\\")
+    .replace(/\|/g, "\\|");
+}
+
+export function normalizeLineEndings(value) {
+  return String(value).replace(/\r\n/g, "\n");
+}

package/src/local/agent-context.mjs

@@ -5,6 +5,8 @@ import { lstat, open, opendir, realpath, stat } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { createBuiltinInstruction, discoverAutomaticProjectInstruction } from "./default-instructions.mjs";
 import { automaticPackageCommands, readProjectPackageMetadata } from "./project-package.mjs";
+import { clampInteger } from "./numbers.mjs";
+import { isPlainRecord } from "./records.mjs";
 
 const CONFIG_RELATIVE_PATH = join(".machine-bridge", "agent.json");
 const GLOBAL_CONFIG_RELATIVE_PATH = join(".config", "machine-bridge-mcp", "agent.json");
@@ -42,7 +44,7 @@ export class AgentContextManager {
   async agentContext(args = {}, context = {}) {
     const state = await this.discoverState(args.path || ".", context);
     const includeContent = args.include_instruction_content !== false;
-    const skillLimit = clampInt(args.max_skills, 100, 1, MAX_SKILL_RESULTS);
+    const skillLimit = clampInteger(args.max_skills, 100, 1, MAX_SKILL_RESULTS);
     const discoveredSkills = await this.discoverSkills(state, { maxResults: MAX_SKILL_RESULTS }, context);
     const contextSkills = contextSkillSummaries(discoveredSkills.skills, this.displayPath, skillLimit, MAX_CONTEXT_SKILL_SUMMARY_CHARS);
     const result = {
@@ -111,7 +113,7 @@ export class AgentContextManager {
     if (task.length > 20_000) throw new Error("task exceeds 20000 characters");
     const state = await this.discoverState(args.path || ".", context);
     const discovered = await this.discoverSkills(state, { maxResults: MAX_SKILL_RESULTS }, context);
-    const maxSkills = clampInt(args.max_skills, 10, 1, 50);
+    const maxSkills = clampInteger(args.max_skills, 10, 1, 50);
     const skillMatches = discovered.skills
       .map((skill) => ({ skill, score: relevanceScore(task, `${skill.name} ${skill.description}`, skill.name) }))
       .filter((item) => item.score > 0)
@@ -169,7 +171,7 @@ export class AgentContextManager {
     const state = await this.discoverState(args.path || ".", context);
     const result = await this.discoverSkills(state, {
       query: typeof args.query === "string" ? args.query : "",
-      maxResults: clampInt(args.max_results, 100, 1, MAX_SKILL_RESULTS),
+      maxResults: clampInteger(args.max_results, 100, 1, MAX_SKILL_RESULTS),
     }, context);
     return {
       target: this.displayPath(state.target),
@@ -190,7 +192,7 @@ export class AgentContextManager {
     if (matches.length > 1) throw new Error(`local skill name is ambiguous; use its id: ${requested}`);
     const skill = matches[0];
     const content = await readRegularUtf8(skill.entrypoint, MAX_SKILL_ENTRY_BYTES, "skill entrypoint");
-    const inventory = await listSkillFiles(skill.directory, clampInt(args.max_files, 200, 1, MAX_SKILL_FILES), context, this.throwIfCancelled);
+    const inventory = await listSkillFiles(skill.directory, clampInteger(args.max_files, 200, 1, MAX_SKILL_FILES), context, this.throwIfCancelled);
     return {
       skill: publicSkill(skill, this.displayPath),
       instructions: content.text,
@@ -381,7 +383,7 @@ export class AgentContextManager {
 
   async discoverSkills(state, options = {}, context = {}) {
     const query = String(options.query || "").trim().toLowerCase();
-    const maxResults = clampInt(options.maxResults, 100, 1, MAX_SKILL_RESULTS);
+    const maxResults = clampInteger(options.maxResults, 100, 1, MAX_SKILL_RESULTS);
     const skills = [];
     const warnings = [];
     const seenEntrypoints = new Set();
@@ -581,7 +583,7 @@ function normalizeCommand(value, name, configPath) {
   const description = typeof value.description === "string" ? value.description.trim() : "";
   if (!description || description.length > 1000) throw new Error(`registered command '${name}' requires a description of at most 1000 characters: ${configPath}`);
   const cwd = value.cwd === undefined ? "." : requiredString(value.cwd, `commands.${name}.cwd`);
-  const timeoutSeconds = clampInt(value.timeout_seconds, 120, 1, 600);
+  const timeoutSeconds = clampInteger(value.timeout_seconds, 120, 1, 600);
   if (value.timeout_seconds !== undefined && timeoutSeconds !== value.timeout_seconds) {
     throw new Error(`registered command '${name}' timeout_seconds must be an integer from 1 to 600: ${configPath}`);
   }
@@ -877,9 +879,6 @@ function isContainedPath(root, target) {
   return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
 }
 
-function isPlainRecord(value) {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
 
 function boundedMessage(error) {
   return String(error?.message || error || "invalid local skill").replace(/[\r\n]+/g, " ").slice(0, 1000);
@@ -897,12 +896,6 @@ function unquoteScalar(value) {
   return value;
 }
 
-function clampInt(value, fallback, min, max) {
-  if (value === undefined || value === null || value === "") return fallback;
-  const parsed = Number(value);
-  if (!Number.isInteger(parsed)) return fallback;
-  return Math.min(Math.max(parsed, min), max);
-}
 
 function sha256(value) {
   return createHash("sha256").update(String(value)).digest("hex");

package/src/local/cli.mjs

@@ -13,12 +13,11 @@ import { createLocalAdminCommands } from "./cli-local-admin.mjs";
 export { resolvePolicy } from "./cli-policy.mjs";
 export { parseArgs, validateCommandOptions, validateLoggingOptions, validatePositionals } from "./cli-options.mjs";
 import { classifyOperationalError, createLogger, normalizeLogLevel, sanitizeLogText } from "./log.mjs";
-import { activeManagedJobs } from "./managed-jobs.mjs";
 import { run, runWrangler } from "./shell.mjs";
 import { runFullAccessTest } from "./full-access-test.mjs";
-import { readBoundedRegularFileSync } from "./secure-file.mjs";
 import { inspectProcessInstance } from "./process-identity.mjs";
 import { stopAndRemoveAutostart } from "./service-lifecycle.mjs";
+import { activeStateJobs, activeStateLocks, knownProfileStates, knownWorkerNames } from "./state-inventory.mjs";
 import { createExclusiveFileSync } from "./exclusive-file.mjs";
 import {
   acquireMaintenanceLock,
@@ -908,37 +907,6 @@ async function deleteKnownWorkers(stateRoot) {
   }
 }
 
-export function knownWorkerNames(stateRoot) {
-  const profiles = resolve(expandHome(stateRoot), "profiles");
-  if (!existsSync(profiles)) return [];
-  const names = new Set();
-  for (const entry of readdirSync(profiles, { withFileTypes: true })) {
-    if (!entry.isDirectory() || !/^[a-f0-9]{24}$/.test(entry.name)) continue;
-    const profileDir = resolve(profiles, entry.name);
-    const stateFile = resolve(profileDir, "state.json");
-    if (!existsSync(stateFile)) {
-      const evidence = readdirSync(profileDir).some((name) => /^state\.json\.corrupt-/.test(name) || name === "daemon.lock");
-      if (evidence) throw new Error(`cannot determine deployed Worker from profile ${entry.name}; local state was kept for inspection`);
-      continue;
-    }
-    let state;
-    try {
-      state = JSON.parse(readBoundedRegularFileSync(stateFile, 2 * 1024 * 1024).toString("utf8"));
-    } catch {
-      throw new Error(`cannot determine deployed Worker from profile ${entry.name}; local state was kept for inspection`);
-    }
-    if (!state || typeof state !== "object" || Array.isArray(state)) {
-      throw new Error(`cannot determine deployed Worker from profile ${entry.name}; local state was kept for inspection`);
-    }
-    const name = String(state?.worker?.name || "");
-    if (name && !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(name)) {
-      throw new Error(`profile ${entry.name} contains an invalid Worker name; local state was kept for inspection`);
-    }
-    if (name) names.add(name);
-  }
-  return [...names];
-}
-
 async function removeAutostartBestEffort(stateRoot) {
   const logger = structuredLogger(false);
   try {
@@ -963,80 +931,6 @@ async function removeAutostartBestEffort(stateRoot) {
   }
 }
 
-export function knownProfileStates(stateRoot) {
-  const canonicalStateRoot = resolve(expandHome(stateRoot));
-  const profiles = resolve(canonicalStateRoot, "profiles");
-  if (!existsSync(profiles)) return [];
-  const states = [];
-  const seen = new Set();
-  for (const entry of readdirSync(profiles, { withFileTypes: true })) {
-    if (!entry.isDirectory() || !/^[a-f0-9]{24}$/.test(entry.name)) continue;
-    const profileDir = resolve(profiles, entry.name);
-    const statePath = resolve(profileDir, "state.json");
-    const candidates = [];
-    if (existsSync(statePath)) {
-      try {
-        const value = JSON.parse(readBoundedRegularFileSync(statePath, 2 * 1024 * 1024).toString("utf8"));
-        if (typeof value?.workspace?.path === "string") candidates.push(value.workspace.path);
-      } catch {}
-    }
-    const daemonLock = resolve(profileDir, "daemon.lock");
-    const daemonOwner = readDaemonLockOwner(daemonLock);
-    if (existsSync(daemonLock) && !daemonOwner) {
-      throw new Error(`cannot inspect daemon lock for profile ${entry.name}; service definitions and state were kept`);
-    }
-    if (typeof daemonOwner?.workspace === "string") candidates.push(daemonOwner.workspace);
-    for (const candidate of candidates) {
-      try {
-        const workspace = resolveWorkspace(candidate);
-        if (seen.has(workspace)) break;
-        states.push({
-          schemaVersion: 5,
-          workspace: { path: workspace, hash: entry.name },
-          paths: { stateRoot: canonicalStateRoot, profileDir, statePath },
-        });
-        seen.add(workspace);
-        break;
-      } catch {}
-    }
-  }
-  return states;
-}
-
-function activeStateJobs(stateRoot) {
-  const profiles = resolve(expandHome(stateRoot), "profiles");
-  if (!existsSync(profiles)) return [];
-  const active = [];
-  for (const profile of readdirSync(profiles, { withFileTypes: true })) {
-    if (!profile.isDirectory()) continue;
-    for (const job of activeManagedJobs(resolve(profiles, profile.name, "jobs"))) {
-      active.push({ profile: profile.name, ...job });
-    }
-  }
-  return active;
-}
-
-function activeStateLocks(stateRoot) {
-  const profiles = resolve(expandHome(stateRoot), "profiles");
-  if (!existsSync(profiles)) return [];
-  const active = [];
-  for (const profile of readdirSync(profiles, { withFileTypes: true })) {
-    if (!profile.isDirectory()) continue;
-    for (const [kind, name] of [["daemon", "daemon.lock"], ["startup", "startup.lock"]]) {
-      const lockPath = resolve(profiles, profile.name, name);
-      if (!existsSync(lockPath)) continue;
-      const owner = readDaemonLockOwner(lockPath);
-      if (!owner) {
-        active.push({ kind, pid: null, path: lockPath, reason: "invalid_or_unreadable_lock" });
-        continue;
-      }
-      const identity = inspectProcessInstance(owner, { maxAgeMs: kind === "startup" ? 2 * 60 * 60 * 1000 : Number.POSITIVE_INFINITY });
-      if (identity.current || (identity.alive && !identity.reclaimable)) active.push({ kind, pid: owner.pid, path: lockPath, reason: identity.reason });
-    }
-  }
-  return active;
-}
-
 function structuredLogger(quiet) {
   return createLogger({ quiet, component: "service" });
 }

package/src/local/daemon-process.mjs

@@ -13,13 +13,15 @@ const DEFAULT_TAKEOVER_POLL_MS = 100;
 
 export async function acquireDaemonLockWithTakeover(state, options = {}) {
   const ownerMetadata = options.ownerMetadata || {};
+  const timeoutMs = boundedPositiveInt(options.timeoutMs, DEFAULT_TAKEOVER_TIMEOUT_MS);
+  const pollMs = boundedPositiveInt(options.pollMs, DEFAULT_TAKEOVER_POLL_MS);
   let lock = acquireDaemonLock(state, ownerMetadata);
   if (lock.acquired || !options.takeOverServiceOwner) return lock;
 
   const stopped = await stopWorkspaceServiceDaemon(state, {
     owner: lock.owner,
-    timeoutMs: options.timeoutMs,
-    pollMs: options.pollMs,
+    timeoutMs,
+    pollMs,
     logger: options.logger,
     reason: "foreground startup",
   });
@@ -29,8 +31,18 @@ export async function acquireDaemonLockWithTakeover(state, options = {}) {
     throw new Error(`background daemon did not release the workspace within ${Math.ceil(stopped.timeout_ms / 1000)} seconds (${pid}); run \`machine-mcp service stop\`, verify \`machine-mcp service status\`, and retry`);
   }
 
-  lock = acquireDaemonLock(state, ownerMetadata);
-  if (lock.acquired) options.logger?.info?.("background daemon stopped; foreground startup is taking over the workspace");
+  // A terminated daemon can release its token immediately before the filesystem
+  // makes the lock removal visible to this process. Retry only this handoff.
+  const handoffDeadline = Date.now() + Math.min(timeoutMs, 1_000);
+  do {
+    lock = acquireDaemonLock(state, ownerMetadata);
+    if (lock.acquired) {
+      options.logger?.info?.("background daemon stopped; foreground startup is taking over the workspace");
+      return lock;
+    }
+    if (lock.owner?.pid && isPidAlive(lock.owner.pid)) return lock;
+    await sleep(Math.min(pollMs, Math.max(1, handoffDeadline - Date.now())));
+  } while (Date.now() < handoffDeadline);
   return lock;
 }
 

package/src/local/default-instructions.mjs

@@ -1,8 +1,8 @@
 import { createHash } from "node:crypto";
-import { constants as fsConstants } from "node:fs";
-import { lstat, open, opendir } from "node:fs/promises";
+import { lstat, opendir } from "node:fs/promises";
 import { join, relative, resolve, sep } from "node:path";
 import { packageScriptDisplayCommand, readProjectPackageMetadata, safeVersionValue } from "./project-package.mjs";
+import { isRegularNonSymlink, readOptionalRegularUtf8, safeSingleLine, skippableMetadataError } from "./project-metadata.mjs";
 
 const MAX_PROJECT_CONTEXT_BYTES = 16 * 1024;
 const MAX_SCRIPT_NAMES = 24;
@@ -208,36 +208,6 @@ async function listWorkflowFiles(root, throwIfCancelled) {
   return files.sort((left, right) => left.localeCompare(right));
 }
 
-async function isRegularNonSymlink(filePath) {
-  const info = await lstat(filePath).catch((error) => skippableMetadataError(error) ? null : Promise.reject(error));
-  return Boolean(info && !info.isSymbolicLink() && info.isFile());
-}
-
-async function readOptionalRegularUtf8(filePath, maxBytes) {
-  const info = await lstat(filePath).catch((error) => skippableMetadataError(error) ? null : Promise.reject(error));
-  if (!info || info.isSymbolicLink() || !info.isFile() || info.size > maxBytes) return null;
-  const handle = await open(filePath, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW || 0)).catch((error) => skippableMetadataError(error) ? null : Promise.reject(error));
-  if (!handle) return null;
-  try {
-    const current = await handle.stat();
-    if (!current.isFile() || current.size > maxBytes) return null;
-    const buffer = Buffer.alloc(current.size);
-    let offset = 0;
-    while (offset < buffer.length) {
-      const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, offset);
-      if (!bytesRead) break;
-      offset += bytesRead;
-    }
-    try {
-      return new TextDecoder("utf-8", { fatal: true }).decode(buffer.subarray(0, offset));
-    } catch {
-      return null;
-    }
-  } finally {
-    await handle.close();
-  }
-}
-
 function virtualInstruction(source, content, precedence, scope) {
   return {
     scope,
@@ -249,19 +219,6 @@ function virtualInstruction(source, content, precedence, scope) {
   };
 }
 
-function skippableMetadataError(error) {
-  return ["ENOENT", "ENOTDIR", "EACCES", "EPERM", "ELOOP", "EBUSY"].includes(error?.code);
-}
-
-function safeSingleLine(value, maxLength) {
-  if (typeof value !== "string") return "";
-  return value.replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").trim().slice(0, maxLength);
-}
-
 function escapeInlineCode(value) {
   return String(value).replaceAll("`", "'");
 }
-
-function isPlainRecord(value) {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}

package/src/local/git-service.mjs

@@ -1,6 +1,7 @@
 import { stat } from "node:fs/promises";
 import { dirname, isAbsolute, relative, sep } from "node:path";
 import { BridgeError } from "./errors.mjs";
+import { clampInteger } from "./numbers.mjs";
 
 export class GitService {
   constructor({ resolveExistingPath, displayPath, runProcess, maximumBytes }) {
@@ -20,7 +21,7 @@ export class GitService {
   }
 
   async diff(args = {}, context = {}) {
-    const maxBytes = clampInt(args.max_bytes, 1024 * 1024, 1, this.maximumBytes);
+    const maxBytes = clampInteger(args.max_bytes, 1024 * 1024, 1, this.maximumBytes);
     const git = await this.context(args.path || ".", context);
     if (!git.ok) return { ...git.result, path: this.displayPath(git.target) };
     const commandArgs = ["-c", "core.fsmonitor=false", "-c", "diff.external=", "-C", git.root, "diff", "--no-ext-diff", "--no-textconv"];
@@ -33,7 +34,7 @@ export class GitService {
   async log(args = {}, context = {}) {
     const git = await this.context(args.path || ".", context);
     if (!git.ok) return { ...git.result, path: this.displayPath(git.target) };
-    const maxCount = clampInt(args.max_count, 20, 1, 100);
+    const maxCount = clampInteger(args.max_count, 20, 1, 100);
     const format = "%H%x1f%h%x1f%aI%x1f%an%x1f%ae%x1f%s%x1e";
     const commandArgs = ["-c", "core.fsmonitor=false", "-C", git.root, "log", `--max-count=${maxCount}`, `--format=${format}`];
     if (git.pathspec) commandArgs.push("--", git.pathspec);
@@ -51,7 +52,7 @@ export class GitService {
     const git = await this.context(args.path || ".", context);
     if (!git.ok) return { ...git.result, path: this.displayPath(git.target) };
     const revision = validateRevision(args.revision || "HEAD");
-    const maxBytes = clampInt(args.max_bytes, 1024 * 1024, 1, this.maximumBytes);
+    const maxBytes = clampInteger(args.max_bytes, 1024 * 1024, 1, this.maximumBytes);
     const commandArgs = ["-c", "core.fsmonitor=false", "-c", "diff.external=", "-C", git.root, "show", "--no-ext-diff", "--no-textconv", "--decorate=no", revision];
     if (git.pathspec) commandArgs.push("--", git.pathspec);
     const result = await this.runProcess("git", commandArgs, 60_000, true, maxBytes, context);
@@ -80,9 +81,3 @@ function validateRevision(value) {
   }
   return revision;
 }
-
-function clampInt(value, fallback, minimum, maximum) {
-  const parsed = Number.parseInt(String(value ?? ""), 10);
-  const number = Number.isFinite(parsed) ? parsed : fallback;
-  return Math.min(Math.max(number, minimum), maximum);
-}