@rubytech/create-maxy-code 0.1.88 → 0.1.91

package/dist/__tests__/entitlement-flag.test.js

@@ -0,0 +1,43 @@
+// Acceptance gate for the founder-side `--entitlement-base64 <b64>` installer
+// flag (Task 240). Pure-module coverage: base64 round-trip validation, mode
+// rejection, decoded-payload non-emptiness, path resolution. Live entitlement
+// delivery to a Pi is exercised by manual install per task verification §4.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { validateEntitlementBase64, entitlementPath, } from "../tier-flag.js";
+// A small but realistic envelope shape — looks like what
+// platform/scripts/generate-entitlement-fixture.mjs sign produces.
+const SAMPLE_PAYLOAD = JSON.stringify({
+    payload: { accountId: "x", tier: "family" },
+    signature: "deadbeef",
+});
+const SAMPLE_B64 = Buffer.from(SAMPLE_PAYLOAD, "utf-8").toString("base64");
+test("validateEntitlementBase64 accepts a well-formed payload when commercialMode is true", () => {
+    const decoded = validateEntitlementBase64(SAMPLE_B64, true);
+    assert.equal(decoded.toString("utf-8"), SAMPLE_PAYLOAD);
+});
+test("validateEntitlementBase64 tolerates embedded whitespace (newlines, tabs, spaces)", () => {
+    // SSH transit and operator-side paste can introduce \r, \n, or stray spaces.
+    // The stripper must normalise them before the round-trip check fires.
+    const noisy = SAMPLE_B64.slice(0, 8) + "\n" + SAMPLE_B64.slice(8, 16) + " \t" + SAMPLE_B64.slice(16);
+    const decoded = validateEntitlementBase64(noisy, true);
+    assert.equal(decoded.toString("utf-8"), SAMPLE_PAYLOAD);
+});
+test("validateEntitlementBase64 rejects garbage characters", () => {
+    assert.throws(() => validateEntitlementBase64("not-valid-base64@#$", true), /not valid base64/);
+});
+test("validateEntitlementBase64 rejects empty value and flag-shaped value", () => {
+    assert.throws(() => validateEntitlementBase64(undefined, true), /requires a base64-encoded value/);
+    assert.throws(() => validateEntitlementBase64("", true), /requires a base64-encoded value/);
+    assert.throws(() => validateEntitlementBase64("--port", true), /requires a base64-encoded value/);
+});
+test("validateEntitlementBase64 rejects whitespace-only value", () => {
+    assert.throws(() => validateEntitlementBase64("   \n\t  ", true), /empty after whitespace stripping/);
+});
+test("validateEntitlementBase64 rejects --entitlement-base64 when brand is personal-mode", () => {
+    assert.throws(() => validateEntitlementBase64(SAMPLE_B64, false), /Personal mode — use --tier <enum>/);
+});
+test("entitlementPath joins homeDir + configDir + entitlement.json", () => {
+    assert.equal(entitlementPath("/home/admin", ".realagent-code"), "/home/admin/.realagent-code/entitlement.json");
+    assert.equal(entitlementPath("/home/me", ".maxy-code"), "/home/me/.maxy-code/entitlement.json");
+});

package/dist/__tests__/tier-flag.test.js

@@ -0,0 +1,53 @@
+// Acceptance gate for the founder-side `--tier <enum>` installer flag (Task 240).
+// Pure-module coverage: validation rules, mode-mismatch rejection, config merge.
+// Wiring through index.ts argv is exercised by manual install per task verification §1.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { validateTierFlag, applyTierToAccountConfig, isValidTier, } from "../tier-flag.js";
+test("validateTierFlag accepts solo|family|pro when commercialMode is false", () => {
+    assert.equal(validateTierFlag("solo", false), "solo");
+    assert.equal(validateTierFlag("family", false), "family");
+    assert.equal(validateTierFlag("pro", false), "pro");
+});
+test("validateTierFlag rejects values outside the enum", () => {
+    assert.throws(() => validateTierFlag("enterprise", false), /--tier value must be one of: solo, family, pro/);
+    assert.throws(() => validateTierFlag("max", false), /--tier value must be one of: solo, family, pro/);
+});
+test("validateTierFlag rejects empty or flag-shaped value", () => {
+    assert.throws(() => validateTierFlag(undefined, false), /--tier requires a value/);
+    assert.throws(() => validateTierFlag("", false), /--tier requires a value/);
+    assert.throws(() => validateTierFlag("--hostname", false), /--tier requires a value/);
+});
+test("validateTierFlag rejects --tier when brand is commercial-mode", () => {
+    assert.throws(() => validateTierFlag("family", true), /Commercial mode — use --entitlement-base64/);
+    // Mode mismatch fires before enum check — operator gets the redirect, not "invalid enum".
+    assert.throws(() => validateTierFlag("enterprise", true), /Commercial mode — use --entitlement-base64/);
+});
+test("applyTierToAccountConfig stamps tier and preserves every other key", () => {
+    const before = {
+        accountId: "abc-123",
+        enabledPlugins: ["whatsapp", "outlook"],
+        outputStyle: "default",
+        thinkingView: "default",
+    };
+    const after = applyTierToAccountConfig(before, "family");
+    assert.equal(after.tier, "family");
+    assert.equal(after.accountId, "abc-123");
+    assert.deepEqual(after.enabledPlugins, ["whatsapp", "outlook"]);
+    assert.equal(after.outputStyle, "default");
+    assert.equal(after.thinkingView, "default");
+    // Input not mutated — caller can safely roundtrip.
+    assert.equal(before.tier, undefined);
+});
+test("applyTierToAccountConfig overwrites a previously-stamped tier", () => {
+    const after = applyTierToAccountConfig({ tier: "solo", accountId: "x" }, "pro");
+    assert.equal(after.tier, "pro");
+    assert.equal(after.accountId, "x");
+});
+test("isValidTier narrows correctly", () => {
+    assert.equal(isValidTier("solo"), true);
+    assert.equal(isValidTier("family"), true);
+    assert.equal(isValidTier("pro"), true);
+    assert.equal(isValidTier("enterprise"), false);
+    assert.equal(isValidTier(""), false);
+});

package/dist/index.js

@@ -5,6 +5,7 @@ import { registerSpecialistAgentsAt, SpecialistSymlinkCollision } from "./specia
 import { resolve, join, dirname } from "node:path";
 import { randomBytes } from "node:crypto";
 import { resolveInstallPortFromFs, buildMaxyUnitFile, buildClaudeSessionManagerUnitFile } from "./port-resolution.js";
+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 { runInitLogging } from "./init-logging.js";
@@ -2350,9 +2351,17 @@ function writeInstallDefaults(accountId) {
     config.enabledPlugins = enabledPlugins;
     config.outputStyle = "default";
     config.thinkingView = "default";
+    if (TIER_FLAG) {
+        config = applyTierToAccountConfig(config, TIER_FLAG);
+    }
     writeFileSync(accountJsonPath, JSON.stringify(config, null, 2) + "\n");
     console.log(`  [install-defaults] account-json plugins=${enabledPlugins.length} outputStyle=default thinkingView=default`);
     logFile(`  [install-defaults] account-json plugins=${enabledPlugins.length} outputStyle=default thinkingView=default`);
+    if (TIER_FLAG) {
+        const tierLine = `  [install-defaults] tier=${TIER_FLAG} mode=personal source=cli-flag`;
+        console.log(tierLine);
+        logFile(tierLine);
+    }
     // Admin SOUL.md is sourced from the bundled template with ${PRODUCT_NAME}
     // substituted at install time. The template carries the Phase 1 standing
     // offer (brochure / preval / Loop CRM) so the agent ships with a stated
@@ -2397,6 +2406,22 @@ function writeInstallDefaults(accountId) {
         logFile(`  [install-defaults] public-config path=${publicConfigDst}`);
     }
 }
+/**
+ * Commercial-mode entitlement delivery (Task 240). Writes the decoded payload
+ * bytes verbatim to ~/<BRAND.configDir>/entitlement.json. Signature and shape
+ * validation happen at the verifier at session start (entitlement lib); the
+ * installer is a dumb delivery channel — a malformed payload that survived
+ * --entitlement-base64 parsing will be caught there and degrade the install
+ * to anonymous-fallback, which is the correct loud-fail per doctrine.
+ */
+function writeEntitlementFromFlag(payload) {
+    const target = entitlementPath(process.env.HOME ?? "/root", BRAND.configDir);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, payload);
+    const line = `  [install-defaults] entitlement-delivered bytes=${payload.length} path=${target} source=cli-flag`;
+    console.log(line);
+    logFile(line);
+}
 // ---------------------------------------------------------------------------
 // Tunnel script shortcuts
 //
@@ -3103,6 +3128,37 @@ WantedBy=multi-user.target
         spawnSync("sudo", ["loginctl", "enable-linger", currentUser], { stdio: "inherit" });
     }
     catch { /* not critical */ }
+    // Task 249: persist the systemd journal so per-unit lifecycle events
+    // (watchdog timeouts, SIGTERM/SIGKILL transitions, restart reasons) survive
+    // reboots and are queryable via `journalctl --user -u <brand>.service`.
+    //
+    // Bookworm-canonical mechanism: journald uses persistent storage when
+    // `/var/log/journal/<machine-id>/` exists. No user-level
+    // systemd-journald.service exists by default on Debian; the system instance
+    // stores user-unit events in the same tree, filtered at read time. We only
+    // restart journald when we just created the directory — if the path already
+    // existed, persistence was already active and restarting would needlessly
+    // churn the system journal during the install.
+    try {
+        const machineId = readFileSync("/etc/machine-id", "utf-8").trim();
+        if (machineId) {
+            const journalPath = `/var/log/journal/${machineId}`;
+            const alreadyPersistent = existsSync(journalPath);
+            if (!alreadyPersistent) {
+                console.log("  [privileged] mkdir /var/log/journal");
+                shell("mkdir", ["-p", journalPath], { sudo: true });
+                console.log("  [privileged] systemctl restart systemd-journald");
+                spawnSync("sudo", ["systemctl", "restart", "systemd-journald"], { stdio: "inherit", timeout: 15_000 });
+                logFile(`  journald persistence: enabled (created ${journalPath} + restarted journald)`);
+            }
+            else {
+                logFile(`  journald persistence: already active (${journalPath} present)`);
+            }
+        }
+    }
+    catch (err) {
+        console.error(`  WARNING: failed to enable journald persistence: ${err instanceof Error ? err.message : String(err)}`);
+    }
     // Reload and (re)start.
     //
     // ordering: on upgrades, the old main brand service still holds
@@ -3376,6 +3432,46 @@ if (hostnameIdx !== -1) {
     }
     HOSTNAME_FLAG = raw;
 }
+// ---------------------------------------------------------------------------
+// Founder-side tier-set flags (Task 240).
+//
+// `--tier <solo|family|pro>` stamps account.json.tier directly when the brand
+// is personal-mode (today's default for both maxy-code and realagent-code).
+// `--entitlement-base64 <b64>` decodes a signed payload and writes it to
+// ~/<BRAND.configDir>/entitlement.json when the brand is commercial-mode.
+// The verifier at session start consumes whichever path the brand is on.
+//
+// Mode-mismatch combinations reject loudly at parse time — operator gets a
+// redirect message pointing at the correct flag. The installer is the sole
+// doctrine-sanctioned device-mutation channel; the admin agent has no tier-
+// upgrade surface by design.
+// ---------------------------------------------------------------------------
+let TIER_FLAG;
+let ENTITLEMENT_PAYLOAD;
+const tierIdx = _args.indexOf("--tier");
+if (tierIdx !== -1) {
+    try {
+        TIER_FLAG = validateTierFlag(_args[tierIdx + 1], BRAND.commercialMode === true);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Setup failed: ${msg}`);
+        console.error(`Error: ${msg}`);
+        process.exit(1);
+    }
+}
+const entitlementIdx = _args.indexOf("--entitlement-base64");
+if (entitlementIdx !== -1) {
+    try {
+        ENTITLEMENT_PAYLOAD = validateEntitlementBase64(_args[entitlementIdx + 1], BRAND.commercialMode === true);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Setup failed: ${msg}`);
+        console.error(`Error: ${msg}`);
+        process.exit(1);
+    }
+}
 let DISPLAY_MODE = "virtual";
 let DISPLAY_MODE_SOURCE = "default";
 const displayIdx = _args.indexOf("--display");
@@ -3638,6 +3734,9 @@ try {
     registerLocalAndExternalPlugins(); // install-time plugin registration
     setupVncViewer();
     setupAccount();
+    if (ENTITLEMENT_PAYLOAD) {
+        writeEntitlementFromFlag(ENTITLEMENT_PAYLOAD);
+    }
     installTunnelScripts(); // ~/setup-tunnel.sh, ~/reset-tunnel.sh — the SKILL contract
     installService();
     // Samba on the LAN. Runs after the brand systemd unit is up so

package/dist/port-resolution.js

@@ -97,7 +97,7 @@ ExecStartPre=-/bin/bash ${o.installDir}/platform/scripts/resume-tunnel.sh
 ExecStart=/usr/bin/node --require ./server-init.cjs server.js
 Restart=on-failure
 RestartSec=5
-WatchdogSec=30
+WatchdogSec=120
 TimeoutStartSec=60
 TimeoutStopSec=10
 Environment=NODE_ENV=production

package/dist/tier-flag.js

@@ -0,0 +1,85 @@
+// Pure validation + path helpers for the founder-side tier-set installer flags
+// (Task 240). Two flags wired into the installer at src/index.ts:
+//   --tier <solo|family|pro>      personal-mode (brand.commercialMode === false)
+//   --entitlement-base64 <b64>    commercial-mode (brand.commercialMode === true)
+//
+// Both helpers throw on invalid input; the caller exits non-zero and surfaces the
+// thrown message. No filesystem or console side effects — index.ts owns those.
+import { resolve } from "node:path";
+const VALID_TIERS = new Set(["solo", "family", "pro"]);
+export function isValidTier(value) {
+    return VALID_TIERS.has(value);
+}
+/**
+ * Validate the `--tier <enum>` argv value and the brand mode.
+ *
+ * Throws when:
+ *   - raw is missing / starts with `--` (no value supplied after the flag)
+ *   - raw is not in {solo, family, pro}
+ *   - brand is commercial-mode (operator must use --entitlement-base64 instead)
+ */
+export function validateTierFlag(raw, commercialMode) {
+    if (commercialMode) {
+        throw new Error("--tier is for personal mode. Commercial mode — use --entitlement-base64 to deliver a signed payload.");
+    }
+    if (!raw || raw.startsWith("--")) {
+        throw new Error("--tier requires a value (one of: solo, family, pro).");
+    }
+    if (!isValidTier(raw)) {
+        throw new Error(`--tier value must be one of: solo, family, pro (got: ${raw}).`);
+    }
+    return raw;
+}
+/**
+ * Validate the `--entitlement-base64 <b64>` argv value and the brand mode.
+ *
+ * Round-trips through Buffer to detect malformed base64 — Buffer.from is loose
+ * (silently drops invalid chars), so an explicit re-encode comparison is the
+ * cheapest way to confirm the input is real base64. Whitespace (newlines from
+ * SSH transit, stray \r) is stripped first.
+ *
+ * Throws when:
+ *   - brand is personal-mode (operator must use --tier instead)
+ *   - raw is missing / starts with `--`
+ *   - stripped base64 fails the round-trip check (malformed chars)
+ *   - decoded bytes are empty
+ *
+ * Returns the decoded Buffer; caller writes it to entitlement.json verbatim.
+ * No JSON parse, no signature validation — that's the verifier's job at session
+ * start. The installer is a dumb delivery channel.
+ */
+export function validateEntitlementBase64(raw, commercialMode) {
+    if (!commercialMode) {
+        throw new Error("--entitlement-base64 is for commercial mode. Personal mode — use --tier <enum> to set tier directly.");
+    }
+    if (!raw || raw.startsWith("--")) {
+        throw new Error("--entitlement-base64 requires a base64-encoded value.");
+    }
+    const stripped = raw.replace(/\s/g, "");
+    if (stripped.length === 0) {
+        throw new Error("--entitlement-base64 value is empty after whitespace stripping.");
+    }
+    const decoded = Buffer.from(stripped, "base64");
+    if (decoded.toString("base64") !== stripped) {
+        throw new Error("--entitlement-base64 value is not valid base64.");
+    }
+    if (decoded.length === 0) {
+        throw new Error("--entitlement-base64 decoded to zero bytes.");
+    }
+    return decoded;
+}
+/**
+ * Build the absolute path where the installer writes entitlement.json. Matches
+ * the verifier's `resolve(brand.configDir, "entitlement.json")` (entitlement
+ * lib src/index.ts:140) so writer + reader agree on a single location.
+ */
+export function entitlementPath(homeDir, configDir) {
+    return resolve(homeDir, configDir, "entitlement.json");
+}
+/**
+ * Stamp the validated tier onto an account.json config object. Pure merge;
+ * preserves every other key (enabledPlugins, outputStyle, thinkingView, etc.).
+ */
+export function applyTierToAccountConfig(config, tier) {
+    return { ...config, tier };
+}

package/package.json

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

package/payload/platform/lib/admin-conversation-purge/dist/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Admin-conversation JSONL purge — Task 237.
+ *
+ * Shared primitive that fires the claude-session-manager's
+ * `DELETE /:sessionId` per attached JSONL. Pure JSONL-only: it does not
+ * touch the graph. Callers (the `cascadeAdminConversationDelete` engine
+ * and `memory-empty-trash`'s defense-in-depth `onEmpty`) own the graph
+ * side and decide whether to proceed after the JSONL outcome lands.
+ *
+ * Contract:
+ *   - manager 204 (purged) or 404 (manager never knew the JSONL) both count
+ *     as "transcript no longer exists" and proceed to the next sessionId.
+ *   - manager 409 is the structural `pty-still-alive` stop check; the loop
+ *     halts and the caller surfaces the live sessionId.
+ *   - any other status or transport failure halts the loop with
+ *     `jsonl-purge-failed`, naming the failing sessionId and the ids already
+ *     purged at the failure point.
+ *
+ * Log lines mirror the Task 217 cascade so a single grep
+ * (`[admin-conversation-delete]`) covers both call sites.
+ */
+export interface PurgeAdminConversationJsonlsArgs {
+    /** Used only for log id8; not for routing. */
+    conversationId: string;
+    /** Used only for log line context; the helper does not enforce isolation
+     *  (the caller has already account-scoped the candidate). */
+    accountId: string;
+    /** Loopback manager base URL — `http://127.0.0.1:${CLAUDE_SESSION_MANAGER_PORT}`. */
+    managerBase: string;
+    /** Pre-resolved sessionIds to purge. Caller chooses the lookup strategy
+     *  (`getConversationClaudeSessionIds` for live conversations,
+     *  elementId-based walk for trashed ones). */
+    claudeSessionIds: string[];
+    fetchImpl?: typeof fetch;
+    logger?: (line: string) => void;
+}
+export type PurgeAdminConversationJsonlsOutcome = {
+    ok: true;
+    claudeSessionIdsPurged: string[];
+} | {
+    ok: false;
+    reason: "pty-still-alive";
+    claudeSessionId: string;
+    claudeSessionIdsPurged: string[];
+} | {
+    ok: false;
+    reason: "jsonl-purge-failed";
+    claudeSessionId: string;
+    claudeSessionIdsPurged: string[];
+    status: number;
+    message: string;
+};
+export declare function purgeAdminConversationJsonls(args: PurgeAdminConversationJsonlsArgs): Promise<PurgeAdminConversationJsonlsOutcome>;
+//# sourceMappingURL=index.d.ts.map

package/payload/platform/lib/admin-conversation-purge/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,WAAW,gCAAgC;IAC/C,8CAA8C;IAC9C,cAAc,EAAE,MAAM,CAAC;IACvB;iEAC6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,WAAW,EAAE,MAAM,CAAC;IACpB;;kDAE8C;IAC9C,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,MAAM,MAAM,mCAAmC,GAC3C;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,sBAAsB,EAAE,MAAM,EAAE,CAAA;CAAE,GAC9C;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,iBAAiB,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,sBAAsB,EAAE,MAAM,EAAE,CAAC;CAClC,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,oBAAoB,CAAC;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEN,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,gCAAgC,GACrC,OAAO,CAAC,mCAAmC,CAAC,CA8D9C"}

package/payload/platform/lib/admin-conversation-purge/dist/index.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * Admin-conversation JSONL purge — Task 237.
+ *
+ * Shared primitive that fires the claude-session-manager's
+ * `DELETE /:sessionId` per attached JSONL. Pure JSONL-only: it does not
+ * touch the graph. Callers (the `cascadeAdminConversationDelete` engine
+ * and `memory-empty-trash`'s defense-in-depth `onEmpty`) own the graph
+ * side and decide whether to proceed after the JSONL outcome lands.
+ *
+ * Contract:
+ *   - manager 204 (purged) or 404 (manager never knew the JSONL) both count
+ *     as "transcript no longer exists" and proceed to the next sessionId.
+ *   - manager 409 is the structural `pty-still-alive` stop check; the loop
+ *     halts and the caller surfaces the live sessionId.
+ *   - any other status or transport failure halts the loop with
+ *     `jsonl-purge-failed`, naming the failing sessionId and the ids already
+ *     purged at the failure point.
+ *
+ * Log lines mirror the Task 217 cascade so a single grep
+ * (`[admin-conversation-delete]`) covers both call sites.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.purgeAdminConversationJsonls = purgeAdminConversationJsonls;
+async function purgeAdminConversationJsonls(args) {
+    const fetchImpl = args.fetchImpl ?? fetch;
+    const log = args.logger ?? ((line) => console.log(line));
+    const id8 = args.conversationId.slice(0, 8);
+    const purged = [];
+    for (const sessionId of args.claudeSessionIds) {
+        const url = `${args.managerBase}/${encodeURIComponent(sessionId)}`;
+        let res;
+        try {
+            res = await fetchImpl(url, { method: "DELETE" });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            log(`[admin-conversation-delete] conversationId=${id8} reason=jsonl-purge-failed claudeSessionId=${sessionId.slice(0, 8)} message=${message}`);
+            return {
+                ok: false,
+                reason: "jsonl-purge-failed",
+                claudeSessionId: sessionId,
+                claudeSessionIdsPurged: purged,
+                status: 0,
+                message,
+            };
+        }
+        if (res.status === 204 || res.status === 404) {
+            purged.push(sessionId);
+            continue;
+        }
+        if (res.status === 409) {
+            log(`[admin-conversation-delete] conversationId=${id8} reason=pty-still-alive claudeSessionId=${sessionId.slice(0, 8)}`);
+            return {
+                ok: false,
+                reason: "pty-still-alive",
+                claudeSessionId: sessionId,
+                claudeSessionIdsPurged: purged,
+            };
+        }
+        let message = `manager returned ${res.status}`;
+        try {
+            const body = (await res.json());
+            if (typeof body.detail === "string")
+                message = body.detail;
+            else if (typeof body.error === "string")
+                message = body.error;
+        }
+        catch {
+            // body isn't JSON — keep status-coded message
+        }
+        log(`[admin-conversation-delete] conversationId=${id8} reason=jsonl-purge-failed claudeSessionId=${sessionId.slice(0, 8)} message=${message}`);
+        return {
+            ok: false,
+            reason: "jsonl-purge-failed",
+            claudeSessionId: sessionId,
+            claudeSessionIdsPurged: purged,
+            status: res.status,
+            message,
+        };
+    }
+    return { ok: true, claudeSessionIdsPurged: purged };
+}
+//# sourceMappingURL=index.js.map

package/payload/platform/lib/admin-conversation-purge/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/payload/platform/lib/admin-conversation-purge/src/index.ts

@@ -0,0 +1,120 @@
+/**
+ * Admin-conversation JSONL purge — Task 237.
+ *
+ * Shared primitive that fires the claude-session-manager's
+ * `DELETE /:sessionId` per attached JSONL. Pure JSONL-only: it does not
+ * touch the graph. Callers (the `cascadeAdminConversationDelete` engine
+ * and `memory-empty-trash`'s defense-in-depth `onEmpty`) own the graph
+ * side and decide whether to proceed after the JSONL outcome lands.
+ *
+ * Contract:
+ *   - manager 204 (purged) or 404 (manager never knew the JSONL) both count
+ *     as "transcript no longer exists" and proceed to the next sessionId.
+ *   - manager 409 is the structural `pty-still-alive` stop check; the loop
+ *     halts and the caller surfaces the live sessionId.
+ *   - any other status or transport failure halts the loop with
+ *     `jsonl-purge-failed`, naming the failing sessionId and the ids already
+ *     purged at the failure point.
+ *
+ * Log lines mirror the Task 217 cascade so a single grep
+ * (`[admin-conversation-delete]`) covers both call sites.
+ */
+
+export interface PurgeAdminConversationJsonlsArgs {
+  /** Used only for log id8; not for routing. */
+  conversationId: string;
+  /** Used only for log line context; the helper does not enforce isolation
+   *  (the caller has already account-scoped the candidate). */
+  accountId: string;
+  /** Loopback manager base URL — `http://127.0.0.1:${CLAUDE_SESSION_MANAGER_PORT}`. */
+  managerBase: string;
+  /** Pre-resolved sessionIds to purge. Caller chooses the lookup strategy
+   *  (`getConversationClaudeSessionIds` for live conversations,
+   *  elementId-based walk for trashed ones). */
+  claudeSessionIds: string[];
+  fetchImpl?: typeof fetch;
+  logger?: (line: string) => void;
+}
+
+export type PurgeAdminConversationJsonlsOutcome =
+  | { ok: true; claudeSessionIdsPurged: string[] }
+  | {
+      ok: false;
+      reason: "pty-still-alive";
+      claudeSessionId: string;
+      claudeSessionIdsPurged: string[];
+    }
+  | {
+      ok: false;
+      reason: "jsonl-purge-failed";
+      claudeSessionId: string;
+      claudeSessionIdsPurged: string[];
+      status: number;
+      message: string;
+    };
+
+export async function purgeAdminConversationJsonls(
+  args: PurgeAdminConversationJsonlsArgs,
+): Promise<PurgeAdminConversationJsonlsOutcome> {
+  const fetchImpl = args.fetchImpl ?? fetch;
+  const log = args.logger ?? ((line: string) => console.log(line));
+  const id8 = args.conversationId.slice(0, 8);
+
+  const purged: string[] = [];
+  for (const sessionId of args.claudeSessionIds) {
+    const url = `${args.managerBase}/${encodeURIComponent(sessionId)}`;
+    let res: Response;
+    try {
+      res = await fetchImpl(url, { method: "DELETE" });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log(
+        `[admin-conversation-delete] conversationId=${id8} reason=jsonl-purge-failed claudeSessionId=${sessionId.slice(0, 8)} message=${message}`,
+      );
+      return {
+        ok: false,
+        reason: "jsonl-purge-failed",
+        claudeSessionId: sessionId,
+        claudeSessionIdsPurged: purged,
+        status: 0,
+        message,
+      };
+    }
+    if (res.status === 204 || res.status === 404) {
+      purged.push(sessionId);
+      continue;
+    }
+    if (res.status === 409) {
+      log(
+        `[admin-conversation-delete] conversationId=${id8} reason=pty-still-alive claudeSessionId=${sessionId.slice(0, 8)}`,
+      );
+      return {
+        ok: false,
+        reason: "pty-still-alive",
+        claudeSessionId: sessionId,
+        claudeSessionIdsPurged: purged,
+      };
+    }
+    let message = `manager returned ${res.status}`;
+    try {
+      const body = (await res.json()) as { error?: string; detail?: string };
+      if (typeof body.detail === "string") message = body.detail;
+      else if (typeof body.error === "string") message = body.error;
+    } catch {
+      // body isn't JSON — keep status-coded message
+    }
+    log(
+      `[admin-conversation-delete] conversationId=${id8} reason=jsonl-purge-failed claudeSessionId=${sessionId.slice(0, 8)} message=${message}`,
+    );
+    return {
+      ok: false,
+      reason: "jsonl-purge-failed",
+      claudeSessionId: sessionId,
+      claudeSessionIdsPurged: purged,
+      status: res.status,
+      message,
+    };
+  }
+
+  return { ok: true, claudeSessionIdsPurged: purged };
+}

package/payload/platform/lib/admin-conversation-purge/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/payload/platform/lib/graph-trash/dist/index.d.ts

@@ -59,7 +59,18 @@ export interface EmptyTrashParams {
     dryRun?: boolean;
     /** Optional label whitelist — only nodes carrying any of these labels are eligible. */
     labels?: string[];
-    /** Side-effect callback invoked per emptied node, e.g. to clean disk attachments. */
+    /** Side-effect callback invoked before the `DETACH DELETE` for each
+     *  emptied node, e.g. to clean disk attachments or purge sibling JSONL
+     *  transcripts.
+     *
+     *  Contract (Task 237): if the callback **throws**, the candidate is
+     *  **skipped this run** — no `DETACH DELETE` runs and no `[trash:emptied]`
+     *  line emits. The thrown message lands in
+     *  `[trash:empty-run] reason=onEmpty-failed` and the candidate becomes
+     *  eligible again on the next sweep. Pre-Task-237 consumers
+     *  (`removeAttachmentDir` for `:KnowledgeDocument`) cannot throw because
+     *  they wrap `fs.rm({force:true})`, so the contract change is invisible
+     *  to them. */
     onEmpty?: (node: TrashCandidate) => Promise<void>;
 }
 export interface TrashCandidate {

package/payload/platform/lib/graph-trash/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAsC5C,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,OAAO,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAyIzE;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CA6G/E;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,uFAAuF;IACvF,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,qFAAqF;IACrF,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gFAAgF;IAChF,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA0EpF;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAI9D;AAED,2FAA2F;AAC3F,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAsC5C,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,OAAO,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAyIzE;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CA6G/E;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,uFAAuF;IACvF,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;;;;;;;mBAWe;IACf,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gFAAgF;IAChF,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAiFpF;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAI9D;AAED,2FAA2F;AAC3F,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAAqB,CAAC"}