@passioncode-ai/passioncode 0.2.49 → 0.2.51

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.2.51 - 2026-10-30
+
+### Fixed
+
+- `setup` finds an app one folder down in its zip, as Fabric Switchboard's archive holds it
+  (`Fabric-Switchboard-<v>-macos-universal/Fabric Switchboard.app`, 0.6.83 to 0.7.1); before, it
+  refused the release with "holds no Fabric Switchboard.app". Two copies in one archive are refused.
+- A release download or a GitHub API read whose connection drops before any answer is tried once
+  more after a second, instead of failing the install with "fetch failed".
+
+### Added
+
+- Release trains (PC-89, organization R1 N-12): `setup --train organization-r1` installs and
+  reinstalls each app at the version the train pins (`trains/organization-r1.json`) instead of its
+  latest release, and remembers the train; `doctor` compares every app with its pin, offline too,
+  in each `app.<id>` line and one `train` line, on macOS and Windows. An app ahead of its pin is
+  reported and never taken back, nor is one whose version cannot be read. `setup --train none` returns to the latest releases. The first
+  pins are the releases of 2026-10-28; the train's record in fabric-workspace decides later ones.
+  In `setup --json`, a change of train is an action of kind `train`, and a run that named a new
+  train but was only a plan carries `trainNotSaved`.
+
+## 0.2.50 - 2026-10-28
+
+### Changed
+
+- **Fabric Agent Adapter is pinned at `v0.57.0`** (it was `v0.56.0`): the kits read the Fabric Agent Contract at
+  `3830a33` (`v0.1.0+2026-10-27.6`). A person's comparison of codes is a human step (DEC-0142), the protocol register
+  knows the peer-share and organization-adaptation revisions, and on Windows the provider writer uses the folder Fabric
+  reads (PC-90).
+
 ## 0.2.49 - 2026-10-28
 
 ### Fixed

package/README.md

@@ -112,6 +112,18 @@ the family; each line names its state and its fix. Exit codes: **0** no check fa
 check (or a setup step) failed, **2** bad arguments. `doctor --fix` runs setup's repairs without
 installing new apps. Details: the [CLI contract](docs/reference/cli.md#setup-and-doctor).
 
+**Release trains.** An organization's machines install one set of pinned app versions instead of
+each app's latest release: `setup --train organization-r1` installs and reinstalls the apps at
+the versions in [`trains/organization-r1.json`](trains/organization-r1.json), remembers the train,
+and `doctor` then compares every app with its pin (offline too) in an `app.<id>` line per app and
+one `train` line. An app newer than its pin is reported and left alone (a damaged one, or one whose version cannot be read, is reinstalled from the latest
+release): the train never takes an app back, because its data may not open in an older release. `setup --train none` returns to the
+latest releases. Either change is saved with `--yes` or in a terminal; without both it is only
+shown as a plan. The skills are pinned by the launcher release itself (`family.json`). Which
+version each app pins is the train's record in fabric-workspace
+([SD-4](https://github.com/passioncode-ai/fabric-workspace/blob/main/knowledge/roadmap.md#sd-4)); a
+change to the file is a launcher release.
+
 ## Staying current
 
 At Claude Code session start the `passioncode` plugin uses a cached npm check for up

package/SECURITY.md

@@ -33,10 +33,13 @@ returns a nonzero exit code. See the [CLI recovery contract](docs/reference/cli.
 `~/.kimi-code/mcp.json` (entry names, commands and arguments; environment values are passed to
 the server it starts and never printed), the Fabric service descriptors (never their token
 files), the apps' `Info.plist` (on Windows, the apps' uninstall entries through `reg query` and their install folders),
+the launcher's own `trains/<name>.json` and the `train` it saved in `~/.passioncode/state.json`,
 and the GitHub releases API. It starts each registered stdio MCP
 server for one proving call and stops it (never Fabric's, which enrols a session as it starts), and writes only `~/.passioncode/doctor.json` and a
 release cache.
 
+`setup --train <name>` (or `none`) also writes that name into `~/.passioncode/state.json`; a train
+changes which release is downloaded (the pinned tag instead of the latest), never how it is verified.
 `setup` also downloads releases from GitHub into `~/.passioncode/downloads/` (removed after
 each app), copies a verified app into `/Applications`, moves an app it replaces into `~/.Trash/`,
 runs `update` (above), runs `launchctl kickstart gui/<uid>/<label>` for a family service whose

package/bin/passioncode.js

@@ -19,7 +19,7 @@ function cachedNpmStatus({ latest, checkedAt, installed }) {
 
 const HELP = `passioncode — set up and check PassionCode.ai on this machine: the apps, their MCP servers, the skills
 
-  npx @passioncode-ai/passioncode@latest setup [--yes] [--with ids] [--without ids] [--no-apps] [--no-open] [--dry-run] [--json]
+  npx @passioncode-ai/passioncode@latest setup [--yes] [--with ids] [--without ids] [--train name|none] [--no-apps] [--no-open] [--dry-run] [--json]
         a new machine: install and configure everything; an existing one: check, repair, check again
   npx @passioncode-ai/passioncode@latest doctor [--fix] [--json]        check everything (read-only); --fix repairs as setup does
   npx @passioncode-ai/passioncode@latest update [--dry-run] [--json]     install or update the skill set and the apps' MCP registrations
@@ -38,11 +38,16 @@ const IDS = ['switchboard', 'dashboards', 'observatory', 'inbox', 'fabric'];
 /** Flags of setup and doctor: booleans, plus --with/--without taking a comma list. Null when invalid. */
 function parseSetupArgs(cmd, rest) {
   const allowed = cmd === 'doctor' ? ['--fix', '--json', '--offline'] : ['--yes', '-y', '--json', '--offline', '--no-apps', '--no-open', '--dry-run'];
-  const o = { flags: new Set(), withIds: null, withoutIds: [] };
+  const o = { flags: new Set(), withIds: null, withoutIds: [], train: undefined };
   for (let i = 0; i < rest.length; i++) {
     const arg = rest[i];
     const m = /^--(with|without)(?:=(.*))?$/.exec(arg);
-    if (m && cmd !== 'doctor') {
+    const tr = /^--train(?:=(.*))?$/.exec(arg);
+    if (tr && cmd !== 'doctor') {
+      const value = tr[1] !== undefined ? tr[1] : rest[++i];
+      if (!value || o.train !== undefined) return null;
+      o.train = value === 'none' ? null : value; // PC-89: a release train's pinned versions instead of the latest
+    } else if (m && cmd !== 'doctor') {
       const value = m[2] !== undefined ? m[2] : rest[++i];
       const ids = String(value || '').split(',').map((x) => x.trim()).filter(Boolean);
       if (!ids.length || ids.some((x) => !IDS.includes(x))) return null;
@@ -68,6 +73,9 @@ async function setupOrDoctor(cmd, rest) {
     process.stderr.write(`passioncode: unsupported arguments for ${cmd}; run passioncode help. App ids: ${IDS.join(', ')}.\n`);
     return 2;
   }
+  if (o.train) {
+    try { require('../lib/trains').load(o.train); } catch (error) { process.stderr.write(`passioncode: ${error.message}.\n`); return 2; }
+  }
   const json = o.flags.has('--json');
   const online = !o.flags.has('--offline');
   if (cmd === 'doctor' && !o.flags.has('--fix')) {
@@ -81,7 +89,7 @@ async function setupOrDoctor(cmd, rest) {
   const log = json ? () => {} : (line) => process.stderr.write(`${line}\n`);
   const r = await S.setup({
     yes: repairOnly || o.flags.has('--yes'), withIds: o.withIds, withoutIds: o.withoutIds, noApps: o.flags.has('--no-apps'),
-    noOpen: o.flags.has('--no-open'), dryRun: o.flags.has('--dry-run'), repairOnly, online, ask: json ? null : asker(), log,
+    noOpen: o.flags.has('--no-open'), dryRun: o.flags.has('--dry-run'), repairOnly, online, ask: json ? null : asker(), log, train: o.train,
   });
   process.stdout.write(json ? JSON.stringify(r, null, 2) + '\n' : S.render(r, { repairOnly }) + '\n');
   return r.planOnly ? 0 : r.ok ? 0 : 1;

package/family.json

@@ -8,7 +8,7 @@
       "name": "fabric-agent-adapter",
       "displayName": "Fabric Agent Adapter",
       "repo": "passioncode-ai/fabric-agent-adapter",
-      "ref": "v0.56.0",
+      "ref": "v0.57.0",
       "kind": "plugin",
       "path": "plugins/fabric-agent-adapter",
       "legacyPluginIds": [

package/lib/doctor.js

@@ -14,10 +14,13 @@ const L = require('./launcher');
 const catalog = require('./catalog');
 const releases = require('./releases');
 const W = require('./windows-apps');
+const trains = require('./trains');
 const { probe } = require('./mcp-probe');
 
 const PKG = (() => { try { return require('../package.json').version; } catch (_) { return '0.0.0'; } })();
 const NPX = 'npx @passioncode-ai/passioncode@latest';
+/** The page of one release: a train's pin is installed from there, not from the product page (which offers the latest). */
+const releasePage = (pr, version) => `https://github.com/${pr.repo}/releases/tag/v${version}`;
 
 function servicesDir(home, platform) {
   if (process.env.PASSIONCODE_SERVICES_DIR) return process.env.PASSIONCODE_SERVICES_DIR;
@@ -84,9 +87,59 @@ async function wellKnown(origin) {
   } catch (error) { return { ok: false, reason: error.name === 'TimeoutError' ? 'no answer within 5 s' : error.message }; }
 }
 
-const newer = (a, b) => { const pa = a.split(/[.-]/).map(Number), pb = b.split(/[.-]/).map(Number); for (let i = 0; i < 3; i++) if (pa[i] !== pb[i]) return pa[i] > pb[i]; return false; };
+const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+/** A version as x.y.z[-pre], or null when it is not one; Windows' four-part `1.2.3.0` reads as `1.2.3`. */
+const normVersion = (v) => { const s = String(v || '').replace(/^(\d+\.\d+\.\d+)\.0$/, '$1'); return VERSION.test(s) ? s : null; };
 
-async function collect({ home, platform, claude, online }) {
+/**
+ * a > b by semver precedence: the numeric core first, then a release above its own prerelease
+ * (`0.3.15` > `0.3.15-rc.2`). A version that is not x.y.z[-pre] is neither newer nor older.
+ */
+const newer = (a, b) => {
+  if (!VERSION.test(String(a)) || !VERSION.test(String(b))) return false;
+  const split = (v) => { const [core, pre = null] = String(v).split(/-(.*)/s); return { core: core.split('.').map(Number), pre }; };
+  const pa = split(a), pb = split(b);
+  for (let i = 0; i < 3; i++) if ((pa.core[i] || 0) !== (pb.core[i] || 0)) return (pa.core[i] || 0) > (pb.core[i] || 0);
+  if (pa.pre === pb.pre) return false;
+  if (pa.pre === null || pb.pre === null) return pa.pre === null;
+  const xa = pa.pre.split('.'), xb = pb.pre.split('.');
+  for (let i = 0; i < Math.max(xa.length, xb.length); i++) {
+    if (xa[i] === undefined) return false;
+    if (xb[i] === undefined) return true;
+    if (xa[i] === xb[i]) continue;
+    const na = /^\d+$/.test(xa[i]), nb = /^\d+$/.test(xb[i]);
+    if (na && nb) return Number(xa[i]) > Number(xb[i]);
+    if (na !== nb) return nb; // numeric identifiers rank below alphanumeric ones
+    return xa[i] > xb[i];
+  }
+  return false;
+};
+
+/**
+ * The release train this machine follows (PC-89): `train` given (a name, or null for none) wins over
+ * the one `setup --train` saved in the launcher's state. { id, train } where train is null when none
+ * is followed, or an Error when the named one cannot be used.
+ */
+function trainOf(home, train) {
+  let id = train;
+  if (id === undefined) { try { id = JSON.parse(fs.readFileSync(L.paths(home).stateFile, 'utf8')).train || null; } catch (_) { id = null; } }
+  if (!id) return { id: null, train: null };
+  try { return { id, train: trains.load(id) }; } catch (error) { return { id, train: error }; }
+}
+
+/** An app's row against the version its train pins: equal, behind (repairable) or ahead (left alone). */
+function pinnedRow(pr, label, raw, at, t, { fixBehind, repairBehind, fixUnknown }) {
+  const pin = t.apps[pr.id];
+  const where = at ? ` in ${at}` : '';
+  const version = normVersion(raw);
+  if (!version) return { state: 'warn', detail: `${label} ${raw ? `${raw} (not a version this launcher compares)` : '(version unknown)'}${where}; release train ${t.id} pins ${pin}`, fix: fixUnknown, repair: null };
+  if (version === pin) return { state: 'ok', detail: `${label} ${version}${where} (pinned by release train ${t.id})`, fix: null, repair: null };
+  if (newer(pin, version)) return { state: 'warn', detail: `${label} ${version}${where}; release train ${t.id} pins ${pin}`, fix: fixBehind, repair: repairBehind };
+  // An app's data may not open in an older release (Fabric's schema), so the train never takes one back.
+  return { state: 'warn', detail: `${label} ${version}${where}, ahead of release train ${t.id} (${pin}); the train never takes an app back`, fix: null, repair: null };
+}
+
+async function collect({ home, platform, claude, online, train: trainName }) {
   const checks = [];
   // `repair` is what setup (and doctor --fix) may do about a check: { kind: 'update' } (the skill
   // set and the bundled MCP registrations), { kind: 'replace', product } (a verified reinstall of an
@@ -126,6 +179,9 @@ async function collect({ home, platform, claude, online }) {
   const probes = new Map();
   let docker = null;
   let windowsEntries = null; // the uninstall entries, read once (three `reg query` calls)
+  const followed = trainOf(home, trainName);
+  const train = followed.train instanceof Error ? null : followed.train;
+  const onTrain = []; // { pr, version } of each installed app the train pins
   for (const pr of catalog.PRODUCTS) {
     const at = catalog.appPath(pr);
     const installed = platform === 'darwin' && fs.existsSync(at);
@@ -138,14 +194,22 @@ async function collect({ home, platform, claude, online }) {
       }
       const found = W.findWindowsApp(pr, { entries: windowsEntries.entries, home });
       if (!found) {
-        add({ id: `app.${pr.id}`, area: 'apps', product: pr.id, state: 'info', detail: `${label}: not installed`, fix: `download it from ${pr.page}` });
+        add({ id: `app.${pr.id}`, area: 'apps', product: pr.id, state: 'info', detail: `${label}: not installed`, fix: train && train.apps[pr.id] ? `download ${train.apps[pr.id]} from ${releasePage(pr, train.apps[pr.id])}` : `download it from ${pr.page}` });
+      } else if (train && train.apps[pr.id]) {
+        onTrain.push({ pr, version: found.version });
+        const r = pinnedRow(pr, label, found.version, found.at, train, {
+          fixBehind: `install ${train.apps[pr.id]} from ${releasePage(pr, train.apps[pr.id])}`, repairBehind: null,
+          fixUnknown: `install ${train.apps[pr.id]} from ${releasePage(pr, train.apps[pr.id])} if this one is older`,
+        });
+        add({ id: `app.${pr.id}`, area: 'apps', product: pr.id, ...r });
       } else {
         let latest = null, latestErr = null;
         if (online) { try { latest = await releases.latestRelease(pr, { cacheFile }); } catch (error) { latestErr = error.message; } }
-        const outdated = latest && found.version && newer(latest.version, found.version);
+        const outdated = latest && normVersion(found.version) && newer(latest.version, normVersion(found.version));
+        const odd = latest && !normVersion(found.version); // unknown or not x.y.z: never read as the latest
         add({
-          id: `app.${pr.id}`, area: 'apps', product: pr.id, state: outdated || (!latest && online) ? 'warn' : 'ok',
-          detail: `${label} ${found.version || '(version unknown)'}${found.at ? ` in ${found.at}` : ''}${latest ? (outdated ? `; ${latest.version} is out` : found.version ? ' (latest)' : `; the latest is ${latest.version}`) : online ? `; latest unknown (${latestErr})` : '; latest not checked (--offline)'}`,
+          id: `app.${pr.id}`, area: 'apps', product: pr.id, state: outdated || odd || (!latest && online) ? 'warn' : 'ok',
+          detail: `${label} ${found.version || '(version unknown)'}${found.at ? ` in ${found.at}` : ''}${latest ? (outdated ? `; ${latest.version} is out` : odd ? (found.version ? ` (not a version this launcher compares); the latest is ${latest.version}` : `; the latest is ${latest.version}`) : ' (latest)') : online ? `; latest unknown (${latestErr})` : '; latest not checked (--offline)'}`,
           fix: outdated ? `install ${latest.version} from ${pr.page} (or accept the update ${pr.name} offers)` : null,
         });
       }
@@ -155,16 +219,28 @@ async function collect({ home, platform, claude, online }) {
       add({ id: `app.${pr.id}`, area: 'apps', product: pr.id, state: 'info', detail: `${label}: not installed`, fix: `${NPX} setup --with ${pr.id}` });
     } else {
       const version = releases.appVersion(at);
-      let latest = null, latestErr = null;
-      if (online) { try { latest = await releases.latestRelease(pr, { cacheFile }); } catch (error) { latestErr = error.message; } }
-      const outdated = latest && version && newer(latest.version, version);
       const running = releases.isRunning(at); // the app, or an agent's MCP server running from its bundle
-      add({
-        id: `app.${pr.id}`, area: 'apps', product: pr.id, state: outdated || (!latest && online) ? 'warn' : 'ok',
-        detail: `${label} ${version || '?'}${latest ? (outdated ? `; ${latest.version} is out` : ' (latest)') : online ? `; latest unknown (${latestErr})` : '; latest not checked (--offline)'}`,
-        fix: outdated ? (running ? `quit ${pr.name}, then run \`${NPX} setup\` (or accept the update ${pr.name} offers)` : `${NPX} setup`) : null,
-        repair: outdated && !running ? { kind: 'replace', product: pr.id } : null,
-      });
+      if (train && train.apps[pr.id]) {
+        onTrain.push({ pr, version });
+        const r = pinnedRow(pr, label, version, null, train, {
+          fixBehind: running ? `quit ${pr.name}, then run \`${NPX} setup\`` : `${NPX} setup`,
+          repairBehind: running ? null : { kind: 'replace', product: pr.id },
+          // Never a hand download on macOS: that skips the signed-checksum, team and notarization checks.
+          fixUnknown: `${pr.name}'s version could not be read; if its signature check fails too, \`${NPX} setup\` reinstalls it from the latest release`,
+        });
+        add({ id: `app.${pr.id}`, area: 'apps', product: pr.id, ...r });
+      } else {
+        let latest = null, latestErr = null;
+        if (online) { try { latest = await releases.latestRelease(pr, { cacheFile }); } catch (error) { latestErr = error.message; } }
+        const outdated = latest && normVersion(version) && newer(latest.version, normVersion(version));
+        const odd = latest && !normVersion(version); // unknown or not x.y.z: never read as the latest
+        add({
+          id: `app.${pr.id}`, area: 'apps', product: pr.id, state: outdated || odd || (!latest && online) ? 'warn' : 'ok',
+          detail: `${label} ${version || '?'}${latest ? (outdated ? `; ${latest.version} is out` : odd ? ` (${version ? 'not a version this launcher compares' : 'version unknown'}); the latest is ${latest.version}` : ' (latest)') : online ? `; latest unknown (${latestErr})` : '; latest not checked (--offline)'}`,
+          fix: outdated ? (running ? `quit ${pr.name}, then run \`${NPX} setup\` (or accept the update ${pr.name} offers)` : `${NPX} setup`) : null,
+          repair: outdated && !running ? { kind: 'replace', product: pr.id } : null,
+        });
+      }
       const v = releases.verifyApp(at, { gatekeeper: false });
       add({ id: `app.${pr.id}.signature`, area: 'apps', product: pr.id, state: v.ok ? 'ok' : 'fail', detail: `${pr.name}: ${v.checks.map((c) => `${c.check} ${c.ok ? 'ok' : `FAILED (${c.detail})`}`).join(', ')}`, fix: v.ok ? null : (running ? `quit ${pr.name}, then run \`${NPX} setup\`` : `${NPX} setup`), repair: !v.ok && !running ? { kind: 'replace', product: pr.id } : null });
       add({ id: `app.${pr.id}.running`, area: 'apps', product: pr.id, state: 'info', detail: `${pr.name}: ${running ? 'in use (the app, or an agent\'s MCP server from its bundle)' : 'not running (it starts when opened)'}`, fix: running ? null : `open "${at}" — or ask this machine's app supervisor to start it` });
@@ -220,6 +296,32 @@ async function collect({ home, platform, claude, online }) {
     }
   }
 
+  // The release train (PC-89): one row naming it and how many of its apps sit at their pin.
+  if (followed.train instanceof Error) {
+    const fix = `${NPX} setup --yes --no-apps --train none (or update the launcher)`;
+    add({ id: 'train', area: 'apps', state: 'fail', detail: `release train ${followed.id}: ${followed.train.message}`, fix });
+    // setup touches no app while the saved train is unusable, so no row may promise that it installs
+    // or reinstalls one. A hand download (Windows) is outside the launcher and stays.
+    for (const c of checks) {
+      if (!c.product || !/^(app\.[^.]+(\.signature)?|mcp\..+)$/.test(c.id)) continue;
+      // An MCP row's plain `setup` is the update repair, which still runs; only its app install does not.
+      const viaSetup = !!c.fix && c.fix.includes(c.id.startsWith('mcp.') ? `${NPX} setup --with` : `${NPX} setup`);
+      if (viaSetup || (c.repair && c.repair.kind === 'replace')) {
+        if (viaSetup) c.fix = `first make the release train usable: ${fix}`;
+        if (c.repair && c.repair.kind === 'replace') c.repair = null;
+      }
+    }
+  } else if (train) {
+    const pinned = Object.keys(train.apps).filter((id) => catalog.byId(id));
+    const at = onTrain.filter((x) => normVersion(x.version) === train.apps[x.pr.id]).length;
+    const off = onTrain.some((x) => normVersion(x.version) !== train.apps[x.pr.id]);
+    add({
+      id: 'train', area: 'apps', state: off ? 'warn' : 'ok',
+      detail: `release train ${train.id} (${train.title}${train.pinned ? `, pinned ${train.pinned}` : ''}): ${at} of ${pinned.length} apps at their pinned version${onTrain.length ? `; ${onTrain.map((x) => `${x.pr.name} ${x.version || '?'}`).join(', ')}` : ''}`,
+      fix: null,
+    });
+  }
+
   // One proving call per distinct registered command.
   const results = await Promise.all([...probes.values()].map(async (t) => {
     const tool = t.product.mcp.prove ? t.product.mcp.prove.tool : false;
@@ -307,4 +409,4 @@ function render(result) {
   return lines.join('\n').replace(/^\n/, '');
 }
 
-module.exports = { doctor, render, servicesDir, presentAgents, mcpEntryOf, collect, summarise, sortChecks, save, NPX, PKG };
+module.exports = { doctor, render, trainOf, newer, normVersion, servicesDir, presentAgents, mcpEntryOf, collect, summarise, sortChecks, save, NPX, PKG };

package/lib/releases.js

@@ -24,8 +24,20 @@ function run(cmd, args, { timeout = 60000, input, maxBuffer = 1024 * 1024 } = {}
   return { code: r.status === null ? 1 : r.status, out: r.stdout || '', err: r.stderr || '' };
 }
 
+/**
+ * fetch, once more after a second when the connection itself failed (no answer at all: a reset or a
+ * dropped socket). Both callers only read, so a repeat is safe; an HTTP error or a timeout is final.
+ */
+async function fetchTwice(url, options) {
+  try { return await fetch(url, options()); } catch (error) {
+    if (error.name === 'TimeoutError' || error.name === 'AbortError') throw error;
+    await new Promise((r) => setTimeout(r, 1000));
+    return fetch(url, options());
+  }
+}
+
 async function getJson(url) {
-  const res = await fetch(url, { headers: { Accept: 'application/vnd.github+json', 'User-Agent': 'passioncode-launcher' }, signal: AbortSignal.timeout(15000) });
+  const res = await fetchTwice(url, () => ({ headers: { Accept: 'application/vnd.github+json', 'User-Agent': 'passioncode-launcher' }, signal: AbortSignal.timeout(15000) }));
   if (!res.ok) throw new Error(`${url} answered HTTP ${res.status}`);
   return res.json();
 }
@@ -48,20 +60,45 @@ async function latestRelease(product, { cacheFile = null, now = Date.now() } = {
   } else {
     raw = await getJson(`${API()}/repos/${product.repo}/releases/latest`);
   }
+  const release = shape(product, raw);
+  if (cacheFile) {
+    cache[product.repo] = { at: new Date(now).toISOString(), release };
+    try { fs.mkdirSync(path.dirname(cacheFile), { recursive: true }); fs.writeFileSync(cacheFile, JSON.stringify(cache, null, 2)); } catch (_) { /* a cache only */ }
+  }
+  return release;
+}
+
+function shape(product, raw) {
   const release = {
     tag: raw.tag_name, version: String(raw.tag_name || '').replace(/^v/, ''), prerelease: !!raw.prerelease, url: raw.html_url,
     assets: (raw.assets || []).map((a) => ({ name: a.name, url: a.browser_download_url, size: a.size, digest: a.digest || null })),
   };
   if (!/^\d+\.\d+\.\d+/.test(release.version)) throw new Error(`${product.repo}: unexpected tag ${raw.tag_name}`);
+  return release;
+}
+
+/**
+ * The release a train pins (PC-89): tag `v<version>`, draft or not published refused. A published
+ * release does not change, so it is cached without expiry beside the latest ones.
+ */
+async function releaseAt(product, version, { cacheFile = null } = {}) {
+  const key = `${product.repo}@v${version}`;
+  let cache = {};
+  if (cacheFile) { try { cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8')); } catch (_) { cache = {}; } }
+  if (cache[key] && cache[key].release) return cache[key].release;
+  const raw = await getJson(`${API()}/repos/${product.repo}/releases/tags/v${encodeURIComponent(version)}`);
+  if (raw.draft) throw new Error(`${product.repo} v${version} is a draft, not a published release`);
+  const release = shape(product, raw);
+  if (release.version !== version) throw new Error(`${product.repo}: asked for v${version}, got ${raw.tag_name}`);
   if (cacheFile) {
-    cache[product.repo] = { at: new Date(now).toISOString(), release };
+    cache[key] = { at: new Date().toISOString(), release };
     try { fs.mkdirSync(path.dirname(cacheFile), { recursive: true }); fs.writeFileSync(cacheFile, JSON.stringify(cache, null, 2)); } catch (_) { /* a cache only */ }
   }
   return release;
 }
 
 async function download(url, dest) {
-  const res = await fetch(url, { headers: { 'User-Agent': 'passioncode-launcher' }, redirect: 'follow', signal: AbortSignal.timeout(30 * 60 * 1000) });
+  const res = await fetchTwice(url, () => ({ headers: { 'User-Agent': 'passioncode-launcher' }, redirect: 'follow', signal: AbortSignal.timeout(30 * 60 * 1000) }));
   if (!res.ok || !res.body) throw new Error(`download ${url}: HTTP ${res.status}`);
   const hash = crypto.createHash('sha256');
   const fd = fs.openSync(dest, 'w');
@@ -118,6 +155,21 @@ function appVersion(appDir) {
  * Download, verify and install one absent app into the applications folder. `report(step)` gets
  * each stage. Throws with the first failed check; the working directory is always removed.
  */
+/**
+ * The app bundle in an unpacked archive or a mounted image: at its root, or inside one folder at the
+ * root (Fabric Switchboard's zip holds `Fabric-Switchboard-<v>-macos-universal/Fabric Switchboard.app`).
+ * Two candidates are refused rather than guessed between. Returns the path or null.
+ */
+function findBundle(root, appName) {
+  const top = path.join(root, appName);
+  if (fs.existsSync(top)) return top;
+  let dirs = [];
+  try { dirs = fs.readdirSync(root, { withFileTypes: true }).filter((d) => d.isDirectory() && !d.name.startsWith('.') && d.name !== '__MACOSX'); } catch (_) { return null; }
+  const found = dirs.map((d) => path.join(root, d.name, appName)).filter((p) => fs.existsSync(p));
+  if (found.length > 1) throw new Error(`the archive holds ${found.length} copies of ${appName}; nothing was installed`);
+  return found[0] || null;
+}
+
 async function installApp(product, release, { work, report = () => {}, replace = false, home = os.homedir() }) {
   const target = catalog.appPath(product);
   if (fs.existsSync(target) && !replace) throw new Error(`${target} already exists`);
@@ -157,13 +209,13 @@ async function installApp(product, release, { work, report = () => {}, replace =
         fs.mkdirSync(mount);
         const a = run('hdiutil', ['attach', '-nobrowse', '-readonly', '-noautoopen', '-mountpoint', mount, file], { timeout: 300000 });
         if (a.code !== 0) { mount = null; throw new Error(`hdiutil attach: ${(a.err || a.out).trim()}`); }
-        source = path.join(mount, product.app);
+        source = findBundle(mount, product.app);
       } else {
         const x = run('ditto', ['-x', '-k', file, unpacked], { timeout: 600000 });
         if (x.code !== 0) throw new Error(`ditto -x: ${(x.err || x.out).trim()}`);
-        source = path.join(unpacked, product.app);
+        source = findBundle(unpacked, product.app);
       }
-      if (!fs.existsSync(source)) throw new Error(`${assetName} holds no ${product.app}`);
+      if (!source) throw new Error(`${assetName} holds no ${product.app}`);
       const app = verifyApp(source);
       for (const c of app.checks) report({ kind: 'verify', detail: `${product.app}: ${c.check} — ${c.detail}`, ok: c.ok });
       if (!app.ok) throw new Error(`${product.app} failed ${app.checks.filter((c) => !c.ok).map((c) => c.check).join(', ')}; nothing was installed`);
@@ -209,4 +261,4 @@ async function installApp(product, release, { work, report = () => {}, replace =
   }
 }
 
-module.exports = { latestRelease, installApp, verifyApp, appVersion, isRunning, freeBytes, run, download, API };
+module.exports = { findBundle, latestRelease, releaseAt, installApp, verifyApp, appVersion, isRunning, freeBytes, run, download, API };

package/lib/setup.js

@@ -18,6 +18,19 @@ const L = require('./launcher');
 const catalog = require('./catalog');
 const releases = require('./releases');
 const D = require('./doctor');
+const trains = require('./trains');
+
+/** `setup --train <name>` remembers the train for later runs and for doctor; `--train none` forgets it. */
+function saveTrain(home, id) {
+  const file = L.paths(home).stateFile;
+  let state = {};
+  try { state = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (id) state.train = id; else delete state.train;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
+  fs.renameSync(tmp, file);
+}
 
 function prereqMissing(product) {
   const missing = [];
@@ -29,7 +42,22 @@ function prereqMissing(product) {
 }
 
 /** What setup would do, from the checks: installs of absent apps and repairs. */
-function plan(checks, { platform, withIds = null, withoutIds = [], noApps = false, repairOnly = false }) {
+/**
+ * The pin a train sets for `pr`, or null for the latest release. An installed app newer than its
+ * pin is never taken back (its data may not open in an older release), so its reinstall (a damaged
+ * signature, PC-89) takes the latest release instead.
+ */
+function pinFor(pr, train) {
+  const pin = train && train.apps[pr.id];
+  if (!pin) return null;
+  if (!fs.existsSync(catalog.appPath(pr))) return pin;
+  // A bundle whose version cannot be read may be ahead of the pin: it is reinstalled from the latest.
+  const installed = D.normVersion(releases.appVersion(catalog.appPath(pr)));
+  return !installed || D.newer(installed, pin) ? null : pin;
+}
+
+function plan(checks, { platform, withIds = null, withoutIds = [], noApps = false, repairOnly = false, train = null }) {
+  const from = (pr) => (pinFor(pr, train) ? `its release ${train.apps[pr.id]}, pinned by release train ${train.id}` : 'its latest signed release');
   const items = [];
   if (platform === 'darwin' && !noApps && !repairOnly) {
     for (const pr of catalog.PRODUCTS) {
@@ -39,7 +67,7 @@ function plan(checks, { platform, withIds = null, withoutIds = [], noApps = fals
       const explicit = !!(withIds && withIds.includes(pr.id));
       items.push({
         kind: 'install', product: pr.id, selected: explicit || !missing.length,
-        detail: `install ${pr.name}${pr.preview ? ' (early preview)' : ''} from its latest signed release`,
+        detail: `install ${pr.name}${pr.preview ? ' (early preview)' : ''} from ${from(pr)}`,
         note: missing.length ? `needs ${missing.join(' and ')}${explicit ? '; installed because you asked for it' : '; skipped unless you ask for it (--with ' + pr.id + ')'}` : null,
       });
     }
@@ -57,7 +85,7 @@ function plan(checks, { platform, withIds = null, withoutIds = [], noApps = fals
     items.push({
       key, kind: r.kind, product: r.product || null, label: r.label || null, selected: true, because: [c.id],
       detail: r.kind === 'update' ? 'install or refresh the skill set and register the apps\' MCP servers for every agent'
-        : r.kind === 'replace' ? `reinstall ${pr.name} from its latest signed release (the current one goes to the Trash)`
+        : r.kind === 'replace' ? `reinstall ${pr.name} from ${from(pr)} (the current one goes to the Trash)`
           : `start the ${r.label} service through launchd`,
     });
   }
@@ -72,13 +100,19 @@ const yesNo = async (ask, question, def) => {
 async function setup({
   home = os.homedir(), yes = false, withIds = null, withoutIds = [], noApps = false, noOpen = false, dryRun = false,
   repairOnly = false, online = true, ask = null, log = () => {}, platform = process.env.PASSIONCODE_PLATFORM || process.platform,
+  train: trainName, // undefined: the saved one; null: none; a name: that train (PC-89)
 } = {}) {
   const claude = L.claudeRunner();
-  const before = D.sortChecks(await D.collect({ home, platform, claude, online }));
+  if (trainName) trains.load(trainName); // refused before anything is checked or changed
+  const before = D.sortChecks(await D.collect({ home, platform, claude, online, train: trainName }));
+  const followed = D.trainOf(home, trainName);
+  const train = followed.train instanceof Error ? null : followed.train; // an unusable one is doctor's fail row
   const fresh = !before.some((c) => c.id === 'skills.installed' && c.state !== 'fail')
     // An app doctor found (ok or warn: on Windows from the installer's records, PC-86) makes it existing.
     && !before.some((c) => /^app\.[^.]+$/.test(c.id) && (c.state === 'ok' || c.state === 'warn'));
-  const items = plan(before, { platform, withIds, withoutIds, noApps, repairOnly });
+  // A saved train this launcher cannot use touches no app: neither its pins nor the latest releases,
+  // until the person names a train or `none` (the `train` row's fix).
+  const items = plan(before, { platform, withIds, withoutIds, noApps: noApps || followed.train instanceof Error, repairOnly, train });
   const result = {
     version: D.PKG, platform, mode: fresh ? 'new' : 'existing', at: new Date().toISOString(), plan: items,
     actions: [], before: { checks: before, summary: D.summarise(before) }, after: null, humanSteps: [], planOnly: false,
@@ -87,10 +121,20 @@ async function setup({
 
   // Ask: one question per absent app, one for the repairs. Without a terminal and without --yes,
   // nothing changes: the plan is the answer.
-  if (dryRun) { result.planOnly = true; return finish(result, home, before); }
+  // A train named again is no change: only a different one waits for agreement.
+  const changesTrain = trainName !== undefined && trainName !== D.trainOf(home).id;
+  if (dryRun) { result.planOnly = true; if (changesTrain) result.trainNotSaved = trainName || 'none'; return finish(result, home, before); }
+  let asked = false;
+  const offeredYes = items.filter((i) => i.selected); // the offers a person declines by answering no
   if (!yes) {
-    if (!ask) { result.planOnly = items.some((i) => i.selected); if (result.planOnly) return finish(result, home, before); }
+    // A train named without --yes and without a terminal is a change nobody agreed to: plan only.
+    if (!ask) {
+      result.planOnly = items.some((i) => i.selected) || changesTrain;
+      if (changesTrain) result.trainNotSaved = trainName || 'none';
+      if (result.planOnly) return finish(result, home, before);
+    }
     else {
+      asked = true;
       for (const i of items.filter((x) => x.kind === 'install')) {
         const pr = catalog.byId(i.product);
         i.selected = await yesNo(ask, `Install ${pr.name}${pr.preview ? ' (early preview)' : ''}${i.note ? ` — ${i.note}` : ''}?`, i.selected);
@@ -103,6 +147,25 @@ async function setup({
     }
   }
 
+  // The train is saved by a run the person agreed to: --yes, or answers in a terminal. Without
+  // either nothing changes, whatever the plan. A person who answered no to every offer that defaulted
+  // to yes declined a named train too; forgetting one (`none`) touches no app, so any answer saves
+  // it: it is the way out of a saved train this launcher cannot use.
+  const declinedAll = asked && offeredYes.length > 0 && !items.some((i) => i.selected);
+  // A named train declined with everything else changes nothing; its checks (made for that train)
+  // are not saved as this machine's state either.
+  if (trainName && declinedAll && changesTrain) { result.planOnly = true; result.trainNotSaved = trainName; return finish(result, home, before); }
+  if (changesTrain) { // the train already saved is left as it is: nothing to write
+    const was = D.trainOf(home).id;
+    saveTrain(home, trainName);
+    // A change of train is a change of this machine, reported like any other action.
+    if (was !== trainName) {
+      const detail = trainName ? `saved release train ${trainName}${was ? ` (it was ${was})` : ''}` : `forgot release train ${was}; apps follow their latest releases`;
+      result.actions.push({ kind: 'train', detail, product: null, outcome: 'done' });
+      log(`${'train'.padEnd(9)} ${detail}`);
+    }
+  }
+
   const act = (kind, detail, product = null) => {
     const a = { kind, detail, product, outcome: 'done' };
     result.actions.push(a);
@@ -118,7 +181,9 @@ async function setup({
     const pr = catalog.byId(i.product);
     const a = act(i.kind, i.detail, pr.id);
     try {
-      const release = await releases.latestRelease(pr, { cacheFile: path.join(L.paths(home).state, 'releases-cache.json') });
+      const cacheFile = path.join(L.paths(home).state, 'releases-cache.json');
+      const pin = pinFor(pr, train);
+      const release = pin ? await releases.releaseAt(pr, pin, { cacheFile }) : await releases.latestRelease(pr, { cacheFile });
       const done = await releases.installApp(pr, release, {
         work: path.join(L.paths(home).state, 'downloads', `${pr.id}-${release.version}`), replace: i.kind === 'replace', home,
         report: (st) => log(`  ${st.ok === false ? 'FAILED' : 'ok'}  ${st.detail}`),
@@ -168,8 +233,9 @@ async function setup({
   const anyFailed = result.actions.some((x) => x.outcome === 'failed');
   for (const c of after) {
     if (!(c.state === 'fail' || c.state === 'warn') || !c.fix) continue;
-    if (c.fix === `${D.NPX} setup` && !anyFailed && !result.planOnly) continue; // this run was that command
-    push(c.fix);
+    if (c.fix === `${D.NPX} setup` && !anyFailed && !result.planOnly && !noApps) continue; // this run was that command
+    const train = 'first make the release train usable: '; // the train row names the same step
+    push(c.fix.startsWith(train) ? c.fix.slice(train.length) : c.fix);
   }
   for (const i of items.filter((x) => x.kind === 'install' && !x.selected)) {
     const pr = catalog.byId(i.product);
@@ -201,6 +267,7 @@ function render(result, { repairOnly = false } = {}) {
   if (result.planOnly) {
     lines.push('', todo.length ? 'Plan (nothing was changed):' : 'Nothing to do.');
     for (const i of result.plan) lines.push(`  ${i.selected ? '•' : '–'} ${i.detail}${i.note ? ` (${i.note})` : ''}`);
+    if (result.trainNotSaved) lines.push('', `The release train (${result.trainNotSaved}) was not saved: run it with --yes, or answer in a terminal.`);
     if (todo.length) lines.push('', 'Run it with --yes to apply, or in a terminal to answer one question per app.');
   } else if (!result.actions.length) {
     lines.push('', 'Everything this command can set up is in place; nothing was changed.');

package/lib/trains.js

@@ -0,0 +1,38 @@
+'use strict';
+/**
+ * Release trains (PC-89, organization R1 SD-4 O-2): one set of pinned app versions that every
+ * machine of an organization installs, instead of each app's latest release. A train is a file in
+ * `trains/<id>.json` shipped with the launcher; the skills are pinned by the launcher release itself
+ * (`family.json`). The train's record (who pins what, and when) lives in fabric-workspace.
+ */
+const fs = require('fs');
+const path = require('path');
+const catalog = require('./catalog');
+
+const ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const dir = () => process.env.PASSIONCODE_TRAINS || path.join(__dirname, '..', 'trains');
+
+/** The train named `id`, validated, or an Error saying why it cannot be used. */
+function load(id) {
+  if (typeof id !== 'string' || !ID.test(id)) throw new Error(`"${id}" is not a release train name`);
+  let doc;
+  try { doc = JSON.parse(fs.readFileSync(path.join(dir(), `${id}.json`), 'utf8')); } catch (error) {
+    if (error.code === 'ENOENT') throw new Error(`no release train "${id}" in this launcher (known: ${list().join(', ') || 'none'})`);
+    throw new Error(`release train "${id}" cannot be read: ${error.message}`);
+  }
+  if (doc.train !== id) throw new Error(`release train file ${id}.json names "${doc.train}"`);
+  const apps = doc.apps && typeof doc.apps === 'object' ? doc.apps : null;
+  if (!apps || !Object.keys(apps).length) throw new Error(`release train "${id}" pins no app`);
+  for (const [app, version] of Object.entries(apps)) {
+    if (!catalog.byId(app)) throw new Error(`release train "${id}" pins an unknown app "${app}"`);
+    if (typeof version !== 'string' || !VERSION.test(version)) throw new Error(`release train "${id}" pins ${app} at "${version}", not a version`);
+  }
+  return { id, title: doc.title || id, pinned: doc.pinned || null, record: doc.record || null, apps: { ...apps } };
+}
+
+function list() {
+  try { return fs.readdirSync(dir()).filter((n) => n.endsWith('.json')).map((n) => n.slice(0, -5)).sort(); } catch (_) { return []; }
+}
+
+module.exports = { load, list };