forge-memory 0.2.108 → 0.2.110

package/bin/forge-memory.mjs

@@ -179,6 +179,14 @@ function webUrl(config) {
   return `${baseUrl(config)}/forge/`;
 }
 
+function localHostHeader(config) {
+  return `127.0.0.1:${config.port || DEFAULT_PORT}`;
+}
+
+function forgeApiUrl(config, pathname) {
+  return new URL(pathname, baseUrl(config));
+}
+
 async function readJson(filePath, fallback = null) {
   try {
     return JSON.parse(await fsp.readFile(filePath, "utf8"));
@@ -734,13 +742,8 @@ async function patchCodexConfig(config, options) {
     `FORGE_DATA_ROOT = "${config.dataRoot.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`,
     ""
   ].join("\n");
-  const pattern =
-    /(?:^|\n)\[mcp_servers\.forge\][\s\S]*?(?=\n\[[^\]]+\]|\s*$)/m;
-  if (pattern.test(source)) {
-    source = source.replace(pattern, `\n${block}`.trimEnd());
-  } else {
-    source = `${source.trimEnd()}\n\n${block}`.trimStart();
-  }
+  const cleaned = stripCodexForgeMcpConfig(source).trimEnd();
+  source = `${cleaned ? `${cleaned}\n\n` : ""}${block}`;
   if (!options.dryRun) {
     await fsp.mkdir(path.dirname(filePath), { recursive: true });
     await backupIfExists(filePath);
@@ -753,6 +756,44 @@ async function patchCodexConfig(config, options) {
   return { filePath };
 }
 
+function stripCodexForgeMcpConfig(source) {
+  const orphanForgeLines = new Set([
+    'command = "npx"',
+    'args = ["forge-memory", "mcp"]',
+    "FORGE_ORIGIN",
+    "FORGE_PORT",
+    "FORGE_ACTOR_LABEL",
+    "FORGE_TIMEOUT_MS",
+    "FORGE_DATA_ROOT"
+  ]);
+  const lines = source.split(/\r?\n/);
+  const kept = [];
+  let skippingForgeTable = false;
+  let currentTable = null;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    const tableMatch = trimmed.match(/^\[([^\]]+)\]$/);
+    if (tableMatch) {
+      currentTable = tableMatch[1];
+      skippingForgeTable = currentTable === "mcp_servers.forge" ||
+        currentTable.startsWith("mcp_servers.forge.");
+      if (skippingForgeTable) continue;
+    }
+    if (skippingForgeTable) continue;
+    const isGlobalOrphanForgeLine =
+      currentTable === null &&
+      (orphanForgeLines.has(trimmed) ||
+        Array.from(orphanForgeLines).some((prefix) =>
+          trimmed.startsWith(`${prefix} =`)
+        ));
+    if (isGlobalOrphanForgeLine) {
+      continue;
+    }
+    kept.push(line);
+  }
+  return kept.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd();
+}
+
 async function runCommand(
   command,
   args,
@@ -895,12 +936,28 @@ async function health(config, timeoutMs = 1_500) {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    const response = await fetch(new URL("/api/v1/health", baseUrl(config)), {
-      headers: { accept: "application/json" },
+    const response = await fetch(forgeApiUrl(config, "/api/v1/health"), {
+      headers: { accept: "application/json", "x-forge-runtime-probe": "1" },
       signal: controller.signal
     });
     if (!response.ok) return { ok: false, status: response.status };
-    return { ok: true, payload: await response.json() };
+    const text = await response.text();
+    let payload;
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      return {
+        ok: true,
+        status: response.status,
+        error: "HTTP health endpoint returned non-JSON content",
+        forge: false
+      };
+    }
+    return {
+      ok: true,
+      payload,
+      forge: isForgeHealthPayload(payload)
+    };
   } catch (error) {
     return {
       ok: false,
@@ -911,6 +968,11 @@ async function health(config, timeoutMs = 1_500) {
   }
 }
 
+function isForgeHealthPayload(payload) {
+  if (!payload || typeof payload !== "object") return false;
+  return payload.app === "forge" && payload.backend === "forge-node-runtime";
+}
+
 function describeNetworkError(error) {
   if (error instanceof Error) {
     if (error.name === "AbortError") return "request timed out";
@@ -922,12 +984,17 @@ function describeNetworkError(error) {
 }
 
 function describeHealthResult(result) {
+  if (result.ok && result.forge === false) return "HTTP 200 from a non-Forge service";
   if (result.ok) return "healthy";
   if (result.status) return `HTTP ${result.status}`;
   if (result.error) return result.error;
   return "not reachable";
 }
 
+function isHealthyForgeRuntime(result) {
+  return Boolean(result?.ok && result.forge !== false);
+}
+
 async function readRuntimeState() {
   return readJson(runtimeStatePath(), null);
 }
@@ -951,8 +1018,8 @@ async function waitForHealth(config, timeoutMs = 30_000) {
   return health(config);
 }
 
-function resolveOpenClawPluginRoot() {
-  const candidates = [require];
+function resolveOpenClawPluginRoot(options = {}) {
+  const candidates = [];
   const installedRuntimePackageJson = path.join(
     runtimeInstallRoot(),
     "package.json"
@@ -960,6 +1027,9 @@ function resolveOpenClawPluginRoot() {
   if (fs.existsSync(installedRuntimePackageJson)) {
     candidates.push(createRequire(installedRuntimePackageJson));
   }
+  if (!options.installedOnly) {
+    candidates.push(require);
+  }
 
   for (const candidateRequire of candidates) {
     try {
@@ -975,8 +1045,10 @@ function resolveOpenClawPluginRoot() {
   return null;
 }
 
-async function ensurePackagedRuntimeInstalled() {
-  const existing = resolveOpenClawPluginRoot();
+async function ensurePackagedRuntimeInstalled(options = {}) {
+  const existing = options.forceInstall
+    ? null
+    : resolveOpenClawPluginRoot();
   if (existing) return existing;
   const installRoot = runtimeInstallRoot();
   await fsp.mkdir(installRoot, { recursive: true });
@@ -1012,19 +1084,108 @@ async function ensurePackagedRuntimeInstalled() {
       ].join(" ")
     );
   }
-  const installed = resolveOpenClawPluginRoot();
+  const installed = resolveOpenClawPluginRoot({ installedOnly: true });
   if (!installed)
     throw new Error(
       `${RUNTIME_PACKAGE} installed but its runtime entry could not be resolved. Log: ${logPath()}`
     );
+  const entry = path.join(installed, "server", "index.js");
+  if (!fs.existsSync(entry)) {
+    throw new Error(
+      `${RUNTIME_PACKAGE} installed but ${entry} is missing. Log: ${logPath()}`
+    );
+  }
   return installed;
 }
 
+async function rotateRuntimeLog(reason) {
+  if (!fs.existsSync(logPath())) return null;
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const backupPath = `${logPath()}.${reason}-${stamp}.log`;
+  await fsp.mkdir(path.dirname(backupPath), { recursive: true });
+  await fsp.copyFile(logPath(), backupPath);
+  return backupPath;
+}
+
+async function repairPackagedRuntimeCache(config) {
+  if (config.mode === "dev") {
+    const result = await startRuntime(config);
+    return {
+      ok: result.ok,
+      mode: "dev",
+      dataRoot: config.dataRoot,
+      health: result.health ?? { ok: result.ok }
+    };
+  }
+
+  await stopRuntime();
+  const rotatedLogPath = await rotateRuntimeLog("repair");
+  await fsp.rm(runtimeStatePath(), { force: true });
+  await fsp.rm(runtimeInstallRoot(), { recursive: true, force: true });
+  const pluginRoot = await ensurePackagedRuntimeInstalled({ forceInstall: true });
+  const result = await startRuntime(config);
+  const record = {
+    repairedAt: new Date().toISOString(),
+    ok: result.ok,
+    mode: config.mode,
+    runtimePackage: RUNTIME_PACKAGE,
+    runtimePackageVersion: RUNTIME_PACKAGE_VERSION,
+    pluginRoot,
+    dataRoot: config.dataRoot,
+    dataPreserved: true,
+    rotatedLogPath,
+    health: result.health ?? { ok: result.ok }
+  };
+  const stamp = record.repairedAt.replace(/[:.]/g, "-");
+  const repairRecordPath = path.join(forgeHome(), "run", `runtime-repair-${stamp}.json`);
+  await fsp.mkdir(path.dirname(repairRecordPath), { recursive: true });
+  await fsp.writeFile(repairRecordPath, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+  return { ...record, repairRecordPath };
+}
+
 async function startRuntime(config) {
+  const current = await health(config);
+  if (isHealthyForgeRuntime(current)) {
+    const existing = await readRuntimeState();
+    return {
+      ok: true,
+      started: false,
+      adopted: true,
+      state: existing,
+      health: current
+    };
+  }
+  if (current.ok && current.forge === false) {
+    return {
+      ok: false,
+      started: false,
+      state: await readRuntimeState(),
+      health: current,
+      portConflict: true,
+      message: `Port ${config.port || DEFAULT_PORT} is already serving a non-Forge HTTP service.`
+    };
+  }
+  if (!(await isPortAvailable(config.port || DEFAULT_PORT))) {
+    return {
+      ok: false,
+      started: false,
+      state: await readRuntimeState(),
+      health: current,
+      portConflict: true,
+      message: `Port ${config.port || DEFAULT_PORT} is already in use.`
+    };
+  }
   const existing = await readRuntimeState();
   if (existing?.pid && processExists(existing.pid)) {
-    const current = await health(config);
-    if (current.ok) return { ok: true, started: false, state: existing };
+    const existingHealth = await health(config);
+    if (isHealthyForgeRuntime(existingHealth))
+      return {
+        ok: true,
+        started: false,
+        adopted: true,
+        state: existing,
+        health: existingHealth
+      };
   }
 
   await fsp.mkdir(path.dirname(logPath()), { recursive: true });
@@ -1122,6 +1283,18 @@ async function startRuntime(config) {
 
 function assertRuntimeStartedForPairing(result, config) {
   if (result?.ok) return;
+  if (result?.portConflict) {
+    throw new Error(
+      [
+        `Forge runtime did not start because ${baseUrl(config)} is already in use by another service.`,
+        `Health check: ${describeHealthResult(result?.health ?? { ok: false })}.`,
+        "Run npx forge-memory status to inspect the configured runtime.",
+        "If Forge Memory owns the running process, run npx forge-memory stop; otherwise stop the conflicting process or choose another --port.",
+        `Runtime log: ${logPath()}.`,
+        "Your data folder is unchanged."
+      ].join(" ")
+    );
+  }
   throw new Error(
     [
       `Forge runtime did not become healthy at ${baseUrl(config)}, so iOS pairing was not started.`,
@@ -1132,22 +1305,38 @@ function assertRuntimeStartedForPairing(result, config) {
   );
 }
 
-async function stopRuntime() {
+async function stopRuntime(config = null) {
+  const effectiveConfig = config ?? (await readConfig());
   const state = await readRuntimeState();
-  if (!state?.children?.length)
-    return {
-      ok: true,
-      stopped: false,
-      message: "No forge-memory runtime state found."
-    };
   const stopped = [];
-  for (const child of state.children) {
+  for (const child of state?.children ?? []) {
     if (!child?.pid || !processExists(child.pid)) continue;
     process.kill(child.pid, "SIGTERM");
     stopped.push(child.pid);
   }
+  const current = await health(effectiveConfig);
+  const runtimePid = Number(current?.payload?.runtime?.pid);
+  if (
+    isHealthyForgeRuntime(current) &&
+    Number.isInteger(runtimePid) &&
+    runtimePid > 0 &&
+    !stopped.includes(runtimePid) &&
+    processExists(runtimePid)
+  ) {
+    process.kill(runtimePid, "SIGTERM");
+    stopped.push(runtimePid);
+  }
   await fsp.rm(runtimeStatePath(), { force: true });
-  return { ok: true, stopped: stopped.length > 0, pids: stopped };
+  if (stopped.length === 0) {
+    return {
+      ok: true,
+      stopped: false,
+      message: state?.children?.length
+        ? "No recorded Forge Memory runtime processes were alive."
+        : "No Forge Memory runtime state or live Forge runtime was found."
+    };
+  }
+  return { ok: true, stopped: true, pids: stopped };
 }
 
 async function exportForgeData(parsed) {
@@ -1274,14 +1463,9 @@ async function removeCodexAdapterConfig() {
   const filePath = path.join(homeDir(), ".codex", "config.toml");
   if (!fs.existsSync(filePath)) return { filePath, changed: false };
   const source = await fsp.readFile(filePath, "utf8");
-  const pattern =
-    /(?:^|\n)\[mcp_servers\.forge\][\s\S]*?(?=\n\[[^\]]+\]|\s*$)/m;
-  if (!pattern.test(source)) return { filePath, changed: false };
+  const next = stripCodexForgeMcpConfig(source);
+  if (next === source.trimEnd()) return { filePath, changed: false };
   await backupIfExists(filePath);
-  const next = source
-    .replace(pattern, "\n")
-    .replace(/\n{3,}/g, "\n\n")
-    .trimEnd();
   await fsp.writeFile(filePath, next ? `${next}\n` : "", "utf8");
   return { filePath, changed: true };
 }
@@ -1363,10 +1547,100 @@ function normalizePublicPairingUrl(value) {
   }
 }
 
+function readSetCookieHeader(headers) {
+  if (typeof headers.getSetCookie === "function") {
+    const values = headers.getSetCookie();
+    if (values.length > 0) return values[0];
+  }
+  return headers.get("set-cookie");
+}
+
+function cookiePairFromSetCookie(value) {
+  if (!value) return null;
+  return value.split(";")[0]?.trim() || null;
+}
+
+class PairingAuthError extends Error {
+  constructor(message, detail = {}) {
+    super(message);
+    this.name = "PairingAuthError";
+    this.code = "pairing_auth_failed";
+    this.detail = detail;
+    this.guidance = [
+      "Forge is reachable, but Forge Memory could not create a local operator session for iOS pairing.",
+      "Run npx forge-memory doctor to confirm the runtime is healthy.",
+      "Then rerun npx forge-memory pair-ios."
+    ];
+  }
+}
+
+class PairingRequestError extends Error {
+  constructor(message, detail = {}) {
+    super(message);
+    this.name = "PairingRequestError";
+    this.code = "pairing_request_failed";
+    this.detail = detail;
+    this.guidance =
+      detail.status === 401
+        ? [
+            "Forge is reachable, but the pairing request was not authenticated.",
+            "Forge Memory should bootstrap a local operator session before pairing; rerun npx forge-memory pair-ios after updating.",
+            "Run npx forge-memory doctor only if runtime health also fails."
+          ]
+        : [
+            "Forge is reachable, but it rejected the iOS pairing request.",
+            "Run npx forge-memory doctor to confirm runtime health, then inspect the response above."
+          ];
+  }
+}
+
+async function bootstrapLocalOperatorSession(config) {
+  const sessionUrl = forgeApiUrl(config, "/api/v1/auth/operator-session");
+  let response;
+  try {
+    response = await fetch(sessionUrl, {
+      method: "GET",
+      headers: {
+        accept: "application/json",
+        host: localHostHeader(config)
+      }
+    });
+  } catch (error) {
+    throw new PairingAuthError(
+      [
+        `Could not create a local operator session at ${sessionUrl}.`,
+        `Network: ${describeNetworkError(error)}.`
+      ].join(" "),
+      { url: sessionUrl.toString() }
+    );
+  }
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new PairingAuthError(
+      [
+        `Could not create a local operator session at ${sessionUrl}: Forge returned HTTP ${response.status}.`,
+        body ? `Response: ${body.slice(0, 500)}` : ""
+      ]
+        .filter(Boolean)
+        .join(" "),
+      { url: sessionUrl.toString(), status: response.status }
+    );
+  }
+  const cookie = cookiePairFromSetCookie(readSetCookieHeader(response.headers));
+  if (!cookie) {
+    throw new PairingAuthError(
+      `Could not create a local operator session at ${sessionUrl}: Forge did not return a session cookie.`,
+      { url: sessionUrl.toString(), status: response.status }
+    );
+  }
+  return cookie;
+}
+
 async function createPairing(config, options = {}) {
   const transportMode = options.transportMode ?? "iroh";
-  const publicUrl = normalizePublicPairingUrl(options.publicUrl);
-  const pairingUrl = new URL("/api/v1/health/pairing-sessions", baseUrl(config));
+  const publicUrl = validatePairingOptions({ transportMode, publicUrl: options.publicUrl });
+  const pairingUrl = forgeApiUrl(config, "/api/v1/health/pairing-sessions");
+  const operatorCookie = await bootstrapLocalOperatorSession(config);
   let response;
   try {
     response = await fetch(pairingUrl, {
@@ -1374,6 +1648,7 @@ async function createPairing(config, options = {}) {
       headers: {
         "content-type": "application/json",
         accept: "application/json",
+        cookie: operatorCookie,
         ...(publicUrl ? { referer: publicUrl } : {})
       },
       body: JSON.stringify({ userId: null, transportMode })
@@ -1396,19 +1671,49 @@ async function createPairing(config, options = {}) {
   }
   if (!response.ok) {
     const body = await response.text().catch(() => "");
-    throw new Error(
+    throw new PairingRequestError(
       [
         `Could not create iOS pairing at ${pairingUrl}: Forge returned HTTP ${response.status}.`,
         body ? `Response: ${body.slice(0, 500)}` : "",
-        `Run npx forge-memory doctor --repair and inspect ${logPath()}.`
+        response.status === 401
+          ? "Forge Memory did not obtain or pass a valid local operator session cookie."
+          : "Inspect the response and rerun npx forge-memory doctor if runtime health is uncertain."
       ]
         .filter(Boolean)
-        .join(" ")
+        .join(" "),
+      { url: pairingUrl.toString(), status: response.status }
     );
   }
   return response.json();
 }
 
+function validatePairingOptions({ transportMode, publicUrl }) {
+  const normalizedPublicUrl = normalizePublicPairingUrl(publicUrl);
+  if (transportMode !== "manual-http") {
+    return normalizedPublicUrl;
+  }
+  if (!normalizedPublicUrl) {
+    throw new Error(
+      [
+        "Manual HTTP pairing for a physical iPhone requires --public-url.",
+        "Use a phone-reachable Tailscale or LAN Forge URL, for example:",
+        "npx forge-memory pair-ios --manual-http --public-url https://your-mac.tailnet.ts.net/forge/",
+        "For normal pairing, omit --manual-http and use the default Iroh transport."
+      ].join(" ")
+    );
+  }
+  if (isLoopbackPairingUrl(normalizedPublicUrl)) {
+    throw new Error(
+      [
+        `Manual HTTP --public-url points at ${normalizedPublicUrl}, which is loopback-only.`,
+        "A physical iPhone cannot reach localhost on this Mac.",
+        "Use a Tailscale or LAN URL, or omit --manual-http and use Iroh pairing."
+      ].join(" ")
+    );
+  }
+  return normalizedPublicUrl;
+}
+
 function compactPairingPayload(payload) {
   const transport = payload.transport
     ? {
@@ -1426,7 +1731,7 @@ function compactPairingPayload(payload) {
         notes: []
       }
     : undefined;
-  return {
+  return compactObject({
     kind: payload.kind,
     apiBaseUrl: payload.apiBaseUrl,
     uiBaseUrl: payload.uiBaseUrl,
@@ -1436,7 +1741,25 @@ function compactPairingPayload(payload) {
     pairingToken: payload.pairingToken,
     expiresAt: payload.expiresAt,
     capabilities: payload.capabilities
-  };
+  });
+}
+
+function compactObject(value) {
+  if (Array.isArray(value)) {
+    const compacted = value.map((entry) => compactObject(entry)).filter((entry) => entry !== undefined);
+    return compacted.length ? compacted : undefined;
+  }
+  if (!value || typeof value !== "object") {
+    return value ?? undefined;
+  }
+  const output = {};
+  for (const [key, entry] of Object.entries(value)) {
+    const compacted = compactObject(entry);
+    if (compacted !== undefined && !(Array.isArray(compacted) && compacted.length === 0)) {
+      output[key] = compacted;
+    }
+  }
+  return Object.keys(output).length ? output : undefined;
 }
 
 async function writePairingPayloadFile(payload) {
@@ -1462,8 +1785,15 @@ function isLoopbackPairingUrl(value) {
 async function printPairing(pairing) {
   const payload = compactPairingPayload(pairing.qrPayload);
   const payloadText = JSON.stringify(payload);
-  console.log("\nScan this compact QR in Forge Companion:\n");
-  qrcode.generate(payloadText, { small: true });
+  const terminalColumns = process.stdout.columns ?? 120;
+  if (terminalColumns >= 72 && payloadText.length <= 2_950) {
+    console.log("\nScan this compact QR in Forge Companion:\n");
+    qrcode.generate(payloadText, { small: true });
+  } else {
+    console.log("");
+    console.log(color.yellow("QR skipped because the terminal is too narrow or the payload is too large to scan reliably."));
+    console.log("Use Manual connection in the iPhone app and paste the saved payload below.");
+  }
   const transport = payload.transport;
   if (transport?.provider) {
     const label =
@@ -1665,25 +1995,34 @@ async function runStatus(parsed) {
   const config = await readConfig();
   const state = await readRuntimeState();
   const currentHealth = await health(config);
+  const stateExists = fs.existsSync(runtimeStatePath());
+  const running = isHealthyForgeRuntime(currentHealth);
   const payload = {
-    ok: currentHealth.ok,
-    running: currentHealth.ok,
+    ok: running,
+    running,
     mode: config.mode,
     baseUrl: baseUrl(config),
     webUrl: webUrl(config),
     dataRoot: config.dataRoot,
     adapters: config.adapters,
+    health: currentHealth,
+    runtimeStatePath: runtimeStatePath(),
+    runtimeStateExists: stateExists,
+    adoptedRuntime: running && !stateExists,
     state
   };
   if (parsed.flags.json) console.log(JSON.stringify(payload, null, 2));
   else {
     console.log(`${color.bold("Forge Memory Status")}`);
     console.log(
-      `Runtime: ${currentHealth.ok ? color.green("healthy") : color.yellow("not reachable")}`
+      `Runtime: ${running ? color.green("healthy") : color.yellow(describeHealthResult(currentHealth))}`
     );
     console.log(`Mode: ${config.mode}`);
     console.log(`UI: ${webUrl(config)}`);
     console.log(`Data: ${config.dataRoot}`);
+    console.log(
+      `Runtime state: ${stateExists ? runtimeStatePath() : color.yellow("missing; healthy runtimes will be adopted")}`
+    );
     console.log(
       `Adapters: ${config.adapters.length ? config.adapters.join(", ") : "none configured"}`
     );
@@ -1694,19 +2033,37 @@ async function runStatus(parsed) {
 async function doctorCheckRuntime(config, options) {
   let result = await health(config);
   let repaired = false;
-  if (!result.ok && options.repair && !options.noStart && !options.dryRun) {
-    await startRuntime(config);
+  let repairRecordPath = null;
+  if (
+    !isHealthyForgeRuntime(result) &&
+    !(result.ok && result.forge === false) &&
+    options.repair &&
+    !options.noStart &&
+    !options.dryRun
+  ) {
+    const repair = await repairPackagedRuntimeCache(config);
+    repairRecordPath = repair.repairRecordPath ?? null;
     result = await health(config, 3_000);
-    repaired = result.ok;
+    repaired = isHealthyForgeRuntime(result);
   }
+  const ok = isHealthyForgeRuntime(result);
   return {
     id: "runtime",
-    ok: result.ok,
-    detail: baseUrl(config),
+    ok,
+    detail:
+      result.ok && result.forge === false
+        ? `${baseUrl(config)} (non-Forge service responded)`
+        : baseUrl(config),
     repaired,
-    guidance: result.ok
+    repairRecordPath,
+    health: result,
+    statePath: runtimeStatePath(),
+    stateExists: fs.existsSync(runtimeStatePath()),
+    guidance: ok
       ? "Forge API is reachable."
-      : `Run npx forge-memory doctor --repair, then inspect ${logPath()} if the runtime still does not start.`
+      : result.ok && result.forge === false
+        ? `Port ${config.port || DEFAULT_PORT} responded, but not with Forge runtime health. Stop the conflicting process or choose another --port.`
+      : `Run npx forge-memory doctor --repair, then inspect ${logPath()} if the runtime still does not start. Repair reinstalls only the owned runtime cache and preserves the data folder.`
   };
 }
 
@@ -1816,6 +2173,11 @@ async function runUi(parsed) {
 
 async function runPairIos(parsed) {
   const config = await readConfig();
+  const transportMode = parsed.flags.manualHttp ? "manual-http" : "iroh";
+  const publicUrl = validatePairingOptions({
+    transportMode,
+    publicUrl: parsed.values.publicUrl
+  });
   if (!parsed.flags.noStart) {
     const runtimeResult = await withProgress(
       "Starting Forge runtime for iOS pairing",
@@ -1824,10 +2186,16 @@ async function runPairIos(parsed) {
       () => startRuntime(config)
     );
     assertRuntimeStartedForPairing(runtimeResult, config);
+  } else {
+    const currentHealth = await health(config, 3_000);
+    assertRuntimeStartedForPairing(
+      { ok: currentHealth.ok, started: false, health: currentHealth },
+      config
+    );
   }
   const pairing = await createPairing(config, {
-    transportMode: parsed.flags.manualHttp ? "manual-http" : "iroh",
-    publicUrl: parsed.values.publicUrl
+    transportMode,
+    publicUrl
   });
   if (parsed.flags.json) {
     console.log(JSON.stringify(pairing, null, 2));
@@ -2256,14 +2624,22 @@ async function main() {
 
 function printFatalError(error, { json = false } = {}) {
   const message = error instanceof Error ? error.message : String(error);
+  const guidance =
+    error && typeof error === "object" && Array.isArray(error.guidance)
+      ? error.guidance
+      : [
+          "Run npx forge-memory doctor --repair to check and repair the local install.",
+          "Run npx forge-memory logs to inspect the runtime log.",
+          "Forge Memory repair never deletes your data folder."
+        ];
   const payload = {
     ok: false,
+    code:
+      error && typeof error === "object" && typeof error.code === "string"
+        ? error.code
+        : "forge_memory_failed",
     error: message,
-    guidance: [
-      "Run npx forge-memory doctor --repair to check and repair the local install.",
-      "Run npx forge-memory logs to inspect the runtime log.",
-      "Forge Memory repair never deletes your data folder."
-    ],
+    guidance,
     logPath: logPath()
   };
   if (json) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-memory",
-  "version": "0.2.108",
+  "version": "0.2.110",
   "description": "Guided Forge installer and local runtime manager for the Forge UI, OpenClaw, Hermes, Codex, and iOS pairing.",
   "type": "module",
   "license": "Apache-2.0",