@rubytech/create-maxy-code 0.1.357 → 0.1.359

package/dist/__tests__/claude-ptys-slice.test.js

@@ -6,7 +6,13 @@
 // slice un-enabled after install).
 import test from "node:test";
 import assert from "node:assert/strict";
-import { buildClaudePtysSliceUnitFile } from "../port-resolution.js";
+import { buildClaudePtysSliceUnitFile, resolveClaudePtysSliceMemoryHigh } from "../port-resolution.js";
+const GiB = 1024 ** 3;
+const memHighMiB = (unit) => {
+    const m = unit.match(/^MemoryHigh=(\d+)M$/m);
+    assert.ok(m, "unit must carry a MemoryHigh=<n>M line");
+    return Number(m[1]);
+};
 test("buildClaudePtysSliceUnitFile emits a valid systemd slice unit", () => {
     const unit = buildClaudePtysSliceUnitFile();
     assert.match(unit, /^\[Unit\]$/m);
@@ -23,3 +29,32 @@ test("buildClaudePtysSliceUnitFile output has no per-brand or per-install templa
     assert.doesNotMatch(unit, /\$\{/);
     assert.doesNotMatch(unit, /__[A-Z_]+__/);
 });
+// Task 1176 — the slice carries a soft MemoryHigh sized to the host so the
+// session cohort absorbs reclaim pressure (throttle/swap within the slice)
+// before the box exhausts RAM and the kernel kills the brand server. The
+// value is total RAM minus a ~2.7GB fixed floor (neo4j + server +
+// edge/manager/chrome), clamped to a 2GiB minimum. MemoryHigh (soft), never
+// MemoryMax (hard — would just relocate the OOM kill inside the slice).
+test("resolveClaudePtysSliceMemoryHigh scales with host RAM and clamps tiny hosts", () => {
+    const low = resolveClaudePtysSliceMemoryHigh(8 * GiB);
+    const high = resolveClaudePtysSliceMemoryHigh(16 * GiB);
+    assert.match(low, /^\d+M$/);
+    assert.match(high, /^\d+M$/);
+    // 8GB host: total minus 2.7GB floor lands in the 4-6 GiB band.
+    const lowMiB = Number(low.replace("M", ""));
+    assert.ok(lowMiB > 4000 && lowMiB < 6000, `8GB MemoryHigh out of band: ${low}`);
+    // A 16GB host gets a strictly larger ceiling than an 8GB host.
+    assert.ok(Number(high.replace("M", "")) > lowMiB);
+    // Tiny host clamps to the 2GiB floor rather than emitting a near-zero or
+    // negative MemoryHigh.
+    assert.equal(resolveClaudePtysSliceMemoryHigh(1 * GiB), "2048M");
+});
+test("buildClaudePtysSliceUnitFile carries a MemoryHigh line under [Slice] that scales with RAM", () => {
+    const low = buildClaudePtysSliceUnitFile(8 * GiB);
+    const high = buildClaudePtysSliceUnitFile(16 * GiB);
+    // MemoryHigh appears, and after the [Slice] header.
+    assert.match(low, /^MemoryHigh=\d+M$/m);
+    assert.ok(low.indexOf("[Slice]") < low.indexOf("MemoryHigh="), "MemoryHigh must be inside [Slice]");
+    // The 16GB unit's ceiling exceeds the 8GB unit's.
+    assert.ok(memHighMiB(high) > memHighMiB(low));
+});

package/dist/__tests__/neo4j-pidfile-scrub.test.js

@@ -0,0 +1,103 @@
+// Contract grid for resolveNeo4jPidfileScrub (the pure decision behind the
+// install-time per-boot scrub provisioning) plus a behaviour grid for the
+// shipped SCRUB_SCRIPT run against crafted PIDs. The wrapper in index.ts owns
+// the privileged fs/systemctl; this suite is decision + script only, no sudo.
+//
+// The load-bearing guarantee: the scrub NEVER removes a pidfile that names a
+// live Neo4j process, and ALWAYS removes one whose PID is dead or reused by an
+// unrelated process. Runs via Node's built-in test runner (codebase convention,
+// see neo4j-teardown.test.ts).
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, existsSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync, spawn } from "node:child_process";
+import { resolveNeo4jPidfileScrub, SCRUB_SCRIPT, SCRUB_SCRIPT_PATH } from "../neo4j-pidfile-scrub.js";
+// ---- resolve grid (pure) ----
+test("default brand (port 7687) → apt neo4j unit + /var/lib/neo4j/run pidfile", () => {
+    const plan = resolveNeo4jPidfileScrub({ brandHostname: "maxy-code", neo4jPort: 7687 });
+    assert.notEqual(plan, null);
+    assert.equal(plan.unit, "neo4j");
+    assert.equal(plan.pidfile, "/var/lib/neo4j/run/neo4j.pid");
+    assert.equal(plan.dropinPath, "/etc/systemd/system/neo4j.service.d/10-maxy-pidfile-scrub.conf");
+    assert.match(plan.dropinContent, /ExecStartPre=\+\/usr\/local\/lib\/maxy-neo4j-pidfile-scrub\.sh \/var\/lib\/neo4j\/run\/neo4j\.pid/);
+    assert.equal(plan.scriptPath, SCRUB_SCRIPT_PATH);
+});
+test("dedicated brand (custom port) → neo4j-<host> unit + per-brand run pidfile", () => {
+    const plan = resolveNeo4jPidfileScrub({ brandHostname: "sitedesk-code", neo4jPort: 7689 });
+    assert.notEqual(plan, null);
+    assert.equal(plan.unit, "neo4j-sitedesk-code");
+    assert.equal(plan.pidfile, "/var/lib/neo4j-sitedesk-code/run/neo4j.pid");
+    assert.equal(plan.dropinPath, "/etc/systemd/system/neo4j-sitedesk-code.service.d/10-maxy-pidfile-scrub.conf");
+    // dedicated drop-in never names the shared run-dir pidfile
+    assert.doesNotMatch(plan.dropinContent, /\/var\/lib\/neo4j\/run\//);
+});
+test("unreadable port (undefined) → null (never guess the unit)", () => {
+    assert.equal(resolveNeo4jPidfileScrub({ brandHostname: "sitedesk-code", neo4jPort: undefined }), null);
+});
+test("dedicated port with empty hostname → null (cannot form a unit)", () => {
+    assert.equal(resolveNeo4jPidfileScrub({ brandHostname: "", neo4jPort: 7689 }), null);
+});
+// ---- script behaviour (writes SCRUB_SCRIPT to disk, runs against crafted PIDs) ----
+function runScrub(pidfile) {
+    const dir = mkdtempSync(join(tmpdir(), "scrub-"));
+    const script = join(dir, "scrub.sh");
+    writeFileSync(script, SCRUB_SCRIPT, { mode: 0o755 });
+    const r = spawnSync("sh", [script, pidfile], { encoding: "utf8" });
+    rmSync(dir, { recursive: true, force: true });
+    return { stdout: r.stdout ?? "", status: r.status ?? -1 };
+}
+test("absent pidfile → no-op, exit 0", () => {
+    const r = runScrub("/no/such/pidfile");
+    assert.equal(r.status, 0);
+    assert.match(r.stdout, /no-op .*reason=absent/);
+});
+test("unparseable pidfile → removed, exit 0", () => {
+    const dir = mkdtempSync(join(tmpdir(), "scrub-pf-"));
+    const pf = join(dir, "neo4j.pid");
+    writeFileSync(pf, "not-a-number\n");
+    const r = runScrub(pf);
+    assert.equal(r.status, 0);
+    assert.match(r.stdout, /removed .*reason=unparseable/);
+    assert.equal(existsSync(pf), false);
+    rmSync(dir, { recursive: true, force: true });
+});
+test("dead PID → removed, exit 0", () => {
+    const dir = mkdtempSync(join(tmpdir(), "scrub-pf-"));
+    const pf = join(dir, "neo4j.pid");
+    // 999999 is above the default pid_max on Linux and unused on darwin — dead.
+    writeFileSync(pf, "999999\n");
+    const r = runScrub(pf);
+    assert.equal(r.status, 0);
+    assert.match(r.stdout, /removed .*reason=dead/);
+    assert.equal(existsSync(pf), false);
+    rmSync(dir, { recursive: true, force: true });
+});
+test("alive non-neo4j PID → removed, exit 0", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "scrub-pf-"));
+    const pf = join(dir, "neo4j.pid");
+    const proc = spawn("sleep", ["30"]); // argv has no 'neo4j'
+    await new Promise((r) => setTimeout(r, 100));
+    writeFileSync(pf, String(proc.pid) + "\n");
+    const r = runScrub(pf);
+    proc.kill("SIGKILL");
+    assert.equal(r.status, 0);
+    assert.match(r.stdout, /removed .*reason=alive-other/);
+    assert.equal(existsSync(pf), false);
+    rmSync(dir, { recursive: true, force: true });
+});
+test("alive Neo4j-cmdline PID → no-op, exit 0 (Linux only — needs /proc)", { skip: process.platform !== "linux" }, async () => {
+    const dir = mkdtempSync(join(tmpdir(), "scrub-pf-"));
+    const pf = join(dir, "neo4j.pid");
+    // a long-lived process whose argv contains 'neo4j' ($0 = the stub name)
+    const proc = spawn("sh", ["-c", "sleep 30", "neo4j-jvm-stub"]);
+    await new Promise((r) => setTimeout(r, 100));
+    writeFileSync(pf, String(proc.pid) + "\n");
+    const r = runScrub(pf);
+    proc.kill("SIGKILL");
+    assert.equal(r.status, 0);
+    assert.match(r.stdout, /no-op .*reason=live-neo4j/);
+    assert.equal(existsSync(pf), true); // never removes a live neo4j's pidfile
+    rmSync(dir, { recursive: true, force: true });
+});

package/dist/index.js

@@ -9,6 +9,7 @@ import { resolveInstallPortFromFs, buildMaxyUnitFile, buildClaudeSessionManagerU
 import { validateTierFlag, validateEntitlementBase64, applyTierToAccountConfig, entitlementPath } from "./tier-flag.js";
 import { parseOsRelease, isUbuntuLike as isUbuntuLikePure, parseAptCacheCandidate, decideAptResolution, } from "./apt-resolve.js";
 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 { protectCommands, unprotectCommands, lsattrShowsImmutable } from "./install-immutability.js";
@@ -1515,13 +1516,16 @@ WantedBy=multi-user.target
     // ============================================================================
     // unified state remediation + start + verify.
     //
-    // Runs on both fresh and recovery paths. The dedicated unit and the apt
-    // package's system unit both exec /usr/bin/neo4j console without overriding
-    // NEO4J_HOME, so server.directories.run resolves to /var/lib/neo4j/run for
-    // both — the launcher refuses with "Neo4j is already running (pid:N)" if
-    // the system unit holds the PID file. Stopping the system unit first frees
-    // the run-state; disabling prevents it returning at next boot. reset-failed
-    // clears any prior start-limit-hit from a half-installed Pi.
+    // Runs on both fresh and recovery paths. The apt system unit leaves
+    // NEO4J_HOME unset so its run dir is /var/lib/neo4j/run; the dedicated unit
+    // sets NEO4J_HOME=<per-brand data dir> so server.directories.run resolves
+    // per-brand to <data dir>/run — no collision with the system unit's pidfile.
+    // Either way the launcher refuses with "Neo4j is already running (pid:N)" if
+    // a stale run-dir pidfile names a still-live PID. Stopping the system unit
+    // first frees its run-state; disabling prevents it returning at next boot.
+    // reset-failed clears any prior start-limit-hit from a half-installed Pi.
+    // (The per-boot scrub from provisionNeo4jPidfileScrub auto-clears the
+    // reused-PID case on every subsequent boot.)
     // ============================================================================
     spawnSync("sudo", ["systemctl", "daemon-reload"], { stdio: "inherit" });
     console.log("  [privileged] systemctl enable");
@@ -1599,6 +1603,36 @@ WantedBy=multi-user.target
     logFile(`  Neo4j dedicated: config=${confDir} data=${dataDir} service=${serviceName} bolt=:${NEO4J_PORT} http=:${httpPort}`);
     console.log(`  Dedicated Neo4j instance ready on bolt://localhost:${NEO4J_PORT}`);
 }
+// Provision the per-boot stale-pidfile scrub drop-in for whichever Neo4j unit
+// this brand uses. The drop-in's ExecStartPre runs the host-shared scrub script
+// before each unit start, removing a stale run-dir pidfile whose PID is not a
+// live Neo4j (the reused-PID case that browns-out a Pi into a non-starting
+// Neo4j after an unclean reboot). Idempotent: fixed paths, overwritten each
+// install, never appended. Linux-only — a no-op on darwin/dev hosts.
+function provisionNeo4jPidfileScrub() {
+    if (process.platform !== "linux")
+        return;
+    const plan = resolveNeo4jPidfileScrub({ brandHostname: BRAND.hostname, neo4jPort: NEO4J_PORT });
+    if (plan === null) {
+        logFile(`  [neo4j] pidfile-scrub: no plan (port=${NEO4J_PORT} hostname=${BRAND.hostname}) — skipped`);
+        return;
+    }
+    // pid-namespaced staging paths so two co-resident brand installs never race
+    // on a shared /tmp file (matches the file's other tmp-staging idioms).
+    const tmpScript = `/tmp/maxy-neo4j-pidfile-scrub.${process.pid}.sh`;
+    writeFileSync(tmpScript, plan.scriptContent);
+    shell("cp", [tmpScript, plan.scriptPath], { sudo: true });
+    shell("chmod", ["0755", plan.scriptPath], { sudo: true });
+    spawnSync("rm", ["-f", tmpScript]);
+    shell("mkdir", ["-p", plan.dropinDir], { sudo: true });
+    const tmpDropin = `/tmp/10-maxy-pidfile-scrub.${process.pid}.conf`;
+    writeFileSync(tmpDropin, plan.dropinContent);
+    shell("cp", [tmpDropin, plan.dropinPath], { sudo: true });
+    spawnSync("rm", ["-f", tmpDropin]);
+    spawnSync("sudo", ["systemctl", "daemon-reload"], { stdio: "inherit" });
+    console.log(`  [neo4j] pidfile-scrub armed for ${plan.unit} (ExecStartPre scrubs ${plan.pidfile})`);
+    logFile(`  [neo4j] pidfile-scrub armed unit=${plan.unit} pidfile=${plan.pidfile} dropin=${plan.dropinPath} script=${plan.scriptPath}`);
+}
 function ensureOllamaServing() {
     const check = () => spawnSync("curl", ["-sf", "http://localhost:11434/api/tags"], {
         stdio: "pipe", timeout: 5_000,
@@ -4347,6 +4381,7 @@ try {
     installClaudeCode();
     installNeo4j();
     setupDedicatedNeo4j();
+    provisionNeo4jPidfileScrub();
     installOllama(EMBED_MODEL);
     installUv();
     installCloudflared();

package/dist/neo4j-pidfile-scrub.js

@@ -0,0 +1,90 @@
+// Pure per-boot Neo4j stale-pidfile scrub resolution + the scrub script body.
+// Mirrors neo4j-teardown.ts: inputs in, plan out, no fs/systemctl. The installer
+// wrapper (provisionNeo4jPidfileScrub in index.ts) owns the privileged writes.
+//
+// Why: after an unclean reboot the neo4j launcher refuses to start with
+// "Neo4j is already running (pid:N)" when the run-dir pidfile names a PID that
+// is alive but reused by an unrelated process (the launcher's kill -0 liveness
+// check false-positives). The scrub runs as the unit's ExecStartPre and removes
+// the pidfile IFF the PID it names is not a live Neo4j process, so the next boot
+// recovers with no human action. It never removes a pidfile naming a live Neo4j.
+import { SHARED_NEO4J_PORT, resolveDedicatedNeo4jTeardown } from "./neo4j-teardown.js";
+/** Host-shared scrub script path. Stateless and parameterised by the pidfile
+ *  path, so one copy serves the apt unit and any dedicated unit. */
+export const SCRUB_SCRIPT_PATH = "/usr/local/lib/maxy-neo4j-pidfile-scrub.sh";
+const DROPIN_BASENAME = "10-maxy-pidfile-scrub.conf";
+/** The scrub script body. POSIX sh. $1 = the run-dir pidfile path. Always exits
+ *  0 — an ExecStartPre that fails would block the unit from starting. Emits one
+ *  line per run naming the action, pidfile, PID, and what the PID was. */
+export const SCRUB_SCRIPT = `#!/bin/sh
+# Maxy per-boot Neo4j stale-pidfile scrub. ExecStartPre for the brand's Neo4j
+# unit. Removes the run-dir pidfile IFF the PID it names is not a live Neo4j
+# process, so an unclean reboot that left a stale pidfile (whose PID may have
+# been reused by an unrelated process) does not make the launcher false-positive
+# "Neo4j is already running". Never removes a pidfile naming a live Neo4j.
+# Always exits 0 so it cannot block unit start.
+set -u
+PIDFILE="\${1:-}"
+emit() { echo "neo4j-pidfile-scrub $1 pidfile=\${PIDFILE:-<none>} pid=$2 reason=$3"; }
+
+if [ -z "$PIDFILE" ]; then emit no-op '<none>' no-pidfile-arg; exit 0; fi
+if [ ! -e "$PIDFILE" ]; then emit no-op '<none>' absent; exit 0; fi
+
+PID="$(tr -d '[:space:]' < "$PIDFILE" 2>/dev/null)"
+case "$PID" in
+  ''|*[!0-9]*) emit removed "\${PID:-<empty>}" unparseable; rm -f "$PIDFILE"; exit 0 ;;
+esac
+
+if ! kill -0 "$PID" 2>/dev/null; then
+  emit removed "$PID" dead
+  rm -f "$PIDFILE"
+  exit 0
+fi
+
+CMD="$(tr '\\0' ' ' < "/proc/$PID/cmdline" 2>/dev/null)"
+case "$CMD" in
+  *neo4j*) emit no-op "$PID" live-neo4j; exit 0 ;;
+  *) emit removed "$PID" alive-other; rm -f "$PIDFILE"; exit 0 ;;
+esac
+`;
+/**
+ * Resolve the per-boot scrub plan for a brand's Neo4j unit, or `null` when no
+ * unit can be safely targeted:
+ *   - `neo4jPort === undefined`: unreadable port — never guess the unit.
+ *   - dedicated port with empty `brandHostname`: no `neo4j-<host>` unit exists.
+ * A default-brand port (7687) targets the shared apt `neo4j` unit; any other
+ * port targets the brand-dedicated `neo4j-<hostname>` unit, whose run dir lives
+ * under its per-brand `NEO4J_HOME` (`<dataDir>/run`). The dedicated unit name +
+ * data dir are taken from `resolveDedicatedNeo4jTeardown` so install, uninstall,
+ * and this scrub share one derivation and never drift.
+ */
+export function resolveNeo4jPidfileScrub(args) {
+    const { brandHostname, neo4jPort } = args;
+    if (neo4jPort === undefined)
+        return null;
+    let unit;
+    let pidfile;
+    if (neo4jPort === SHARED_NEO4J_PORT) {
+        unit = "neo4j";
+        pidfile = "/var/lib/neo4j/run/neo4j.pid";
+    }
+    else {
+        // Dedicated brand: reuse the teardown resolver's unit/dataDir derivation
+        // (returns null on empty hostname) rather than re-deriving the names here.
+        const dedicated = resolveDedicatedNeo4jTeardown({ brandHostname, neo4jPort });
+        if (dedicated === null)
+            return null;
+        unit = dedicated.service;
+        pidfile = `${dedicated.dataDir}/run/neo4j.pid`;
+    }
+    const dropinDir = `/etc/systemd/system/${unit}.service.d`;
+    return {
+        unit,
+        pidfile,
+        dropinDir,
+        dropinPath: `${dropinDir}/${DROPIN_BASENAME}`,
+        dropinContent: `[Service]\nExecStartPre=+${SCRUB_SCRIPT_PATH} ${pidfile}\n`,
+        scriptPath: SCRUB_SCRIPT_PATH,
+        scriptContent: SCRUB_SCRIPT,
+    };
+}

package/dist/port-resolution.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import os from "node:os";
 const PORT_RE = /^PORT=(\d+)/m;
 const ENV_PORT_RE = /^Environment=PORT=(\d+)/m;
 const ENV_EDGE_PORT_RE = /^Environment=EDGE_PORT=(\d+)/m;
@@ -174,13 +175,29 @@ WantedBy=default.target
 // `~/.config/systemd/user/claude-ptys.slice` and runs
 // `systemctl --user daemon-reload` so the new unit is picked up.
 // ---------------------------------------------------------------------------
-export function buildClaudePtysSliceUnitFile() {
+// Task 1176 — the slice carries a soft MemoryHigh so the session cohort
+// absorbs reclaim pressure (throttle/swap within the slice) before the box
+// exhausts RAM and the kernel kills the brand server. The value is total
+// RAM minus a fixed ~2.7GB floor (neo4j + brand server + edge/manager/chrome
+// must stay resident), clamped to a 2GiB minimum so a small host still emits
+// a valid, non-trivial ceiling. MemoryHigh is a SOFT reclaim threshold —
+// never MemoryMax, which would hard-kill within the slice and just relocate
+// the failure.
+const SLICE_FLOOR_BYTES = Math.round(2.7 * 1024 ** 3);
+const SLICE_MIN_HIGH_BYTES = 2 * 1024 ** 3;
+export function resolveClaudePtysSliceMemoryHigh(totalMemBytes) {
+    const high = Math.max(totalMemBytes - SLICE_FLOOR_BYTES, SLICE_MIN_HIGH_BYTES);
+    return `${Math.round(high / 1024 ** 2)}M`;
+}
+export function buildClaudePtysSliceUnitFile(totalMemBytes = os.totalmem()) {
+    const memoryHigh = resolveClaudePtysSliceMemoryHigh(totalMemBytes);
     return `[Unit]
 Description=Claude Code PTY sessions (Task 250)
 Documentation=https://github.com/rubytech/maxy-code/blob/main/.tasks/archive/250-claude-ptys-survive-manager-restart-via-systemd-scope-per-pty.md
 Before=shutdown.target
 
 [Slice]
+MemoryHigh=${memoryHigh}
 
 [Install]
 WantedBy=default.target

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.357",
+  "version": "0.1.359",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"