@rubytech/create-maxy-code 0.1.232 → 0.1.233

package/dist/__tests__/rss-sampler-installer.test.js

@@ -0,0 +1,27 @@
+// Static-grep contracts for Task 600 installer additions:
+// swap provisioning and rss-sampler service registration.
+//
+// Why static-grep, not behaviour: the install branches spawn (sudo, systemctl,
+// dphys-swapfile), so end-to-end reproduction belongs to the manual smoke path.
+// The unit suite pins the branch points so a future refactor that removes them
+// fails loudly here.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+const here = dirname(fileURLToPath(import.meta.url));
+const INDEX_TS = resolve(here, "../../src/index.ts");
+const SRC = readFileSync(INDEX_TS, "utf-8");
+test("installSystemDeps Linux branch installs dphys-swapfile and writes CONF_SWAPSIZE=2048", () => {
+    assert.match(SRC, /apt-get.*install.*dphys-swapfile/s, "apt install dphys-swapfile must be present");
+    assert.match(SRC, /CONF_SWAPSIZE=2048/, "swap size must be 2048MB");
+    assert.match(SRC, /CONF_MAXSWAP=4096/, "swap max must be 4096MB");
+    assert.match(SRC, /dphys-swapfile.*restart|restart.*dphys-swapfile/s, "dphys-swapfile service must be restarted");
+});
+test("installService Linux branch writes rss-sampler user unit and enables it", () => {
+    assert.match(SRC, /rss-sampler\.service/, "rss-sampler.service unit must be written");
+    assert.match(SRC, /rss-sampler\.sh/, "rss-sampler.sh must appear in ExecStart");
+    assert.match(SRC, /rss-sampler.*enable|enable.*rss-sampler/s, "rss-sampler must be enabled");
+    assert.match(SRC, /rss-sampler installed/, "rss-sampler install must emit a logFile entry");
+});

package/dist/index.js

@@ -709,6 +709,42 @@ function installSystemDeps() {
     // so deployPayload's writeChromiumBinaryPathFile and installService's
     // buildMaxyUnitFile both have a real absolute path to thread through.
     ensureNonSnapChromium();
+    // Task 600 — provision swap so the OOM-killer has a buffer to work in
+    // instead of silently freezing the box. dphys-swapfile is the standard
+    // Raspberry Pi OS swap manager. CONF_MAXSWAP raised to 4096 so the
+    // operator can manually grow the swap file without reinstalling.
+    // Best-effort: a failure here warns but does not abort the install.
+    try {
+        console.log("  [privileged] apt-get install dphys-swapfile");
+        shell("apt-get", ["install", "-y", "dphys-swapfile"], { sudo: true, bestEffort: true });
+        const desiredSwapConf = "CONF_SWAPSIZE=2048\nCONF_MAXSWAP=4096\n";
+        const swapConfPath = "/etc/dphys-swapfile";
+        let swapCurrent = "";
+        if (existsSync(swapConfPath)) {
+            try {
+                swapCurrent = readFileSync(swapConfPath, "utf-8");
+            }
+            catch {
+                swapCurrent = "";
+            }
+        }
+        if (swapCurrent === desiredSwapConf) {
+            logFile("  swap: already configured (CONF_SWAPSIZE=2048 CONF_MAXSWAP=4096)");
+        }
+        else {
+            const swapTmpPath = `/tmp/dphys-swapfile.${process.pid}`;
+            writeFileSync(swapTmpPath, desiredSwapConf);
+            console.log("  [privileged] install /etc/dphys-swapfile (CONF_SWAPSIZE=2048 CONF_MAXSWAP=4096)");
+            shell("cp", [swapTmpPath, swapConfPath], { sudo: true });
+            spawnSync("rm", ["-f", swapTmpPath]);
+            console.log("  [privileged] systemctl restart dphys-swapfile");
+            shell("systemctl", ["restart", "dphys-swapfile"], { sudo: true, bestEffort: true });
+            logFile("  swap: configured CONF_SWAPSIZE=2048 CONF_MAXSWAP=4096 and restarted dphys-swapfile");
+        }
+    }
+    catch (err) {
+        console.error(`  WARNING: failed to provision swap: ${err instanceof Error ? err.message : String(err)}`);
+    }
     // Hostname resolution — four sources, in priority order:
     //   1. --hostname flag (unconditional — the caller is the authority)
     //   2. OS detection on same-brand upgrade (service exists → keep whatever is currently set)
@@ -3084,6 +3120,28 @@ function installService() {
     const claudePtysSliceName = "claude-ptys.slice";
     writeFileSync(join(serviceDir, claudePtysSliceName), buildClaudePtysSliceUnitFile());
     logFile(`  ${claudePtysSliceName}: Task 250 slice for claude-session-*.scope cohort`);
+    // Task 600 — per-brand RSS sampler: a long-running user service that
+    // periodically writes per-claude.exe RSS + aggregate RSS to disk.
+    // Named per-brand (BRAND.hostname prefix) so two brands on the same
+    // device each own their own sampler writing to their own log path.
+    const rssSamplerUnitName = `${BRAND.hostname}-rss-sampler.service`;
+    const rssSamplerScriptPath = resolve(INSTALL_DIR, "platform/scripts/rss-sampler.sh");
+    const rssSamplerLogPath = join(persistDir, "rss-sampler.log");
+    const rssSamplerUnit = `[Unit]
+Description=${BRAND.productName} RSS Sampler
+
+[Service]
+Type=simple
+ExecStart=/bin/bash ${rssSamplerScriptPath}
+Environment=LOG_PATH=${rssSamplerLogPath}
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+`;
+    writeFileSync(join(serviceDir, rssSamplerUnitName), rssSamplerUnit);
+    logFile(`  rss-sampler installed: ${rssSamplerUnitName} LOG_PATH=${rssSamplerLogPath}`);
     // the edge service: always-on front door that owns the public
     // port (PORT) and the VNC stack (Xtigervnc + websockify). Its lifecycle is
     // independent of the main brand service, so an in-place upgrade triggered
@@ -3294,11 +3352,14 @@ WantedBy=multi-user.target
     spawnSync("systemctl", ["--user", "enable", edgeUnitShort], { stdio: "inherit" });
     spawnSync("systemctl", ["--user", "enable", claudeSessionManagerUnitShort], { stdio: "inherit" });
     spawnSync("systemctl", ["--user", "enable", unitName], { stdio: "inherit" });
+    spawnSync("systemctl", ["--user", "enable", `${BRAND.hostname}-rss-sampler`], { stdio: "inherit" });
     // edge first: binds public port + starts VNC stack. Then claude-session-manager
     // (so the main brand unit's Requires= is satisfied). Then main brand service.
+    // rss-sampler is independent — start last, failure is non-blocking.
     spawnSync("systemctl", ["--user", "restart", edgeUnitShort], { stdio: "inherit" });
     spawnSync("systemctl", ["--user", "restart", claudeSessionManagerUnitShort], { stdio: "inherit" });
     spawnSync("systemctl", ["--user", "restart", unitName], { stdio: "inherit" });
+    spawnSync("systemctl", ["--user", "restart", `${BRAND.hostname}-rss-sampler`], { stdio: "inherit" });
     // Session manager runs in its own systemd user unit and can boot-fail silently
     // (e.g. mcp-block-missing). The web server below comes up regardless, so the
     // install terminal would otherwise report success while every API call 503s.

package/package.json

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

package/payload/platform/plugins/memory/PLUGIN.md

@@ -205,7 +205,7 @@ Graph hygiene is **agent-directed, case by case** — no autonomous rule engine,
 
 ## Dream-cycle maintenance — `memory-dream-run` / `memory-review-queue`
 
-`memory-dream-run` is the operator-initiated graph-hygiene sweep — four phases (orphan detection on `:Person`/`:Organization`/`:Concept`/`:Project`; stale compiled-truth scan on `compiledTruthUpdatedAt`; mark edges to `:Trashed` targets with `staleTarget: true`; LLM-bounded citation audit on `:TimelineEvent`). Each run writes a `:Report` (via `memory-report-write` from Task 332) summarising counts; per-phase log lines `[dream-cycle:phase-<n>]` join on the run id. Failure of any phase logs `[dream-cycle:phase-<n>:error]` and continues — subsequent phases still run. Pass `phases: [4]` to run only the citation audit (e.g. after a bulk ingest); `maxEventsPerRun` defaults to 200 to cap LLM cost, with a resume cursor stored as `:Report.lastEventCursor` so subsequent runs continue from the last processed event. `memory-review-queue` is the read-only surface for `:OrphanCandidate` and `:CitationProposal` queues — counts plus a small sample per queue. Phase 5 (backlinks) and phase 6 (tag consistency) are deferred to follow-up tasks. Task 327; absorbs Task 330.
+`memory-dream-run` is the operator-initiated graph-hygiene sweep — seven phases: orphan detection on `:Person`/`:Organization`/`:Concept`/`:Project`; stale compiled-truth scan on `compiledTruthUpdatedAt`; mark edges to `:Trashed` targets with `staleTarget: true`; LLM-bounded citation audit on `:TimelineEvent`; prune compiled-truth revisions to newest 20 per entity; materialise persistent `:BACKLINKS` edges derived from `:MENTIONS`/`:REFERENCES` (making reverse-link queries O(1)); normalise `tags[]` array properties on `:KnowledgeDocument` nodes and merge `:DefinedTerm {category:'obsidian-tag'}` variants. Each run writes a `:Report` (via `memory-report-write`) summarising counts; per-phase log lines `[dream-cycle] phase=<n>` join on the run id. Failure of any phase logs `[dream-cycle:phase-<n>:error]` and continues. Pass `phases: [4]` to run only the citation audit (e.g. after a bulk ingest); `maxEventsPerRun` defaults to 200 for phase 4, with a resume cursor stored as `:Report.lastEventCursor`. `memory-review-queue` is the read-only surface for `:OrphanCandidate` and `:CitationProposal` queues — counts plus a small sample per queue. Task 327; absorbs Task 330; extended Task 596.
 
 ## Brain-capture diagnostic — `memory-brain-capture-recent`
 
@@ -286,3 +286,7 @@ After a successful `memory-ingest` call, the dispatching admin agent should:
 3. If the user provides additional keywords post-ingest, call `memory-update` on the `documentNodeId` with the merged array.
 
 Keywords support user-defined collections via naming convention (e.g., `["reports", "reports/quarterly", "reports/quarterly/q1-2026"]`).
+
+**Inline compiled-truth reconciliation (opt-in).** Pass `inlineRewrite: true` to enable the edge-density gate. After all sections and edges are written, the writer counts MENTIONS and REFERENCES edges from the new document (KnowledgeDocument and its sections) to existing entities that carry `compiledTruth`. Entities with >= `inlineRewriteThreshold` (default 2) such edges qualify — unless their `compiledTruthUpdatedAt` is within the 7-day cooldown, in which case they land in `inlineRewriteDeferred` and remain candidates for the next dream-cycle. The result includes `inlineRewriteCandidates: [{ elementId, label, name, edgeCount }]`. Dispatch the `compiled-truth-rewriter` specialist for each entry before the skill returns; pass `nodeId = entry.elementId` and an optional `operatorHint` if the new source suggests a correction. Pass `forceRewrite: true` to bypass the cooldown. Diagnostic: `grep '[memory-ingest] op=compiled-truth-inline'` shows `entitiesChecked`, `entitiesRecompiled`, `entitiesDeferred`, and `reason` per ingest.
+
+For the conversation-archive path, the equivalent signal is in `conversation-archive-derive-insights`: pass `inlineRewrite: true` and optionally `inlineRewriteThreshold` to receive `inlineRewriteSignals` (display name + mention count) in the per-chunk result. The skill accumulates signals across chunks; when a cumulative count hits threshold, resolve the entity via `memory-search` and dispatch the `compiled-truth-rewriter` specialist.

package/payload/platform/plugins/memory/mcp/dist/index.js

@@ -504,7 +504,9 @@ server.tool("conversation-archive-derive-insights", "Convert one chunk's agent-p
     claims: z
         .array(claimSchema)
         .describe("Claims the dispatched specialist emitted in-turn from the chunk body. Zero is valid — pass [] to record an empty-chunk pass."),
-}, async ({ archiveElementId, chunkElementId, claims }) => {
+    inlineRewrite: z.boolean().optional().describe("When true, count mention-claim subjects in this chunk and return those reaching inlineRewriteThreshold in inlineRewriteSignals. The calling skill accumulates signals across chunks; when an entity's cumulative count hits threshold, resolve it via memory-search and dispatch the compiled-truth-rewriter specialist."),
+    inlineRewriteThreshold: z.number().int().min(1).optional().describe("Minimum mention-claim count for a subject to appear in inlineRewriteSignals. Default: 2."),
+}, async ({ archiveElementId, chunkElementId, claims, inlineRewrite, inlineRewriteThreshold }) => {
     if (!accountId)
         return refuseNoAccount("conversation-archive-derive-insights");
     try {
@@ -514,6 +516,8 @@ server.tool("conversation-archive-derive-insights", "Convert one chunk's agent-p
             chunkElementId,
             claims: claims,
             sessionId: resolveSessionId(),
+            inlineRewrite,
+            inlineRewriteThreshold,
         });
         const proposalLines = result.proposals
             .map((p, i) => {
@@ -532,7 +536,10 @@ server.tool("conversation-archive-derive-insights", "Convert one chunk's agent-p
             ].join("\n");
         })
             .join("\n\n");
-        const header = `archiveElementId=${result.archiveElementId} chunkElementId=${result.chunkElementId} proposals=${result.proposals.length} rejectionsFiltered=${result.rejectionsFiltered} invalidClaims=${result.invalidClaims}`;
+        const signalsSuffix = result.inlineRewriteSignals && result.inlineRewriteSignals.length > 0
+            ? ` inlineRewriteSignals=${JSON.stringify(result.inlineRewriteSignals)}`
+            : "";
+        const header = `archiveElementId=${result.archiveElementId} chunkElementId=${result.chunkElementId} proposals=${result.proposals.length} rejectionsFiltered=${result.rejectionsFiltered} invalidClaims=${result.invalidClaims}${signalsSuffix}`;
         return {
             content: [
                 {
@@ -1220,7 +1227,10 @@ if (!readOnly) {
         documentKeywords: z.array(z.string()).optional().describe("Classifier-extracted topic keywords."),
         userKeywords: z.array(z.string()).optional().describe("Keywords explicitly provided by the user. Merged additively with documentKeywords."),
         sessionId: z.string().optional().describe("Session UUID for provenance stamping. Optional override; the server falls back to the SESSION_ID env var set by the admin agent at MCP spawn. The agent only needs to pass this when calling outside the normal admin-session context."),
-    }, async ({ attachmentId, conversationIdentity, source, archiveSha256, archiveSourceFile, participantElementIds, lastIngestedMessageHash, lastIngestedMessageAt, archiveTitle, cleanupPriorChunks, sessionIndex, documentSummary, anchorNodeId, anchorLabel, sections, documentEdges, orphanCandidates, scope, sourceUrl, sourceType, documentKeywords, userKeywords, sessionId: sessionIdOverride }) => {
+        inlineRewrite: z.boolean().optional().describe("When true, after writing all sections and edges, run the inline compiled-truth reconciliation gate. Counts MENTIONS/REFERENCES edges from this document (KnowledgeDocument + its sections) to existing entities that carry compiledTruth. Entities with >= inlineRewriteThreshold such edges (default 2) and compiledTruthUpdatedAt older than 7 days are returned in inlineRewriteCandidates. Dispatch the compiled-truth-rewriter specialist for each before the skill returns. Disabled by default."),
+        forceRewrite: z.boolean().optional().describe("When inlineRewrite is true, bypass the 7-day per-entity cooldown on compiledTruthUpdatedAt. All threshold-qualifying entities are returned as inlineRewriteCandidates regardless of when their truth was last rewritten."),
+        inlineRewriteThreshold: z.number().int().min(1).optional().describe("Minimum MENTIONS/REFERENCES edge count from this source to an entity for it to qualify as an inline-rewrite candidate. Default: 2."),
+    }, async ({ attachmentId, conversationIdentity, source, archiveSha256, archiveSourceFile, participantElementIds, lastIngestedMessageHash, lastIngestedMessageAt, archiveTitle, cleanupPriorChunks, sessionIndex, documentSummary, anchorNodeId, anchorLabel, sections, documentEdges, orphanCandidates, scope, sourceUrl, sourceType, documentKeywords, userKeywords, sessionId: sessionIdOverride, inlineRewrite, forceRewrite, inlineRewriteThreshold }) => {
         if (!accountId)
             return refuseNoAccount("memory-ingest");
         try {
@@ -1249,6 +1259,9 @@ if (!readOnly) {
                 documentKeywords,
                 userKeywords,
                 sessionId: resolveSessionId(sessionIdOverride),
+                inlineRewrite,
+                forceRewrite,
+                inlineRewriteThreshold,
             });
             return {
                 content: [{
@@ -1264,6 +1277,8 @@ if (!readOnly) {
                             documentSummary: result.documentSummary,
                             keywords: result.keywords,
                             cleanedPriorChunks: result.cleanedPriorChunks,
+                            inlineRewriteCandidates: result.inlineRewriteCandidates,
+                            inlineRewriteDeferred: result.inlineRewriteDeferred,
                         }),
                     }],
             };
@@ -2494,13 +2509,14 @@ server.tool("session-retrospective-skip-rate", "Return the ratio of recent sessi
 // ===================================================================
 // Report MCP tools (Task 332) are registered earlier in this file.
 // Dream-run calls the same writer in-process for the per-run :Report.
-server.tool("memory-dream-run", "Operator-initiated dream-cycle: graph-hygiene sweep across five phases " +
+server.tool("memory-dream-run", "Operator-initiated dream-cycle: graph-hygiene sweep across seven phases " +
     "(orphan detection, stale compiled-truth, edges to :Trashed targets, citation audit on :TimelineEvent, " +
-    "prune compiled-truth revisions to newest 20 per entity). " +
+    "prune compiled-truth revisions, materialise :BACKLINKS edges, tag normalisation). " +
     "Writes a :Report node at the end. Failure of any phase logs and continues. " +
-    "Pass phases=[4] to run only the citation audit (e.g. after a bulk ingest), or phases=[5] for revision prune only.", {
+    "Pass phases=[4] to run only the citation audit (e.g. after a bulk ingest), phases=[5] for revision prune only, " +
+    "or phases=[6,7] for backlink/tag maintenance only.", {
     operatorId: z.string().optional().describe("Identifier of the operator who triggered the run; appears in the report and log line."),
-    phases: z.array(z.number().int().min(1).max(5)).optional().describe("Subset of phases to run. Default [1,2,3,4,5]. Order is fixed."),
+    phases: z.array(z.number().int().min(1).max(7)).optional().describe("Subset of phases to run. Default [1,2,3,4,5,6,7]. Order is fixed."),
     maxEventsPerRun: z.number().int().positive().optional().describe("Phase 4 cap on :TimelineEvent rows scanned per run. Default 200."),
 }, async ({ operatorId, phases, maxEventsPerRun }) => {
     if (!accountId)