@rubytech/create-realagent-code 0.1.21 → 0.1.23

package/dist/samba-provision.js

@@ -0,0 +1,215 @@
+// Task 034 — Samba provisioning for the brand Pi filesystem.
+//
+// Same shape as apt-resolve.ts: pure decision functions in this file, no I/O;
+// the installer wraps them with the side-effecting spawnSync + log lines. The
+// pure layer is fully unit-tested; the wrapper is exercised end-to-end on a
+// real Pi during install/uninstall verification.
+//
+// What this module owns:
+//   1. Pick the LAN interface to bind smbd to (loopback excluded).
+//   2. Render the brand-scoped Samba stanza per the spec in the task brief.
+//   3. Merge that stanza into an existing /etc/samba/smb.conf idempotently —
+//      replace if a stanza for this brand already exists, otherwise append.
+//   4. Remove this brand's stanza on uninstall while leaving every peer brand's
+//      stanza intact (peer-brand isolation is the structural invariant).
+//   5. Report whether any brand stanza remains so the uninstall step can
+//      decide whether to apt-purge samba.
+// ---------------------------------------------------------------------------
+// Brand-scoped Samba stanza
+// ---------------------------------------------------------------------------
+/**
+ * Render the `[<brand>]` share stanza. Exact directives are the task's spec
+ * verbatim: share rooted at `sharePath`, writable by `admin` only, force-uid
+ * to admin so files created via SMB are owned by the same uid as files
+ * created over SSH, and standard create/dir masks for an ext4 home directory.
+ */
+export function renderBrandStanza(input) {
+    return [
+        `[${input.brand}]`,
+        `   path = ${input.sharePath}`,
+        `   read only = no`,
+        `   valid users = admin`,
+        `   force user = admin`,
+        `   browseable = yes`,
+        `   create mask = 0664`,
+        `   directory mask = 0775`,
+        ``,
+    ].join("\n");
+}
+/**
+ * Render the `[global]` section. `interfaces = lo <lan>` plus `bind interfaces
+ * only = yes` is the LAN-only posture: smbd accepts connections on the LAN
+ * interface and loopback, nothing else. Cloudflare tunnels carry HTTPS only,
+ * so this is the structural guarantee that SMB never leaves the LAN even if
+ * the firewall is misconfigured upstream.
+ */
+export function renderGlobalSection(input) {
+    return [
+        `[global]`,
+        `   workgroup = WORKGROUP`,
+        `   server string = %h Samba`,
+        `   server role = standalone server`,
+        `   interfaces = lo ${input.lanInterface}`,
+        `   bind interfaces only = yes`,
+        `   log file = /var/log/samba/log.%m`,
+        `   max log size = 1000`,
+        `   panic action = /usr/share/samba/panic-action %d`,
+        `   passdb backend = tdbsam`,
+        `   unix password sync = no`,
+        `   map to guest = bad user`,
+        `   usershare allow guests = no`,
+        ``,
+    ].join("\n");
+}
+/**
+ * Build a complete smb.conf from scratch — globals + one brand stanza. Used
+ * only when no existing config is present (fresh apt install always writes
+ * one, so this branch fires on weird edge cases like operator-deleted conf
+ * files). Normal path is `mergeSmbConf` against the apt-shipped default.
+ */
+export function renderFullSmbConf(input) {
+    return renderGlobalSection({ lanInterface: input.lanInterface }) +
+        renderBrandStanza({ brand: input.brand, sharePath: input.sharePath });
+}
+// ---------------------------------------------------------------------------
+// LAN interface detection
+// ---------------------------------------------------------------------------
+/**
+ * Pick the LAN interface to bind smbd to. Preference order: wlan0, eth0, then
+ * the first non-loopback interface with a non-internal IPv4 address. Returns
+ * null when no such interface exists — the caller treats that as a hard
+ * failure (the Pi has no LAN connectivity; SMB has nothing to bind to).
+ *
+ * Input is the shape returned by `os.networkInterfaces()` so the test can pass
+ * realistic fixtures without spinning up real interfaces.
+ */
+export function pickLanInterface(ifaces) {
+    const hasIPv4 = (name) => {
+        const addrs = ifaces[name];
+        if (!addrs)
+            return false;
+        return addrs.some((a) => a.family === "IPv4" && !a.internal);
+    };
+    if (hasIPv4("wlan0"))
+        return "wlan0";
+    if (hasIPv4("eth0"))
+        return "eth0";
+    for (const name of Object.keys(ifaces)) {
+        if (name === "lo")
+            continue;
+        if (hasIPv4(name))
+            return name;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// smb.conf merge / remove
+// ---------------------------------------------------------------------------
+/**
+ * Find the start and end byte offsets of a `[<section>]` block in an smb.conf.
+ * End is the index just before the next `[…]` header or EOF, whichever comes
+ * first. Returns null when no such section exists.
+ *
+ * Section names are matched case-sensitively because Samba itself is
+ * case-sensitive for share names on Linux filesystems.
+ */
+function findSectionRange(conf, section) {
+    const lines = conf.split("\n");
+    const header = `[${section}]`;
+    let startLine = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === header) {
+            startLine = i;
+            break;
+        }
+    }
+    if (startLine === -1)
+        return null;
+    let endLine = lines.length;
+    for (let i = startLine + 1; i < lines.length; i++) {
+        if (/^\[[^\]]+\]\s*$/.test(lines[i].trim())) {
+            endLine = i;
+            break;
+        }
+    }
+    const start = lines.slice(0, startLine).reduce((n, l) => n + l.length + 1, 0);
+    const sectionText = lines.slice(startLine, endLine).join("\n") + (endLine < lines.length ? "\n" : "");
+    return { start, end: start + sectionText.length };
+}
+/**
+ * Merge globals + brand stanza into an existing smb.conf. Idempotent: a
+ * second call with the same inputs produces byte-identical output.
+ *
+ *   - `[global]`: replace verbatim with our rendered globals. The apt-shipped
+ *     `[global]` is a good starting point but doesn't carry our LAN-only
+ *     directives; replacing it is the only way to guarantee `bind interfaces
+ *     only = yes` is in effect.
+ *   - `[<brand>]`: replace if present, append at end of file otherwise. Peer
+ *     brand stanzas (other `[…]` blocks) are preserved verbatim.
+ */
+export function mergeSmbConf(input) {
+    const { existing, brand, sharePath, lanInterface } = input;
+    const newGlobals = renderGlobalSection({ lanInterface });
+    const newBrand = renderBrandStanza({ brand, sharePath });
+    let conf = existing;
+    // Replace or insert the global section.
+    const globalRange = findSectionRange(conf, "global");
+    if (globalRange) {
+        conf = conf.slice(0, globalRange.start) + newGlobals + conf.slice(globalRange.end);
+    }
+    else {
+        conf = newGlobals + (conf.startsWith("\n") ? conf : conf);
+    }
+    // Replace or insert the brand stanza.
+    const brandRange = findSectionRange(conf, brand);
+    if (brandRange) {
+        conf = conf.slice(0, brandRange.start) + newBrand + conf.slice(brandRange.end);
+    }
+    else {
+        // Append with a single trailing newline guarantee.
+        if (!conf.endsWith("\n"))
+            conf += "\n";
+        conf += newBrand;
+    }
+    return conf;
+}
+/**
+ * Remove `[<brand>]` from an smb.conf. Returns the input unchanged when no
+ * such stanza exists. Other sections (global, other brands) are preserved
+ * byte-for-byte. Used by the uninstall path.
+ */
+export function removeBrandStanza(input) {
+    const { existing, brand } = input;
+    const range = findSectionRange(existing, brand);
+    if (!range)
+        return existing;
+    return existing.slice(0, range.start) + existing.slice(range.end);
+}
+/**
+ * True when at least one non-global stanza remains in the smb.conf. Used by
+ * uninstall to decide whether to apt-purge samba: only purge when no brand
+ * stanza is left.
+ */
+export function hasAnyBrandStanza(conf) {
+    const lines = conf.split("\n");
+    for (const line of lines) {
+        const m = line.trim().match(/^\[([^\]]+)\]$/);
+        if (m && m[1].toLowerCase() !== "global")
+            return true;
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Step-marker contract
+// ---------------------------------------------------------------------------
+/**
+ * The four install-invariant markers the installer (and uninstall, set-pin)
+ * emit. Locked here so a typo at a call site cannot silently drift from the
+ * spec. The state vocabulary is also locked: `ok` (step succeeded), `fail:
+ * <stderr>` (step threw — installer aborts), `deferred reason=<…>` (step
+ * intentionally skipped because a precondition wasn't met).
+ */
+export const SAMBA_STEPS = ["apt", "conf", "user", "units"];
+export function formatSambaMarker(step, state) {
+    return `[install-invariant] samba-provision-${step} ${state}`;
+}

package/dist/uninstall.js

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, appendFileSyn
 import { resolve, join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { createInterface } from "node:readline";
+import { removeBrandStanza, hasAnyBrandStanza } from "./samba-provision.js";
 const HOME = homedir();
 const PAYLOAD_DIR = resolve(import.meta.dirname, "../payload");
 // Brand manifest — read from payload to derive brand-specific installation paths.
@@ -23,7 +24,7 @@ catch (err) {
 const INSTALL_DIR = resolve(HOME, BRAND.installDir);
 const CONFIG_DIR = resolve(HOME, BRAND.configDir);
 const LOG_FILE = join("/tmp", `${BRAND.productName.toLowerCase().replace(/\s+/g, "-")}-uninstall-${new Date().toISOString().replace(/[:.]/g, "-")}.log`);
-const TOTAL = "10";
+const TOTAL = "11";
 // ---------------------------------------------------------------------------
 // Logging — timestamped to console AND persistent log file in /tmp
 // (Log lives in /tmp because the uninstall deletes the config directory)
@@ -233,6 +234,80 @@ function stopServices() {
     console.log("  Stopped Ollama");
 }
 // ---------------------------------------------------------------------------
+// Step 1b: Strip the legacy installer-registered cron block
+//
+// Task 039 retired `installCrons()` in src/index.ts. Older installs (every
+// brand prior to the Task 039 release) wrote three minute-cadence entries
+// between `# BEGIN <BRAND> CRONS` and `# END <BRAND> CRONS`. This step
+// removes that block on uninstall so an upgraded device is fully torn down
+// and a subsequent reinstall does not get re-seeded by cron recreating
+// `data/accounts/<accountId>/logs/` every 60s (which tripped seed-neo4j.sh's
+// stub-account-dirs guard — see Task 039 problem statement). Idempotent:
+// no-op when the block is absent. Gated on Linux to mirror the installer's
+// `installCrons` which early-returned on every other platform.
+// ---------------------------------------------------------------------------
+function removeLegacyCronBlock() {
+    log("1b", "Removing legacy cron block...");
+    if (!isLinux()) {
+        console.log("  Skipped — non-Linux platform.");
+        return;
+    }
+    if (!commandExists("crontab")) {
+        console.log("  crontab not available — nothing to strip.");
+        return;
+    }
+    const current = spawnSync("crontab", ["-l"], { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+    // Non-zero status (or empty stdout) on `crontab -l` means the user has no
+    // crontab at all — nothing to strip, and writing back would create one.
+    if (current.status !== 0 || !current.stdout) {
+        console.log("  Cron block: none present");
+        return;
+    }
+    const beginMarker = `# BEGIN ${BRAND.productName.toUpperCase()} CRONS`;
+    const endMarker = `# END ${BRAND.productName.toUpperCase()} CRONS`;
+    const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const blockPattern = new RegExp(`${escapeRegex(beginMarker)}[\\s\\S]*?${escapeRegex(endMarker)}\\n?`, "g");
+    // Count entry lines (non-comment, non-blank) between markers for the
+    // operator-visible log. matchAll returns all block bodies in one pass.
+    const extractPattern = new RegExp(`${escapeRegex(beginMarker)}([\\s\\S]*?)${escapeRegex(endMarker)}`, "g");
+    let entryCount = 0;
+    for (const match of current.stdout.matchAll(extractPattern)) {
+        entryCount += match[1]
+            .split("\n")
+            .filter((l) => l.trim().length > 0 && !l.trim().startsWith("#"))
+            .length;
+    }
+    if (entryCount === 0 && !blockPattern.test(current.stdout)) {
+        console.log("  Cron block: none present");
+        return;
+    }
+    const stripped = current.stdout.replace(blockPattern, "").trimEnd();
+    if (stripped.length === 0) {
+        // Block was the only content — remove the crontab outright so `crontab -l`
+        // reports "no crontab for admin" (Task 039 success criterion). Writing an
+        // empty buffer via `crontab -` leaves a zero-byte crontab on Debian.
+        const removed = spawnSync("crontab", ["-r"], { stdio: "pipe" });
+        if (removed.status !== 0) {
+            console.log(`  Cron block: stripped ${entryCount} entries but crontab -r failed — ${(removed.stderr ?? "").toString().trim()}`);
+            logFile(`  crontab -r failed: ${removed.stderr}`);
+            return;
+        }
+    }
+    else {
+        const write = spawnSync("crontab", ["-"], {
+            input: stripped + "\n",
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        if (write.status !== 0) {
+            console.log(`  Cron block: write failed — ${(write.stderr ?? "").trim()}`);
+            logFile(`  crontab write failed: ${write.stderr}`);
+            return;
+        }
+    }
+    console.log(`  Cron block: removed ${entryCount} entries`);
+}
+// ---------------------------------------------------------------------------
 // Step 2: Delete Cloudflare tunnel
 // ---------------------------------------------------------------------------
 function deleteCloudflareTunnel() {
@@ -709,10 +784,90 @@ function removeOllama() {
     // Models directory (~/.ollama/) is removed in step 4 (removeAppDirs)
 }
 // ---------------------------------------------------------------------------
-// Step 10: Restore hostname
+// Task 034 — Samba teardown. Symmetric to provisionSamba in index.ts.
+//
+// Peer-brand discipline: smb.conf, the smbpasswd entry, and the samba apt
+// package are device-wide singletons shared by every brand that ships an
+// SMB share. Drop only this brand's stanza on every uninstall; stop+disable
+// units / smbpasswd -x admin / apt-purge samba run only when no brand stanza
+// remains in smb.conf AND no peer brand is detected. This mirrors the
+// Neo4j / cloudflared / Ollama treatment in steps 5–9 above.
+// ---------------------------------------------------------------------------
+function removeSamba() {
+    log("10", "Removing Samba share...");
+    if (!isLinux()) {
+        console.log("  Not Linux — skipping.");
+        return;
+    }
+    const SMB_CONF = "/etc/samba/smb.conf";
+    if (!existsSync(SMB_CONF)) {
+        console.log("  /etc/samba/smb.conf not present — nothing to remove.");
+        return;
+    }
+    let existing = "";
+    try {
+        const cat = spawnSync("sudo", ["cat", SMB_CONF], { encoding: "utf-8", stdio: "pipe", timeout: 5_000 });
+        if (cat.status === 0)
+            existing = cat.stdout ?? "";
+    }
+    catch {
+        console.log("  Could not read smb.conf — skipping stanza removal.");
+        return;
+    }
+    const stripped = removeBrandStanza({ existing, brand: BRAND.hostname });
+    if (stripped !== existing) {
+        const tee = spawnSync("sudo", ["tee", SMB_CONF], { input: stripped, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"], timeout: 10_000 });
+        if (tee.status === 0) {
+            console.log(`  Removed [${BRAND.hostname}] stanza from ${SMB_CONF}`);
+        }
+        else {
+            console.log(`  Failed to write stripped smb.conf: ${(tee.stderr ?? "").trim()}`);
+        }
+    }
+    else {
+        console.log(`  No [${BRAND.hostname}] stanza found in ${SMB_CONF}`);
+    }
+    // Reload smbd so the brand share disappears from the running config without
+    // dropping connections to peer brand shares. `reload` is best-effort: the
+    // operator has already torn down the brand; failing to reload would leave a
+    // dangling share name but nothing routable to its (now-deleted) sharePath.
+    spawnSync("sudo", ["systemctl", "reload", "smbd"], { stdio: "pipe", timeout: 10_000 });
+    // Per-brand cleanup stops here when a peer brand stanza still references the
+    // share — disabling smbd or purging samba would take the peer's share down.
+    const peer = peerBrandPresent();
+    if (hasAnyBrandStanza(stripped) || peer) {
+        const reason = peer ? `peer brand present (${peer})` : "other brand stanza remains";
+        console.log(`  Leaving smbd/nmbd + samba package in place — ${reason}`);
+        return;
+    }
+    // No brand stanza, no peer brand — full device-wide teardown.
+    try {
+        spawnSync("sudo", ["systemctl", "disable", "--now", "smbd", "nmbd"], { stdio: "pipe", timeout: 30_000 });
+        console.log("  Stopped + disabled smbd, nmbd");
+    }
+    catch (err) {
+        console.log(`  Failed to disable smbd/nmbd: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Drop the admin smbpasswd entry. `smbpasswd -x` exits 0 on success, non-zero
+    // if the user isn't in the passdb — both are acceptable end-states.
+    spawnSync("sudo", ["smbpasswd", "-x", "admin"], { stdio: "pipe", timeout: 10_000 });
+    try {
+        shell("apt-get", ["remove", "--purge", "-y", "samba", "samba-common-bin"], { sudo: true, timeout: 120_000 });
+        console.log("  Purged samba package.");
+    }
+    catch (err) {
+        console.log(`  apt-get purge samba failed: ${err instanceof Error ? err.message : String(err)}`);
+        console.log("  Run manually: sudo apt-get remove --purge -y samba samba-common-bin");
+    }
+    // Drop the smbpasswd sudoers grant once no brand stanza references it.
+    spawnSync("sudo", ["rm", "-f", "/etc/sudoers.d/maxy-samba"], { stdio: "pipe", timeout: 5_000 });
+    console.log("  Removed /etc/sudoers.d/maxy-samba");
+}
+// ---------------------------------------------------------------------------
+// Step 11: Restore hostname
 // ---------------------------------------------------------------------------
 function restoreHostname() {
-    log("10", "Restoring hostname...");
+    log("11", "Restoring hostname...");
     if (!isLinux()) {
         console.log("  Not Linux — skipping.");
         return;
@@ -810,6 +965,7 @@ export async function runUninstall(options) {
     const failures = [];
     const steps = [
         { name: "Stop services", fn: stopServices },
+        { name: "Remove legacy cron block", fn: removeLegacyCronBlock },
         { name: "Delete Cloudflare tunnel", fn: deleteCloudflareTunnel },
         ...(options.exportPath
             ? [{ name: "Export data", fn: () => exportData(options.exportPath) }]
@@ -821,6 +977,7 @@ export async function runUninstall(options) {
         { name: "Remove system configuration", fn: removeSystemConfig },
         { name: "Remove systemd service", fn: removeSystemdService },
         { name: "Remove Ollama", fn: removeOllama },
+        { name: "Remove Samba share", fn: removeSamba },
         { name: "Restore hostname", fn: restoreHostname },
     ];
     for (const step of steps) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent-code",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "Install Real Agent — Built for agents. By agents.",
   "bin": {
     "create-realagent-code": "./dist/index.js"

package/payload/platform/plugins/docs/references/deployment.md

@@ -68,6 +68,26 @@ Failure signals to grep in `~/.maxy/logs/server.log` (or `~/.realagent/logs/serv
 
 If you need to restart the service manually (rare), ask {{productName}} to do it for you.
 
+## Browsing the brand filesystem on your LAN (SMB)
+
+{{productName}} exposes its install folder (`/home/admin/<brand>` on the Pi) as a network share so you can drop files in, drag files out, and edit them from your Mac, Windows PC, iPhone, or Android device. It uses SMB — the same protocol Windows file sharing uses — which every modern OS speaks natively. No client install required.
+
+The share is **LAN-only**: it binds to the loopback and your Pi's Wi-Fi/Ethernet interface only. Cloudflare tunnels carry HTTPS for the web UI, not SMB, so the share is invisible from the public internet. Off-LAN access for travelling operators is handled by a separate route (in progress).
+
+**Credentials:** SMB user is `admin`; password is your {{productName}} PIN. The installer wires the sync so every time you set or rotate the PIN in the admin UI, the SMB password updates with it.
+
+**macOS Finder**: Press `Cmd-K` from any Finder window, type `smb://<hostname>.local` (use the hostname your installer printed — for example `smb://maxy-code.local` or `smb://realagent-code.local`), click Connect, sign in as `admin` with your PIN. The share appears in the Finder sidebar; drag-and-drop works in both directions.
+
+**Windows Explorer**: Open File Explorer, type `\\<hostname>.local\<brand>` in the address bar (for example `\\maxy-code.local\maxy-code`), press Enter, sign in as `admin` with your PIN. To keep it across reboots, right-click → "Map network drive".
+
+**iOS Files**: Open Files → tap the `…` menu (top-right) → "Connect to Server" → enter `smb://<hostname>.local` → "Registered User" → username `admin`, password is your PIN.
+
+**Android (Solid Explorer, CX File Explorer)**: Add a new connection of type SMB / Network. Host = `<hostname>.local`, share = `<brand>` (same as your install folder name), user = `admin`, password = your PIN.
+
+**Troubleshooting:** if the mount fails with "logon failure", change your PIN in the admin UI and try again — that re-triggers the smbpasswd sync. If the share doesn't show up at all, your client may need `<hostname>.local` resolved by mDNS — try the Pi's LAN IP address as a fallback (`smb://192.168.1.50` on macOS, `\\192.168.1.50\<brand>` on Windows).
+
+The installer maintains the share automatically. To remove it, uninstalling the brand strips its stanza from `/etc/samba/smb.conf` and (when no peer brand remains on the device) stops `smbd`, drops the smbpasswd entry, and purges the samba package.
+
 ## Remote Access via Cloudflare
 
 {{productName}} uses a Cloudflare tunnel to make your local Pi accessible from anywhere without opening router ports. The tunnel is configured during setup and runs as a background service.

package/payload/platform/plugins/email/references/email-reference.md

@@ -73,7 +73,7 @@ When `agentAddress` is not set or matches the auth email, all tools behave as be
 
 ## Email Persistence
 
-Emails are automatically polled from IMAP and stored as `Email` nodes in the graph. This happens via a background cron job — no manual triggering needed.
+Emails are fetched from IMAP and stored as `Email` nodes in the graph. The fetcher binary lives at `email/mcp/dist/scripts/email-fetch.js`. As of Task 039 it is **not currently scheduled on any install** — migration to Desktop scheduled tasks (the canonical dispatch surface, see `maxy-code-prd.md` §Scheduled tasks) is tracked separately. Until that landing, new email is only ingested when an operator invokes the fetcher manually.
 
 - **Polling:** After `email-setup` completes, the platform polls IMAP at the configured interval (default: every 5 minutes). Only emails addressed TO the agent's `agentAddress` are stored.
 - **Deduplication:** Each email is identified by its Message-ID header. Re-polling the same messages does not create duplicates, even if the agent's email address changes between poll cycles. A composite unique constraint on `(messageId, accountId)` provides database-level enforcement.
@@ -82,7 +82,7 @@ Emails are automatically polled from IMAP and stored as `Email` nodes in the gra
 
 ## Email Threading
 
-Emails are linked into conversation threads via `REPLY_TO` graph edges. When an email has an `In-Reply-To` header, the platform looks up the parent email by `Message-ID` within the same account and creates an edge. Thread linking happens automatically during the polling cron job.
+Emails are linked into conversation threads via `REPLY_TO` graph edges. When an email has an `In-Reply-To` header, the platform looks up the parent email by `Message-ID` within the same account and creates an edge. Thread linking happens as part of each fetch run (which is operator-invoked until the dispatcher is wired — see above).
 
 - **Out-of-order delivery:** If a reply arrives before its parent, the edge is created later when the parent is stored (orphan back-fill).
 - **Thread context:** `email-read` and `email-search` include `Thread-Depth` (number of hops to the thread root) and `Thread-ID` (emailId of the root message) for any email that is part of a thread. Root emails (no parent) have no thread fields.
@@ -150,7 +150,7 @@ Classification verdicts are logged to `{accountDir}/logs/email-fetch.log` with p
 
 ## Auto-Respond
 
-When enabled, a public agent automatically replies to incoming emails. A cron job polls the inbox for new messages and generates replies via the assigned agent.
+When enabled, a public agent replies to incoming emails. The auto-respond binary lives at `email/mcp/dist/scripts/email-auto-respond.js` and, like the fetcher, is **not currently scheduled on any install** as of Task 039 — see `maxy-code-prd.md` §Scheduled tasks for the canonical dispatch destination. Until that landing, auto-respond only runs when an operator invokes the script manually.
 
 ### Setup
 
@@ -168,7 +168,7 @@ When called without an `agentSlug`, the tool returns available agents. Present t
 
 ### Behaviour
 
-- The cron job runs every minute. Each account's poll is skipped if the configured interval hasn't elapsed since the last poll.
+- Once the dispatcher is wired (see above), each account's poll is skipped if the configured interval hasn't elapsed since the last poll. The interval gate is enforced inside `email-auto-respond.js`, so the same skip logic applies whether the script is fired by the dispatcher or manually by an operator.
 - Only emails addressed TO the agent's email address are processed (alias filtering applies).
 - Auto-replies, mailing list messages, and emails from the agent's own address are automatically skipped (RFC 3834 loop prevention).
 - Outgoing replies include `In-Reply-To` and `References` headers for correct threading, and `Auto-Submitted: auto-replied` to prevent loops with other auto-responders.

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

@@ -49,7 +49,7 @@ For recurring events, `schedule-update` with `skipNext: true` advances `nextRun`
 
 ## Event actions
 
-Events can carry an automated action that fires when the event's time arrives. The platform heartbeat cron (every minute) checks for due events and dispatches their actions by spawning the target plugin's MCP server and calling the named tool.
+Events can carry an automated action that fires when the event's time arrives. The dispatcher binary that reads due events and spawns the target plugin's MCP server lives at `scheduling/mcp/dist/scripts/check-due-events.js`. As of Task 039 it is **not currently scheduled on any install**: the legacy crontab writer was removed and migration of the dispatcher to Desktop scheduled tasks (the canonical dispatch surface — see `maxy-code-prd.md` §Scheduled tasks) is tracked separately. Until that landing, `action:` payloads are stored on the event and only execute when an operator invokes the dispatcher manually.
 
 To create an event with an action, pass the `action` parameter to `schedule-event`:
 

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

@@ -15,7 +15,7 @@ metadata: {"platform":{"always":false,"embed":[],"pluginKey":"workflows"}}
 
 # Workflows
 
-> **Loading note:** `platform.always:false` in the frontmatter above refers to **prose embedding** — this file's contents are not auto-injected into every agent system prompt. It does **not** refer to MCP server loading. The workflows MCP server is always loaded in admin sessions (registered in `getMcpServers()` in `claude-agent.ts` alongside `tasks` / `scheduling` / `email`), and the same binary is also spawned ad-hoc from the heartbeat cron for scheduled `workflow-execute` calls via `.mcp.json`.
+> **Loading note:** `platform.always:false` in the frontmatter above refers to **prose embedding** — this file's contents are not auto-injected into every agent system prompt. It does **not** refer to MCP server loading. The workflows MCP server is always loaded in admin sessions (registered in `getMcpServers()` in `claude-agent.ts` alongside `tasks` / `scheduling` / `email`). The same binary is designed to be spawned ad-hoc by the platform's scheduled-task dispatcher for `workflow-execute` calls via `.mcp.json`; that dispatcher is currently unwired (see `maxy-code-prd.md` §Scheduled tasks for the canonical destination surface).
 
 Workflows are persistent, named compositions of executable steps that the user creates and the engine executes. Steps can chain MCP tool calls and LLM reasoning into composable pipelines. Steps are validated at creation time — a workflow with unmet dependencies cannot be activated. The user manages them conversationally.
 
@@ -207,7 +207,7 @@ To trigger a workflow on a schedule, create an Event with the scheduling plugin
 action: { plugin: "workflows", tool: "workflow-execute", args: { workflowId: "..." } }
 ```
 
-The existing `check-due-events` heartbeat dispatches the workflow execution at the scheduled time. The WorkflowRun captures `trigger: "schedule"`.
+Scheduled workflows are dispatched by `check-due-events`, which is currently unwired pending migration to Desktop scheduled tasks (see `maxy-code-prd.md` §Scheduled tasks). When the dispatcher fires, the WorkflowRun captures `trigger: "schedule"`.
 
 ## Managing Workflows
 

package/payload/platform/plugins/workflows/skills/workflow-manager/SKILL.md

@@ -85,4 +85,4 @@ To run a workflow on a schedule, create a scheduling event with action dispatch:
 - Tool: `schedule-event`
 - Action: `{ plugin: "workflows", tool: "workflow-execute", args: { workflowId: "..." } }`
 
-The platform heartbeat cron dispatches the workflow at the scheduled time. The WorkflowRun captures `trigger: "schedule"`.
+The `check-due-events` dispatcher (currently unwired — see `maxy-code-prd.md` §Scheduled tasks) is the surface that will fire the workflow at the scheduled time. The WorkflowRun captures `trigger: "schedule"` when the dispatcher fires.

package/payload/platform/templates/agents/admin/IDENTITY.md

@@ -4,17 +4,16 @@
 
 Three rules govern every turn. They are load-bearing — when they conflict with anything else in this prompt, they win.
 
-**PRECISE.** Use exact names: exact tool names, exact field values, exact file paths, exact node properties. When relaying a tool result, relay what the tool returned — do not paraphrase, do not approximate, do not invent flags. When uncertain about an exact value, look it up; never substitute a loose-but-plausible string. *Failure symptoms:* paraphrasing tool output, approximate tool name, inventing a flag.
+**BE PRECISE.**
 
-**CONCISE.** Every output is the minimum tokens that convey the signal. The Neo4j graph is the canonical store of knowledge for this account; keep it dense in signal via the two-step memory discipline:
-- *Compress on write.* Before `memory-write`, reduce the input to the minimal node/edge/property set that preserves the signal. Do not persist raw monologues, document bodies, or tool-result dumps — persist the extracted structure. If extraction is unclear, ask in one sentence what to preserve rather than saving everything.
-- *Filter on read.* `memory-search` returns candidates, not answers. Filter the returned set to the subset that answers the current turn. Relay one line of signal, not ten lines of candidate text.
+**BE CONCISE.** 
 
-*Failure symptoms:* unrequested summary, three-paragraph answer to a one-line question, pasting a raw tool result verbatim into chat.
+**BE EVIDENCE-BASED.** 
 
-**EVIDENCE-BASED.** The graph is the single, canonical source of truth about this account. Consult it — via `memory-search`, `memory-read`, or `profile-read` — before answering factual questions or embarking on activity. When the graph is wrong, correct it via `memory-write` or `memory-update`, then answer. Never substitute training-data recall for a graph read when the graph holds the canonical version. When the graph has no answer and you must rely on training knowledge, say so explicitly. *Failure symptoms:* factual claim without a prior graph read this turn, training-data fallback when the graph has the canonical version.
-
-A landfill graph defeats EVIDENCE-BASED: search returns noise, the agent re-writes the noise, the noise compounds. Compress on write; filter on read.
+The Neo4j graph is the canonical store of knowledge for this account; keep it dense in signal via the two-step memory discipline:
+- *Compress on write.* Before `memory-write`, reduce the input to the minimal node/edge/property set that preserves the signal.
+- *Filter on read.* `memory-search` returns candidates, not answers. Filter the returned set to the subset that answers the current turn in the least amount of tokens. When the graph is wrong, correct it via `memory-write` or `memory-update`, then answer. Never substitute training-data recall for a graph read when the graph holds the canonical version. When the graph has no answer and you must rely on training knowledge, say so explicitly.
+Comply with these doctrines and you cannot help but be precise and concise.
 
 ---
 
@@ -28,21 +27,16 @@ No action without clear intent. Before acting on any request, you must know:
 
 When the owner's words are precise, all three are self-evident — act without delay. When any of the three requires assumption, stop and ask. Vagueness and urgency are signals to slow down, not speed up. Once confirmed, the rules of engagement are binding for the duration of the task.
 
-**Antecedent lookup before asking.** The owner's words are not the only source of intent — the chain on this conversationId is the first place to consult, not the last. Before emitting any "stop and ask"-class reply (phrasings such as "what are you referring to?", "not enough signal", "could you clarify?"), call `mcp__memory__conversation-search` against the live conversationId. Only when that lookup returns nothing relevant may you ask. Asking while your own history sits one tool-call away unread is a doctrine violation — the chain is your memory, and ignoring it is the same failure mode as paraphrasing a tool result instead of reading it.
-
-**Recovery from any recorded breakdown.** If the chain holds a recent `:TurnFailure` event (mode such as `server-shutdown` or `client-network-drop`) and the owner's next message is a natural follow-up to that breakdown ("what happened?", "where are we?", "did that work?"), the reply names the recorded failure mode and resumes from the preserved chain. Never ask the owner to reframe what they were doing — that information is already in the chain.
-
-This governs everything below.
+**Antecedent lookup before asking.** The owner's words are not the only source of intent — the chain on this conversationId is the first place to consult, not the last. 
 
 ---
 
-You are the head of operations. Your purpose across every session — not just the first, not just when asked — is three things:
+## Your role
 
-1. **Calibrate what excellence means here.** Learn the owner's standards — what good looks like in their work, their decisions, their outcomes. Refine this understanding every session. Session 300 should be more precise than session 3.
-2. **Prevent what used to go wrong.** Learn the failure patterns — what fell through the cracks before you, what keeps breaking, what frustrates. Your job is to break those patterns, not just record them.
-3. **Compress what takes months to learn.** Recognise the compound knowledge — the rhythms, instincts, and patterns that humans build only through sustained repetition. Encode them from the first instance. Give the owner the benefit of experience immediately.
+You are the head of operations, chief of staff and private secretary. Your purpose across every session:
 
-These are not tasks to complete. They are the lens through which you approach every interaction. As your understanding sharpens, your own identity should become more precise — possibly more concise — never merely longer. Every refinement replaces vagueness with exactness.
+1. **Condense every conversation into a precise, concise action.** Cut through the vagueness, filter out the noise, isolate the signal and explicitly surface it.
+2. **Keep everything hyper-organised.** The core function and architecture of the graph is to maintain order. Everything that has reason to be stored should be done under a proper hierarchy. Use projects to host top-level entity nodes, tasks for activities related to them and person and organisation nodes for the relationships between projects and activities.
 
 Your personalisation is in `agents/admin/SOUL.md`. Read it and apply it. SOUL.md is personality and tone only — never behavioural rules, knowledge, or operational constraints. When writing or updating SOUL.md, keep it to how you sound, not what you do.
 

package/payload/platform/templates/specialists/agents/personal-assistant.md

@@ -45,7 +45,7 @@ Manages events, appointments, and recurring triggers in the graph.
 
 **Cron patterns:** `0 8 * * 1-5` (weekdays 8am), `0 9 * * 1` (Monday 9am), `0 0 1 * *` (first of month), `*/30 * * * *` (every 30 min).
 
-**Event actions:** Events can dispatch automated MCP tool calls when their time arrives. Pass `action: { plugin, tool, args }` to `schedule-event`. The platform heartbeat cron (every minute) fires the action by spawning the target plugin's MCP server. Use this to trigger workflows on a schedule: `action: { plugin: "workflows", tool: "workflow-execute", args: { workflowId: "..." } }`.
+**Event actions:** Events can carry an MCP tool-call payload that fires when their time arrives. Pass `action: { plugin, tool, args }` to `schedule-event`. The `check-due-events` dispatcher binary is the surface that reads due events and spawns the target plugin's MCP server. As of Task 039 the dispatcher is **not currently scheduled** — migration to Desktop scheduled tasks is tracked separately (see `maxy-code-prd.md` §Scheduled tasks). Until that landing, scheduled `action:` payloads are stored on the event but only fire when an operator invokes the dispatcher manually. Use this to schedule workflow runs: `action: { plugin: "workflows", tool: "workflow-execute", args: { workflowId: "..." } }`.
 
 **Skip vs cancel:** `schedule-update` with `skipNext: true` advances one cycle without triggering. `schedule-cancel` kills the entire series — there is no per-occurrence cancellation.
 

package/payload/platform/templates/specialists/agents/project-manager.md

@@ -98,7 +98,7 @@ Workflows are persistent, named compositions of executable steps — tool calls
 
 **Listing and reading:** `workflow-list` returns all workflows with status. `workflow-get` returns a single workflow with full step definitions. `workflow-update` modifies steps or metadata. `workflow-delete` removes a workflow.
 
-**Schedule integration:** Workflows can be triggered by scheduled events via the platform heartbeat cron. Link a workflow to a schedule by creating a scheduled event with `action: { plugin: "workflows", tool: "workflow-execute", args: { workflowId: "..." } }`.
+**Schedule integration:** Workflows can be triggered by scheduled events via the `check-due-events` dispatcher. Link a workflow to a schedule by creating a scheduled event with `action: { plugin: "workflows", tool: "workflow-execute", args: { workflowId: "..." } }`. Note: as of Task 039 the dispatcher is **not currently scheduled** — migration to Desktop scheduled tasks is tracked separately (see `maxy-code-prd.md` §Scheduled tasks). Until that landing, the action stays inert until an operator invokes the dispatcher manually.
 
 ## Contacts (domain context — you do not have contact tools)
 

package/payload/server/public/assets/{Checkbox-B79fVxpA.js → Checkbox-D1OQD43b.js}

@@ -1 +1 @@
-import{a as e}from"./brand-jT16ErmC.js";var t=e();function n({checked:e,onChange:n,label:r,disabled:i}){return(0,t.jsxs)(`label`,{className:`maxy-checkbox${i?` maxy-checkbox--disabled`:``}`,children:[(0,t.jsx)(`input`,{type:`checkbox`,checked:e,onChange:e=>n(e.target.checked),disabled:i}),(0,t.jsx)(`span`,{className:`maxy-checkbox__box`,children:`✱`}),r&&(0,t.jsx)(`span`,{className:`maxy-checkbox__label`,children:r})]})}export{n as t};
+import{a as e}from"./brand-CSQuxS9w.js";var t=e();function n({checked:e,onChange:n,label:r,disabled:i}){return(0,t.jsxs)(`label`,{className:`maxy-checkbox${i?` maxy-checkbox--disabled`:``}`,children:[(0,t.jsx)(`input`,{type:`checkbox`,checked:e,onChange:e=>n(e.target.checked),disabled:i}),(0,t.jsx)(`span`,{className:`maxy-checkbox__box`,children:`✱`}),r&&(0,t.jsx)(`span`,{className:`maxy-checkbox__label`,children:r})]})}export{n as t};