@rubytech/create-sitedesk-code 0.1.514 → 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.514",
+  "version": "0.1.516",
   "description": "Install SiteDesk — automated back office for independent building contractors",
   "bin": {
     "create-sitedesk-code": "./dist/index.js"