archctx 0.1.4-beta.0 → 0.1.5

package/assets/catalog.yaml

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "archcontext.practice-catalog-manifest/v1",
   "catalogVersion": "2026.06.0",
-  "productVersion": "0.1.4-beta.0",
+  "productVersion": "0.1.5",
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "entries": [
     {
@@ -389,5 +389,5 @@
     "structurizr.dsl",
     "twelve-factor"
   ],
-  "catalogDigest": "sha256:19c4fdf4068eaf19f782d92373354cff071947134e76eb6927998d5a9a1146c3"
+  "catalogDigest": "sha256:6da748c8c6230d18597951e5ff2de7d483e90caed61435cbd80418a5339c0299"
 }

package/bin/archctx.mjs

@@ -702,7 +702,7 @@ function productVersionManifest() {
     }
   };
 }
-var ARCHCONTEXT_PRODUCT_NAME = "archctx", ARCHCONTEXT_PRODUCT_VERSION = "0.1.4-beta.0", ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.3.10", ARCHCONTEXT_NODE_RANGE = ">=24 <26", LOCAL_RUNTIME_RPC_SCHEMA_VERSION = "archcontext.runtime-rpc/v1", ARCHCONTEXT_SCHEMA_SET_VERSION = "2026-06-25.al0-ledger";
+var ARCHCONTEXT_PRODUCT_NAME = "archctx", ARCHCONTEXT_PRODUCT_VERSION = "0.1.5", ARCHCONTEXT_PACKAGE_MANAGER = "bun@1.3.10", ARCHCONTEXT_NODE_RANGE = ">=24 <26", LOCAL_RUNTIME_RPC_SCHEMA_VERSION = "archcontext.runtime-rpc/v1", ARCHCONTEXT_SCHEMA_SET_VERSION = "2026-06-25.al0-ledger";
 // packages/contracts/src/index.ts
 var init_src = __esm(() => {
   init_control_plane_routes();
@@ -9485,7 +9485,7 @@ function migrateLegacyLocalStoreIfNeeded(root = process.cwd(), env = process.env
       integrityCheck.target = "failed";
       integrityCheck.error = error instanceof Error ? error.message : String(error);
       if (!legacyExists) {
-        throw new Error(`ArchContext runtime state target is not a valid SQLite database and no legacy store is available: ${paths.localStorePath}`);
+        return upgradeExistingLocalStoreTarget(paths, integrityCheck);
       }
     }
   }
@@ -9524,6 +9524,28 @@ function migrateLegacyLocalStoreIfNeeded(root = process.cwd(), env = process.env
     releaseLegacyMigrationLock(lock);
   }
 }
+function upgradeExistingLocalStoreTarget(paths, integrityCheck) {
+  const lock = acquireLegacyMigrationLock(paths);
+  try {
+    assertUpgradeableLocalStoreTarget(paths.localStorePath);
+    integrityCheck.target = assertSqliteIntegrity(paths.localStorePath);
+    migrateSqliteDatabaseSync(paths.localStorePath);
+    compactSqliteDatabase(paths.localStorePath);
+    integrityCheck.target = assertCurrentLocalStore(paths.localStorePath);
+    delete integrityCheck.error;
+    const markerPath = writeLegacyMigrationMarker(paths, integrityCheck, []);
+    return legacyMigrationResult(true, undefined, paths, [paths.localStorePath], {
+      status: "target-upgraded",
+      integrityCheck,
+      markerPath,
+      quarantinedFiles: []
+    });
+  } catch (error) {
+    throw new Error(`ArchContext runtime state target is not a valid SQLite database and no legacy store is available: ${paths.localStorePath}; target upgrade failed: ${error instanceof Error ? error.message : String(error)}`);
+  } finally {
+    releaseLegacyMigrationLock(lock);
+  }
+}
 function applyLocalSqliteMigrations(db) {
   for (const pragma of SQLITE_PRAGMAS)
     db.exec(pragma);
@@ -9640,6 +9662,21 @@ function assertCurrentLocalStoreSchema(db, path) {
     throw new Error(`SQLite local store schema incomplete for ${path}: missing migrations ${missingMigrations.join(", ")}`);
   }
 }
+function assertUpgradeableLocalStoreTarget(path) {
+  const db = openSqliteDatabaseSync(path);
+  try {
+    const integrity = sqliteIntegrityCheckOpenDatabase(db, path);
+    const tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all().map((row) => String(row.name)));
+    const hasArchContextMarker = ["schema_migrations", "task_states", "repository_sessions", "snapshots"].some((table) => tables.has(table));
+    if (!hasArchContextMarker) {
+      throw new Error(`SQLite target is not an ArchContext local store candidate: ${path}`);
+    }
+    if (integrity !== "ok")
+      throw new Error(`SQLite integrity_check failed for ${path}: ${integrity}`);
+  } finally {
+    db.close();
+  }
+}
 function assertTrustedLegacyLocalStoreSource(paths) {
   const stat = lstatSync(paths.legacyLocalStorePath);
   if (stat.isSymbolicLink()) {
@@ -15961,7 +15998,7 @@ function migrateLegacyLocalStoreIfNeeded2(root = process.cwd(), env = process.en
       integrityCheck.target = "failed";
       integrityCheck.error = error instanceof Error ? error.message : String(error);
       if (!legacyExists) {
-        throw new Error(`ArchContext runtime state target is not a valid SQLite database and no legacy store is available: ${paths.localStorePath}`);
+        return upgradeExistingLocalStoreTarget2(paths, integrityCheck);
       }
     }
   }
@@ -16000,6 +16037,28 @@ function migrateLegacyLocalStoreIfNeeded2(root = process.cwd(), env = process.en
     releaseLegacyMigrationLock2(lock);
   }
 }
+function upgradeExistingLocalStoreTarget2(paths, integrityCheck) {
+  const lock = acquireLegacyMigrationLock2(paths);
+  try {
+    assertUpgradeableLocalStoreTarget2(paths.localStorePath);
+    integrityCheck.target = assertSqliteIntegrity2(paths.localStorePath);
+    migrateSqliteDatabaseSync2(paths.localStorePath);
+    compactSqliteDatabase2(paths.localStorePath);
+    integrityCheck.target = assertCurrentLocalStore2(paths.localStorePath);
+    delete integrityCheck.error;
+    const markerPath = writeLegacyMigrationMarker2(paths, integrityCheck, []);
+    return legacyMigrationResult2(true, undefined, paths, [paths.localStorePath], {
+      status: "target-upgraded",
+      integrityCheck,
+      markerPath,
+      quarantinedFiles: []
+    });
+  } catch (error) {
+    throw new Error(`ArchContext runtime state target is not a valid SQLite database and no legacy store is available: ${paths.localStorePath}; target upgrade failed: ${error instanceof Error ? error.message : String(error)}`);
+  } finally {
+    releaseLegacyMigrationLock2(lock);
+  }
+}
 var RUNTIME_AGENT_JOB_STATUSES = ["queued", "running", "succeeded", "failed", "cancelled", "superseded", "expired"];
 
 class SqliteLocalStore {
@@ -17334,6 +17393,21 @@ function assertCurrentLocalStoreSchema2(db, path) {
     throw new Error(`SQLite local store schema incomplete for ${path}: missing migrations ${missingMigrations.join(", ")}`);
   }
 }
+function assertUpgradeableLocalStoreTarget2(path) {
+  const db = openSqliteDatabaseSync2(path);
+  try {
+    const integrity = sqliteIntegrityCheckOpenDatabase2(db, path);
+    const tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all().map((row) => String(row.name)));
+    const hasArchContextMarker = ["schema_migrations", "task_states", "repository_sessions", "snapshots"].some((table) => tables.has(table));
+    if (!hasArchContextMarker) {
+      throw new Error(`SQLite target is not an ArchContext local store candidate: ${path}`);
+    }
+    if (integrity !== "ok")
+      throw new Error(`SQLite integrity_check failed for ${path}: ${integrity}`);
+  } finally {
+    db.close();
+  }
+}
 function assertTrustedLegacyLocalStoreSource2(paths) {
   const stat = lstatSync5(paths.legacyLocalStorePath);
   if (stat.isSymbolicLink()) {
@@ -25904,8 +25978,14 @@ var ARCHITECTURE_BOOK_RESOURCES = [
 class McpLocalServer {
   resources = new Map;
   runtimeInstance;
-  constructor(runtime) {
-    this.runtimeInstance = runtime;
+  runtimeResolver;
+  constructor(runtimeOrOptions) {
+    if (isMcpLocalServerOptions(runtimeOrOptions)) {
+      this.runtimeInstance = runtimeOrOptions.runtime;
+      this.runtimeResolver = runtimeOrOptions.runtimeResolver;
+    } else {
+      this.runtimeInstance = runtimeOrOptions;
+    }
   }
   listTools() {
     return LOCAL_MCP_TOOLS;
@@ -26027,7 +26107,7 @@ class McpLocalServer {
       }))
     ];
     try {
-      const status = await (await this.runtime(root)).docs(root, { command: "status", provider: "context7" });
+      const status = await (await this.runtime(root, { allowResolver: false })).docs(root, { command: "status", provider: "context7" });
       if (!status.ok)
         return localResources;
       const cacheEntries = status.data?.cacheEntries ?? [];
@@ -26090,7 +26170,7 @@ class McpLocalServer {
       dataClassification: "local-architecture"
     };
   }
-  async runtime(root = process.cwd()) {
+  async runtime(root = process.cwd(), options = { allowResolver: true }) {
     if (this.runtimeInstance)
       return this.runtimeInstance;
     const client = createRuntimeRpcClientFromConnectionFile2(root);
@@ -26103,9 +26183,16 @@ class McpLocalServer {
         return this.runtimeInstance;
       }
     }
+    if (options.allowResolver !== false && this.runtimeResolver) {
+      this.runtimeInstance = await this.runtimeResolver(root);
+      return this.runtimeInstance;
+    }
     throw new Error("archctxd RPC is unavailable; run `archctx daemon start` before using the local MCP surface");
   }
 }
+function isMcpLocalServerOptions(value) {
+  return Boolean(value && typeof value === "object" && (("runtime" in value) || ("runtimeResolver" in value)));
+}
 function requiredArg(args, key) {
   const value = args[key];
   if (typeof value !== "string" || value.length === 0)
@@ -26119,8 +26206,8 @@ function runtimeUnavailable(requestId, error) {
   };
 }
 async function runStdioMcpLoop(input, output, log = (line) => process.stderr.write(`${line}
-`)) {
-  const server = new McpLocalServer;
+`), options = {}) {
+  const server = new McpLocalServer(options);
   log("[archctx-mcp] started");
   for await (const line of input) {
     const message = JSON.parse(line);
@@ -26173,7 +26260,8 @@ class RuntimeVersionUnsupportedError extends Error {
 if (__require.main == __require.module) {
   if (command === "mcp" && args.length === 0) {
     await runStdioMcpLoop(stdinLines(), (line) => process.stdout.write(`${line}
-`));
+`), (line) => process.stderr.write(`${line}
+`), { runtimeResolver: (root) => createOrStartRuntimeRpcClient(root) });
   } else if (command === "daemon" && args[0] === "start" && args.includes("--foreground")) {
     await runForegroundDaemon(process.cwd(), args).catch((error) => {
       process.stderr.write(`${error instanceof Error ? error.message : String(error)}
@@ -26446,7 +26534,7 @@ async function runCliUnchecked(command2 = "help", args2 = [], cwd, deps = {}) {
           requestId: "help",
           data: {
             commands: ["init", "sync", "validate", "context", "status", "daemon", "repo", "landscape", "ledger", "book", "recommendations", "explore", "prepare", "practices", "checkpoint", "hook", "hooks", "investigate", "agents", "jobs", "plan", "apply", "review", "complete", "github", "config", "mcp", "install", "uninstall", "doctor", "update", "paths", "privacy-audit", "export", "import", "tunnel"],
-            examples: ["archctx init --name MyApp", "archctx ledger migrate --from-yaml --dry-run", "archctx book recommendations --open --explain", "archctx recommendations accept --id recommendation.<id> --reason 'Accepted after local readback.'", "archctx recommendations metrics", "archctx practices validate --strict", "archctx practices list --json", "archctx practices waivers", "archctx practices waive --practice-id modularity.no-new-cycle --owner team-architecture --reason 'External migration window requires this edge until cutover.' --review-at 2026-07-10T00:00:00.000Z --expires-at 2026-07-24T00:00:00.000Z --evidence-digest sha256:<64-hex> --subject module.a->module.b", "archctx checkpoint --task-session-id task_cli", "archctx investigate --runner-port codex", "archctx agents status --status queued,running", "archctx agents budget", "archctx hook enqueue --event post-edit --path src/app.ts", "archctx jobs list --status queued", "archctx hooks install --host codex", "archctx paths", "archctx update --check", "archctx doctor --check-updates", "archctx github connect", "archctx github status", "archctx daemon start", "archctx explore start --foreground", "archctx export likec4", "archctx import structurizr --content '<json>'", "archctx tunnel"]
+            examples: ["archctx init --name MyApp", "archctx ledger migrate --from-yaml --dry-run", "archctx ledger promote --mode authoritative --preflight --rollback-plan", "archctx book recommendations --open --explain", "archctx recommendations accept --id recommendation.<id> --reason 'Accepted after local readback.'", "archctx recommendations metrics", "archctx practices validate --strict", "archctx practices list --json", "archctx practices waivers", "archctx practices waive --practice-id modularity.no-new-cycle --owner team-architecture --reason 'External migration window requires this edge until cutover.' --review-at 2026-07-10T00:00:00.000Z --expires-at 2026-07-24T00:00:00.000Z --evidence-digest sha256:<64-hex> --subject module.a->module.b", "archctx checkpoint --task-session-id task_cli", "archctx investigate --runner-port codex", "archctx agents status --status queued,running", "archctx agents budget", "archctx hook enqueue --event post-edit --path src/app.ts", "archctx jobs list --status queued", "archctx hooks install --host codex", "archctx paths", "archctx update --check", "archctx doctor --check-updates", "archctx github connect", "archctx github status", "archctx daemon start", "archctx explore start --foreground", "archctx export likec4", "archctx import structurizr --content '<json>'", "archctx tunnel"]
           }
         };
     }
@@ -26465,6 +26553,24 @@ async function runLedgerCommand(args2, cwd, runtime) {
     const daemon = await requiredLedgerRuntime(runtime);
     return daemon.ledgerDrift(cwd);
   }
+  if (subcommand === "promote") {
+    if (args2.includes("--write") || args2.includes("--enable") || args2.includes("--apply")) {
+      return errorEnvelope("ledger.promote", "AC_SCHEMA_INVALID", "ledger promote is preflight-only; it does not write runtime config or enable authority");
+    }
+    const mode = readFlag(args2, "--mode") ?? args2[1];
+    const targetMode = normalizeLedgerPromotionTargetMode(mode);
+    if (!targetMode) {
+      return errorEnvelope("ledger.promote", "AC_SCHEMA_INVALID", "ledger promote requires --mode authoritative");
+    }
+    if (!args2.includes("--preflight")) {
+      return errorEnvelope("ledger.promote", "AC_SCHEMA_INVALID", "ledger promote requires --preflight");
+    }
+    if (!args2.includes("--rollback-plan")) {
+      return errorEnvelope("ledger.promote", "AC_SCHEMA_INVALID", "ledger promote requires --rollback-plan");
+    }
+    const daemon = await requiredLedgerRuntime(runtime);
+    return runLedgerPromotionPreflight(cwd, daemon, targetMode);
+  }
   if (subcommand === "project") {
     if (!args2.includes("--to-git")) {
       return errorEnvelope("ledger.project", "AC_SCHEMA_INVALID", "ledger project currently requires --to-git");
@@ -26533,13 +26639,124 @@ async function runLedgerCommand(args2, cwd, runtime) {
       expectedWorktreeDigest
     });
   }
-  return errorEnvelope("ledger", "AC_SCHEMA_INVALID", "ledger requires status, state, drift --json, migrate --from-yaml, rebuild --from-git, rollback --to-yaml, or project --to-git");
+  return errorEnvelope("ledger", "AC_SCHEMA_INVALID", "ledger requires status, state, drift --json, promote --mode authoritative --preflight --rollback-plan, migrate --from-yaml, rebuild --from-git, rollback --to-yaml, or project --to-git");
 }
 async function requiredLedgerRuntime(runtime) {
   if (!runtime)
     throw new Error("ledger command requires runtime daemon");
   return runtime();
 }
+function normalizeLedgerPromotionTargetMode(value) {
+  if (value === "authoritative" || value === "ledger-authoritative" || value === "ledger")
+    return "ledger-authoritative";
+  return;
+}
+async function runLedgerPromotionPreflight(cwd, daemon, targetMode) {
+  const stateEnvelope = await daemon.ledgerState(cwd);
+  if (!stateEnvelope.ok)
+    return stateEnvelope;
+  const driftEnvelope = await daemon.ledgerDrift(cwd);
+  if (!driftEnvelope.ok)
+    return driftEnvelope;
+  const state = readObject(stateEnvelope.data);
+  const driftData = readObject(driftEnvelope.data);
+  const architectureLedger = readObject(state.architectureLedger);
+  const phaseFlags = readObject(architectureLedger.phaseFlags);
+  const currentPhase = String(phaseFlags.activePhase ?? architectureLedger.rolloutMode ?? "unknown");
+  const worktree = readObject(state.worktree);
+  const ledger3 = readObject(state.ledger);
+  const yaml = readObject(state.yaml);
+  const drift = readObject(driftData.drift ?? state.drift);
+  const reconcile = readObject(driftData.reconcile ?? state.reconcile);
+  const worktreeDigest = typeof worktree.worktreeDigest === "string" ? worktree.worktreeDigest : "<current>";
+  const nextRequiredPhase = nextLedgerPromotionPhase(currentPhase);
+  const preconditions = {
+    currentPhase,
+    targetMode,
+    noModeSkip: currentPhase === "ledger-shadow" || currentPhase === targetMode,
+    driftClean: drift.ok === true,
+    reconcileClean: reconcile.ok === true,
+    unsupportedYamlFilesAbsent: Number(yaml.unsupportedFileCount ?? 0) === 0,
+    ledgerStatePresent: Number(ledger3.entityCount ?? 0) + Number(ledger3.relationCount ?? 0) + Number(ledger3.constraintCount ?? 0) > 0,
+    rollbackPlanPresent: true,
+    hardEnforcementUnchanged: true
+  };
+  const alreadyActive = currentPhase === targetMode;
+  const ready = !alreadyActive && Object.values(preconditions).every((value) => value === true || typeof value === "string");
+  const reasonCodes = [
+    ...alreadyActive ? ["already-ledger-authoritative"] : [],
+    ...preconditions.noModeSkip ? [] : [`mode-sequence-not-ready:${currentPhase}->${nextRequiredPhase ?? "ledger-shadow"}`],
+    ...preconditions.driftClean ? [] : ["ledger-yaml-drift-not-clean"],
+    ...preconditions.reconcileClean ? [] : ["ledger-reconcile-not-clean"],
+    ...preconditions.unsupportedYamlFilesAbsent ? [] : ["unsupported-yaml-files-present"],
+    ...preconditions.ledgerStatePresent ? [] : ["ledger-state-empty"]
+  ];
+  return okEnvelope("ledger.promote", {
+    schemaVersion: "archcontext.runtime-architecture-ledger-promotion-preflight/v1",
+    targetMode,
+    status: alreadyActive ? "already-active" : ready ? "ready" : "blocked",
+    ready,
+    writes: "none",
+    sideEffects: {
+      ledgerModeChanged: false,
+      hardEnforcementChanged: false,
+      sqliteMutated: false,
+      yamlMutated: false
+    },
+    repository: state.repository,
+    worktree: state.worktree,
+    current: {
+      phase: currentPhase,
+      readMode: architectureLedger.readMode,
+      writeMode: architectureLedger.writeMode,
+      readAuthority: architectureLedger.readAuthority,
+      writeAuthority: architectureLedger.writeAuthority,
+      graphDigest: state.graphDigest,
+      ledgerGraphDigest: ledger3.graphDigest,
+      yamlGraphDigest: yaml.graphDigest
+    },
+    preconditions,
+    reasonCodes,
+    nextRequiredPhase,
+    recommendedEnvironment: {
+      ARCHCONTEXT_LEDGER_MODE: targetMode,
+      ARCHCONTEXT_LEDGER_READ_MODE: "ledger",
+      ARCHCONTEXT_LEDGER_WRITE_MODE: "ledger-with-projection"
+    },
+    rollbackPlan: {
+      required: true,
+      targetAuthority: "yaml",
+      dryRunCommand: "archctx ledger rollback --to-yaml --dry-run",
+      command: `archctx ledger rollback --to-yaml --write --expected-worktree-digest ${worktreeDigest}`,
+      commandTemplate: "archctx ledger rollback --to-yaml --write --expected-worktree-digest <current>",
+      environment: {
+        ARCHCONTEXT_LEDGER_MODE: "yaml",
+        ARCHCONTEXT_LEDGER_READ_MODE: "yaml",
+        ARCHCONTEXT_LEDGER_WRITE_MODE: "yaml"
+      }
+    },
+    boundary: {
+      advisoryDefaultPreserved: true,
+      productionGaClaimed: false,
+      hardEnforcementEnabled: false,
+      operatorActionRequired: true
+    }
+  });
+}
+function nextLedgerPromotionPhase(currentPhase) {
+  if (currentPhase === "yaml")
+    return "dual";
+  if (currentPhase === "dual")
+    return "ledger-shadow";
+  if (currentPhase === "ledger-shadow")
+    return "ledger-authoritative";
+  if (currentPhase === "ledger-authoritative")
+    return null;
+  return "yaml";
+}
+function readObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
 async function runBookCommand(args2, cwd, daemon) {
   const subcommand = args2[0] ?? "status";
   const maxItems = readOptionalNonNegativeIntegerFlag(args2, "--max-items", "book");
@@ -28241,39 +28458,9 @@ async function createCliRuntime(cwd, deps) {
       return;
     } };
   if (!deps.disableRpcDiscovery && !hasEmbeddedRuntimeDeps(deps)) {
-    const fileIssue = runtimeRpcCompatibilityIssue(cwd);
-    if (fileIssue?.pidAlive)
-      throw new RuntimeVersionUnsupportedError(fileIssue);
-    const client = createRuntimeRpcClientFromConnectionFile(cwd);
-    if (client) {
-      const health = await client.health().catch(() => {
-        return;
-      });
-      const healthIssue = runtimeRpcCompatibilityIssueFromHealth(cwd, client, health);
-      if (healthIssue)
-        throw new RuntimeVersionUnsupportedError(healthIssue);
-      if (health?.ok === true)
-        return { client, close: async () => {
-          return;
-        } };
-      recoverStaleDaemonControlFiles(cwd, { removeUnhealthyConnection: true });
-    } else {
-      recoverStaleDaemonControlFiles(cwd);
-    }
-    const started = await startBackgroundDaemon([], cwd);
-    if (!started.ok)
-      throw new Error(started.error?.message ?? "archctxd did not start");
-    const startedClient = createRuntimeRpcClientFromConnectionFile(cwd);
-    if (startedClient) {
-      const health = await startedClient.health().catch(() => {
-        return;
-      });
-      if (health?.ok === true)
-        return { client: startedClient, close: async () => {
-          return;
-        } };
-    }
-    throw new Error("archctxd started but no healthy runtime RPC connection was available");
+    return { client: await createOrStartRuntimeRpcClient(cwd), close: async () => {
+      return;
+    } };
   }
   const {
     runtimeClient: _runtimeClient,
@@ -28294,6 +28481,40 @@ async function createCliRuntime(cwd, deps) {
   });
   return { client: daemon, close: () => daemon.stop() };
 }
+async function createOrStartRuntimeRpcClient(cwd) {
+  const fileIssue = runtimeRpcCompatibilityIssue(cwd);
+  if (fileIssue?.pidAlive)
+    throw new RuntimeVersionUnsupportedError(fileIssue);
+  const client = createRuntimeRpcClientFromConnectionFile(cwd);
+  if (client) {
+    const health = await client.health().catch(() => {
+      return;
+    });
+    const healthIssue = runtimeRpcCompatibilityIssueFromHealth(cwd, client, health);
+    if (healthIssue)
+      throw new RuntimeVersionUnsupportedError(healthIssue);
+    if (health?.ok === true)
+      return client;
+    recoverStaleDaemonControlFiles(cwd, { removeUnhealthyConnection: true });
+  } else {
+    recoverStaleDaemonControlFiles(cwd);
+  }
+  const started = await startBackgroundDaemon([], cwd);
+  if (!started.ok)
+    throw new Error(mcpDaemonStartRecoveryMessage(started.error?.message ?? "archctxd did not start"));
+  const startedClient = createRuntimeRpcClientFromConnectionFile(cwd);
+  if (startedClient) {
+    const health = await startedClient.health().catch(() => {
+      return;
+    });
+    if (health?.ok === true)
+      return startedClient;
+  }
+  throw new Error(mcpDaemonStartRecoveryMessage("archctxd started but no healthy runtime RPC connection was available"));
+}
+function mcpDaemonStartRecoveryMessage(message) {
+  return message.includes("archctx daemon") ? message : `${message}; run \`archctx daemon start\` before using the local MCP surface`;
+}
 function hasEmbeddedRuntimeDeps(deps) {
   return [
     "codeFacts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archctx",
-  "version": "0.1.4-beta.0",
+  "version": "0.1.5",
   "description": "Local architecture context CLI for agentic coding workflows.",
   "private": false,
   "type": "module",
@@ -16,7 +16,7 @@
     "README.md"
   ],
   "homepage": "https://archcontext.repoharness.com",
-  "license": "UNLICENSED",
+  "license": "Apache-2.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },