@rubytech/create-sitedesk-code 0.1.515 → 0.1.516

package/dist/__tests__/launchd-bootstrap.test.js

@@ -1,10 +1,12 @@
-// acceptance grid for launchd-bootstrap.ts (Task 1401).
+// acceptance grid for launchd-bootstrap.ts (Task 1401, reshaped by Task 2069).
 //
-// Locks the darwin session-manager bootstrap contract: bootout (idempotent,
-// rc 3 "No such process" ignored) then bootstrap, with a bounded retry on
-// exit 5 ("Input/output error" — a known transient/racey launchctl failure on
-// re-install). Pure logic — the launchctl runner and the retry sleep are both
-// injected, so no real launchctl or wall-clock delay runs here.
+// Locks the darwin LaunchAgent bootstrap contract: bootout (idempotent, rc 3
+// "No such process" ignored), then poll `launchctl print` until the label
+// leaves the domain, then bootstrap, with a bounded retry on exit 5
+// ("Input/output error" — returned for as long as the previous instance is
+// still terminating). Pure logic — the launchctl runner, the sleep and the
+// clock are all injected, so no real launchctl and no wall-clock delay runs
+// here.
 //
 // Compiles to dist/__tests__/launchd-bootstrap.test.js so
 // `node --test dist/__tests__/*.test.js` picks it up after build.
@@ -13,33 +15,74 @@ import assert from "node:assert/strict";
 import { bootstrapLaunchAgent } from "../launchd-bootstrap.js";
 const OPTS = { gui: "gui/502", label: "com.rubytech.host-claude-session-manager", plistPath: "/tmp/sm.plist" };
 const noSleep = () => { };
-test("first bootstrap succeeds — one bootout, one bootstrap, attempts=1", () => {
+/** A fake clock the injected sleepFn advances, so the wait-budget arithmetic
+ *  runs with no wall-clock cost. */
+function fakeClock() {
+    let t = 0;
+    return { now: () => t, sleep: (ms) => { t += ms; } };
+}
+test("waits for the label to leave the domain before bootstrapping", () => {
+    const clock = fakeClock();
     const calls = [];
+    let prints = 0;
     const run = (args) => {
         calls.push(args);
-        return args[0] === "bootstrap" ? { status: 0, stderr: "" } : { status: 3, stderr: "No such process" };
+        if (args[0] === "print") {
+            prints += 1;
+            // The old instance lingers for 3 polls, then leaves the domain.
+            return prints <= 3 ? { status: 0, stderr: "" } : { status: 113, stderr: "" };
+        }
+        if (args[0] === "bootstrap")
+            return { status: 0, stderr: "" };
+        return { status: 0, stderr: "" };
     };
-    const r = bootstrapLaunchAgent(run, { ...OPTS, sleepFn: noSleep });
+    const r = bootstrapLaunchAgent(run, { ...OPTS, sleepFn: clock.sleep, nowFn: clock.now });
     assert.equal(r.ok, true);
     assert.equal(r.attempts, 1);
+    assert.equal(prints, 4); // 3 polls with the label present, 1 showing it gone
+    assert.equal(r.totalWaitedMs, 1500); // 3 sleeps of 500ms before the gone poll
+    const bootstrapIdx = calls.findIndex((c) => c[0] === "bootstrap");
+    assert.ok(bootstrapIdx > 3, `bootstrap issued at index ${bootstrapIdx}, before the label was gone`);
+});
+test("fresh install — bootout, one absence poll, bootstrap, attempts=1", () => {
+    const clock = fakeClock();
+    const calls = [];
+    const run = (args) => {
+        calls.push(args);
+        if (args[0] === "print")
+            return { status: 113, stderr: "" };
+        if (args[0] === "bootstrap")
+            return { status: 0, stderr: "" };
+        return { status: 3, stderr: "No such process" };
+    };
+    const r = bootstrapLaunchAgent(run, { ...OPTS, sleepFn: clock.sleep, nowFn: clock.now });
+    assert.equal(r.ok, true);
+    assert.equal(r.attempts, 1);
+    assert.equal(r.totalWaitedMs, 0); // gone on the first poll — a fresh install never waits
     assert.deepEqual(calls[0], ["bootout", "gui/502/com.rubytech.host-claude-session-manager"]);
-    assert.deepEqual(calls[1], ["bootstrap", "gui/502", "/tmp/sm.plist"]);
-    assert.equal(calls.length, 2);
+    assert.deepEqual(calls[1], ["print", "gui/502/com.rubytech.host-claude-session-manager"]);
+    assert.deepEqual(calls[2], ["bootstrap", "gui/502", "/tmp/sm.plist"]);
+    assert.equal(calls.length, 3);
 });
 test("exit 5 twice then 0 — retries and reports the winning attempt", () => {
+    const clock = fakeClock();
     let bootstraps = 0;
     const sleeps = [];
     const run = (args) => {
+        if (args[0] === "print")
+            return { status: 113, stderr: "" };
         if (args[0] !== "bootstrap")
             return { status: 3, stderr: "No such process" };
         bootstraps += 1;
         return bootstraps < 3 ? { status: 5, stderr: "Bootstrap failed: 5: Input/output error" } : { status: 0, stderr: "" };
     };
-    const r = bootstrapLaunchAgent(run, { ...OPTS, sleepFn: (ms) => { sleeps.push(ms); } });
+    const r = bootstrapLaunchAgent(run, {
+        ...OPTS, sleepFn: (ms) => { sleeps.push(ms); clock.sleep(ms); }, nowFn: clock.now,
+    });
     assert.equal(r.ok, true);
     assert.equal(r.attempts, 3);
     assert.equal(bootstraps, 3);
-    assert.equal(sleeps.length, 2); // slept before each of the two retries
+    assert.equal(sleeps.filter((ms) => ms === 500).length, 2); // slept before each of the two retries
 });
 test("exit 5 on every attempt — fails after the attempt cap, not before", () => {
     let bootstraps = 0;
@@ -69,17 +112,120 @@ test("non-5 non-zero bootstrap aborts immediately — no retry", () => {
     assert.equal(r.bootstrapStatus, 9);
     assert.equal(bootstraps, 1);
 });
-test("emits one structured log line per attempt with bootout and bootstrap rc", () => {
+test("label never leaves the domain — bootstraps anyway at the budget, wait is reported", () => {
+    const clock = fakeClock();
+    const lines = [];
+    const run = (args) => {
+        if (args[0] === "print")
+            return { status: 0, stderr: "" }; // always present
+        if (args[0] === "bootstrap")
+            return { status: 5, stderr: "Bootstrap failed: 5: Input/output error" };
+        return { status: 0, stderr: "" };
+    };
+    const r = bootstrapLaunchAgent(run, {
+        ...OPTS, maxAttempts: 1, sleepFn: clock.sleep, nowFn: clock.now, logger: (l) => lines.push(l),
+    });
+    assert.equal(r.ok, false);
+    assert.equal(r.lastPresent, true);
+    assert.equal(r.totalWaitedMs, 60_000);
+    assert.ok(lines.some((l) => /op=wait-timeout waitedMs=60000 polls=\d+ present=true probeFailures=0 action=bootstrap-anyway/.test(l)));
+});
+test("the wait budget is shared across attempts, not spent per attempt", () => {
+    const clock = fakeClock();
+    const run = (args) => {
+        if (args[0] === "print")
+            return { status: 0, stderr: "" };
+        if (args[0] === "bootstrap")
+            return { status: 5, stderr: "eio" };
+        return { status: 0, stderr: "" };
+    };
+    const r = bootstrapLaunchAgent(run, { ...OPTS, maxAttempts: 3, sleepFn: clock.sleep, nowFn: clock.now });
+    assert.equal(r.attempts, 3);
+    // 60s of waiting in total across three attempts, not 180s.
+    assert.equal(r.totalWaitedMs, 60_000);
+});
+test("each exit-5 retry re-enters the wait rather than firing after retryDelayMs", () => {
+    const clock = fakeClock();
+    const seq = [];
+    let prints = 0;
+    const run = (args) => {
+        seq.push(args[0]);
+        if (args[0] === "print") {
+            prints += 1;
+            // present for one poll per attempt, then gone
+            return prints % 2 === 1 ? { status: 0, stderr: "" } : { status: 113, stderr: "" };
+        }
+        if (args[0] === "bootstrap")
+            return { status: 5, stderr: "eio" };
+        return { status: 0, stderr: "" };
+    };
+    bootstrapLaunchAgent(run, { ...OPTS, maxAttempts: 2, sleepFn: clock.sleep, nowFn: clock.now });
+    assert.deepEqual(seq, [
+        "bootout", "print", "print", "bootstrap",
+        "bootout", "print", "print", "bootstrap",
+    ]);
+});
+test("a probe that cannot run is not read as an absent label", () => {
+    const clock = fakeClock();
+    const lines = [];
+    const run = (args) => {
+        // status null = launchctl could not be spawned, or was killed by the
+        // spawnSync timeout. That is not evidence the label is gone.
+        if (args[0] === "print")
+            return { status: null, stderr: "" };
+        if (args[0] === "bootstrap")
+            return { status: 5, stderr: "eio" };
+        return { status: 0, stderr: "" };
+    };
+    const r = bootstrapLaunchAgent(run, {
+        ...OPTS, maxAttempts: 1, sleepFn: clock.sleep, nowFn: clock.now, logger: (l) => lines.push(l),
+    });
+    assert.equal(r.lastPresent, true); // never confirmed gone
+    assert.equal(r.totalWaitedMs, 60_000); // the full wait was served, not skipped
+    assert.ok(r.probeFailures > 0);
+    assert.ok(lines.some((l) => /op=wait-poll present=true probeRc=null/.test(l)));
+});
+test("the wait terminates on the poll cap even if the clock never advances", () => {
+    // A wall clock that steps backwards (an NTP correction) would leave the
+    // elapsed-time test permanently unsatisfied. Termination must not depend on
+    // time moving forwards.
+    const frozenNow = () => 0;
+    let polls = 0;
+    const run = (args) => {
+        if (args[0] === "print") {
+            polls += 1;
+            return { status: 0, stderr: "" };
+        }
+        if (args[0] === "bootstrap")
+            return { status: 5, stderr: "eio" };
+        return { status: 0, stderr: "" };
+    };
+    const r = bootstrapLaunchAgent(run, {
+        ...OPTS, maxAttempts: 1, sleepFn: noSleep, nowFn: frozenNow,
+    });
+    assert.equal(r.ok, false);
+    assert.equal(r.totalWaitedMs, 0); // the frozen clock measures no elapsed time
+    assert.equal(polls, 121); // ceil(60000/500) + 1 — the cap, not an infinite loop
+});
+test("emits one structured line per lifecycle step, correlated by agent label", () => {
+    const clock = fakeClock();
     let bootstraps = 0;
     const lines = [];
     const run = (args) => {
+        if (args[0] === "print")
+            return { status: 113, stderr: "" };
         if (args[0] !== "bootstrap")
             return { status: 3, stderr: "No such process" };
         bootstraps += 1;
         return bootstraps < 2 ? { status: 5, stderr: "eio" } : { status: 0, stderr: "" };
     };
-    bootstrapLaunchAgent(run, { ...OPTS, sleepFn: noSleep, logger: (l) => lines.push(l) });
-    assert.equal(lines.length, 2);
-    assert.match(lines[0], /agent=com\.rubytech\.host-claude-session-manager bootout=3 bootstrap=5 attempt=1/);
-    assert.match(lines[1], /bootout=3 bootstrap=0 attempt=2/);
+    bootstrapLaunchAgent(run, { ...OPTS, sleepFn: clock.sleep, nowFn: clock.now, logger: (l) => lines.push(l) });
+    const ops = lines.map((l) => l.match(/op=([a-z-]+)/)[1]);
+    assert.deepEqual(ops, [
+        "bootout", "wait-poll", "gone", "bootstrap",
+        "bootout", "wait-poll", "gone", "bootstrap", "result",
+    ]);
+    assert.ok(lines.every((l) => l.startsWith("[launchd] agent=com.rubytech.host-claude-session-manager ")));
+    assert.match(lines[3], /op=bootstrap rc=5 attempt=1 waitedMs=0/);
+    assert.match(lines[8], /op=result ok=true attempts=2 totalWaitedMs=0 probeFailures=0 rc=0/);
 });

package/dist/index.js

@@ -1361,8 +1361,9 @@ function resetNeo4jAuth(port = DEFAULT_NEO4J_PORT, dataDir = "/var/lib/neo4j", p
         const label = `${launchdLabel()}-neo4j`;
         console.log("  Resetting dedicated Neo4j auth (launchd)...");
         spawnSync("launchctl", ["bootout", `${gui()}/${label}`], { stdio: "pipe" });
-        // launchctl bootout returns once the job leaves the domain, but neo4j does a
-        // graceful multi-second store flush on SIGTERM — so the JVM can still hold
+        // launchctl bootout returns as soon as launchd accepts the request (Task
+        // 2069), and neo4j does a graceful multi-second store flush on SIGTERM — so
+        // the JVM can still hold
         // the port (and the store) after bootout returns. Wait for the bolt port to
         // free before clearing the auth db and re-seeding: set-initial-password only
         // takes effect against a stopped store, and rm must not race a live flush.
@@ -1386,7 +1387,7 @@ function resetNeo4jAuth(port = DEFAULT_NEO4J_PORT, dataDir = "/var/lib/neo4j", p
         const plistPath = join(launchAgentsDir(), `${label}.plist`);
         const boot = bootstrapLaunchAgent((a) => { const r = spawnSync("launchctl", a, { stdio: "pipe", encoding: "utf-8", timeout: 15_000 }); return { status: r.status, stderr: (r.stderr ?? "").toString() }; }, { gui: gui(), label, plistPath, logger: (l) => { console.log(`  ${l}`); logFile(`  ${l}`); } });
         if (!boot.ok) {
-            throw new Error(`launchctl bootstrap ${label} failed (exit ${boot.bootstrapStatus}) after ${boot.attempts} attempt(s) during dedicated darwin auth reset: ${boot.stderr}`);
+            throw new Error(`launchctl bootstrap ${label} failed (exit ${boot.bootstrapStatus}) after ${boot.attempts} attempt(s), waited ${boot.totalWaitedMs}ms, stillPresent=${boot.lastPresent}, probeFailures=${boot.probeFailures} during dedicated darwin auth reset: ${boot.stderr}`);
         }
         logFile(`  [neo4j-darwin-auth-reset] dedicated datadir=${dataDir} conf=${p.confDir} label=${label}`);
     }
@@ -1804,7 +1805,7 @@ function setupDedicatedNeo4jDarwin() {
     logFile(`  ${plistPath} written (${plist.length} bytes)`);
     const boot = bootstrapLaunchAgent((a) => { const r = spawnSync("launchctl", a, { stdio: "pipe", encoding: "utf-8", timeout: 15_000 }); return { status: r.status, stderr: (r.stderr ?? "").toString() }; }, { gui: gui(), label, plistPath, logger: (l) => { console.log(`  ${l}`); logFile(`  ${l}`); } });
     if (!boot.ok) {
-        throw new Error(`launchctl bootstrap ${label} failed (exit ${boot.bootstrapStatus}) after ${boot.attempts} attempt(s): ${boot.stderr}`);
+        throw new Error(`launchctl bootstrap ${label} failed (exit ${boot.bootstrapStatus}) after ${boot.attempts} attempt(s), waited ${boot.totalWaitedMs}ms, stillPresent=${boot.lastPresent}, probeFailures=${boot.probeFailures}: ${boot.stderr}`);
     }
     // Health-check the brand's bolt port — loud failure, no silent fallback to the
     // shared instance (matches the Linux dedicated bind check).
@@ -3891,12 +3892,12 @@ function installServiceDarwin() {
     });
     if (smBoot.ok) {
         console.log(`  [launchd] bootstrap ${gui()}/${smLabel} ok`);
-        logFile(`  [create-maxy] launchd-plist=${smLabel} loaded=true attempts=${smBoot.attempts}`);
+        logFile(`  [create-maxy] launchd-plist=${smLabel} loaded=true attempts=${smBoot.attempts} waitedMs=${smBoot.totalWaitedMs}`);
     }
     else {
-        console.error(`  [launchd] bootstrap ${smLabel} returned ${smBoot.bootstrapStatus} after ${smBoot.attempts} attempt(s): ${smBoot.stderr}`);
-        logFile(`  [create-maxy] launchd-plist=${smLabel} loaded=false exit=${smBoot.bootstrapStatus} attempts=${smBoot.attempts}`);
-        throw new Error(`launchctl bootstrap ${smLabel} failed (exit ${smBoot.bootstrapStatus}) after ${smBoot.attempts} attempt(s): ${smBoot.stderr}`);
+        console.error(`  [launchd] bootstrap ${smLabel} returned ${smBoot.bootstrapStatus} after ${smBoot.attempts} attempt(s), waited ${smBoot.totalWaitedMs}ms, stillPresent=${smBoot.lastPresent}, probeFailures=${smBoot.probeFailures}: ${smBoot.stderr}`);
+        logFile(`  [create-maxy] launchd-plist=${smLabel} loaded=false exit=${smBoot.bootstrapStatus} attempts=${smBoot.attempts} waitedMs=${smBoot.totalWaitedMs} stillPresent=${smBoot.lastPresent} probeFailures=${smBoot.probeFailures}`);
+        throw new Error(`launchctl bootstrap ${smLabel} failed (exit ${smBoot.bootstrapStatus}) after ${smBoot.attempts} attempt(s), waited ${smBoot.totalWaitedMs}ms, stillPresent=${smBoot.lastPresent}, probeFailures=${smBoot.probeFailures}: ${smBoot.stderr}`);
     }
     // Health-probe the manager (/healthz) so a silent boot failure surfaces at
     // install time, not at first session spawn as `manager-unreachable`.
@@ -3947,11 +3948,11 @@ function installServiceDarwin() {
         logger: (line) => { console.log(`  ${line}`); logFile(`  ${line}`); },
     });
     if (hbBoot.ok) {
-        logFile(`  [create-maxy] launchd-plist=${hbLabel} loaded=true attempts=${hbBoot.attempts}`);
+        logFile(`  [create-maxy] launchd-plist=${hbLabel} loaded=true attempts=${hbBoot.attempts} waitedMs=${hbBoot.totalWaitedMs}`);
     }
     else {
-        console.error(`  WARNING: heartbeat LaunchAgent ${hbLabel} bootstrap returned ${hbBoot.bootstrapStatus} after ${hbBoot.attempts} attempt(s): ${hbBoot.stderr} — scheduling ticks will not fire until a re-install succeeds.`);
-        logFile(`  [create-maxy] launchd-plist=${hbLabel} loaded=false exit=${hbBoot.bootstrapStatus} attempts=${hbBoot.attempts}`);
+        console.error(`  WARNING: heartbeat LaunchAgent ${hbLabel} bootstrap returned ${hbBoot.bootstrapStatus} after ${hbBoot.attempts} attempt(s), waited ${hbBoot.totalWaitedMs}ms, stillPresent=${hbBoot.lastPresent}, probeFailures=${hbBoot.probeFailures}: ${hbBoot.stderr} — scheduling ticks will not fire until a re-install succeeds.`);
+        logFile(`  [create-maxy] launchd-plist=${hbLabel} loaded=false exit=${hbBoot.bootstrapStatus} attempts=${hbBoot.attempts} waitedMs=${hbBoot.totalWaitedMs} stillPresent=${hbBoot.lastPresent} probeFailures=${hbBoot.probeFailures}`);
     }
     // Task 1706 — the log rotator. On Linux a */15 entry in the per-brand cron
     // block ticks logs-rotate.sh (installCrons/buildBrandCronBlock); darwin has no
@@ -3987,11 +3988,11 @@ function installServiceDarwin() {
         logger: (line) => { console.log(`  ${line}`); logFile(`  ${line}`); },
     });
     if (lrBoot.ok) {
-        logFile(`  [create-maxy] launchd-plist=${lrLabel} loaded=true attempts=${lrBoot.attempts}`);
+        logFile(`  [create-maxy] launchd-plist=${lrLabel} loaded=true attempts=${lrBoot.attempts} waitedMs=${lrBoot.totalWaitedMs}`);
     }
     else {
-        console.error(`  WARNING: logs-rotate LaunchAgent ${lrLabel} bootstrap returned ${lrBoot.bootstrapStatus} after ${lrBoot.attempts} attempt(s): ${lrBoot.stderr} — brand logs will not be rotated until a re-install succeeds.`);
-        logFile(`  [create-maxy] launchd-plist=${lrLabel} loaded=false exit=${lrBoot.bootstrapStatus} attempts=${lrBoot.attempts}`);
+        console.error(`  WARNING: logs-rotate LaunchAgent ${lrLabel} bootstrap returned ${lrBoot.bootstrapStatus} after ${lrBoot.attempts} attempt(s), waited ${lrBoot.totalWaitedMs}ms, stillPresent=${lrBoot.lastPresent}, probeFailures=${lrBoot.probeFailures}: ${lrBoot.stderr} — brand logs will not be rotated until a re-install succeeds.`);
+        logFile(`  [create-maxy] launchd-plist=${lrLabel} loaded=false exit=${lrBoot.bootstrapStatus} attempts=${lrBoot.attempts} waitedMs=${lrBoot.totalWaitedMs} stillPresent=${lrBoot.lastPresent} probeFailures=${lrBoot.probeFailures}`);
     }
     // Wait for the server to come up.
     console.log("  Waiting for web server...");

package/dist/launchd-bootstrap.js

@@ -1,19 +1,34 @@
-// Task 1401 — darwin session-manager LaunchAgent bootstrap, made idempotent and
+// Task 1401 / Task 2069 — darwin LaunchAgent bootstrap, made idempotent and
 // EIO-tolerant.
 //
-// `launchctl bootstrap` intermittently returns exit 5 ("Bootstrap failed: 5:
-// Input/output error") on a re-install even when the target label is not
-// loaded (a `bootout` of it returns 3, "No such process"). It is a known
-// transient/racey launchd failure: bootstrapping the same plist from a clean
-// state succeeds. The earlier phase-11 code issued a single bare `bootstrap`
-// and treated any non-zero exit as fatal, so one EIO aborted the whole install.
+// `launchctl bootstrap` returns exit 5 ("Bootstrap failed: 5: Input/output
+// error") when the label's previous instance has not finished terminating.
+// 1401 read this as a transient racey failure and retried three times 500 ms
+// apart; 2069 measured it instead. `launchctl bootout` returns as soon as
+// launchd accepts the request, but the job's process keeps running — a
+// dedicated Neo4j's JVM took 14.2 s to reach "Stopped." on the Muvin iMac while
+// all three retries fired inside 1.043 s and every one got exit 5. The failure
+// is deterministic for the length of that shutdown, not random.
 //
-// This helper bootout-then-bootstraps with a bounded retry on exit 5. Both the
-// launchctl runner and the retry sleep are injected, so the logic is unit-tested
-// with no real launchctl and no wall-clock delay. Kept synchronous to match the
-// spawnSync-based installer body (installService is a synchronous `void`).
-/** `launchctl bootstrap` exit code for "Input/output error" — the transient,
- *  racey failure this retry loop exists to absorb. */
+// So this helper boots the label out, polls `launchctl print <gui>/<label>`
+// until the label leaves the domain, and only then bootstraps. `print` returns
+// 0 for the whole time the old process lives and non-zero once it exits
+// (measured: rc 113), which makes it an exit-code probe rather than prose
+// parsing. The exit-5 retry is kept for the residual case, and each retry
+// re-enters the wait.
+//
+// What `print`'s exit code does NOT report is liveness: a job that loads and
+// exits immediately still returns rc 0, with "state = not running" appearing
+// only in stdout. Detecting a dead-on-arrival agent therefore needs a different
+// primitive and is not attempted here.
+//
+// The launchctl runner, the sleep, and the clock are all injected, so the logic
+// is unit-tested with no real launchctl and no wall-clock delay. Kept
+// synchronous to match the spawnSync-based installer body (installService is a
+// synchronous `void`).
+/** `launchctl bootstrap` exit code for "Input/output error" — returned for as
+ *  long as the label's previous instance is still terminating. The wait above
+ *  is what removes that window; the retry covers what is left. */
 const BOOTSTRAP_EIO = 5;
 /** Blocking sleep with no imports, safe inside the synchronous installer. */
 function blockingSleep(ms) {
@@ -24,20 +39,69 @@ function blockingSleep(ms) {
 export function bootstrapLaunchAgent(run, o) {
     const maxAttempts = Math.max(1, o.maxAttempts ?? 3);
     const retryDelayMs = o.retryDelayMs ?? 500;
+    const waitBudgetMs = o.waitBudgetMs ?? 60_000;
+    const pollIntervalMs = Math.max(1, o.pollIntervalMs ?? 500);
+    const now = o.nowFn ?? Date.now;
     const sleepFn = o.sleepFn ?? blockingSleep;
     const log = o.logger ?? (() => { });
+    const target = `${o.gui}/${o.label}`;
+    const tag = `[launchd] agent=${o.label}`;
+    // The wall clock is not monotonic — an NTP step backwards during the wait
+    // would leave the elapsed-time test below permanently unsatisfied. This poll
+    // allowance bounds the loop independently of the clock, so termination never
+    // depends on time moving forwards.
+    let pollsRemaining = Math.ceil(waitBudgetMs / pollIntervalMs) + 1;
+    let totalWaitedMs = 0;
+    let lastPresent = false;
+    let probeFailures = 0;
     let attempt = 0;
     let last = { status: null, stderr: "" };
     for (attempt = 1; attempt <= maxAttempts; attempt++) {
         // Idempotent: bootout any prior instance so the following bootstrap starts
         // clean. rc 3 ("No such process") is the expected fresh case; it and any
         // other bootout rc are ignored — bootout is cleanup, not the verified op.
-        const bootout = run(["bootout", `${o.gui}/${o.label}`]);
+        const bootout = run(["bootout", target]);
+        log(`${tag} op=bootout rc=${bootout.status ?? "null"} attempt=${attempt}`);
+        // bootout returns as soon as launchd accepts the request, but the job's
+        // process can keep running for seconds (Neo4j's JVM: 14.2 s measured on the
+        // Muvin iMac). `launchctl print` returns 0 for that whole window and
+        // non-zero once the process is gone, so it is the absence probe.
+        // Bootstrapping before that is what returns EIO.
+        const waitStart = now();
+        let present = true;
+        let polls = 0;
+        for (;;) {
+            const p = run(["print", target]);
+            polls += 1;
+            pollsRemaining -= 1;
+            // Three outcomes, not two. rc 0 = still in the domain. A non-zero rc
+            // (113) = gone. A null status means the probe could not run at all —
+            // that is not evidence of absence, so the wait continues rather than
+            // treating an unrunnable probe as a clear domain.
+            const gone = p.status !== null && p.status !== 0;
+            if (p.status === null)
+                probeFailures += 1;
+            present = !gone;
+            const elapsedMs = now() - waitStart;
+            log(`${tag} op=wait-poll present=${present} probeRc=${p.status ?? "null"} elapsedMs=${elapsedMs}`);
+            if (gone) {
+                log(`${tag} op=gone goneMs=${elapsedMs} polls=${polls} attempt=${attempt}`);
+                break;
+            }
+            if (totalWaitedMs + elapsedMs >= waitBudgetMs || pollsRemaining <= 0) {
+                log(`${tag} op=wait-timeout waitedMs=${totalWaitedMs + elapsedMs} polls=${polls} present=true probeFailures=${probeFailures} action=bootstrap-anyway`);
+                break;
+            }
+            sleepFn(pollIntervalMs);
+        }
+        totalWaitedMs += Math.max(0, now() - waitStart);
+        lastPresent = present;
         const bootstrap = run(["bootstrap", o.gui, o.plistPath]);
         last = { status: bootstrap.status, stderr: (bootstrap.stderr ?? "").trim() };
-        log(`[launchd] agent=${o.label} bootout=${bootout.status ?? "null"} bootstrap=${bootstrap.status ?? "null"} attempt=${attempt}`);
+        log(`${tag} op=bootstrap rc=${bootstrap.status ?? "null"} attempt=${attempt} waitedMs=${totalWaitedMs}`);
         if (bootstrap.status === 0) {
-            return { ok: true, attempts: attempt, bootstrapStatus: 0, stderr: last.stderr };
+            log(`${tag} op=result ok=true attempts=${attempt} totalWaitedMs=${totalWaitedMs} probeFailures=${probeFailures} rc=0`);
+            return { ok: true, attempts: attempt, bootstrapStatus: 0, stderr: last.stderr, totalWaitedMs, lastPresent, probeFailures };
         }
         // Only exit 5 (EIO) is retried, and only while attempts remain. Every other
         // non-zero status is a real failure that aborts now rather than burning the
@@ -48,10 +112,15 @@ export function bootstrapLaunchAgent(run, o) {
         }
         break;
     }
+    const attempts = Math.min(attempt, maxAttempts);
+    log(`${tag} op=result ok=false attempts=${attempts} totalWaitedMs=${totalWaitedMs} probeFailures=${probeFailures} rc=${last.status ?? "null"}`);
     return {
         ok: false,
-        attempts: Math.min(attempt, maxAttempts),
+        attempts,
         bootstrapStatus: last.status,
         stderr: last.stderr,
+        totalWaitedMs,
+        lastPresent,
+        probeFailures,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-sitedesk-code",
-  "version": "0.1.515",
+  "version": "0.1.516",
   "description": "Install SiteDesk — automated back office for independent building contractors",
   "bin": {
     "create-sitedesk-code": "./dist/index.js"

package/payload/platform/plugins/admin/skills/platform-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: platform-architecture
 description: Use when grounding any documented-surface claim about what SiteDesk ships — plugins, skills, specialists, install/deploy flows, internals. This is the install catalogue, not evidence of what is enabled on the current account. For install state on this account, call `capabilities-here`; for documented surface, cite the `Source:` URL inline.
-content-hash: sha256:414b3a1a40f8b871635c0746cd30d4ea4203fd9baa8f4727c435c75c01f9bc2a
+content-hash: sha256:f164b44ebf79eb2e637d1157465fb53eb4d226989b350d3dbcf2df4fc8afd6b2
 brand: sitedesk-code
 product-name: SiteDesk
 ---
@@ -793,7 +793,29 @@ cat ~/Library/LaunchAgents/com.rubytech.maxy-code.plist
 
 The plist points at the wrapper script the installer wrote and at log files under `$HOME/.maxy-code/logs/`. `launchctl bootstrap`'s exit code is recorded in the install log as `[create-maxy] launchd-plist=… loaded=true|false`.
 
-Each brand runs two LaunchAgents: the main service (`com.rubytech.maxy-code`) and a session manager (`com.rubytech.maxy-code-claude-session-manager`). On a re-install `launchctl bootstrap` of the session-manager agent can return a transient `exit 5: Input/output error` even when the agent was not already loaded; the installer boots the agent out and retries automatically. Each attempt is logged as `[launchd] agent=<label> bootout=<rc> bootstrap=<rc> attempt=<n>`, and only an EIO that persists across every attempt aborts the install.
+Each brand runs the main service (`com.rubytech.maxy-code`) plus three supporting LaunchAgents: a session manager (`…-claude-session-manager`), a heartbeat (`…-heartbeat`) and a log rotator (`…-logs-rotate`). A brand with a dedicated Neo4j adds a fifth, `…-neo4j`.
+
+On a re-install the installer boots an agent out before bootstrapping it back. `launchctl bootout` returns as soon as launchd accepts the request, but the job's process keeps running — Neo4j's JVM took 14.2 s to finish its store flush on one host — and `launchctl bootstrap` returns `exit 5: Input/output error` for that entire window. So after the bootout the installer polls `launchctl print gui/$UID/<label>` every 500 ms until the label leaves the domain, up to 60 s in total across all attempts, and only then bootstraps. If the label has still not left when the budget runs out, it bootstraps anyway and the resulting exit code decides.
+
+This applies to the four supporting agents and the dedicated Neo4j agent. The main service (`com.rubytech.maxy-code`) bootstraps directly and does not wait.
+
+Every step is one line in the install log, keyed by `agent=<label>`:
+
+```
+[launchd] agent=<label> op=bootout rc=<n> attempt=<n>
+[launchd] agent=<label> op=wait-poll present=<bool> probeRc=<n|null> elapsedMs=<n>
+[launchd] agent=<label> op=gone goneMs=<n> polls=<n> attempt=<n>
+[launchd] agent=<label> op=bootstrap rc=<n> attempt=<n> waitedMs=<n>
+[launchd] agent=<label> op=result ok=<bool> attempts=<n> totalWaitedMs=<n> probeFailures=<n> rc=<n>
+```
+
+Read one agent's whole lifeline with:
+
+```bash
+grep '\[launchd\]' ~/.maxy-code/logs/install-*.log | grep 'agent=com.rubytech.maxy-code-neo4j'
+```
+
+`op=gone goneMs=<n>` is how long the previous instance actually took to exit. `op=wait-timeout` means it never left within 60 s. `probeRc=null` on a `wait-poll` line means `launchctl print` could not run at all — the wait then continues rather than treating an unrunnable probe as a clear domain, and `probeFailures=<n>` on the result line counts how often that happened. Only an EIO that persists across every attempt aborts the install.
 
 ## 4. Open the admin UI
 
@@ -3134,6 +3156,22 @@ both `kind: 'specialist'` and differ only by origin.
   highest-capability agents on the box were the ones the operator could not see.
   These are the only agents that can be disabled, and the route enforces that
   rather than relying on the UI to withhold the control.
+  **A file in the LIVE directory whose name also exists under
+  `<accountDir>/plugins/*/agents/` is excluded from this set.** `agent-builder`
+  copies the authored file into `specialists/agents/` because presence there is
+  what makes an agent dispatchable, so the live directory says nothing about who
+  wrote the agent and every activated user-created specialist used to render
+  twice, the second time as Shipped. The account plugin tree is the authorship
+  evidence and its row wins, which is also why `disable` refuses a slug present
+  under `plugins/*/agents/`: quarantine exists to stop provisioning re-delivering
+  a file, and provisioning never writes that tree. Both gates read filenames off
+  disk, so a plugin file whose frontmatter does not parse still suppresses its
+  live twin — it is authored either way, and `specialistsSkipped` is what reports
+  the parse failure. The exclusion applies to the live copy only: a copy found in
+  quarantine is operator state, keeps its Shipped row and its `disabled:true`,
+  and is therefore still switchable back on. Each exclusion logs
+  `op=list-shipped-dedup file=<name>` and the count rides `op=list` and the
+  response as `deduped`.
 
 The former "Public" flyout toggle in the account menu was removed; this page is
 the sole agent surface.
@@ -3201,9 +3239,9 @@ explicit `?plugin=` parameter, not inferred from `--` in the slug.
 
 | Route | Behaviour |
 |-------|-----------|
-| `GET /api/admin/agents` | Session-scoped. Lists the session account's public `agents/*/` dirs (never the `admin` agent), its user-created specialists from `plugins/*/agents/*.md`, and its shipped specialists, each row tagged `kind` and `origin` and carrying `risk`, `riskiestTool`, `unresolved` and `disabled`. Returns `{agents, accountId, skipped, specialistsSkipped, shippedSkipped}`. 401 when the session maps to no account. |
+| `GET /api/admin/agents` | Session-scoped. Lists the session account's public `agents/*/` dirs (never the `admin` agent), its user-created specialists from `plugins/*/agents/*.md`, and its shipped specialists, each row tagged `kind` and `origin` and carrying `risk`, `riskiestTool`, `unresolved` and `disabled`. A live-directory candidate whose filename also exists under `plugins/*/agents/` is dropped and counted, so an activated user-created agent is listed once. Returns `{agents, accountId, skipped, specialistsSkipped, shippedSkipped, deduped, riskSurfaceFailed}`. 401 when the session maps to no account. |
 | `GET /api/admin/agents/:slug` | Session-scoped. Without `?plugin=` or `?origin=`, returns a public agent's config fields + four owned docs + a `present` map (a missing or unreadable doc is `''`/`present.<role>=false`, never a 500). With `?plugin=`, that plugin's user-created specialist; with `?origin=shipped`, the shipped one. Both specialist shapes add `{risk, riskiestTool, unresolved, byTool, disabled}`, where `byTool` is one class per declared tool. Selection is explicit rather than inferred, because a premium file and a user-created specialist under a plugin of the same name produce the same slug. Unknown 404s, 401 as above. |
-| `POST /api/admin/agents/:slug/disable?accountId=` | Shipped agents only, enforced here: a slug present in none of the three shipped directories 404s. Moves the file from `specialists/agents/` to `specialists/agents-disabled/` and records the basename in the 0600 store. Returns `{ok, moved}`; `moved:false` means the agent existed only as a bundled template, so nothing was there to move and the store entry is what stops the next provisioning run delivering it. The store is read strictly before anything moves, so an unreadable store 500s with the file untouched rather than rewriting the file whole from an empty set and dropping every other disabled agent. Returns `routingReconciled`, which is `false` when the AGENTS.md reconcile threw: the move and the store write already happened, so the request is not failed, and the caller is told rather than left assuming the prose is correct. Same `accountId` contract as delete. |
+| `POST /api/admin/agents/:slug/disable?accountId=` | Shipped agents only, enforced here: a slug present in none of the three shipped directories 404s, and so does a slug present under `plugins/*/agents/` (a user-created specialist, `reason=user-created-specialist`), because its activated copy in the live directory would otherwise pass the shipped test. Moves the file from `specialists/agents/` to `specialists/agents-disabled/` and records the basename in the 0600 store. Returns `{ok, moved}`; `moved:false` means the agent existed only as a bundled template, so nothing was there to move and the store entry is what stops the next provisioning run delivering it. The store is read strictly before anything moves, so an unreadable store 500s with the file untouched rather than rewriting the file whole from an empty set and dropping every other disabled agent. Returns `routingReconciled`, which is `false` when the AGENTS.md reconcile threw: the move and the store write already happened, so the request is not failed, and the caller is told rather than left assuming the prose is correct. Same `accountId` contract as delete. |
 | `POST /api/admin/agents/:slug/enable?accountId=` | Covers both of disable's outcomes. Returns `{ok, restored}`: a quarantined file moves back (`restored:true`); a bundled-only agent has nothing to move, so clearing the store entry is the whole job (`restored:false`), which is what stops provisioning withholding it. Treating that second case as "nothing to restore" made disable a one-way door. 404 only when neither directory nor store knows the agent. Carries the same `routingReconciled` field; the restored file is what puts the routing line back. |
 | `DELETE /api/admin/agents/:slug?accountId=` | Public agents only, on the named validated account. Removes the dir after `deleteAgentProjection`; refuses the `admin` slug (403) and a missing/unknown `accountId` (400) with no write. Loud-fail: a graph-cleanup throw aborts the file removal. |
 | `POST /api/admin/agents/:slug/project?accountId=` | Re-projects the named account's on-disk agent into the graph. Same `accountId` contract as delete. |
@@ -3231,6 +3269,13 @@ Agents page survived undiagnosed on a multi-account install.
 - `op=delete accountId=<id8> slug=<…> outcome=<ok|failed>` with
   `reason=<graph-cleanup-failed|rm-error>` on failure (files preserved on a
   graph-cleanup throw).
+- `op=list-shipped-dedup file=<name>` — one line per live-directory candidate
+  dropped as an authored duplicate, with `deduped=<n>` on the `op=list` line and
+  in the response. `shipped + shippedSkipped + deduped` equals the number of
+  distinct `.md` names across the three source directories, so a listing that
+  does not add up is visible without reproducing anything. The over-exclusion to
+  watch for is a `deduped` line naming a file that is also a bundled or premium
+  agent: the authored file then hides a genuinely shipped one.
 - `op=classify account=<id8> agent=<name> origin=<shipped|public|specialist>
   risk=<green|amber|red> riskiestTool=<tool> tools=<n> unresolved=<comma-list|none>
   disabled=<bool>` — one line per classified agent per listing, so it fires on
@@ -4795,6 +4840,10 @@ npx -y @rubytech/create-realagent-code       # realagent brand
 
 **LaunchAgent.** The installer registers `SiteDesk` as a launchd LaunchAgent at `~/Library/LaunchAgents/com.rubytech.<brand-hostname>.plist` — for example `com.rubytech.maxy-code.plist`. Survives logout/login and reboot via `KeepAlive=true` and `RunAtLoad=true`. Two brands on the same Mac get two distinct plists (brand-hostname-keyed), so install order is independent. Use `launchctl print gui/$UID/com.rubytech.<brand-hostname>` for service state. The `[create-maxy] launchd-plist=<path> loaded=true` line in the install log confirms `launchctl bootstrap` accepted the plist; `loaded=false exit=<n>` is the failure signal (run `plutil -lint <path>` to diagnose).
 
+**Restart waits for the old instance.** This covers the session-manager, heartbeat, logs-rotate and dedicated-Neo4j agents — not the main service above, which bootstraps directly. A re-install boots the agent out first, but `launchctl bootout` returns as soon as launchd accepts the request: the job's process can keep running for seconds afterwards (a dedicated Neo4j's JVM took 14.2 s to finish its store flush), and `launchctl bootstrap` returns `exit 5: Input/output error` for that whole window. The installer therefore polls `launchctl print gui/$UID/<label>` every 500 ms until the label leaves the domain, up to 60 s total across all attempts, before bootstrapping; if it never leaves, the installer bootstraps anyway and the exit code decides. The lifecycle is one log line per step, keyed `agent=<label>`: `op=bootout`, `op=wait-poll present=<bool> probeRc=<n|null>`, `op=gone goneMs=<n> polls=<n>`, `op=bootstrap rc=<n> waitedMs=<n>`, `op=result ok=<bool> totalWaitedMs=<n> probeFailures=<n>`. `op=gone goneMs=<n>` is how long the previous instance actually took to exit; `op=wait-timeout` means it never left within 60 s; `probeFailures=<n>` counts probes that could not run at all, which makes the wait blind.
+
+Note `launchctl print`'s exit code reports domain membership, not liveness — a job that loads and exits immediately still returns 0. Detecting a dead-on-arrival agent needs a different primitive and is not attempted; for the main service and the session manager the existing `/healthz` probe is what catches it.
+
 **Cloudflare on darwin.** The installer brew-installs the `cloudflared` binary so it is on PATH, but does not invoke `cloudflared service install` or `cloudflared tunnel route dns` — public reach is opt-in. After install, the operator runs `cloudflared tunnel login` (browser-driven) followed by the existing tunnel-setup flow if they want a public address. Grep `[create-maxy] darwin-cloudflare-skip=true` in the install log to confirm the installer took the documented skip path.
 
 **Uninstall.** `npx -y @rubytech/create-maxy-code uninstall` (or the realagent equivalent) bootsout the LaunchAgent, removes the plist, and deletes `~/.<brand>/`. Homebrew-installed dependencies (curl, git, unzip, jq, poppler, ffmpeg, node@22, neo4j, cloudflared) remain — remove them with `brew uninstall` if you want a clean slate.

package/payload/platform/plugins/admin/skills/whats-new/SKILL.md

@@ -9,6 +9,12 @@ Invoked by the admin agent directly.
 
 This is the platform's release timeline, newest first. Each entry shows the date it shipped and the version it shipped in, so you can tell the operator how current their install is. To compare, read the installed version from `capabilities-here` and match it against the versions below. Keep answers high level and in plain English; this is a summary, not a full commit log.
 
+## 2026-07-27 (0.1.516)
+
+- Meeting invitations attached to an email are no longer invisible: a calendar part now counts as an attachment on every read path.
+- The Agents page no longer lists a specialist you created twice, once as your own and again as shipped.
+- Outlook errors now say what actually happened. A refusal on an item that was deleted reads as deletion rather than a missing permission, and a mailbox being moved gets its own message instead of a bare server error.
+
 ## 2026-07-27 (0.1.515)
 
 - Disabling an agent now takes effect straight away: it is dropped from the routing table, reported as disabled rather than missing, and the agents file is reconciled on both disable and enable.