truthspine 0.2.1 → 0.2.2

package/README.md

@@ -4,12 +4,24 @@
 
 The free MCP connector for TruthSpine, the local-first project-truth app for AI agents.
 
-The keeper of your projects. You lead the work. TruthSpine keeps the truth automatically.
+Stop re-explaining your project to every new AI chat. It works on your computer, with no cloud account and nothing extra to install.
 
-One checked record of what was decided, what was done, what failed and what comes next. Every connected chat starts already knowing your project. Your project stays on your computer.
+One checked record of what was decided, what was done, what failed and what comes next. Every connected chat checks your project before it answers, so you never re-explain it. Your project stays on your computer.
 
 This is the free connector. It needs the TruthSpine desktop app installed on the same computer: the [Microsoft Store](https://apps.microsoft.com/detail/9pbn25k75vdj) on Windows, the [Mac App Store](https://apps.apple.com/app/id6794478470) on macOS, or the AppImage from [truthspine.app](https://truthspine.app/download) on Linux.
 
+## See it
+
+![Codex in VS Code is asked what was decided for custom cake orders and answers from TruthSpine's saved record: $39.](https://truthspine.app/media/listing/truthspine-codex-demo.gif)
+
+*Codex in VS Code. Real recording, waits shortened.*
+
+![Every new chat makes me explain the entire project again. Every connected chat checks your project before it answers, so you never re-explain it.](https://truthspine.app/media/listing/truthspine-panel-1.png)
+
+![My agents drift onto old plans or the wrong project. Each chat works with its own project, and the current decisions win over old ones.](https://truthspine.app/media/listing/truthspine-panel-2.png)
+
+![Built to work where You work. 19 AI apps on Windows, 18 on Mac and Linux, and cloud agents through Remote access.](https://truthspine.app/media/listing/truthspine-panel-6.png)
+
 ## Setup
 
 1. Install and open the TruthSpine app, and connect your project folder in it.
@@ -43,18 +55,18 @@ The TruthSpine app can also write these settings for you: open Connections and c
 
 ## Tools
 
-- `truthspine_attach`: Attach this chat to the project's TruthSpine record and receive the current brief: decisions, completed work, evidence and next steps.
-- `truthspine_consult`: Ask what is true about the project, what was decided and why, or what to do next. Read only.
-- `truthspine_record`: Save a decision, finished work, a failure or the next step to the project's record on this computer.
-- `truthspine_history`: Read what was saved recently, or confirm that a save was recorded. Read only.
+- `attach`: Attach this chat to the project's TruthSpine record and receive the current brief: decisions, completed work, evidence and next steps.
+- `consult`: Ask what is true about the project, what was decided and why, or what to do next. Read only.
+- `record`: Save a decision, finished work, a failure or the next step to the project's record on this computer.
+- `history`: Read what was saved recently, or confirm that a save was recorded. Read only.
 
 ## Licence
 
-This connector is free (Apache License 2.0). It needs the TruthSpine app, which you get and buy separately.
-Installing the connector does not start a trial or need its own license.
-On Windows, start the free 14-day trial in the TruthSpine app. Then buy once in the Microsoft Store: $99.99 at the launch price (regular price $249.99), for V1 and every 1.x update. Reinstalling does not restart the trial.
-On Mac, start the free 14-day trial in the TruthSpine app. Then buy once in the App Store: $99.99 at the launch price (regular price $249.99), for V1 and every 1.x update. Restore Purchases brings it back on your other Macs.
-On Linux, the TruthSpine AppImage from truthspine.app starts with a free 14-day trial. Then buy once from us: $99.99 at the launch price (regular price $249.99), for V1 and every 1.x update, on up to three of your own Linux computers. You can move it between them in the app.
+This connector is open source (Apache License 2.0). It needs the TruthSpine app, which you get separately.
+The connector needs no license of its own.
+On Windows, get the TruthSpine app from the Microsoft Store.
+On Mac, get the TruthSpine app from the App Store.
+On Linux, get the TruthSpine AppImage from truthspine.app.
 
 ## Privacy Policy
 

package/bin/truthspine-mcp.mjs

@@ -26,12 +26,15 @@ try {
   startupStage = "installed-runtime-start";
   process.env.TRUTHSPINE_RUNTIME_REGISTRATION_PATH = contract.defaultRuntimeRegistrationPath();
   connection = await launcher.startInstalledMcpLauncherWithRecovery({ signal: controller.signal });
-  const result = await connection.closed;
-  process.exitCode = result.code;
-} catch {
+  if (!connection?.inPlace) { const result = await connection.closed; process.exitCode = result.code; }
+} catch (error) {
   const guidance = startupStage === "workspace-binding"
     ? "Start it inside your project folder or pass --project <folder>. Licensing has not been checked; do not sign in or purchase to resolve this."
     : "Install and open the TruthSpine app, connect this project in it, and check --host names your tool. This startup error alone does not establish a licensing failure.";
-  process.stderr.write(`TruthSpine startup failed at ${startupStage}. ${guidance}\n`);
+  const said = (value, most) => String(value ?? "").replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/(?:[A-Za-z]:)?[\\/][^\s'"`]+/g, "[path]").trim().slice(0, most);
+  const where = String(error?.stack ?? "").split("\n").slice(1).map(frame => /at (?:async )?([\w.$<>]+) \(.*?([\w.-]+):(\d+):\d+\)$/.exec(frame.trim())).filter(Boolean).slice(0, 3).map(([, name, file, line]) => `${name} ${file}:${line}`).join(" < ");
+  const words = /purchase is not affected/i.test(String(error?.message ?? "")) ? "" : said(error?.message ?? error, 400);
+  const cause = [said(error?.code, 80), words, where && `at ${where}`].filter(Boolean).join(": ");
+  process.stderr.write(`TruthSpine startup failed at ${startupStage}. ${guidance}${cause ? ` Cause: ${cause}` : ""}\n`);
   process.exitCode = 1;
 } finally { process.removeListener("SIGINT", stop); process.removeListener("SIGTERM", stop); }

package/lib/claude-lifecycle-contract.cjs

@@ -16,7 +16,7 @@ function buildClaudeSessionStartRequest(input, { homeDir, platform = process.pla
     || event.session_id.length > 2048 || /[\u0000-\u001f\u007f]/.test(event.session_id)) fail();
   const { projectRoot } = launcher.resolveBoundedHostWorkspace({ cwd: event.cwd, homeDir, platform });
   return Object.freeze({
-    tool: "truthspine_onboard_chat",
+    tool: "onboard_chat",
     // Host/workspace are fixed by the transport, not overridable tool selectors.
     // Older catalogs reject identityMode before tools/call, preventing silent
     // fallback to the old per-attachment/title-derived chat identity.
@@ -28,7 +28,7 @@ function buildClaudeSessionStartRequest(input, { homeDir, platform = process.pla
 
 function formatClaudeSessionStartResult(request, result) {
   const metrics = result?.metrics;
-  if (!request || request.tool !== "truthspine_onboard_chat"
+  if (!request || request.tool !== "onboard_chat"
     || result?.project?.projectRoot !== request.projectRoot
     || result?.binding?.hostSurface !== "claude-code"
     || result?.binding?.hostChatIdHash !== request.sessionIdHash
@@ -36,19 +36,31 @@ function formatClaudeSessionStartResult(request, result) {
     || typeof metrics?.label !== "string" || !/^[a-z0-9][a-z0-9_-]{0,255}$/.test(metrics.label)
     || metrics.runId !== metrics.label || metrics.sourceRef !== metrics.label
     || !/^[a-f0-9]{32}$/.test(metrics.chatSessionFingerprint || "")) fail();
-  const readScope = { chatId: metrics.label, chatSessionFingerprint: metrics.chatSessionFingerprint };
-  const syncIdentity = { runId: metrics.label, sourceRef: metrics.label,
-    chatSessionFingerprint: metrics.chatSessionFingerprint };
-  return {
-    hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: [
-      "TruthSpine has returned this session's workspace-bound attachment identity.",
-      `Use this readScope for project-dependent TruthSpine reads: ${JSON.stringify(readScope)}.`,
-      `Use this identity for governed session updates: ${JSON.stringify(syncIdentity)}.`,
-      `For an explicit Attach TruthSpine request in this same host session/workspace, call truthspine_onboard_chat with these exact arguments: ${JSON.stringify(request.arguments)}. Never replace them with an empty object or a guessed title/ID.`,
-      "Consult truthspine_answer_guard before project-dependent answers and actions. Persist meaningful work deltas through governed session updates using this same identity; do not copy another chat's identity.",
-      "These identifiers provide attribution, not owner authorization or proof that reported work is correct."
-    ].join("\n") }
-  };
+  const identity = [
+    "TruthSpine has returned this session's workspace-bound attachment identity.",
+    `For an explicit Attach TruthSpine request in this same host session/workspace, call attach with these exact arguments: ${JSON.stringify(request.arguments)}. Never replace them with an empty object or a guessed title/ID.`,
+    "Consult answer_guard before project-dependent answers and actions. Save meaningful work with record; do not copy another chat's identity.",
+    "These identifiers provide attribution, not owner authorization or proof that reported work is correct."
+  ].join("\n");
+  return { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: withProjectPacket(identity, result?.packet?.text) } };
+}
+// The session starts with the project itself (B2, Brain 2026-11-01: "every new session starts already knowing my project"
+// was true nowhere, since the hook gave only the identity): the connect reply's packet follows the identity lines. Claude
+// Code keeps a hook's text to 10,000 characters and shows only a short preview of anything longer, so the whole text stays
+// under HOOK_CONTEXT_LIMIT, the packet cut at a whole line with a pointer to the rest.
+const HOOK_CONTEXT_LIMIT = 9500;
+function withProjectPacket(identity, packet) {
+  const text = typeof packet === "string" ? packet.replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, "").trim() : "";
+  if (!text) return identity;
+  const head = `${identity}\n\nThis project, as TruthSpine keeps it now:\n`;
+  const rest = "\n(Shortened here; consult answer_guard for the rest.)";
+  if (head.length + text.length <= HOOK_CONTEXT_LIMIT) return head + text;
+  let kept = "";
+  for (const line of text.split("\n")) {
+    if (head.length + kept.length + line.length + 1 + rest.length > HOOK_CONTEXT_LIMIT) break;
+    kept += `${kept ? "\n" : ""}${line}`;
+  }
+  return kept ? head + kept + rest : identity;
 }
 // Where the installed app records itself (the same place the app writes it). Used when a
 // public connector carries no machine-specific path; an explicit setting still wins.

package/lib/installed-mcp-launcher.cjs

@@ -23,6 +23,8 @@ const fail = () => { throw new Error(ERROR); };
 const LAUNCHER_RESULTS = Object.freeze({
   app_not_installed: "TruthSpine isn't installed on this computer.",
   app_not_running: "TruthSpine is installed but not running. Open it and try again.",
+  app_not_answering: "TruthSpine is installed but did not answer. Open the TruthSpine app and try again.",
+  app_not_opened: "TruthSpine is installed but has not been opened yet. Open TruthSpine once, then try again.",
   unavailable: ERROR
 });
 const LAUNCHER_STORE_LINKS = Object.freeze({ win32: "https://apps.microsoft.com/detail/9pbn25k75vdj", darwin: "https://apps.apple.com/us/app/truthspine/id6794478470?mt=12" });
@@ -36,13 +38,27 @@ const typedCode = error => {
 // The one line a person should read when the launcher cannot connect.
 function describeLauncherFailure(error, platform) {
   const code = typedCode(error) || "unavailable";
-  const link = code === "app_not_installed" ? LAUNCHER_STORE_LINKS[platform || process.platform] : undefined;
-  return { code, message: LAUNCHER_RESULTS[code] + (link ? " Install it from " + link : ""), storeLink: link };
+  const where = platform || process.platform;
+  const link = code === "app_not_installed" ? LAUNCHER_STORE_LINKS[where] : undefined;
+  // (truthspine.app on every platform, and Linux its own page: B8)
+  const get = code === "app_not_installed" ? " Get it here: " + (link ? link + " or " + DOWNLOAD_PAGE : LAUNCHER_GET_LINKS[where] || DOWNLOAD_PAGE) : "";
+  return { code, message: LAUNCHER_RESULTS[code] + get, storeLink: link };
 }
 const object = value => value !== null && typeof value === "object" && !Array.isArray(value);
 // "continue" stays accepted so an entry an earlier version wrote keeps starting; TruthSpine no longer offers or writes it
 // (Continue retired by the owner, 2026-10-09).
 const HOST_IDS = new Set(["claude-desktop", "claude-code", "codex-cli", "cursor", "vscode", "github-copilot-vscode", "continue", "cline", "cline-cli", "windsurf-devin", "opencode", "opencode-ide", "lm-studio", "kiro", "antigravity", "jetbrains", "zed", "hermes-agent", "openclaw", "copilot-cli", "droid", "pi", "computer-agent", "gemini-cli"]);
+// The smaller tool set each app gets; every app not named here gets the full catalog. Nothing falls into a smaller set by
+// default: Claude Code did, from the copilot fallback (2026-09-08) and its joining the host list (2026-09-24), and a
+// shipped package refused its session_update (Brain 2026-10-29).
+const HOST_TOOL_PROFILES = Object.freeze({
+  "claude-desktop": "claude-desktop",
+  "lm-studio": "lm-studio",
+  opencode: "local-agent", "hermes-agent": "local-agent", openclaw: "local-agent", droid: "local-agent", pi: "local-agent",
+  vscode: "copilot", // VS Code's own sync command carries its session updates, not this connection
+  "github-copilot-vscode": "copilot", // the same VS Code extension and sync command
+  "copilot-cli": "copilot" // named so since July (surface-connector-runtime.js)
+});
 function absolute(value, paths) {
   if (typeof value !== "string" || !value.trim() || value !== value.trim()
     || /[\u0000-\u001f\u007f]/.test(value) || !paths.isAbsolute(value)) fail();
@@ -154,16 +170,42 @@ function systemTempFolder(root, platform, env) {
   if (platform === process.platform) { try { named.push(require("node:os").tmpdir()); } catch { /* no temporary folder known */ } }
   return named.some(base => typeof base === "string" && paths.isAbsolute(base) && equal(root, paths.resolve(base), platform));
 }
+// TruthSpine's own throwaway folders (Brain 2026-10-28): a folder named truthspine-* in a temporary folder, and every
+// folder inside one, is made by TruthSpine's tests and checks, never by the person; one test run on the owner PC
+// (2026-09-27) left twenty such projects' data in the person's own TruthSpine home. A TruthSpine home that itself lives
+// in a temporary folder (a test's or a check's own) keeps them as projects.
+function temporaryFolders(platform, env) {
+  const paths = platform === "win32" ? path.win32 : path.posix;
+  const folders = platform === "win32" ? [env.TEMP, env.TMP, env.LOCALAPPDATA && paths.join(env.LOCALAPPDATA, "Temp")]
+    : [env.TMPDIR, "/tmp", "/var/tmp", "/private/tmp", "/private/var/tmp", ...(platform === "darwin" ? ["/var/folders", "/private/var/folders"] : [])];
+  if (platform === process.platform) {
+    try { folders.push(require("node:os").tmpdir()); } catch { /* no temporary folder known */ }
+    const account = platform === "win32" ? accountHomeFolder() : null;
+    if (account) folders.push(paths.join(account, "AppData", "Local", "Temp"));
+  }
+  return folders.filter(folder => typeof folder === "string" && paths.isAbsolute(folder)).map(folder => paths.resolve(folder));
+}
+function throwawayFolder(root, homeDir, platform, env) {
+  const paths = platform === "win32" ? path.win32 : path.posix;
+  const temps = temporaryFolders(platform, env);
+  let made = false;
+  for (let folder = root; !made && paths.dirname(folder) !== folder; folder = paths.dirname(folder)) {
+    made = /^truthspine-/i.test(paths.basename(folder)) && temps.some(temp => equal(paths.dirname(folder), temp, platform));
+  }
+  const truthHome = env.TRUTHSPINE_HOME || (typeof homeDir === "string" && paths.isAbsolute(homeDir) ? paths.join(homeDir, ".truthspine") : null);
+  if (!made || typeof truthHome !== "string" || !paths.isAbsolute(truthHome)) return false;
+  return !temps.some(temp => insideFolder(paths.resolve(truthHome), temp, platform));
+}
 // Judged by the path alone (a sandboxed relay may not look inside the folder): the disk root, a home folder (the one
-// given and the account's own), a system or program folder, the temporary folder itself, or an AI app's own folder is
-// never a project.
+// given and the account's own), a system or program folder, the temporary folder itself, TruthSpine's own throwaway
+// folders, or an AI app's own folder is never a project.
 function neverAProjectFolder(folder, { homeDir, platform = process.platform, env = process.env } = {}) {
   const paths = platform === "win32" ? path.win32 : path.posix;
   if (typeof folder !== "string" || !paths.isAbsolute(folder)) return true;
   // (also for a saved project: the start-of-app tidy then removes a "MICROS~1" project an earlier version made)
   const root = longWindowsName(paths.resolve(folder), platform);
   if (equal(root, paths.parse(root).root, platform) || systemOrProgramFolder(root, platform, env || {})
-    || systemTempFolder(root, platform, env || {})) return true;
+    || systemTempFolder(root, platform, env || {}) || throwawayFolder(root, homeDir, platform, env || {})) return true;
   const homes = [homeDir, platform === process.platform ? accountHomeFolder() : null].filter(home => typeof home === "string" && paths.isAbsolute(home));
   return homes.some(home => equal(root, paths.resolve(home), platform) || appOwnFolder(root, home, platform));
 }
@@ -203,10 +245,30 @@ function restrictiveTelemetryEnv(...sources) {
   }) ? { TRUTHSPINE_TELEMETRY_MODE: "disabled" } : {};
 }
 
+// Whether TruthSpine's own files are where its installer puts them (Brain 2026-11-01, B8): a copy installed but never opened
+// has written no install record yet, and is told to open TruthSpine once rather than to get it. Names only, nothing run:
+// the Store's command in WindowsApps, the app in Applications, the snap's or the system package's command.
+function installedAppPresent({ platform = process.platform, env = process.env, homeDir = env.HOME || env.USERPROFILE || "",
+  exists = file => fs.existsSync(file), names = folder => fs.readdirSync(folder) } = {}) {
+  try {
+    if (platform === "win32") {
+      // (the execution alias is listed, never read: reading it may fail while starting it works)
+      const folder = typeof env.LOCALAPPDATA === "string" && path.win32.isAbsolute(env.LOCALAPPDATA) ? path.win32.join(env.LOCALAPPDATA, "Microsoft", "WindowsApps") : null;
+      return Boolean(folder) && names(folder).some(name => name.toLowerCase() === "truthspine-runtime.exe");
+    }
+    if (platform === "darwin") return ["/Applications/TruthSpine.app", homeDir ? path.posix.join(homeDir, "Applications", "TruthSpine.app") : null].some(file => file && exists(file));
+    if (platform === "linux") return Object.values(LINUX_PACKAGE_COMMANDS).some(file => exists(file));
+  } catch { /* not found */ }
+  return false;
+}
+
 function readRegistration(filename) {
   let fd;
   try {
-    const before = fs.lstatSync(filename);
+    // (no record at all: TruthSpine has never been installed and opened on this computer, B8; or installed, never opened)
+    let before;
+    try { before = fs.lstatSync(filename); }
+    catch (error) { if (error && error.code === "ENOENT") typedFail(installedAppPresent() ? "app_not_opened" : "app_not_installed"); fail(); }
     if (!before.isFile() || before.isSymbolicLink() || before.size > 65536) fail();
     fd = fs.openSync(filename, "r");
     const opened = fs.fstatSync(fd);
@@ -218,17 +280,23 @@ function readRegistration(filename) {
     const parsed = JSON.parse(buffer.subarray(0, used).toString("utf8"));
     if (!object(parsed) || parsed.schema !== "truthspine.installed-runtime.v1") fail();
     return parsed;
-  } catch { fail(); }
+  } catch (error) { if (["app_not_installed", "app_not_opened"].includes(typedCode(error))) throw error; fail(); }
   finally { if (fd !== undefined) fs.closeSync(fd); }
 }
 
 const WINDOWS_OS_NAMES = new Set(["systemroot", "windir", "comspec", "temp", "tmp", "userprofile", "localappdata", "appdata",
   "programfiles", "programfiles(x86)", "programdata", "allusersprofile", "public", "processor_architecture",
-  "number_of_processors", "computername", "os", "pathext", "path"]);
+  "number_of_processors", "computername", "os", "pathext", "path", "tz"]);
 // Linux: what the AppImage runtime and the server need to find the user's folders, and nothing else.
+// (TZ on both: a chat server reads the day in the zone the app reads it in, Brain 2026-10-30)
 const LINUX_OS_NAMES = new Set(["home", "path", "user", "logname", "lang", "lc_all", "lc_ctype", "lc_messages", "tmpdir",
-  "xdg_data_home", "xdg_config_home", "xdg_cache_home", "xdg_runtime_dir", "appimage_extract_and_run"]);
+  "xdg_data_home", "xdg_config_home", "xdg_cache_home", "xdg_runtime_dir", "appimage_extract_and_run", "tz"]);
 const LINUX_APP_ROOT = "@app";
+// The fixed launchers of the Linux packages that have one (src/packaged-platform.cjs keeps the same table; this file ships
+// alone in the VS Code extension, so it keeps its own copy, and a test keeps the two the same). The snap's follows store
+// updates; a versioned /snap/truthspine/<revision>/ path is never accepted.
+const LINUX_PACKAGE_COMMANDS = Object.freeze({ "linux-snap": "/snap/bin/truthspine", "linux-system": "/usr/bin/truthspine" });
+const linuxPackageCommand = name => (typeof name === "string" && Object.prototype.hasOwnProperty.call(LINUX_PACKAGE_COMMANDS, name) ? LINUX_PACKAGE_COMMANDS[name] : null);
 function installedChildEnv({ env, platform, profile, root, hostId, developmentBuild = false }) {
   const childEnv = {};
   const osNames = platform === "linux" ? LINUX_OS_NAMES : WINDOWS_OS_NAMES;
@@ -245,12 +313,9 @@ function installedChildEnv({ env, platform, profile, root, hostId, developmentBu
     ...(root && env.TRUTHSPINE_PROJECT_FROM_CWD === "1" ? { TRUTHSPINE_FOLLOWED_FOLDER: "1" } : {}),
     TRUTHSPINE_HOST_ID: hostId,
     TRUTHSPINE_MCP_OUTPUT_FRAMING: "jsonl" });
-  // Codex retains its existing full catalog, including session_update. Host
-  // identity is a policy selector, not authentication or permission to broaden
-  // another host's advertised tool profile.
-  if (!["codex-cli", "cursor", "kiro", "antigravity", "jetbrains", "zed"].includes(hostId)) childEnv.TRUTHSPINE_MCP_TOOL_PROFILE = hostId === "claude-desktop"
-    ? "claude-desktop"
-    : hostId === "lm-studio" ? "lm-studio" : ["opencode", "hermes-agent", "openclaw", "droid", "pi"].includes(hostId) ? "local-agent" : "copilot";
+  // Host identity is a policy selector, not authentication or permission to broaden another host's advertised tool
+  // profile. An app HOST_TOOL_PROFILES does not name keeps the full catalog, including session_update.
+  if (Object.hasOwn(HOST_TOOL_PROFILES, hostId)) childEnv.TRUTHSPINE_MCP_TOOL_PROFILE = HOST_TOOL_PROFILES[hostId];
   // Preserve an existing restrictive opt-out, never an ambient opt-in or
   // telemetry identity. Dropping an opt-out could enable collection when the
   // registered profile has consent. This grants no product access.
@@ -283,13 +348,15 @@ function buildInstalledMcpLaunchPlan({ registration, registrationPath, projectRo
       socketPath: paths.join(dataRoot, ".ts", `mcp-${hash}.sock`) });
   }
   if (platform === "linux") {
-    // Linux AppImage lane (P12). The AppImage file is the one stable path: the app inside it is mounted
-    // under /tmp at a new path on every launch, so no mount path is trusted. The AppImage's AppRun turns
-    // a leading "@app/" argument into a path inside its own mount.
+    // Linux packaged lane (P12). The AppImage file, or the package's fixed launcher (the snap's /snap/bin/truthspine), is
+    // the one stable path: the app inside an AppImage is mounted under /tmp at a new path on every launch, and a snap's
+    // folder changes with each update, so no path inside the package is trusted. The package's own entry point (AppRun,
+    // the snap's truthspine-launch) turns a leading "@app/" argument into a path inside it.
     const provenance = registration.runtimeProvenance;
     const command = absolute(registration.command, paths);
-    if (!object(provenance) || provenance.packaged !== true || provenance.packagedPlatform !== "linux-appimage"
-      || !/[.]AppImage$/.test(paths.basename(command))
+    const fixed = object(provenance) ? linuxPackageCommand(provenance.packagedPlatform) : null;
+    if (!object(provenance) || provenance.packaged !== true
+      || !(provenance.packagedPlatform === "linux-appimage" ? /[.]AppImage$/.test(paths.basename(command)) : fixed !== null && command === fixed)
       || !equal(absolute(provenance.appExecutable, paths), command, platform)) fail();
     return Object.freeze({ mode: "installed-stdio", platform, hostId, packageRoot: LINUX_APP_ROOT, command,
       args: Object.freeze([`${LINUX_APP_ROOT}/src/mcp-server.js`]), cwd: root ?? profile, projectRoot: root, truthHome: profile,
@@ -512,7 +579,8 @@ function inPlaceHandover(plan, { platform = process.platform, execPath = process
   const paths = platform === "win32" ? path.win32 : path.posix;
   let serverPath;
   if (platform === "linux") {
-    if (typeof env.APPIMAGE !== "string" || !paths.isAbsolute(env.APPIMAGE) || !equal(paths.resolve(env.APPIMAGE), plan.command, platform)) return null;
+    const sameAppImage = typeof env.APPIMAGE === "string" && paths.isAbsolute(env.APPIMAGE) && equal(paths.resolve(env.APPIMAGE), plan.command, platform);
+    if (!sameAppImage && linuxPackageCommand(env.TRUTHSPINE_PACKAGED_PLATFORM) !== plan.command) return null;
     if (plan.args[0] !== `${LINUX_APP_ROOT}/src/mcp-server.js`) return null;
     serverPath = paths.join(paths.dirname(execPath), "resources", "app", "src", "mcp-server.js");
   } else {
@@ -535,10 +603,8 @@ async function handOverInPlace(handover, { importer = file => import(require("no
   return { inPlace: true };
 }
 
-async function startInstalledMcpLauncherWithRecovery({ signal, inPlace = handOverInPlace } = {}) {
-  if (signal?.aborted) fail();
-  const delegated = relayDelegationPlan();
-  if (delegated) return relayInstalledMcp(delegated);
+// The installed copy's plan, validated; Windows tries the Store package again when the recorded one is gone.
+async function installedPlan(signal) {
   const options = installedLauncherOptions();
   let plan = buildInstalledMcpLaunchPlan(options);
   try { validateInstalledLaunchPlan(plan); }
@@ -546,11 +612,193 @@ async function startInstalledMcpLauncherWithRecovery({ signal, inPlace = handOve
     if (plan.platform !== 'win32') throw error;
     plan = (await prepareRecoveredMcpPlan(options, { signal })).plan;
   }
+  return plan;
+}
+
+// With no TruthSpine to reach (B8, Brain 2026-11-01): the connection stays up and answers by itself, so the chat can say
+// "TruthSpine isn't installed yet. Get it here: <link>" instead of the app showing a server that failed. The page opens
+// only when the chat calls open_download_page after the person says yes, and once TruthSpine is there the next tool call
+// connects this same chat to it (the person's first message is passed on, and the app is told the tools changed).
+// A copy that starts but does not answer within NO_ANSWER_MS is given up the same way.
+const NO_ANSWER_MS = 10000;
+const LAUNCHER_GET_LINKS = Object.freeze({ ...LAUNCHER_STORE_LINKS, linux: "https://truthspine.app/download/linux" });
+const DOWNLOAD_PAGE = "https://truthspine.app/download";
+function noAppLines(code, platform) {
+  const link = LAUNCHER_GET_LINKS[platform] || DOWNLOAD_PAGE;
+  if (code === "app_not_installed") return { link, say: `TruthSpine isn't installed yet. Get it here: ${link}`,
+    next: "Ask the person whether to open this page now, and call open_download_page only if they say yes. Once TruthSpine is installed and open, call attach again: this chat then connects by itself." };
+  const say = code === "app_not_opened" ? "Open TruthSpine once. It is installed on this computer but has not been opened yet, so chats can't reach it."
+    : code === "app_not_running" ? "TruthSpine is installed but not running. Open the TruthSpine app, then ask again."
+    : "TruthSpine is installed but did not answer. Open the TruthSpine app, then ask again.";
+  return { link: null, say, next: "Once it is open, call attach again: this chat then connects by itself." };
+}
+function openPage(url, platform, spawnImpl = spawn) {
+  const [command, args] = platform === "win32" ? ["explorer.exe", [url]] : platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
+  const child = spawnImpl(command, args, { detached: true, stdio: "ignore", windowsHide: true, shell: false });
+  child.on("error", () => {}); child.unref();
+}
+// Newline-framed JSON-RPC lines from a stream (MCP over standard input and output).
+function readLines(stream, onLine) {
+  let pending = "";
+  const onData = chunk => {
+    pending += chunk.toString("utf8");
+    let end;
+    while ((end = pending.indexOf("\n")) !== -1) { const line = pending.slice(0, end).replace(/\r$/, ""); pending = pending.slice(end + 1); if (line.trim()) onLine(line); }
+  };
+  stream.on("data", onData);
+  return () => stream.removeListener("data", onData);
+}
+const parse = line => { try { const message = JSON.parse(line); return object(message) ? message : null; } catch { return null; } };
+
+// Relays to the installed copy, and gives it up when it does not answer the app's first request in time (onSilent gets the
+// lines it was sent). Lines come in through send(); the copy's answers go to output, the swallowed id's answer excepted.
+function answeredRelay(plan, { output, waitMs = NO_ANSWER_MS, onSilent, onAnswered = () => {}, swallowId = null, relay = relayInstalledMcp }) {
+  const { PassThrough } = require("node:stream");
+  const toCopy = new PassThrough(), fromCopy = new PassThrough();
+  const sent = [];
+  let waitingFor = undefined, answered = false, gaveUp = false, timer = null;
+  const connection = relay(plan, { input: toCopy, output: fromCopy });
+  function giveUp() {
+    if (gaveUp) return;
+    gaveUp = true; clearTimeout(timer); stopReading(); connection.stop(1);
+    onSilent(sent.slice());
+  }
+  const stopReading = readLines(fromCopy, line => {
+    if (gaveUp) return;
+    const message = parse(line);
+    if (message && !answered && waitingFor !== undefined && message.id === waitingFor) { answered = true; clearTimeout(timer); onAnswered(); }
+    if (message && swallowId !== null && message.id === swallowId) return;
+    output.write(line + "\n");
+  });
+  // (a copy that ends before it answered is given up too)
+  connection.closed.then(result => { if (!answered && !gaveUp && result.code !== 0) giveUp(); });
+  return {
+    connection,
+    send(line) {
+      if (gaveUp) return false;
+      // (the wait starts with the app's first request: an app may start the connection long before it asks anything)
+      if (waitingFor === undefined) {
+        const message = parse(line);
+        if (message && message.id !== undefined && message.id !== null) { waitingFor = message.id; timer = setTimeout(() => { if (!answered) giveUp(); }, waitMs); }
+      }
+      if (!answered) sent.push(line);
+      toCopy.write(line + "\n");
+      return true;
+    },
+    end() { if (!gaveUp) { clearTimeout(timer); toCopy.end(); } },
+    gaveUp: () => gaveUp
+  };
+}
+
+function serveWithoutApp(code, { input = process.stdin, output = process.stdout, platform = process.platform, attempt,
+  waitMs = NO_ANSWER_MS, spawnImpl = spawn, retryEveryMs = 10000, now = () => Date.now(), relay = relayInstalledMcp, earlier = [] } = {}) {
+  let resolveClosed, live = null, init = null, lastTry = -Infinity, trying = null, done = false;
+  const closed = new Promise(resolve => { resolveClosed = resolve; });
+  const write = message => output.write(JSON.stringify(message) + "\n");
+  const lines = () => noAppLines(code, platform);
+  const finish = codeOut => { if (done) return; done = true; stopReading(); input.removeListener("end", ended); resolveClosed({ code: codeOut, pid: null, cleanupConfirmed: true }); };
+  const ended = () => { if (live) { live.end(); live.connection.closed.then(result => finish(result.code)); } else finish(0); };
+  const tools = () => [{ name: "attach", description: `Connect TruthSpine. ${lines().say}`, inputSchema: { type: "object", properties: {}, additionalProperties: true } }]
+    .concat(code === "app_not_installed" ? [{ name: "open_download_page", description: "Open the TruthSpine download page in the browser. Call it only after the person says yes.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false } }] : []);
+  const answer = message => {
+    const { method, id } = message;
+    const reply = result => { if (id !== undefined && id !== null) write({ jsonrpc: "2.0", id, result }); };
+    if (method === "initialize") {
+      init = message;
+      return reply({ protocolVersion: (message.params && message.params.protocolVersion) || "2025-06-18", capabilities: { tools: { listChanged: true } },
+        serverInfo: { name: "truthspine", version: "not-connected" }, instructions: `${lines().say} ${lines().next}` });
+    }
+    if (method === "tools/list") return reply({ tools: tools() });
+    if (method === "resources/list") return reply({ resources: [] });
+    if (method === "prompts/list") return reply({ prompts: [] });
+    if (method === "ping") return reply({});
+    if (method === "tools/call") {
+      const name = message.params && message.params.name;
+      if (name === "open_download_page" && code === "app_not_installed") {
+        try { openPage(lines().link, platform, spawnImpl); return reply({ content: [{ type: "text", text: `Opened ${lines().link}. ${lines().next}` }] }); }
+        catch { return reply({ content: [{ type: "text", text: `Could not open the page. The link is ${lines().link}.` }] }); }
+      }
+      return reply({ content: [{ type: "text", text: `${lines().say} ${lines().next}` }] });
+    }
+    if (typeof method === "string" && method.indexOf("notifications/") === 0) return undefined;
+    if (id !== undefined && id !== null) write({ jsonrpc: "2.0", id, error: { code: -32601, message: lines().say } });
+    return undefined;
+  };
+  // Once TruthSpine is there: the copy gets the app's first request under its own id (its answer is not passed on, the app
+  // has one already), the initialized notice, then the waiting call; the app hears that the tools changed.
+  async function connect(callLine) {
+    let plan;
+    try { plan = await attempt(); } catch (error) { const next = typedCode(error); if (next && next !== code && next !== "unavailable") code = next; return false; }
+    if (done) return false;
+    const handoverId = `truthspine-handover-${crypto.randomUUID()}`;
+    let copy = null;
+    const outcome = new Promise(resolve => {
+      copy = answeredRelay(plan, { output, waitMs, relay, swallowId: handoverId, onAnswered: () => resolve("answered"),
+        onSilent: () => { code = "app_not_answering"; resolve("silent"); } });
+    });
+    const first = init ? { ...init, id: handoverId } : { jsonrpc: "2.0", id: handoverId, method: "initialize",
+      params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "truthspine-launcher", version: "1" } } };
+    copy.send(JSON.stringify(first));
+    if (await outcome !== "answered" || done) { if (!copy.gaveUp()) copy.connection.stop(1); return false; }
+    copy.send(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }));
+    live = copy;
+    copy.connection.closed.then(result => finish(result.code));
+    write({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
+    live.send(callLine);
+    return true;
+  }
+  const onLine = line => {
+    if (live) { live.send(line); return; }
+    const message = parse(line);
+    if (!message) return;
+    if (message.method === "tools/call" && !trying && now() - lastTry >= retryEveryMs && !(message.params && message.params.name === "open_download_page")) {
+      lastTry = now();
+      trying = connect(line).then(connected => { trying = null; if (!connected) answer(message); }, () => { trying = null; answer(message); });
+      return;
+    }
+    if (trying) { trying.then(() => onLine(line)); return; }
+    answer(message);
+  };
+  for (const line of earlier) onLine(line);
+  const stopReading = readLines(input, onLine);
+  input.once("end", ended);
+  if (input.readableEnded) ended();
+  return { closed, stop: codeOut => finish(codeOut || 0), pid: null, failure: () => code, withoutApp: true };
+}
+
+async function startInstalledMcpLauncherWithRecovery({ signal, inPlace = handOverInPlace, input = process.stdin, output = process.stdout,
+  waitMs = NO_ANSWER_MS, relay = relayInstalledMcp } = {}) {
+  if (signal?.aborted) fail();
+  const delegated = relayDelegationPlan();
+  if (delegated) return relayInstalledMcp(delegated);
+  let plan;
+  try { plan = await installedPlan(signal); }
+  catch (error) {
+    const code = typedCode(error);
+    if (!["app_not_installed", "app_not_opened", "app_not_running"].includes(code)) throw error;
+    return serveWithoutApp(code, { input, output, waitMs, relay, attempt: () => installedPlan(signal) });
+  }
   if (signal?.aborted) fail();
   // (only a plan that passed validation is ever handed over)
   const handover = inPlaceHandover(plan);
   if (handover) return inPlace(handover);
-  return relayInstalledMcp(plan);
+  if (plan.mode !== "installed-stdio") return relayInstalledMcp(plan);
+  // A copy that does not answer the app's first request in time is given up, and this connection answers by itself.
+  let resolveClosed, without = null;
+  const closed = new Promise(resolve => { resolveClosed = resolve; });
+  let watched;
+  const stopReading = readLines(input, line => { if (without) return; watched.send(line); });
+  const ended = () => { if (!without) watched.end(); };
+  watched = answeredRelay(plan, { output, waitMs, relay, onSilent: sent => {
+    stopReading(); input.removeListener("end", ended);
+    without = serveWithoutApp("app_not_answering", { input, output, waitMs, relay, attempt: () => installedPlan(signal), earlier: sent });
+    without.closed.then(resolveClosed);
+  } });
+  input.once("end", ended);
+  watched.connection.closed.then(result => { if (!watched.gaveUp()) { stopReading(); resolveClosed(result); } });
+  return { closed, stop: code => (without ? without.stop(code) : watched.connection.stop(code)), pid: watched.connection.pid,
+    failure: () => (without ? without.failure() : watched.connection.failure()) };
 }
 
 // Store package discovery stays in this single-file thin transport so generated
@@ -683,10 +931,10 @@ async function prepareRecoveredInstalledPlan(initial, signal) {
     recovered: selected.version !== registered[1] });
 }
 
-module.exports = { readRegistration, resolveBoundedHostWorkspace, neverAProjectFolder, scratchFolder, launcherProjectRoot, buildInstalledMcpLaunchPlan, buildInstalledCliLaunchPlan,
+module.exports = { HOST_IDS, HOST_TOOL_PROFILES, LINUX_PACKAGE_COMMANDS, readRegistration, resolveBoundedHostWorkspace, neverAProjectFolder, scratchFolder, launcherProjectRoot, buildInstalledMcpLaunchPlan, buildInstalledCliLaunchPlan,
   validateInstalledLaunchPlan, restrictiveTelemetryEnv, relayInstalledMcp, relayDelegationPlan, startInstalledMcpLauncher,
   startInstalledMcpLauncherWithRecovery, qualifyCurrentStorePackage, discoverCurrentStorePackage, prepareRecoveredMcpPlan, prepareRecoveredCliPlan,
-  LAUNCHER_RESULTS, LAUNCHER_STORE_LINKS, describeLauncherFailure, inPlaceHandover, handOverInPlace, IN_PLACE_RUNTIME_KEYS };
+  LAUNCHER_RESULTS, LAUNCHER_STORE_LINKS, LAUNCHER_GET_LINKS, installedAppPresent, NO_ANSWER_MS, describeLauncherFailure, serveWithoutApp, answeredRelay, inPlaceHandover, handOverInPlace, IN_PLACE_RUNTIME_KEYS };
 if (require.main === module) {
   const controller = new AbortController();
   let connection;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "truthspine",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Stop re-explaining your project to every new AI chat. MCP connector for TruthSpine: gives AI agents a checked, local record of your project (decisions, work done, failures, next steps). Works on your computer. No cloud account. Needs the TruthSpine app.",
   "license": "Apache-2.0",
   "author": {