@passioncode-ai/passioncode 0.1.53 → 0.2.1

package/lib/setup.js

@@ -0,0 +1,238 @@
+'use strict';
+/**
+ * `passioncode setup` (alias `onboard`): one idempotent command for a new machine and an existing
+ * setup (ADR-0004). It checks everything first (the doctor's checks), plans, asks, then:
+ *   installs the absent apps the person chose — verified releases only;
+ *   repairs what the checks found — the skill set and MCP registrations (`update`), an outdated or
+ *   damaged app nobody is running (a verified reinstall; the old bundle goes to the Trash), a
+ *   launchd service that does not answer (`launchctl kickstart`, never a kill);
+ *   opens the apps it installed;
+ * then checks again and prints the before/after table and the steps that stay a person's.
+ * On a healthy machine the plan is empty, nothing changes, and it exits 0.
+ * `doctor --fix` is this command with `repairOnly`: no new apps, nothing opened.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const L = require('./launcher');
+const catalog = require('./catalog');
+const releases = require('./releases');
+const D = require('./doctor');
+
+function prereqMissing(product) {
+  const missing = [];
+  for (const need of product.needs || []) {
+    if (need === 'docker' && releases.run('docker', ['--version'], { timeout: 10000 }).code === 127) missing.push('Docker (OrbStack or Docker Desktop)');
+    if (need === 'supabase' && releases.run('supabase', ['--version'], { timeout: 10000 }).code === 127) missing.push('the Supabase CLI');
+  }
+  return missing;
+}
+
+/** What setup would do, from the checks: installs of absent apps and repairs. */
+function plan(checks, { platform, withIds = null, withoutIds = [], noApps = false, repairOnly = false }) {
+  const items = [];
+  if (platform === 'darwin' && !noApps && !repairOnly) {
+    for (const pr of catalog.PRODUCTS) {
+      if (fs.existsSync(catalog.appPath(pr))) continue;
+      if (withoutIds.includes(pr.id) || (withIds && !withIds.includes(pr.id))) continue;
+      const missing = prereqMissing(pr);
+      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`,
+        note: missing.length ? `needs ${missing.join(' and ')}${explicit ? '; installed because you asked for it' : '; skipped unless you ask for it (--with ' + pr.id + ')'}` : null,
+      });
+    }
+  }
+  const seen = new Set();
+  for (const c of checks) {
+    const r = c.repair;
+    if (!r) continue;
+    if (r.kind === 'replace' && (noApps || platform !== 'darwin')) continue;
+    if (r.kind === 'replace' && (withoutIds.includes(r.product) || (withIds && !withIds.includes(r.product)))) continue;
+    const key = r.kind === 'update' ? 'update' : `${r.kind}:${r.product || r.label}`;
+    if (seen.has(key)) { items.find((i) => i.key === key).because.push(c.id); continue; }
+    seen.add(key);
+    const pr = r.product ? catalog.byId(r.product) : null;
+    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)`
+          : `start the ${r.label} service through launchd`,
+    });
+  }
+  return items;
+}
+
+const yesNo = async (ask, question, def) => {
+  const a = String(await ask(`${question} [${def ? 'Y/n' : 'y/N'}] `) || '').trim().toLowerCase();
+  return a ? a.startsWith('y') || a.startsWith('д') : 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,
+} = {}) {
+  const claude = L.claudeRunner();
+  const before = D.sortChecks(await D.collect({ home, platform, claude, online }));
+  const fresh = !before.some((c) => c.id === 'skills.installed' && c.state !== 'fail')
+    && !catalog.PRODUCTS.some((pr) => platform === 'darwin' && fs.existsSync(catalog.appPath(pr)));
+  const items = plan(before, { platform, withIds, withoutIds, noApps, repairOnly });
+  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,
+    keyOverride: process.env.PASSIONCODE_RELEASE_KEY || null,
+  };
+
+  // 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); }
+  if (!yes) {
+    if (!ask) { result.planOnly = items.some((i) => i.selected); if (result.planOnly) return finish(result, home, before); }
+    else {
+      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);
+      }
+      const repairs = items.filter((x) => x.kind !== 'install');
+      if (repairs.length) {
+        const go = await yesNo(ask, `Apply ${repairs.length} repair(s): ${repairs.map((r) => r.detail).join('; ')}?`, true);
+        for (const r of repairs) r.selected = go;
+      }
+    }
+  }
+
+  const act = (kind, detail, product = null) => {
+    const a = { kind, detail, product, outcome: 'done' };
+    result.actions.push(a);
+    log(`${kind.padEnd(9)} ${detail}`);
+    return a;
+  };
+  const fail = (a, error) => { a.outcome = 'failed'; a.error = error.message || String(error); log(`  failed: ${a.error}`); };
+  const installed = [];
+  let needUpdate = items.some((i) => i.kind === 'update' && i.selected);
+
+  // 1. Apps: installs of absent ones, verified reinstalls of outdated or damaged ones.
+  for (const i of items.filter((x) => (x.kind === 'install' || x.kind === 'replace') && x.selected)) {
+    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 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}`),
+      });
+      a.detail = `${i.kind === 'install' ? 'installed' : 'reinstalled'} ${pr.name} ${done.version} at ${done.path}${done.replaced ? `; the previous one is in ${done.replaced}` : ''}`;
+      if (i.kind === 'install') installed.push(pr); // a reinstalled app was idle and stays closed
+      needUpdate = needUpdate || (i.kind === 'install' && !!(pr.mcp && !pr.mcp.external));
+    } catch (error) { fail(a, error); }
+  }
+
+  // 2. The skill set and the bundled MCP registrations.
+  if (needUpdate) {
+    const a = act('update', 'the skill set and the apps\' MCP registrations');
+    try {
+      const r = L.update({ home, claude, includePreview: true }); // setup is where a person chose Fabric
+      const failed = r.steps.filter((st) => st.outcome === 'failed');
+      const changed = r.steps.filter((st) => st.outcome === 'done');
+      a.steps = changed.concat(failed);
+      a.detail = `PassionCode.ai ${r.version}: ${changed.length} change(s)${failed.length ? `, ${failed.length} failed` : ''}`;
+      if (failed.length) fail(a, new Error(failed.map((st) => `${st.detail}: ${st.error}`).join('; ')));
+    } catch (error) { fail(a, error); }
+  }
+
+  // 3. Services launchd owns and that did not answer: start, never kill.
+  for (const i of items.filter((x) => x.kind === 'kickstart' && x.selected)) {
+    const a = act('start', `launchctl kickstart gui/${process.getuid ? process.getuid() : 0}/${i.label}`);
+    const r = releases.run('launchctl', ['kickstart', `gui/${process.getuid ? process.getuid() : 0}/${i.label}`], { timeout: 30000 });
+    if (r.code !== 0) fail(a, new Error((r.err || r.out || `exit ${r.code}`).trim()));
+  }
+
+  // 4. Open what was installed for its first run (never in --fix, never with --no-open).
+  if (!repairOnly && !noOpen) {
+    for (const pr of installed) {
+      const a = act('open', `${pr.name} for its first run`, pr.id);
+      const r = releases.run('open', [catalog.appPath(pr)], { timeout: 30000 });
+      if (r.code !== 0) fail(a, new Error((r.err || r.out || `exit ${r.code}`).trim()));
+    }
+  }
+
+  const after = result.actions.length ? D.sortChecks(await D.collect({ home, platform, claude, online })) : before;
+  result.after = { checks: after, summary: D.summarise(after) };
+
+  // The person's steps, once: every remaining problem's fix, the guides of the apps just installed,
+  // what an install leaves to a person, and a restart when skills or MCP servers changed.
+  const steps = [];
+  const push = (t) => { if (t && !steps.includes(t)) steps.push(t); };
+  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);
+  }
+  for (const i of items.filter((x) => x.kind === 'install' && !x.selected)) {
+    const pr = catalog.byId(i.product);
+    if (i.note) push(`${pr.name}: ${i.note}`);
+  }
+  for (const pr of installed) push(pr.guide);
+  if (result.actions.some((a) => a.kind === 'update' && a.outcome === 'done' && /[1-9]\d* change/.test(a.detail)) || installed.length) {
+    push('Restart your coding agents: skills and MCP servers load when a session starts.');
+  }
+  result.humanSteps = steps;
+  return finish(result, home, after);
+}
+
+function finish(result, home, checks) {
+  result.ok = !result.actions.some((a) => a.outcome === 'failed') && D.summarise(checks).fail === 0;
+  if (!result.after) result.after = { checks, summary: D.summarise(checks) };
+  // Stamped after the after-check: the update inside this run set installedAt earlier, and the
+  // session hook ignores a result older than the installed release.
+  if (!result.planOnly) D.save(home, { at: new Date().toISOString(), checks, summary: D.summarise(checks) });
+  return result;
+}
+
+function render(result, { repairOnly = false } = {}) {
+  const lines = [];
+  if (result.keyOverride) lines.push(`NOTE: releases are checked against the key in PASSIONCODE_RELEASE_KEY (${result.keyOverride}), not the bundled PassionCode.ai release key.`, '');
+  const b = result.before.summary, a = result.after.summary;
+  lines.push(`${repairOnly ? 'doctor --fix' : 'setup'} · ${result.mode === 'new' ? 'a new setup' : 'an existing setup'} · ${result.platform}`);
+  const todo = result.plan.filter((i) => i.selected);
+  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 (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.');
+  } else {
+    lines.push('', 'Done:');
+    for (const x of result.actions) lines.push(`  ${x.outcome === 'failed' ? 'FAILED' : 'done  '} ${x.detail}${x.error ? `\n         ${x.error}` : ''}`);
+  }
+  // Before → after, by area, and every check whose state moved.
+  const areas = ['prerequisites', 'skills', 'apps', 'mcp', 'services'];
+  const count = (checks, area, st) => checks.filter((c) => c.area === area && c.state === st).length;
+  const single = result.planOnly || !result.actions.length;
+  lines.push('', single ? 'Checks          now (ok/warn/fail)' : 'Checks          before (ok/warn/fail)   after (ok/warn/fail)');
+  for (const area of areas) {
+    const bc = result.before.checks, ac = result.after.checks;
+    if (!bc.some((c) => c.area === area) && !ac.some((c) => c.area === area)) continue;
+    const f = (cs) => `${count(cs, area, 'ok')}/${count(cs, area, 'warn')}/${count(cs, area, 'fail')}`;
+    lines.push(single ? `  ${area.padEnd(14)}${f(ac)}` : `  ${area.padEnd(14)}${f(bc).padEnd(24)}${f(ac)}`);
+  }
+  const was = new Map(result.before.checks.map((c) => [c.id, c.state]));
+  const moved = result.after.checks.filter((c) => was.has(c.id) && was.get(c.id) !== c.state && c.state !== 'info');
+  for (const c of moved) lines.push(`  ${was.get(c.id)} → ${c.state}: ${c.detail}`);
+  const left = result.after.checks.filter((c) => c.state === 'fail' || c.state === 'warn');
+  if (left.length) {
+    lines.push('', result.planOnly ? 'Open now:' : 'Still open:');
+    for (const c of left) lines.push(`  ${c.state === 'fail' ? 'FAIL' : 'warn'}  ${c.detail}`);
+  }
+  if (result.humanSteps.length) {
+    lines.push('', 'Your steps (an agent cannot do these for you — sign-ins, consents, secrets in hidden prompts):');
+    result.humanSteps.forEach((t, n) => lines.push(`  ${n + 1}. ${t}`));
+  }
+  lines.push('', single ? `${a.fail ? `${a.fail} problem(s)` : 'No problems'}. Check again any time: npx @passioncode-ai/passioncode@latest doctor`
+    : `${a.fail ? `${a.fail} problem(s) remain` : 'No problems remain'} (before: ${b.fail}). Check again any time: npx @passioncode-ai/passioncode@latest doctor`);
+  return lines.join('\n');
+}
+
+module.exports = { setup, plan, render };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@passioncode-ai/passioncode",
-  "version": "0.1.53",
-  "description": "The PassionCode.ai agent skill set \u2014 Fabric Agent Adapter, Observatory Log and the organisation's working rules \u2014 for Claude Code and every other agent on the machine, updated as one set.",
+  "version": "0.2.1",
+  "description": "Set up PassionCode.ai on a computer with one command — the apps from their verified releases, their MCP servers for every coding agent and the PassionCode.ai skills — and check and repair it with the same command or `doctor`.",
   "bin": {
     "passioncode": "bin/passioncode.js"
   },
@@ -45,6 +45,9 @@
     "passioncode",
     "fabric",
     "skills",
-    "launcher"
+    "launcher",
+    "setup",
+    "doctor",
+    "mcp"
   ]
 }

package/payload/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "fabric-agent-adapter",
       "displayName": "Fabric Agent Adapter",
       "source": "./plugins/fabric-agent-adapter",
-      "version": "0.29.0",
+      "version": "0.30.0",
       "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles; and teach a coding agent to work in a project through Fabric (fabric-mcp, fabric_whoami, claim and release), with Claude Code session hooks.",
       "author": {
         "name": "PassionCode.ai",
@@ -35,8 +35,8 @@
       "name": "passioncode",
       "displayName": "PassionCode.ai",
       "source": "./plugins/passioncode",
-      "version": "0.1.53",
-      "description": "The organisation's working rules for every contributor's agent (working-in-passioncode), and a once-a-day check that keeps the PassionCode.ai set current.",
+      "version": "0.2.1",
+      "description": "Set up and check PassionCode.ai on a computer with one command (setting-up-passioncode), the organisation's working rules for every contributor's agent (working-in-passioncode), and a once-a-day check that keeps the PassionCode.ai set current.",
       "author": {
         "name": "PassionCode.ai",
         "url": "https://passioncode.ai/"

package/payload/manifest.json

@@ -1,15 +1,15 @@
 {
   "family": "passioncode",
-  "version": "0.1.53",
+  "version": "0.2.1",
   "release": true,
   "members": [
     {
       "name": "fabric-agent-adapter",
       "displayName": "Fabric Agent Adapter",
       "repo": "passioncode-ai/fabric-agent-adapter",
-      "ref": "v0.29.0",
-      "commit": "73af866a11e5f5df16e062d860806e3af331d014",
-      "version": "0.29.0",
+      "ref": "v0.30.0",
+      "commit": "668b934ae92b1b52356f250e7dd7c3131d81842c",
+      "version": "0.30.0",
       "via": "clone of https://***@github.com/passioncode-ai/fabric-agent-adapter.git",
       "skills": [
         "adapting-projects-to-fabric",
@@ -23,7 +23,7 @@
       "legacyMarketplaces": [
         "fabric-agent-adapter"
       ],
-      "contentHash": "sha256:ab96afe1f3face2a185938cc5a8f4f2893079a30e2ea279bd686177f4a16efc4",
+      "contentHash": "sha256:7d270382683711b72cfb4a6ce0ddfbe28612a5f6d71ffe978c10ce96adad019f",
       "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles; and teach a coding agent to work in a project through Fabric (fabric-mcp, fabric_whoami, claim and release), with Claude Code session hooks.",
       "author": {
         "name": "PassionCode.ai",
@@ -62,17 +62,18 @@
       "name": "passioncode",
       "displayName": "PassionCode.ai",
       "repo": "passioncode-ai/passioncode",
-      "ref": "v0.1.53",
+      "ref": "v0.2.1",
       "commit": null,
-      "version": "0.1.53",
+      "version": "0.2.1",
       "via": "this repository",
       "skills": [
+        "setting-up-passioncode",
         "working-in-passioncode"
       ],
       "legacyPluginIds": [],
       "legacyMarketplaces": [],
-      "contentHash": "sha256:3a08376ccad2da28008eb612cc2eb5d2fe6b06e7a8be67adabbf27f1ae187758",
-      "description": "The organisation's working rules for every contributor's agent (working-in-passioncode), and a once-a-day check that keeps the PassionCode.ai set current.",
+      "contentHash": "sha256:d982253f26d5d1135cb02afc64465d1ade106485f3a79bacfdfd6db4ff4f4965",
+      "description": "Set up and check PassionCode.ai on a computer with one command (setting-up-passioncode), the organisation's working rules for every contributor's agent (working-in-passioncode), and a once-a-day check that keeps the PassionCode.ai set current.",
       "author": {
         "name": "PassionCode.ai",
         "url": "https://passioncode.ai/"

package/payload/plugins/fabric-agent-adapter/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "fabric-agent-adapter",
   "displayName": "Fabric Agent Adapter",
   "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles; and teach a coding agent to work in a project through Fabric (fabric-mcp, fabric_whoami, claim and release), with Claude Code session hooks.",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

package/payload/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/SKILL.md

@@ -5,7 +5,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode.
 metadata:
   author: PassionCode.ai
-  version: "0.29.0"
+  version: "0.30.0"
   contract-version: "0.1.0"
   contract-commit: "f00a7685e3861c27f7899c033fb850a145a1708f"
 ---

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/SKILL.md

@@ -17,7 +17,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Python 3.9+ or Node.js 20+ for the kits; the probe needs Python 3.9+. launchd steps are macOS-only; Linux services install a systemd user unit and Windows ones a per-user Scheduled Task with the kits' writers. Dashboard handoff optionally uses Fabric Dashboards MCP link/host_status/open; without it, report unresolved host capability. The contract checkout is optional.
 metadata:
   author: PassionCode.ai
-  version: "0.29.0"
+  version: "0.30.0"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
   extension-commit: "f00a7685e3861c27f7899c033fb850a145a1708f"
@@ -203,7 +203,8 @@ The installer, not the service, owns the plist and the descriptor. Sequence:
 
 On Linux the supervisor is a systemd user unit (`systemd_unit` + `systemd_install`), on
 Windows a per-user Scheduled Task (`task_xml` + `task_install`); the Node kit has the same
-writers (`systemdUnit`, `taskXml`, …) and both kits write identical files.
+writers and installers (`launchdPlist` + `launchdInstall`, `systemdUnit`, `taskXml`, …) and
+both kits write identical files.
 
 Code runs from an immutable release directory; an upgrade writes a new release,
 rewrites the plist and restarts. Read [the lifecycle reference](references/lifecycle.md)

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/references/lifecycle.md

@@ -12,7 +12,7 @@ wins and this page is the defect. The rule each section serves:
 | LC-09 the footprint is declared | the descriptor and the plist, unit or task; the service's own `AGENTS.md` names its label (unit, task) and port | `write_descriptor`, `launchd_plist`, `systemd_unit` / `systemdUnit`, `task_xml` / `taskXml` |
 | LC-11 previous release kept, older pruned | [Install, upgrade, uninstall](#install-upgrade-uninstall) | `prune_releases` / `pruneReleases` |
 | LC-12 every file is bounded | [Logs](#logs) | `RotatingLog`, `cap_stdout_log` / `RotatingLog`, `capStdoutLog` |
-| LC-14 operator intent wins; uninstall is symmetric | [Install, upgrade, uninstall](#install-upgrade-uninstall), [Linux and Windows](#linux-and-windows) | `launchd_install`, `launchd_uninstall` (Python); `systemd_install` / `systemdInstall`, `task_install` / `taskInstall` and their uninstalls |
+| LC-14 operator intent wins; uninstall is symmetric | [Install, upgrade, uninstall](#install-upgrade-uninstall), [Linux and Windows](#linux-and-windows) | `launchd_install` / `launchdInstall`, `launchd_uninstall` / `launchdUninstall`; `systemd_install` / `systemdInstall`, `task_install` / `taskInstall` and their uninstalls |
 | LC-15 builds clean up after themselves | release pruning runs inside the installer, not later | `prune_releases` / `pruneReleases` |
 
 ## Contents
@@ -26,7 +26,7 @@ wins and this page is the defect. The rule each section serves:
 - [Being managed by a host lifecycle broker](#being-managed-by-a-host-lifecycle-broker)
 - [Linux and Windows](#linux-and-windows)
 
-## launchd plist (generate it with `launchd_plist`)
+## launchd plist (generate it with `launchd_plist` or `launchdPlist`; both kits write the same bytes)
 
 | Key | Value | Why |
 |---|---|---|
@@ -37,7 +37,7 @@ wins and this page is the defect. The rule each section serves:
 | `ThrottleInterval` | `10` | bounds a crash loop |
 | `ExitTimeOut` | above the drain and its hard exit (15 s default; `Drain` ends by 10 s) | SIGKILL arrives after it, so it must never come first |
 | `ProcessType` | `Standard` — never `Background`, and no `Nice` > 0 or `LowPriorityIO` | a host probes the service and agents call it while the Mac is busy; a background job is starved for tens of seconds under load and every host reports an outage that never happened (the probe's `lifecycle.priority` rule fails it) |
-| `EnvironmentVariables` | `PATH` set explicitly; `*_FILE` paths to secrets; `FABRIC_SERVICE_SUPERVISOR=launchd` | never a secret value — the plist is world-readable in backups; the supervisor marker is how the lock knows to back off |
+| `EnvironmentVariables` | `PATH` set explicitly; `*_FILE` paths to secrets; `FABRIC_SERVICE_SUPERVISOR=launchd` | never a secret value — the plist is world-readable in backups; the supervisor marker is how the lock knows to back off (the probe's `lifecycle.supervisor-marker` rule fails a plist without it: a copy that finds the lock held would exit 75 at once into a respawn every `ThrottleInterval`) |
 | `StandardOutPath`/`StandardErrorPath` | `~/Library/Logs/<id>/service.log` | one place the host tails |
 
 ## Install, upgrade, uninstall
@@ -45,14 +45,14 @@ wins and this page is the defect. The rule each section serves:
 1. Build or unpack the release into `~/.local/share/<id>/releases/<version>-<sha12>/`
    (a venv or `node_modules` inside it). Never edit a release after it is written.
 2. `write_descriptor` (port and id claims are checked here).
-3. `launchd_install`: write + `plutil -lint`, read `launchctl print-disabled gui/<uid>`,
+3. `launchd_install` (Node: `await launchdInstall(...)`, the same steps): write + `plutil -lint`, read `launchctl print-disabled gui/<uid>`,
    `enable` **only when no override is recorded** (a first install), `bootout` and wait
    until `launchctl print gui/<uid>/<label>` fails, `bootstrap` with up to five retries,
    then poll the well-known document until it answers with this `id.instance`.
 4. Upgrade = new release, rewrite the plist with the new path, `launchd_install`
    again, then `prune_releases(releases_dir, current=<new release>)`: the running release
    and the one before it stay for rollback, older ones go (LC-11, LC-15).
-5. Uninstall = `launchd_uninstall` + `remove_descriptor`. Data stays; `purge=True`
+5. Uninstall = `launchd_uninstall` (Node: `await launchdUninstall(...)`) + `remove_descriptor`. Data stays; `purge=True`
    (with `service_id`) removes data, logs and cache when the operator asks.
 
 **The operator's intent wins (LC-14).** A host stops a service with `bootout` **and**

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/check_service.py

@@ -75,6 +75,29 @@ def plist_problems(plist: dict, label: object, token: object = None) -> list:
     return problems
 
 
+def marker_problem(plist: dict) -> Optional[str]:
+    """What is wrong with the job's supervisor marker (DEC-0057; FAA-05), read the way the copy it starts reads it.
+
+    Without ``FABRIC_SERVICE_SUPERVISOR=launchd`` (or ``--fabric-supervisor launchd``) a copy that finds the
+    lock held exits 75 at once, and KeepAlive starts it again every ThrottleInterval."""
+    env = plist.get("EnvironmentVariables")
+    env = {str(k): str(v) for k, v in env.items()} if isinstance(env, dict) else {}
+    argv = plist.get("ProgramArguments")
+    argv = [str(a) for a in argv] if isinstance(argv, list) else []
+    marker = fs.supervisor_marker(env, argv)
+    if marker["kind"] == "supervised" and marker["manager"] == "launchd":
+        return None
+    fix = ("a copy that finds the lock held exits 75 at once and KeepAlive respawns it every ThrottleInterval; "
+           "regenerate the plist with launchd_plist / launchdPlist and reinstall")
+    if marker["kind"] == "conflict":
+        return "%s — %s" % (fs.marker_conflict_message(marker), fix)
+    if marker["kind"] == "supervised":
+        return "the marker names %s, not launchd — %s" % (marker["manager"], fix)
+    if marker.get("unreadable") is not None:
+        return "the marker %r names no supervisor — %s" % (marker["unreadable"], fix)
+    return "no %s=launchd — %s" % (fs.SUPERVISOR_ENV, fix)
+
+
 def priority_problems(plist: dict) -> list:
     """A service that answers hosts and agents must not be scheduled as background work."""
     out = []
@@ -701,6 +724,9 @@ class Probe:
             return
         problems = plist_problems(plist, life.get("label"), self.token)
         self.add("lifecycle.plist", "FAIL" if problems else "PASS", "; ".join(problems) or "%s: RunAtLoad, KeepAlive, no secrets" % plist_path.name)
+        marker = marker_problem(plist)
+        self.add("lifecycle.supervisor-marker", "FAIL" if marker else "PASS",
+                 marker or "%s: %s=launchd, so a copy that finds the lock held backs off" % (plist_path.name, fs.SUPERVISOR_ENV))
         slow = priority_problems(plist)
         self.add("lifecycle.priority", "FAIL" if slow else "PASS",
                  "; ".join(slow) + " — macOS may starve the service under load and hosts then see an outage; use ProcessType Standard"