@rubytech/create-maxy-code 0.1.389 → 0.1.392

package/dist/__tests__/claude-bin.test.js

@@ -0,0 +1,51 @@
+// acceptance grid for claude-bin.ts (Task 1395 gap 4).
+//
+// Pure resolver: version parse/compare, canonical pick (highest version),
+// and PATH enumeration with injected fs/spawn so no real binary is probed.
+// Runs under node --test alongside the rest of the package.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { pickCanonicalClaude, compareVersions, parseClaudeVersion, enumerateClaudeCandidates, } from "../claude-bin.js";
+test("parseClaudeVersion extracts leading version", () => {
+    assert.equal(parseClaudeVersion("2.1.201 (Claude Code)"), "2.1.201");
+    assert.equal(parseClaudeVersion("  2.1.153 (Claude Code)\n"), "2.1.153");
+    assert.equal(parseClaudeVersion("not installed"), null);
+});
+test("compareVersions orders by numeric parts", () => {
+    assert.ok(compareVersions("2.1.201", "2.1.153") > 0);
+    assert.ok(compareVersions("2.1.153", "2.1.201") < 0);
+    assert.equal(compareVersions("2.1.1", "2.1.1"), 0);
+    assert.ok(compareVersions("2.2.0", "2.1.999") > 0);
+});
+test("pickCanonicalClaude picks highest version (nvm over stale Cask)", () => {
+    const pick = pickCanonicalClaude([
+        { path: "/usr/local/bin/claude", version: "2.1.153" },
+        { path: "/Users/x/.nvm/versions/node/v22/bin/claude", version: "2.1.201" },
+    ]);
+    assert.equal(pick, "/Users/x/.nvm/versions/node/v22/bin/claude");
+});
+test("pickCanonicalClaude: empty -> null, ties -> first", () => {
+    assert.equal(pickCanonicalClaude([]), null);
+    assert.equal(pickCanonicalClaude([
+        { path: "/a/claude", version: "2.1.1" },
+        { path: "/b/claude", version: "2.1.1" },
+    ]), "/a/claude");
+});
+test("enumerateClaudeCandidates dedupes by realpath, skips non-exec/unversioned", () => {
+    const versions = {
+        "/opt/homebrew/bin/claude": "2.1.201 (Claude Code)",
+        "/usr/local/bin/claude": "2.1.153 (Claude Code)",
+    };
+    const deps = {
+        isExecutable: (p) => p === "/opt/homebrew/bin/claude" || p === "/usr/local/bin/claude" || p === "/dup/claude",
+        // /dup/claude is a symlink to the homebrew one -> deduped away
+        realpath: (p) => (p === "/dup/claude" ? "/opt/homebrew/bin/claude" : p),
+        runVersion: (p) => versions[p] ?? null,
+    };
+    const cands = enumerateClaudeCandidates("/opt/homebrew/bin:/usr/local/bin:/dup:/empty", deps);
+    assert.deepEqual(cands, [
+        { path: "/opt/homebrew/bin/claude", version: "2.1.201" },
+        { path: "/usr/local/bin/claude", version: "2.1.153" },
+    ]);
+    assert.equal(pickCanonicalClaude(cands), "/opt/homebrew/bin/claude");
+});

package/dist/__tests__/claude-upgrade-privilege.test.js

@@ -0,0 +1,17 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { decideClaudeUpgradePrivilege } from "../claude-upgrade-privilege.js";
+test("darwin: writable user-owned prefix runs the upgrade without sudo", () => {
+    assert.equal(decideClaudeUpgradePrivilege({ platform: "darwin", prefixWritable: true, canSudo: false }), "run-no-sudo");
+    assert.equal(decideClaudeUpgradePrivilege({ platform: "darwin", prefixWritable: true, canSudo: true }), "run-no-sudo");
+});
+test("darwin: non-writable prefix falls back to sudo when available, else skips", () => {
+    assert.equal(decideClaudeUpgradePrivilege({ platform: "darwin", prefixWritable: false, canSudo: true }), "run-sudo");
+    assert.equal(decideClaudeUpgradePrivilege({ platform: "darwin", prefixWritable: false, canSudo: false }), "skip");
+});
+test("linux: unchanged — sudo when available, skip when not; prefixWritable is ignored", () => {
+    assert.equal(decideClaudeUpgradePrivilege({ platform: "linux", prefixWritable: false, canSudo: true }), "run-sudo");
+    assert.equal(decideClaudeUpgradePrivilege({ platform: "linux", prefixWritable: false, canSudo: false }), "skip");
+    // prefixWritable must not change the Linux decision (root-owned global prefix assumed).
+    assert.equal(decideClaudeUpgradePrivilege({ platform: "linux", prefixWritable: true, canSudo: false }), "skip");
+});

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

@@ -10,7 +10,7 @@
 // package so `node --test dist/__tests__/*.test.js` picks it up after build.
 import test from "node:test";
 import assert from "node:assert/strict";
-import { renderPlist } from "../launchd-plist.js";
+import { renderPlist, buildSessionManagerWrapper } from "../launchd-plist.js";
 // ---------------------------------------------------------------------------
 // Standard render — every required field present, no escaping needed.
 // ---------------------------------------------------------------------------
@@ -193,3 +193,38 @@ test("renderPlist omits WorkingDirectory key when workingDirectory is absent", (
     assert.match(xml, /<key>KeepAlive<\/key>/);
     assert.match(xml, /<key>RunAtLoad<\/key>/);
 });
+// ---------------------------------------------------------------------------
+// buildSessionManagerWrapper — Task 1395 gap 2
+// ---------------------------------------------------------------------------
+test("buildSessionManagerWrapper sources .env and execs the manager", () => {
+    const w = buildSessionManagerWrapper({
+        envPath: "/Users/x/.maxy/.env",
+        installDir: "/Users/x/maxy-code",
+        nodeBin: "/usr/local/bin/node",
+        persistDir: "/Users/x/.maxy",
+        brandPort: 19200,
+    });
+    assert.match(w, /^#!\/bin\/bash\n/);
+    assert.match(w, /set -a; \[ -f "\/Users\/x\/\.maxy\/\.env" \] && \. "\/Users\/x\/\.maxy\/\.env"; set \+a/);
+    assert.match(w, /export CLAUDE_SESSION_MANAGER_PERSIST_DIR="\/Users\/x\/\.maxy"/);
+    assert.match(w, /export PLATFORM_ROOT="\/Users\/x\/maxy-code\/platform"/);
+    assert.match(w, /export MAXY_BRAND_PORT="19200"/);
+    assert.match(w, /export PLATFORM_PORT="19200"/);
+    assert.match(w, /cd "\/Users\/x\/maxy-code\/platform\/services\/claude-session-manager"/);
+    assert.match(w, /exec \/usr\/local\/bin\/node dist\/index\.js\n$/);
+});
+test("session-manager plist renders bash wrapper as sole ProgramArguments", () => {
+    const xml = renderPlist({
+        label: "com.rubytech.maxy-code-claude-session-manager",
+        programArguments: ["/bin/bash", "/Users/x/.maxy/claude-session-manager-wrapper.sh"],
+        stdoutPath: "/Users/x/.maxy/logs/server.log",
+        stderrPath: "/Users/x/.maxy/logs/server.log",
+        keepAlive: true,
+        runAtLoad: true,
+        workingDirectory: "/Users/x/maxy-code/platform/services/claude-session-manager",
+    });
+    assert.match(xml, /<string>com\.rubytech\.maxy-code-claude-session-manager<\/string>/);
+    assert.match(xml, /<string>\/bin\/bash<\/string>\s*<string>\/Users\/x\/\.maxy\/claude-session-manager-wrapper\.sh<\/string>/);
+    assert.match(xml, /<key>KeepAlive<\/key>\s*<true\/>/);
+    assert.match(xml, /<key>RunAtLoad<\/key>\s*<true\/>/);
+});

package/dist/__tests__/macos-darwin-branch.test.js

@@ -81,3 +81,21 @@ test("uninstall darwin path bootsout the LaunchAgent and removes the plist", ()
     // brand-keyed — install + uninstall both depend on the same label shape.
     assert.match(SRC, /function launchdLabel\(\):\s*string\s*\{\s*return\s*`com\.rubytech\.\$\{BRAND\.hostname\}`/);
 });
+test("resetNeo4jAuth has a darwin branch that uses brew services and no sudo", () => {
+    // On darwin Neo4j runs under a user launchd agent (brew services) and its
+    // datadir is user-owned — no systemctl, no sudo. Task 1394. Static-grep, not
+    // behaviour: resetNeo4jAuth spawns brew/neo4j-admin and can't run headless.
+    const fn = SRC.slice(SRC.indexOf("function resetNeo4jAuth"), SRC.indexOf("function redactInstallLogs"));
+    assert.match(fn, /platform === "darwin"/, "resetNeo4jAuth must branch on darwin");
+    assert.match(fn, /brew["']?,\s*\[["']services["']\s*,\s*["']stop["']/, "darwin branch stops neo4j via brew services");
+    assert.match(fn, /brew["']?,\s*\[["']services["']\s*,\s*["']start["']/, "darwin branch starts neo4j via brew services");
+    assert.match(fn, /neo4j-darwin-auth-reset/, "darwin branch emits the reset observability marker");
+    // The darwin branch must NOT shell out to systemctl or sudo (that path is
+    // Linux-only). Match invocation shapes — quoted command literals and the
+    // `sudo: true` option — not prose, so the branch's own explanatory comment
+    // ("no systemctl, no sudo") does not defeat the assertion.
+    const darwinBranch = fn.slice(fn.indexOf('platform === "darwin"'), fn.indexOf("} else {"));
+    assert.ok(!/["']systemctl["']/.test(darwinBranch), "darwin branch must not invoke systemctl");
+    assert.ok(!/["']sudo["']/.test(darwinBranch), "darwin branch must not spawn sudo");
+    assert.ok(!/sudo:\s*true/.test(darwinBranch), "darwin branch must not pass { sudo: true } on the user-owned datadir");
+});

package/dist/__tests__/neo4j-datadir.test.js

@@ -0,0 +1,14 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { resolveNeo4jDataDir } from "../neo4j-datadir.js";
+test("darwin resolves the Homebrew datadir under the brew prefix (Intel + Apple Silicon)", () => {
+    assert.equal(resolveNeo4jDataDir({ platform: "darwin", brewPrefix: "/usr/local", dedicated: false, hostname: "maxy-code" }), "/usr/local/var/neo4j");
+    assert.equal(resolveNeo4jDataDir({ platform: "darwin", brewPrefix: "/opt/homebrew", dedicated: false, hostname: "maxy-code" }), "/opt/homebrew/var/neo4j");
+});
+test("darwin ignores dedicated — only the shared Homebrew instance exists on darwin", () => {
+    assert.equal(resolveNeo4jDataDir({ platform: "darwin", brewPrefix: "/usr/local", dedicated: true, hostname: "realagent-code" }), "/usr/local/var/neo4j");
+});
+test("linux shared and dedicated datadirs are unchanged", () => {
+    assert.equal(resolveNeo4jDataDir({ platform: "linux", brewPrefix: "", dedicated: false, hostname: "maxy-code" }), "/var/lib/neo4j");
+    assert.equal(resolveNeo4jDataDir({ platform: "linux", brewPrefix: "", dedicated: true, hostname: "realagent" }), "/var/lib/neo4j-realagent");
+});

package/dist/claude-bin.js

@@ -0,0 +1,78 @@
+// Task 1395 gap 4 — resolve one canonical `claude` binary.
+//
+// A Mac can carry more than one `claude` on PATH at different versions — e.g.
+// an npm-global (nvm/Homebrew node) claude AND a Homebrew Cask `claude-code` at
+// /usr/local/bin/claude. Whichever the runtime PATH hits first wins, which
+// during the Task 1393 migration was the STALE Cask (2.1.153) rather than the
+// logged-in nvm binary (2.1.201). The installer resolves a single canonical
+// path and persists it as CLAUDE_BIN in `.env`; every runtime spawn then uses
+// that exact binary instead of a PATH lottery.
+//
+// Canonical = highest version. This is deterministic and picks the newest
+// claude, which is the defensible choice when two are present. All fs/spawn I/O
+// is injected so the resolver stays pure and unit-testable.
+import { join } from "node:path";
+/** Extract the leading dotted-numeric version from `claude --version` output,
+ *  e.g. "2.1.201 (Claude Code)" -> "2.1.201". Returns null when absent. */
+export function parseClaudeVersion(raw) {
+    const m = raw.trim().match(/(\d+(?:\.\d+)+)/);
+    return m ? m[1] : null;
+}
+function toParts(v) {
+    const m = v.trim().match(/^(\d+(?:\.\d+)*)/);
+    return m ? m[1].split(".").map((n) => parseInt(n, 10)) : [];
+}
+/** Numeric dotted-version compare (a<b -> <0, a>b -> >0). Missing parts = 0. */
+export function compareVersions(a, b) {
+    const pa = toParts(a);
+    const pb = toParts(b);
+    const len = Math.max(pa.length, pb.length);
+    for (let i = 0; i < len; i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+/** Pick the highest-version candidate's path; first-wins on ties. Null when the
+ *  list is empty. */
+export function pickCanonicalClaude(candidates) {
+    if (candidates.length === 0)
+        return null;
+    let best = candidates[0];
+    for (let i = 1; i < candidates.length; i++) {
+        if (compareVersions(candidates[i].version, best.version) > 0)
+            best = candidates[i];
+    }
+    return best.path;
+}
+/** Enumerate every distinct `claude` reachable from `pathEnv` (colon-separated
+ *  PATH), deduped by realpath, each probed for its version. Non-executable
+ *  entries, symlink duplicates, and version-probe failures are skipped. */
+export function enumerateClaudeCandidates(pathEnv, deps) {
+    const seen = new Set();
+    const out = [];
+    for (const dir of pathEnv.split(":").filter(Boolean)) {
+        const cand = join(dir, "claude");
+        if (!deps.isExecutable(cand))
+            continue;
+        let real;
+        try {
+            real = deps.realpath(cand);
+        }
+        catch {
+            real = cand;
+        }
+        if (seen.has(real))
+            continue;
+        seen.add(real);
+        const raw = deps.runVersion(cand);
+        if (!raw)
+            continue;
+        const version = parseClaudeVersion(raw);
+        if (!version)
+            continue;
+        out.push({ path: cand, version });
+    }
+    return out;
+}

package/dist/claude-upgrade-privilege.js

@@ -0,0 +1,21 @@
+// Pure decision for whether the phase-3 `npm install -g @anthropic-ai/claude-code`
+// upgrade runs under sudo, runs unprivileged, or is skipped. Peer of
+// apt-resolve.ts / brew-resolve.ts: no spawnSync, no fs — the caller injects the
+// probed inputs and applies the result.
+//
+// Root cause this encodes: on darwin the npm global prefix (nvm or Homebrew) is
+// user-owned, so `npm install -g` needs no sudo; wrapping it in sudo forces a
+// non-interactive password prompt that hard-fails. On Linux the global prefix is
+// root-owned by default, so the existing sudo-or-skip behaviour is preserved
+// unchanged (prefixWritable is not consulted on Linux).
+export function decideClaudeUpgradePrivilege(input) {
+    if (input.platform === "darwin") {
+        if (input.prefixWritable)
+            return "run-no-sudo";
+        if (input.canSudo)
+            return "run-sudo";
+        return "skip";
+    }
+    // linux: unchanged from the historical `isLinux() && !canSudo()` skip.
+    return input.canSudo ? "run-sudo" : "skip";
+}

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { execFileSync, spawn, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, writeFileSync, cpSync, readFileSync, rmSync, readdirSync, appendFileSync, openSync, closeSync, chmodSync, statSync, realpathSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync, cpSync, readFileSync, rmSync, readdirSync, appendFileSync, openSync, closeSync, chmodSync, statSync, realpathSync, accessSync, constants as fsConstants } from "node:fs";
 import { registerSpecialistAgentsAt, SpecialistSymlinkCollision } from "./specialist-registration.js";
 import { seedBypassPermissionsSettings, assertBypassPermissionsSeed } from "./permissions-seed.js";
 import { resolve, join, dirname } from "node:path";
@@ -13,8 +13,11 @@ import { findPeerBrandOnDefaultNeo4jPort } from "./peer-brand-detect.js";
 import { resolveNeo4jPidfileScrub } from "./neo4j-pidfile-scrub.js";
 import { runInitLogging } from "./init-logging.js";
 import { requireSupportedPlatform, detectPlatform } from "./platform-detect.js";
+import { decideClaudeUpgradePrivilege } from "./claude-upgrade-privilege.js";
+import { resolveNeo4jDataDir } from "./neo4j-datadir.js";
 import { protectCommands, unprotectCommands, lsattrShowsImmutable } from "./install-immutability.js";
-import { renderPlist } from "./launchd-plist.js";
+import { renderPlist, buildSessionManagerWrapper } from "./launchd-plist.js";
+import { enumerateClaudeCandidates, pickCanonicalClaude } from "./claude-bin.js";
 import { installAllBrewPackages } from "./brew-install.js";
 import { parseSwVers, isSupportedMacosVersion } from "./macos-version.js";
 import { decideChromiumAction, isSnapConfinedPath } from "./snap-chromium.js";
@@ -278,6 +281,29 @@ function canSudo() {
     const result = spawnSync("sudo", ["-n", "true"], { stdio: "pipe", timeout: 5_000 });
     return result.status === 0;
 }
+/** True when the npm global prefix's node_modules dir is writable by the current
+ *  user (nvm/Homebrew installs) — meaning `npm install -g` needs no sudo. */
+function npmGlobalPrefixWritable() {
+    try {
+        const prefix = execFileSync("npm", ["prefix", "-g"], { encoding: "utf-8", timeout: 10_000 }).trim();
+        accessSync(join(prefix, "lib", "node_modules"), fsConstants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve the Homebrew prefix (`/usr/local` on Intel, `/opt/homebrew` on Apple
+ *  Silicon). Falls back to the arch default if `brew --prefix` is unavailable. */
+function resolveBrewPrefix() {
+    try {
+        const out = execFileSync("brew", ["--prefix"], { encoding: "utf-8", timeout: 10_000 }).trim();
+        if (out)
+            return out;
+    }
+    catch { /* fall through to arch default */ }
+    return isArm64() ? "/opt/homebrew" : "/usr/local";
+}
 // verified-not-asserted apt-dep reconciliation.
 // resolve package-name aliases before probing dpkg, so the
 // post-install check no longer false-negatives when apt resolves a virtual
@@ -1023,13 +1049,44 @@ function installNodejs() {
     console.log("  [privileged] apt-get install");
     shell("apt-get", ["install", "-y", "nodejs"], { sudo: true });
 }
+// Task 1395 gap 4 — the single canonical `claude` path resolved for this
+// install, pinned into `.env` as CLAUDE_BIN by installServiceDarwin. Null on
+// Linux (and darwin when unresolved) — callers fall back to bare `claude`.
+let RESOLVED_CLAUDE_BIN = null;
+/** Resolve the highest-version `claude` reachable from the runtime PATH the
+ *  launchd wrapper will use (`/opt/homebrew/bin:/usr/local/bin:$PATH`). Darwin
+ *  only — a Mac can carry two claude binaries at different versions; the
+ *  logged-in one must win, not whichever the bare PATH hits first. */
+function resolveCanonicalClaudeBin() {
+    if (process.platform !== "darwin")
+        return null;
+    const runtimePath = `/opt/homebrew/bin:/usr/local/bin:${process.env.PATH ?? ""}`;
+    const candidates = enumerateClaudeCandidates(runtimePath, {
+        isExecutable: (p) => { try {
+            accessSync(p, fsConstants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        } },
+        realpath: (p) => realpathSync(p),
+        runVersion: (p) => {
+            const r = spawnSync(p, ["--version"], { encoding: "utf-8", timeout: 5_000 });
+            return r.status === 0 ? (r.stdout ?? "").toString() : null;
+        },
+    });
+    return pickCanonicalClaude(candidates);
+}
 function installClaudeCode() {
     let needsInstall = true;
+    // Darwin: pin the canonical claude before the version check so the check (and
+    // any upgrade decision) targets the logged-in binary, not the stale one.
+    const claudeForCheck = (RESOLVED_CLAUDE_BIN = resolveCanonicalClaudeBin()) ?? "claude";
     if (commandExists("claude")) {
         try {
             // `claude --version` prints "2.1.114 (Claude Code)" — extract the semver so
             // the equality check against `npm view` (which returns bare "2.1.114") works.
-            const rawVersion = execFileSync("claude", ["--version"], { encoding: "utf-8", timeout: 10_000 }).trim();
+            const rawVersion = execFileSync(claudeForCheck, ["--version"], { encoding: "utf-8", timeout: 10_000 }).trim();
             const installed = rawVersion.match(/^(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)/)?.[1] ?? rawVersion;
             let latest = null;
             try {
@@ -1054,21 +1111,38 @@ function installClaudeCode() {
         log("3", TOTAL, "Installing Claude Code...");
     }
     if (needsInstall) {
-        // `npm install -g` needs write access to the global prefix, which on Linux is
-        // root-owned by default — so we run it under sudo. When sudo requires a password
-        // and the installer is running non-interactively (e.g. systemd-run --scope on
-        // upgrade), sudo fails instantly. Skip the upgrade in that case; the running
-        // installation is assumed adequate. Matches the apt-get skip in step 1.
-        if (isLinux() && !canSudo()) {
+        // `npm install -g` needs write access to the global prefix. On Linux that
+        // prefix is root-owned by default, so we run under sudo — and skip when sudo
+        // is non-interactive (e.g. systemd-run --scope on upgrade), keeping the
+        // running version. On darwin the nvm/Homebrew prefix is user-owned, so the
+        // upgrade runs unprivileged; sudo there would force a password prompt that
+        // hard-fails non-interactively.
+        const platform = requireSupportedPlatform(process.platform);
+        const decision = decideClaudeUpgradePrivilege({
+            platform,
+            prefixWritable: platform === "darwin" ? npmGlobalPrefixWritable() : false,
+            canSudo: canSudo(),
+        });
+        if (decision === "skip") {
+            logFile(`[create-maxy] claude-upgrade skipped reason=no-noninteractive-sudo platform=${platform}`);
             console.log("  Skipping Claude Code upgrade (sudo unavailable non-interactively — keeping installed version)");
         }
         else {
+            const useSudo = decision === "run-sudo";
+            logFile(`[create-maxy] claude-upgrade platform=${platform} sudo=${useSudo}`);
             console.log("  This may take 15–30 minutes on Raspberry Pi...");
-            console.log("  [privileged] npm install -g @anthropic-ai/claude-code@latest");
-            shellRetry("npm", ["install", "-g", ...NPM_NET_FLAGS, "--loglevel", "verbose", "@anthropic-ai/claude-code@latest"], { sudo: true, timeout: 2_400_000 }, // 40 min — Pi downloads can take 25+ min
+            console.log(`  ${useSudo ? "[privileged] " : ""}npm install -g @anthropic-ai/claude-code@latest`);
+            shellRetry("npm", ["install", "-g", ...NPM_NET_FLAGS, "--loglevel", "verbose", "@anthropic-ai/claude-code@latest"], { sudo: useSudo, timeout: 2_400_000 }, // 40 min — Pi downloads can take 25+ min
             3, 30);
         }
     }
+    // Task 1395 gap 4 — a darwin upgrade may have just installed a newer
+    // npm-global claude; re-resolve so the pinned CLAUDE_BIN reflects post-upgrade
+    // state. Keep the pre-upgrade pick if re-resolution finds nothing.
+    RESOLVED_CLAUDE_BIN = resolveCanonicalClaudeBin() ?? RESOLVED_CLAUDE_BIN;
+    if (process.platform === "darwin") {
+        logFile(`  [create-maxy] claude-bin=${RESOLVED_CLAUDE_BIN ?? "unresolved"}`);
+    }
     console.log("  Registering Claude plugin marketplaces...");
     // pre-create the per-brand CLAUDE_CONFIG_DIR so the first
     // `claude plugin marketplace add` has a directory to write into.
@@ -1176,34 +1250,54 @@ function installClaudeCode() {
         console.log(`  Warning: Playwright MCP cache may be incomplete (browser automation may not work).${npxResult.stderr ? ` npx stderr: ${npxResult.stderr.slice(0, 200)}` : ""}`);
     }
 }
-function resetNeo4jAuth(port = DEFAULT_NEO4J_PORT, dataDir = "/var/lib/neo4j") {
+function resetNeo4jAuth(port = DEFAULT_NEO4J_PORT, dataDir = "/var/lib/neo4j", platform = "linux") {
     const password = randomBytes(24).toString("base64url");
     const dedicated = port !== DEFAULT_NEO4J_PORT;
-    const serviceName = dedicated ? `neo4j-${BRAND.hostname}` : "neo4j";
-    console.log(`  Resetting Neo4j auth with fresh password (${serviceName})...`);
-    spawnSync("sudo", ["systemctl", "stop", serviceName], { stdio: "inherit" });
-    // Clear the system database (stores auth/roles) and dbms auth config.
-    // The neo4j user database (graph data) is preserved.
-    // set-initial-password only works before the system DB's first start,
-    // so we must delete it to make Neo4j treat the next start as initial.
-    spawnSync("sudo", ["rm", "-rf",
+    // Clear the system database (stores auth/roles) and dbms auth config so the
+    // next start is treated as initial and set-initial-password takes. The neo4j
+    // user database (graph data) is preserved.
+    const clearPaths = [
         `${dataDir}/data/dbms`,
         `${dataDir}/data/databases/system`,
         `${dataDir}/data/transactions/system`,
-    ], { stdio: "inherit" });
-    if (dedicated) {
-        const confDir = `/etc/neo4j-${BRAND.hostname}`;
-        // sudo env VAR=val passes the variable through sudo's env_reset
-        spawnSync("sudo", ["env", `NEO4J_CONF=${confDir}`, "neo4j-admin", "dbms", "set-initial-password", "--", password], {
-            stdio: "inherit",
-        });
+    ];
+    if (platform === "darwin") {
+        // Homebrew Neo4j runs under a user launchd agent (brew services) and its
+        // datadir is user-owned — no systemctl, no sudo. This branch handles the
+        // shared (default-brand) instance. Dedicated brands (realagent-code etc.)
+        // set NEO4J_DEDICATED, but their dedicated provisioning (setupDedicatedNeo4j)
+        // is Linux-only and aborts a dedicated-brand darwin install upstream, so a
+        // non-default port never reaches here — see Task 1396 for darwin dedicated
+        // support.
+        console.log("  Resetting Neo4j auth with fresh password (brew services)...");
+        spawnSync("brew", ["services", "stop", "neo4j"], { stdio: "inherit" });
+        spawnSync("rm", ["-rf", ...clearPaths], { stdio: "inherit" });
+        shell("neo4j-admin", ["dbms", "set-initial-password", "--", password], { redact: true });
+        const brewStart = spawnSync("brew", ["services", "start", "neo4j"], { stdio: "inherit" });
+        if (brewStart.status !== 0) {
+            throw new Error(`brew services start neo4j failed (exit ${brewStart.status}) during auth reset — Neo4j must be running before the brand server starts`);
+        }
+        logFile(`  [neo4j-darwin-auth-reset] datadir=${dataDir} service=brew-services sudo=false`);
     }
     else {
-        console.log("  [privileged] neo4j-admin dbms");
-        shell("neo4j-admin", ["dbms", "set-initial-password", "--", password], { sudo: true, redact: true });
+        const serviceName = dedicated ? `neo4j-${BRAND.hostname}` : "neo4j";
+        console.log(`  Resetting Neo4j auth with fresh password (${serviceName})...`);
+        spawnSync("sudo", ["systemctl", "stop", serviceName], { stdio: "inherit" });
+        spawnSync("sudo", ["rm", "-rf", ...clearPaths], { stdio: "inherit" });
+        if (dedicated) {
+            const confDir = `/etc/neo4j-${BRAND.hostname}`;
+            // sudo env VAR=val passes the variable through sudo's env_reset
+            spawnSync("sudo", ["env", `NEO4J_CONF=${confDir}`, "neo4j-admin", "dbms", "set-initial-password", "--", password], {
+                stdio: "inherit",
+            });
+        }
+        else {
+            console.log("  [privileged] neo4j-admin dbms");
+            shell("neo4j-admin", ["dbms", "set-initial-password", "--", password], { sudo: true, redact: true });
+        }
+        console.log("  [privileged] systemctl start");
+        shell("systemctl", ["start", serviceName], { sudo: true });
     }
-    console.log("  [privileged] systemctl start");
-    shell("systemctl", ["start", serviceName], { sudo: true });
     console.log("  Waiting for Neo4j to start...");
     for (let i = 0; i < 15; i++) {
         const check = spawnSync("cypher-shell", [
@@ -1249,7 +1343,15 @@ function ensureNeo4jPassword() {
     const persistentPasswordFile = join(persistDir, ".neo4j-password");
     // Dedicated instances have their own auth database — password checks and resets
     // must target the dedicated port and data directory, not the shared instance.
-    const dataDir = NEO4J_DEDICATED ? `/var/lib/neo4j-${BRAND.hostname}` : "/var/lib/neo4j";
+    // On darwin the datadir lives under the Homebrew prefix and is user-owned.
+    const platform = requireSupportedPlatform(process.platform);
+    const dataDir = resolveNeo4jDataDir({
+        platform,
+        brewPrefix: platform === "darwin" ? resolveBrewPrefix() : "",
+        dedicated: NEO4J_DEDICATED,
+        hostname: BRAND.hostname,
+    });
+    logFile(`[create-maxy] neo4j-datadir=${dataDir} platform=${platform}`);
     // 1. Same-brand check: if our own password file exists and works, done (upgrade path).
     if (existsSync(passwordFile)) {
         const existingPassword = readFileSync(passwordFile, "utf-8").trim();
@@ -1276,7 +1378,7 @@ function ensureNeo4jPassword() {
         console.log("  Neo4j has existing data. Resetting auth only (data preserved)...");
         logFile(`  Neo4j auth reset — clearing dbms auth in ${dataDir}, preserving databases + transactions`);
     }
-    const password = resetNeo4jAuth(NEO4J_PORT, dataDir);
+    const password = resetNeo4jAuth(NEO4J_PORT, dataDir, platform);
     writeFileSync(passwordFile, password, { mode: 0o600 });
     mkdirSync(persistDir, { recursive: true });
     writeFileSync(persistentPasswordFile, password, { mode: 0o600 });
@@ -2542,6 +2644,39 @@ function buildPlatform() {
         }
         console.log(`  Installing claude-session-manager dependencies (${csmDir})...`);
         shellRetry("npm", ["install", "--omit=dev", ...NPM_NET_FLAGS], { cwd: csmDir }, 3, 15);
+        // Task 1395 gap 3 — on darwin node-pty ships uncompiled. Its install script
+        // is `node scripts/prebuild.js || node-gyp rebuild`; on this platform
+        // prebuild.js exits 0 without placing a binary, so `node-gyp rebuild` never
+        // runs and every PTY spawn fails `posix_spawnp failed`. `npm rebuild` just
+        // re-runs the same broken script — proven inert. The fix is to invoke
+        // `node-gyp rebuild` DIRECTLY in node-pty's resolved directory, bypassing
+        // prebuild.js. node-pty hoists to the platform workspace root, so resolve
+        // its real location rather than assuming csmDir. Xcode Command Line Tools
+        // are the prerequisite. Blocker, not warning: no addon means no session
+        // ever spawns.
+        if (process.platform === "darwin") {
+            const nodePtyCandidates = [
+                join(INSTALL_DIR, "platform", "node_modules", "node-pty"),
+                join(csmDir, "node_modules", "node-pty"),
+            ];
+            const nodePtyDir = nodePtyCandidates.find((d) => existsSync(d));
+            if (!nodePtyDir) {
+                throw new Error(`node-pty not found after install (looked in ${nodePtyCandidates.join(", ")}). ` +
+                    `The platform / claude-session-manager npm install did not place it.`);
+            }
+            console.log(`  Rebuilding node-pty native addon (darwin, ${nodePtyDir})...`);
+            const rebuilt = spawnSync("npx", ["--yes", "node-gyp", "rebuild"], { cwd: nodePtyDir, stdio: "inherit", timeout: 300_000 });
+            const nodePtyRelease = join(nodePtyDir, "build", "Release");
+            const ptyNode = join(nodePtyRelease, "pty.node");
+            const spawnHelper = join(nodePtyRelease, "spawn-helper");
+            const built = existsSync(ptyNode) && existsSync(spawnHelper);
+            logFile(`  [create-maxy] node-pty build=${built ? "rebuilt" : "failed"} exit=${rebuilt.status ?? "null"} dir=${nodePtyDir} pty.node=${existsSync(ptyNode)} spawn-helper=${existsSync(spawnHelper)}`);
+            if (!built) {
+                throw new Error(`node-pty native addon missing after node-gyp rebuild in ${nodePtyDir} ` +
+                    `(pty.node=${existsSync(ptyNode)} spawn-helper=${existsSync(spawnHelper)}). ` +
+                    `Install Xcode Command Line Tools (xcode-select --install) and re-run.`);
+            }
+        }
     }
     // (maxy-code, Task 677 P2) — whatsapp-channel service has its own
     // package.json declaring @modelcontextprotocol/sdk. It ships dist/ +
@@ -3203,8 +3338,20 @@ function installServiceDarwin() {
                 envContent = envContent.trimEnd() + (envContent.length > 0 ? "\n" : "") + `${key}=${value}\n`;
             }
         }
+        // Task 1395 gap 4 — pin the canonical claude path (resolved in phase 3) so
+        // every runtime spawn under launchd uses the logged-in binary, not whichever
+        // the bare launchd PATH resolves first. Written only when resolved; an unset
+        // CLAUDE_BIN makes runtime callers fall back to bare `claude` on PATH.
+        const canonicalClaude = RESOLVED_CLAUDE_BIN ?? resolveCanonicalClaudeBin();
+        if (canonicalClaude) {
+            const re = /^CLAUDE_BIN=.*$/m;
+            if (re.test(envContent))
+                envContent = envContent.replace(re, `CLAUDE_BIN=${canonicalClaude}`);
+            else
+                envContent = envContent.trimEnd() + (envContent.length > 0 ? "\n" : "") + `CLAUDE_BIN=${canonicalClaude}\n`;
+        }
         writeFileSync(envPath, envContent);
-        logFile(`  .env: DISPLAY_MODE=${DISPLAY_MODE}, EMBED_MODEL=${EMBED_MODEL}, EMBED_DIMENSIONS=${EMBED_DIMS}, NEO4J_URI=bolt://localhost:${NEO4J_PORT}, PORT=${PORT}, MAXY_UI_INTERNAL_PORT=${PORT} (darwin-collapsed), CLAUDE_SESSION_MANAGER_PORT=${BRAND.claudeSessionManagerPort}, HOSTNAME=0.0.0.0, ACCOUNT_ID=${installAccountId.slice(0, 8)}…, CLAUDE_CONFIG_DIR=${persistDir}/.claude`);
+        logFile(`  .env: DISPLAY_MODE=${DISPLAY_MODE}, EMBED_MODEL=${EMBED_MODEL}, EMBED_DIMENSIONS=${EMBED_DIMS}, NEO4J_URI=bolt://localhost:${NEO4J_PORT}, PORT=${PORT}, MAXY_UI_INTERNAL_PORT=${PORT} (darwin-collapsed), CLAUDE_SESSION_MANAGER_PORT=${BRAND.claudeSessionManagerPort}, HOSTNAME=0.0.0.0, ACCOUNT_ID=${installAccountId.slice(0, 8)}…, CLAUDE_CONFIG_DIR=${persistDir}/.claude, CLAUDE_BIN=${canonicalClaude ?? "unresolved(PATH)"}`);
     }
     catch (err) {
         console.error(`  WARNING: failed to write .env to ${envPath}: ${err instanceof Error ? err.message : String(err)}`);
@@ -3266,6 +3413,66 @@ function installServiceDarwin() {
         logFile(`  [create-maxy] launchd-plist=${path} loaded=false exit=${bootstrap.status}`);
         throw new Error(`launchctl bootstrap ${gui()} ${path} failed (exit ${bootstrap.status}): ${stderr}`);
     }
+    // Task 1395 gap 2 — the claude-session-manager. On Linux it is a separate
+    // systemd user unit (buildClaudeSessionManagerUnitFile) the brand unit
+    // Requires=; darwin authored no such unit, so nothing listened on the manager
+    // port and every session spawn returned `manager-unreachable`. Author a second
+    // LaunchAgent mirroring the Linux unit: a wrapper sources .env + the
+    // manager-only vars, then execs `node dist/index.js`.
+    const smLabel = `${launchdLabel()}-claude-session-manager`;
+    const smPlistPath = join(launchAgentsDir(), `${smLabel}.plist`);
+    const smWrapperPath = join(persistDir, "claude-session-manager-wrapper.sh");
+    writeFileSync(smWrapperPath, buildSessionManagerWrapper({
+        envPath,
+        installDir: INSTALL_DIR,
+        nodeBin,
+        persistDir,
+        brandPort: PORT,
+    }));
+    chmodSync(smWrapperPath, 0o755);
+    const smPlist = renderPlist({
+        label: smLabel,
+        programArguments: ["/bin/bash", smWrapperPath],
+        stdoutPath: join(logsDir, "server.log"),
+        stderrPath: join(logsDir, "server.log"),
+        keepAlive: true,
+        runAtLoad: true,
+        workingDirectory: `${INSTALL_DIR}/platform/services/claude-session-manager`,
+    });
+    writeFileSync(smPlistPath, smPlist);
+    logFile(`  ${smPlistPath} written (${smPlist.length} bytes)`);
+    spawnSync("launchctl", ["bootout", `${gui()}/${smLabel}`], { stdio: "pipe" });
+    const smBootstrap = spawnSync("launchctl", ["bootstrap", gui(), smPlistPath], {
+        stdio: "pipe",
+        encoding: "utf-8",
+        timeout: 15_000,
+    });
+    if (smBootstrap.status === 0) {
+        console.log(`  [launchd] bootstrap ${gui()}/${smLabel} ok`);
+        logFile(`  [create-maxy] launchd-plist=${smLabel} loaded=true`);
+    }
+    else {
+        const smStderr = (smBootstrap.stderr ?? "").trim();
+        console.error(`  [launchd] bootstrap ${smLabel} returned ${smBootstrap.status}: ${smStderr}`);
+        logFile(`  [create-maxy] launchd-plist=${smLabel} loaded=false exit=${smBootstrap.status}`);
+        throw new Error(`launchctl bootstrap ${smLabel} failed (exit ${smBootstrap.status}): ${smStderr}`);
+    }
+    // Health-probe the manager (/healthz) so a silent boot failure surfaces at
+    // install time, not at first session spawn as `manager-unreachable`.
+    console.log("  Waiting for session manager...");
+    let smUp = false;
+    for (let i = 0; i < 15; i++) {
+        const probe = spawnSync("curl", ["-sf", `http://127.0.0.1:${BRAND.claudeSessionManagerPort}/healthz`, "-o", "/dev/null"], { timeout: 3000 });
+        if (probe.status === 0) {
+            smUp = true;
+            break;
+        }
+        spawnSync("sleep", ["2"]);
+    }
+    logFile(`  [create-maxy] session-manager-health=${smUp ? "ok" : "timeout"} port=${BRAND.claudeSessionManagerPort}`);
+    if (!smUp) {
+        console.log(`  Session manager not yet healthy on ${BRAND.claudeSessionManagerPort} — check ${join(logsDir, "server.log")}.`);
+    }
     // Wait for the server to come up.
     console.log("  Waiting for web server...");
     let webServerUp = false;