@rubytech/create-maxy-code 0.1.542 → 0.1.544

package/dist/__tests__/public-instruction-seed.test.js

@@ -0,0 +1,102 @@
+// Task 2342 — a public agent owns the `## Instruction` block of the turns it
+// answers. install-defaults runs on upgrade, so this pass is what gives every
+// agent created before the file existed a file of its own. Filesystem fixtures
+// under a tmp dir; no installer side effects. Runs under `node --test dist/__tests__/*`.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync, statSync, chmodSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { seedPublicInstructionFiles } from "../public-instruction-seed.js";
+function makeAccount() {
+    const dir = mkdtempSync(join(tmpdir(), "pub-instr-2342-"));
+    mkdirSync(join(dir, "agents"), { recursive: true });
+    return dir;
+}
+function agent(accountDir, slug, files) {
+    const d = join(accountDir, "agents", slug);
+    mkdirSync(d, { recursive: true });
+    for (const [name, body] of Object.entries(files))
+        writeFileSync(join(d, name), body);
+}
+test("creates a zero-byte INSTRUCTION.md for an agent that has none", () => {
+    const acct = makeAccount();
+    try {
+        agent(acct, "beagle", { "config.json": "{}", "SOUL.md": "s" });
+        const out = seedPublicInstructionFiles(acct);
+        assert.deepEqual(out.map((r) => [r.slug, r.action, r.bytes]), [["beagle", "created", 0]]);
+        const p = join(acct, "agents", "beagle", "INSTRUCTION.md");
+        assert.equal(existsSync(p), true);
+        assert.equal(statSync(p).size, 0);
+    }
+    finally {
+        rmSync(acct, { recursive: true, force: true });
+    }
+});
+test("never overwrites an operator's file, and reports its size", () => {
+    const acct = makeAccount();
+    try {
+        agent(acct, "beagle", { "config.json": "{}", "INSTRUCTION.md": "Ask for the trip.\n" });
+        const out = seedPublicInstructionFiles(acct);
+        assert.deepEqual(out.map((r) => [r.slug, r.action]), [["beagle", "preserved"]]);
+        assert.equal(readFileSync(join(acct, "agents", "beagle", "INSTRUCTION.md"), "utf-8"), "Ask for the trip.\n");
+        assert.equal(out[0].bytes, 18);
+    }
+    finally {
+        rmSync(acct, { recursive: true, force: true });
+    }
+});
+// installDefaults seeds agents/admin/INSTRUCTION.md from its own template
+// immediately before this pass runs; reaching it here would report a file this
+// pass did not handle.
+test("skips admin, and skips a directory with no config.json", () => {
+    const acct = makeAccount();
+    try {
+        agent(acct, "admin", { "config.json": "{}", "IDENTITY.md": "i" });
+        agent(acct, "public", { "IDENTITY.md": "i" });
+        const out = seedPublicInstructionFiles(acct);
+        assert.deepEqual(out, []);
+        assert.equal(existsSync(join(acct, "agents", "admin", "INSTRUCTION.md")), false);
+        assert.equal(existsSync(join(acct, "agents", "public", "INSTRUCTION.md")), false);
+    }
+    finally {
+        rmSync(acct, { recursive: true, force: true });
+    }
+});
+// writeInstallDefaults runs on every upgrade. One unwritable agent directory
+// must not abort the install, and must not pass as done either.
+test("reports write-failed instead of throwing when the agent dir is read-only", () => {
+    const acct = makeAccount();
+    try {
+        agent(acct, "beagle", { "config.json": "{}" });
+        agent(acct, "clerk", { "config.json": "{}" });
+        chmodSync(join(acct, "agents", "beagle"), 0o500);
+        const out = seedPublicInstructionFiles(acct).sort((a, b) => a.slug.localeCompare(b.slug));
+        assert.deepEqual(out.map((r) => [r.slug, r.action]), [["beagle", "write-failed"], ["clerk", "created"]]);
+        // The pass continued past the failure: the later agent still got its file.
+        assert.equal(existsSync(join(acct, "agents", "clerk", "INSTRUCTION.md")), true);
+    }
+    finally {
+        chmodSync(join(acct, "agents", "beagle"), 0o700);
+        rmSync(acct, { recursive: true, force: true });
+    }
+});
+test("handles several agents in one pass and returns [] for an account with no agents dir", () => {
+    const acct = makeAccount();
+    try {
+        agent(acct, "beagle", { "config.json": "{}" });
+        agent(acct, "clerk", { "config.json": "{}", "INSTRUCTION.md": "x" });
+        const out = seedPublicInstructionFiles(acct).sort((a, b) => a.slug.localeCompare(b.slug));
+        assert.deepEqual(out.map((r) => [r.slug, r.action]), [["beagle", "created"], ["clerk", "preserved"]]);
+    }
+    finally {
+        rmSync(acct, { recursive: true, force: true });
+    }
+    const bare = mkdtempSync(join(tmpdir(), "pub-instr-bare-"));
+    try {
+        assert.deepEqual(seedPublicInstructionFiles(bare), []);
+    }
+    finally {
+        rmSync(bare, { recursive: true, force: true });
+    }
+});

package/dist/index.js

@@ -11,6 +11,7 @@ import { validateTierFlag, validateEntitlementBase64, applyTierToAccountConfig,
 import { parseOsRelease, isUbuntuLike as isUbuntuLikePure, parseAptCacheCandidate, decideAptResolution, } from "./apt-resolve.js";
 import { findPeerBrandOnDefaultNeo4jPort } from "./peer-brand-detect.js";
 import { removeClientAdminsKey } from "./converge-client-admins.js";
+import { seedPublicInstructionFiles } from "./public-instruction-seed.js";
 import { backupHouseCloudflare, restoreHouseCloudflare, migrateHouseCredentialFromAccount, } from "./preserve-house-cloudflare.js";
 import { resolveNeo4jPidfileScrub } from "./neo4j-pidfile-scrub.js";
 import { runInitLogging } from "./init-logging.js";
@@ -2577,6 +2578,12 @@ function deployPayload() {
     // User data lives at {installDir}/data/ — outside the platform/ wipe zone.
     // Install path creates this fresh; runtime writers populate it on demand.
     mkdirSync(join(INSTALL_DIR, "data"), { recursive: true });
+    // Task 2323 — the install-wide shared folder: written by the house account,
+    // read by every account. Created here rather than lazily by a writer so the
+    // standing census reports exists=true from first boot, and so the pty-spawner's
+    // existsSync-guarded --add-dir and write-deny are live on the first spawn.
+    // Idempotent: an upgrade over an existing install leaves its contents alone.
+    mkdirSync(join(INSTALL_DIR, "data", "shared"), { recursive: true });
     // Task 848 — on upgrade the prior server/, platform/, premium-plugins/ trees are
     // immutable (chattr +i). Clear all three BEFORE the wipe loop, or the rmSync of
     // those dirs below fails with EPERM. Gate on INSTALL_DIR existence (any prior
@@ -3480,6 +3487,37 @@ function writeInstallDefaults(accountId) {
         console.log(`  [install-defaults] soul-md created path=${soulPath} bytes=${soulContent.length}`);
         logFile(`  [install-defaults] soul-md created path=${soulPath} bytes=${soulContent.length}`);
     }
+    // Admin INSTRUCTION.md is operator-controlled: it is the `## Instruction` body
+    // every WhatsApp channel turn carries, so the operator owns what their agent
+    // does with an inbound and can change it on disk without a publish. Create it
+    // from the bundled template on a fresh install and never overwrite it, exactly
+    // as SOUL.md above. install-defaults runs on upgrades too, which is what
+    // backfills accounts provisioned before this file existed. There is no
+    // code-level default downstream: an account with no such file has its channel
+    // turns refused, so this seeding is what keeps an upgraded install working.
+    //
+    // Unlike the SOUL.md branch above, a missing template here logs and continues
+    // rather than returning: returning would skip the public-agent seeding below.
+    const instructionPath = join(accountDir, "agents/admin/INSTRUCTION.md");
+    mkdirSync(dirname(instructionPath), { recursive: true });
+    if (existsSync(instructionPath)) {
+        const preservedBytes = statSync(instructionPath).size;
+        console.log(`  [install-defaults] instruction-md preserved path=${instructionPath} bytes=${preservedBytes}`);
+        logFile(`  [install-defaults] instruction-md preserved path=${instructionPath} bytes=${preservedBytes}`);
+    }
+    else {
+        const instructionTemplate = join(INSTALL_DIR, "platform/templates/agents/admin/INSTRUCTION.md");
+        try {
+            const content = readFileSync(instructionTemplate, "utf-8").replace(/\$\{PRODUCT_NAME\}/g, BRAND.productName);
+            writeFileSync(instructionPath, content);
+            console.log(`  [install-defaults] instruction-md created path=${instructionPath} bytes=${content.length}`);
+            logFile(`  [install-defaults] instruction-md created path=${instructionPath} bytes=${content.length}`);
+        }
+        catch (err) {
+            console.error(`  [install-defaults] admin-instruction template missing at ${instructionTemplate}: ${err.message}`);
+            logFile(`  [install-defaults] admin-instruction template missing: ${err.message}`);
+        }
+    }
     // Public agent IDENTITY.md — the only template-seeded public file, always
     // overwritten (Rubytech-controlled toolless directive). Per Task 618/623,
     // each public agent's SOUL.md, KNOWLEDGE.md, and config.json are authored
@@ -3517,6 +3555,15 @@ function writeInstallDefaults(accountId) {
     }
     console.log(`  [install-defaults] public-identity path=${publicIdentityDst}`);
     logFile(`  [install-defaults] public-identity path=${publicIdentityDst}`);
+    // Task 2342 — each public agent's own INSTRUCTION.md, created empty and never
+    // overwritten. install-defaults runs on upgrade, which is what backfills the
+    // agents created before this file existed. Placed after the public-identity
+    // block so the log reads in the same order the files are made.
+    for (const seeded of seedPublicInstructionFiles(accountDir)) {
+        const line = `  [install-defaults] public-instruction-md ${seeded.action} path=${seeded.path} bytes=${seeded.bytes}`;
+        console.log(line);
+        logFile(line);
+    }
 }
 /**
  * Commercial-mode entitlement delivery (Task 240). Writes the decoded payload

package/dist/public-instruction-seed.js

@@ -0,0 +1,70 @@
+// Task 2342 — every public agent owns the `## Instruction` block of the channel
+// turns it answers, at agents/<slug>/INSTRUCTION.md. Before 2342 that block was
+// read from agents/admin/INSTRUCTION.md whoever the turn woke, so a visitor's
+// turn carried the operator's own operating doctrine.
+//
+// The file is created EMPTY. An empty file resolves 'absent' at the resolver and
+// refuses the turn, which is the intended closed state for an agent whose
+// per-turn behaviour nobody has written; seeding any text would make that text
+// the instruction on every account that never edits it, which is the
+// arrangement 2342 removes. It is never overwritten, so an operator's own file
+// survives every upgrade.
+//
+// A public agent is a directory holding a config.json. `agents/public/` is the
+// template holder installDefaults writes IDENTITY.md into and has no
+// config.json, so it is skipped without needing to be named. `admin` is named
+// because it does carry one on some installs, and installDefaults seeds its
+// file from a template directly before calling this.
+import { existsSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export function seedPublicInstructionFiles(accountDir) {
+    const out = [];
+    const agentsDir = join(accountDir, "agents");
+    let entries = [];
+    try {
+        entries = readdirSync(agentsDir);
+    }
+    catch {
+        return out;
+    }
+    for (const slug of entries) {
+        if (slug.startsWith(".") || slug === "admin")
+            continue;
+        const dir = join(agentsDir, slug);
+        try {
+            if (!statSync(dir).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        if (!existsSync(join(dir, "config.json")))
+            continue;
+        const path = join(dir, "INSTRUCTION.md");
+        if (existsSync(path)) {
+            let bytes = 0;
+            try {
+                bytes = statSync(path).size;
+            }
+            catch {
+                bytes = 0;
+            }
+            out.push({ slug, action: "preserved", path, bytes });
+            continue;
+        }
+        // Guarded like the two reads above, and for the same reason: this runs
+        // inside writeInstallDefaults on every upgrade, and one agent directory the
+        // installer cannot write must not abort the install part-way. The sibling
+        // admin-instruction block does the same. The failure is reported rather
+        // than skipped, so it reaches the install log instead of passing as done.
+        try {
+            writeFileSync(path, "");
+        }
+        catch {
+            out.push({ slug, action: "write-failed", path, bytes: 0 });
+            continue;
+        }
+        out.push({ slug, action: "created", path, bytes: 0 });
+    }
+    return out;
+}

package/package.json

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

package/payload/platform/lib/shared-folder/dist/index.d.ts

@@ -0,0 +1,47 @@
+/** The one literal. The shared root is `<dataRoot>/shared`, a sibling of
+ *  `<dataRoot>/accounts`, so it is inside DATA_ROOT (which is what lets the
+ *  /data browser reach it at all) but outside every account partition. */
+export declare const SHARED_DIR_NAME = "shared";
+/** Absolute path of the shared root. `dataRoot` is `<install>/data`. */
+export declare function sharedRoot(dataRoot: string): string;
+/**
+ * True when a DATA_ROOT-relative path is inside the shared root.
+ *
+ * FIRST SEGMENT ONLY. `accounts/<id>/shared` is an account's own directory that
+ * happens to be called `shared` and must keep account semantics; a deeper
+ * `shared` segment is likewise ordinary content. Callers pass the `relative`
+ * that `resolveDataPath` already produces, which is DATA_ROOT-relative.
+ *
+ * The filesystem plugin does NOT call this: its tool paths are account-relative,
+ * so it selects the shared root with an explicit `shared` flag instead.
+ */
+export declare function isSharedPath(relPath: string): boolean;
+export type SharedWriteDecision = {
+    allow: true;
+} | {
+    reject: "shared-folder-read-only";
+};
+/**
+ * The write decision. `isHouse` is INJECTED rather than resolved here so the
+ * decision stays pure and unit-testable without a filesystem — the same reason
+ * `resolveEffectiveAccountCore` takes an injected `isValidAccountId`.
+ */
+export declare function decideSharedWrite(isHouse: boolean): SharedWriteDecision;
+/**
+ * Disk-backed house check for the two surfaces that have none: the `filesystem`
+ * plugin and the `/data` browser. Drift-safe, matching
+ * claude-session-manager/src/config.ts:464 — false when the census shows zero
+ * or more than one `role:"house"` account, because under drift there is no
+ * single house to grant write to.
+ *
+ * `platform/plugins/admin/mcp/src/tools/account-lifecycle.ts:85` is a SECOND,
+ * different definition (true for any role-house account). It is deliberately
+ * not consolidated here: it guards account deletion, where `true` means refuse,
+ * so giving it these drift semantics would make a drifted install start
+ * ALLOWING deletion of a house account. Consolidation is its own task.
+ *
+ * Never throws: an unreadable accounts dir or an unparseable account.json reads
+ * as "not house", which is the fail-closed answer for a write gate.
+ */
+export declare function isHouseAccountDir(accountsDir: string, accountId: string): boolean;
+//# sourceMappingURL=index.d.ts.map

package/payload/platform/lib/shared-folder/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA;;0EAE0E;AAC1E,eAAO,MAAM,eAAe,WAAW,CAAC;AAExC,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAGrD;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GACf;IAAE,MAAM,EAAE,yBAAyB,CAAA;CAAE,CAAC;AAE1C;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,mBAAmB,CAEvE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAuBjF"}

package/payload/platform/lib/shared-folder/dist/index.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHARED_DIR_NAME = void 0;
+exports.sharedRoot = sharedRoot;
+exports.isSharedPath = isSharedPath;
+exports.decideSharedWrite = decideSharedWrite;
+exports.isHouseAccountDir = isHouseAccountDir;
+// shared-folder — the single definition of the install-wide shared directory.
+//
+// Task 2323. Three surfaces gate on this module: the `filesystem` plugin, the
+// `/data` admin browser, and the pty-spawner's native --add-dir + deny push.
+// One definition, no drift — the same discipline as platform/lib/account-scope.
+//
+// The pure predicates never touch the filesystem, so this module is safe to
+// import into an MCP server that boots with empty env during plugin-system
+// `tools/list` enumeration. `isHouseAccountDir` DOES read disk, but only when
+// called — nothing runs at module load.
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** The one literal. The shared root is `<dataRoot>/shared`, a sibling of
+ *  `<dataRoot>/accounts`, so it is inside DATA_ROOT (which is what lets the
+ *  /data browser reach it at all) but outside every account partition. */
+exports.SHARED_DIR_NAME = "shared";
+/** Absolute path of the shared root. `dataRoot` is `<install>/data`. */
+function sharedRoot(dataRoot) {
+    return (0, node_path_1.resolve)(dataRoot, exports.SHARED_DIR_NAME);
+}
+/**
+ * True when a DATA_ROOT-relative path is inside the shared root.
+ *
+ * FIRST SEGMENT ONLY. `accounts/<id>/shared` is an account's own directory that
+ * happens to be called `shared` and must keep account semantics; a deeper
+ * `shared` segment is likewise ordinary content. Callers pass the `relative`
+ * that `resolveDataPath` already produces, which is DATA_ROOT-relative.
+ *
+ * The filesystem plugin does NOT call this: its tool paths are account-relative,
+ * so it selects the shared root with an explicit `shared` flag instead.
+ */
+function isSharedPath(relPath) {
+    const segs = relPath.split("/").filter(Boolean);
+    return segs.length >= 1 && segs[0] === exports.SHARED_DIR_NAME;
+}
+/**
+ * The write decision. `isHouse` is INJECTED rather than resolved here so the
+ * decision stays pure and unit-testable without a filesystem — the same reason
+ * `resolveEffectiveAccountCore` takes an injected `isValidAccountId`.
+ */
+function decideSharedWrite(isHouse) {
+    return isHouse ? { allow: true } : { reject: "shared-folder-read-only" };
+}
+/**
+ * Disk-backed house check for the two surfaces that have none: the `filesystem`
+ * plugin and the `/data` browser. Drift-safe, matching
+ * claude-session-manager/src/config.ts:464 — false when the census shows zero
+ * or more than one `role:"house"` account, because under drift there is no
+ * single house to grant write to.
+ *
+ * `platform/plugins/admin/mcp/src/tools/account-lifecycle.ts:85` is a SECOND,
+ * different definition (true for any role-house account). It is deliberately
+ * not consolidated here: it guards account deletion, where `true` means refuse,
+ * so giving it these drift semantics would make a drifted install start
+ * ALLOWING deletion of a house account. Consolidation is its own task.
+ *
+ * Never throws: an unreadable accounts dir or an unparseable account.json reads
+ * as "not house", which is the fail-closed answer for a write gate.
+ */
+function isHouseAccountDir(accountsDir, accountId) {
+    let entries;
+    try {
+        entries = (0, node_fs_1.readdirSync)(accountsDir, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name);
+    }
+    catch {
+        return false;
+    }
+    const houses = [];
+    for (const name of entries) {
+        let cfg;
+        try {
+            cfg = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(accountsDir, name, "account.json"), "utf-8"));
+        }
+        catch {
+            continue;
+        }
+        if (cfg.role === "house")
+            houses.push(name);
+    }
+    if (houses.length !== 1)
+        return false;
+    return houses[0] === accountId;
+}
+//# sourceMappingURL=index.js.map

package/payload/platform/lib/shared-folder/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAmBA,gCAEC;AAaD,oCAGC;AAWD,8CAEC;AAkBD,8CAuBC;AA3FD,8EAA8E;AAC9E,EAAE;AACF,8EAA8E;AAC9E,6EAA6E;AAC7E,gFAAgF;AAChF,EAAE;AACF,4EAA4E;AAC5E,2EAA2E;AAC3E,8EAA8E;AAC9E,wCAAwC;AACxC,qCAAoD;AACpD,yCAA0C;AAE1C;;0EAE0E;AAC7D,QAAA,eAAe,GAAG,QAAQ,CAAC;AAExC,wEAAwE;AACxE,SAAgB,UAAU,CAAC,QAAgB;IACzC,OAAO,IAAA,mBAAO,EAAC,QAAQ,EAAE,uBAAe,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,YAAY,CAAC,OAAe;IAC1C,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAChD,OAAO,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,uBAAe,CAAC;AACzD,CAAC;AAMD;;;;GAIG;AACH,SAAgB,iBAAiB,CAAC,OAAgB;IAChD,OAAO,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,yBAAyB,EAAE,CAAC;AAC3E,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,iBAAiB,CAAC,WAAmB,EAAE,SAAiB;IACtE,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,IAAA,qBAAW,EAAC,WAAW,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;aACxD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;aAC9B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,IAAI,GAAuB,CAAC;QAC5B,IAAI,CAAC;YACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAA,sBAAY,EAAC,IAAA,gBAAI,EAAC,WAAW,EAAE,IAAI,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,CAE9E,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO;YAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9C,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO,MAAM,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC;AACjC,CAAC"}

package/payload/platform/lib/shared-folder/src/index.ts

@@ -0,0 +1,92 @@
+// shared-folder — the single definition of the install-wide shared directory.
+//
+// Task 2323. Three surfaces gate on this module: the `filesystem` plugin, the
+// `/data` admin browser, and the pty-spawner's native --add-dir + deny push.
+// One definition, no drift — the same discipline as platform/lib/account-scope.
+//
+// The pure predicates never touch the filesystem, so this module is safe to
+// import into an MCP server that boots with empty env during plugin-system
+// `tools/list` enumeration. `isHouseAccountDir` DOES read disk, but only when
+// called — nothing runs at module load.
+import { readFileSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+/** The one literal. The shared root is `<dataRoot>/shared`, a sibling of
+ *  `<dataRoot>/accounts`, so it is inside DATA_ROOT (which is what lets the
+ *  /data browser reach it at all) but outside every account partition. */
+export const SHARED_DIR_NAME = "shared";
+
+/** Absolute path of the shared root. `dataRoot` is `<install>/data`. */
+export function sharedRoot(dataRoot: string): string {
+  return resolve(dataRoot, SHARED_DIR_NAME);
+}
+
+/**
+ * True when a DATA_ROOT-relative path is inside the shared root.
+ *
+ * FIRST SEGMENT ONLY. `accounts/<id>/shared` is an account's own directory that
+ * happens to be called `shared` and must keep account semantics; a deeper
+ * `shared` segment is likewise ordinary content. Callers pass the `relative`
+ * that `resolveDataPath` already produces, which is DATA_ROOT-relative.
+ *
+ * The filesystem plugin does NOT call this: its tool paths are account-relative,
+ * so it selects the shared root with an explicit `shared` flag instead.
+ */
+export function isSharedPath(relPath: string): boolean {
+  const segs = relPath.split("/").filter(Boolean);
+  return segs.length >= 1 && segs[0] === SHARED_DIR_NAME;
+}
+
+export type SharedWriteDecision =
+  | { allow: true }
+  | { reject: "shared-folder-read-only" };
+
+/**
+ * The write decision. `isHouse` is INJECTED rather than resolved here so the
+ * decision stays pure and unit-testable without a filesystem — the same reason
+ * `resolveEffectiveAccountCore` takes an injected `isValidAccountId`.
+ */
+export function decideSharedWrite(isHouse: boolean): SharedWriteDecision {
+  return isHouse ? { allow: true } : { reject: "shared-folder-read-only" };
+}
+
+/**
+ * Disk-backed house check for the two surfaces that have none: the `filesystem`
+ * plugin and the `/data` browser. Drift-safe, matching
+ * claude-session-manager/src/config.ts:464 — false when the census shows zero
+ * or more than one `role:"house"` account, because under drift there is no
+ * single house to grant write to.
+ *
+ * `platform/plugins/admin/mcp/src/tools/account-lifecycle.ts:85` is a SECOND,
+ * different definition (true for any role-house account). It is deliberately
+ * not consolidated here: it guards account deletion, where `true` means refuse,
+ * so giving it these drift semantics would make a drifted install start
+ * ALLOWING deletion of a house account. Consolidation is its own task.
+ *
+ * Never throws: an unreadable accounts dir or an unparseable account.json reads
+ * as "not house", which is the fail-closed answer for a write gate.
+ */
+export function isHouseAccountDir(accountsDir: string, accountId: string): boolean {
+  let entries: string[];
+  try {
+    entries = readdirSync(accountsDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+  } catch {
+    return false;
+  }
+  const houses: string[] = [];
+  for (const name of entries) {
+    let cfg: { role?: unknown };
+    try {
+      cfg = JSON.parse(readFileSync(join(accountsDir, name, "account.json"), "utf-8")) as {
+        role?: unknown;
+      };
+    } catch {
+      continue;
+    }
+    if (cfg.role === "house") houses.push(name);
+  }
+  if (houses.length !== 1) return false;
+  return houses[0] === accountId;
+}

package/payload/platform/lib/shared-folder/tsconfig.json

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

package/payload/platform/package.json

@@ -10,8 +10,8 @@
     "pdf-lib": "^1.17.1"
   },
   "scripts": {
-    "build": "tsc -p lib/account-schema-regions/tsconfig.json && tsc -p lib/account-ingest-token/tsconfig.json && tsc -p lib/models/tsconfig.json && tsc -p lib/agent-slug/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-lifeline/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/account-scope/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/ledger-core/tsconfig.json && tsc -p lib/embed-client/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/active-rules/tsconfig.json && tsc -p lib/admin-conversation-purge/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-style/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/admin-access-password/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p lib/aeo-llms-txt-writer/tsconfig.json && tsc -p lib/obsidian-parser/tsconfig.json && tsc -p lib/storage-broker/tsconfig.json && tsc -p lib/routine-templates/tsconfig.json && tsc -p lib/agent-dispatch-rule/tsconfig.json && tsc -p lib/learning-constants/tsconfig.json && tsc -p services/claude-session-manager/tsconfig.json && tsc -p services/whatsapp-channel/tsconfig.json && tsc -p services/webchat-channel/tsconfig.json && tsc -p services/telegram-channel/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
-    "build:lib": "tsc -p lib/account-schema-regions/tsconfig.json && tsc -p lib/account-ingest-token/tsconfig.json && tsc -p lib/models/tsconfig.json && tsc -p lib/agent-slug/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-lifeline/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/account-scope/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/ledger-core/tsconfig.json && tsc -p lib/embed-client/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/active-rules/tsconfig.json && tsc -p lib/admin-conversation-purge/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-style/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/admin-access-password/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p lib/aeo-llms-txt-writer/tsconfig.json && tsc -p lib/obsidian-parser/tsconfig.json && tsc -p lib/storage-broker/tsconfig.json && tsc -p lib/routine-templates/tsconfig.json && tsc -p lib/agent-dispatch-rule/tsconfig.json",
+    "build": "tsc -p lib/account-schema-regions/tsconfig.json && tsc -p lib/account-ingest-token/tsconfig.json && tsc -p lib/models/tsconfig.json && tsc -p lib/agent-slug/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-lifeline/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/account-scope/tsconfig.json && tsc -p lib/shared-folder/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/ledger-core/tsconfig.json && tsc -p lib/embed-client/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/active-rules/tsconfig.json && tsc -p lib/admin-conversation-purge/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-style/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/admin-access-password/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p lib/aeo-llms-txt-writer/tsconfig.json && tsc -p lib/obsidian-parser/tsconfig.json && tsc -p lib/storage-broker/tsconfig.json && tsc -p lib/routine-templates/tsconfig.json && tsc -p lib/agent-dispatch-rule/tsconfig.json && tsc -p lib/learning-constants/tsconfig.json && tsc -p services/claude-session-manager/tsconfig.json && tsc -p services/whatsapp-channel/tsconfig.json && tsc -p services/webchat-channel/tsconfig.json && tsc -p services/telegram-channel/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
+    "build:lib": "tsc -p lib/account-schema-regions/tsconfig.json && tsc -p lib/account-ingest-token/tsconfig.json && tsc -p lib/models/tsconfig.json && tsc -p lib/agent-slug/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-lifeline/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/account-scope/tsconfig.json && tsc -p lib/shared-folder/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/ledger-core/tsconfig.json && tsc -p lib/embed-client/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/active-rules/tsconfig.json && tsc -p lib/admin-conversation-purge/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-style/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/admin-access-password/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p lib/aeo-llms-txt-writer/tsconfig.json && tsc -p lib/obsidian-parser/tsconfig.json && tsc -p lib/storage-broker/tsconfig.json && tsc -p lib/routine-templates/tsconfig.json && tsc -p lib/agent-dispatch-rule/tsconfig.json && tsc -p lib/shared-folder/tsconfig.json",
     "gen:canonical-tools": "node scripts/generate-canonical-tool-names.mjs",
     "build:memory": "tsc -p plugins/memory/mcp/tsconfig.json",
     "build:contacts": "tsc -p plugins/contacts/mcp/tsconfig.json",

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

@@ -256,6 +256,7 @@ Tools are available via the `admin` MCP server.
 | Compose a business document | User asks to write or draft a proposal, report (market / analysis / strategic), brief, memo, white paper, plan (non-fundraise), or case study | `skills/professional-document/SKILL.md` |
 | Manage admin users | User asks to add, remove, or list admins on this account, or change an admin PIN | `skills/admin-user-management/SKILL.md` |
 | Session reset / continue / resume | User asks to clear the session, start fresh, continue the last session, or pick up where they left off | `skills/session-management/SKILL.md` |
+| Set up channel message handling | Owner asks to set up or change what the agent does with incoming channel messages, asks why an incoming message got no answer, or reports the agent replying to someone it should not have | `skills/channel-instruction/SKILL.md` |
 | Show or download a file | User asks to view, attach, or download a file or document, or the current turn produces a document the owner needs to review | `skills/file-presentation/SKILL.md` |
 | Upgrade Maxy | User asks to upgrade, update, install the latest version, or accepts an upgrade offer | `skills/upgrade/SKILL.md` |
 | Run a structured sprint without `gstack` | User asks to run a sprint, execute a `.tasks/NNN-*.md`, or invokes "superpowers sprint" / "sprint without gstack" | `skills/superpowers-sprint/SKILL.md` |
@@ -273,6 +274,7 @@ Tools are available via the `admin` MCP server.
 - `hooks/webfetch-preflight.mjs` — short-circuits WebFetch on JS-SPA shells with a structured `WEBFETCH_CANNOT_READ_JS_SPA` error so the agent surfaces a loud failure to the owner instead of paying the 60s extraction timeout. Fail-open on any internal error.
 - `hooks/askuserquestion-investigate-gate.sh` — PreToolUse matcher=`AskUserQuestion`. Blocks the question (exit 2) when no read-only investigation tool has fired since the latest real user turn in the session JSONL. The structural fix for the failure class where the agent fabricates a menu before evidence-gathering (session `c085ec2c-46fb-4b73-8865-68cf85866ea8` 2026-05-22 — "change remote access password" → invented options "Admin PIN / Cloudflare tunnel / WiFi password" with zero prior tool_use; post-correction the agent immediately fired `remote-auth-status` → `ToolSearch` → `remote-auth-set-password`, proving it knew the moves). **Allowlist** (exact, with trailing `__<tool>` suffix-match for namespaced `mcp__plugin_<plugin>_<server>__<tool>` aliases): `ToolSearch`, `Grep`, `Glob`, `Read`, `LS`, `NotebookRead`, `Bash`, `WebFetch`, `WebSearch`, plus the read-only admin / memory MCP tools (`*-status`, `*-list`, `*-read`, `skill-find`, `memory-find-candidates`, `profile-read`, `conversation-list`, `memory-list-attachments`, `memory-read-attachment`). **Block message:** `Blocked: AskUserQuestion requires at least one investigation tool (ToolSearch, Grep, Read, *-list, *-status, *-read, skill-find, ...) earlier in this turn. Search the operator's literal phrase first.` **Log line** (stderr, one per call): `[ask-gate] decision=<allow|block> sessionId=<id8> seen=<csv|-> reason=<allowlist-hit|no-investigation|fail-open-no-transcript|fail-open-parse-error>`. **Fail-open** on missing transcript or parse error — nudges, never bricks the UI.
 - `hooks/askuserquestion-channel-carrier-gate.sh` — PreToolUse matcher=`AskUserQuestion`, registered as a **second command on the same matcher** as the investigate-gate (either exit 2 blocks; the two guard different conditions). Blocks the question (exit 2) when the session has a native channel attached, because the Claude Code channel protocol carries only the two permission methods — there is no carrier for the `AskUserQuestion` elicitation, so on an rc-spawn channel (webchat/WhatsApp/Telegram) session the harness would block the turn awaiting a selection that can never arrive and the reader renders only delivered replies, wedging the turn (live SiteDesk incident session `1a085718` 2026-07-11: `/chat` stalled on the delivered "On it…" ack with no card). **Signal:** the rc-spawn writes the channel MCP registration as a config file in `os.tmpdir()` keyed by session id (`maxy-channel-<sid>.json` / `maxy-webchat-channel-<sid>.json` / `maxy-wa-channel-<sid>.json` / `maxy-telegram-channel-<sid>.json`, `sid` sanitized `[^A-Za-z0-9_-]→_` exactly as the writers do); its presence at tool-call time is the authoritative "channel attached to this session" marker. The hook resolves the tmpdir the way Node's `os.tmpdir()` does (`${TMPDIR:-/tmp}`, trailing slash stripped). Correct in both readings of the claude.ai/code scoping question: a Pi channel process sees the tmpfile (block); a claude.ai/code process on another host never sees the Pi tmpfile (fail-open → allow, that surface can answer the card). **Block message:** `Blocked: this is a native-channel session and AskUserQuestion cannot be delivered over a channel (the channel protocol carries no elicitation card, so the turn would wedge). Ask the same question as prose in your channel reply tool and wait for the operator's next message.` **Log line** (stderr, one per decisive call): `[ask-channel] decision=<allow|block> sessionId=<id8> channel=<attached|none> reason=<channel-attached|no-channel|fail-open-no-envelope|fail-open-no-session>`. **Fail-open** on no envelope, blank session id, or absent channel file — nudges, never bricks the UI. The complementary standing check (`interactive-wedge` in the session manager) catches any un-carried interactive tool_use that slips past this hook; it scans every account's project-slug (not just the boot slug), so a client sub-account channel wedge is covered too. **Reach on upgrade:** `provision-account-dir.sh` writes this matcher only at account-provision time, and the upgrade path re-provisions only the house account — so an account provisioned before this gate landed keeps a stale matcher and re-wedges (live SiteDesk recurrence session `d39a22b0`, account `2078cb54`, 2026-07-15). `setup-account.sh` runs `reconcile_all_accounts_askgate` (`platform/scripts/lib/account-settings-askgate.sh`) on every install to retrofit the carrier gate onto every existing account's `settings.json` — idempotent surgical jq patch of the `AskUserQuestion` matcher, one `[backfill-1683] file=<f> status=<absent|no-hooks|already-set|updated|rewrite-failed>` line per account, contents never echoed.
+- `hooks/public-tool-surface.sh` — **PreToolUse matcher-less (every tool) + UserPromptSubmit + Stop.** Records the tool surface a `role='public'` spawn REALISES, which nothing recorded before: `tool-allowlist` records the surface a spawn was given, and `[public-surface] op=audit` reconciles MCP server names from spawn-tee filenames, so it is blind to `Read`, `Bash`, `Skill` and `ToolSearch` (no MCP child, no tee file). On 2026-08-01 five such tools ran in a session spawned with `--allowed-tools mcp__whatsapp-channel__reply --strict-mcp-config --permission-mode dontAsk` and produced no line. **Input:** `MAXY_PUBLIC_ALLOWED_TOOLS`, stamped by both spawn paths (`http-server.ts` rc-spawn, `pty-spawner.ts`) for `role='public'` only, carrying that spawn's final `--allowed-tools` argv set comma-joined. Absent means not a public spawn: the hook exits 0 in silence. **Log lines** (server.log only — a visitor's PTY gains no output): `[public-surface] op=tool-realised sessionId=<id8> tool=<name> allowed=<y|n>` per call, `allowed` being exact membership of the stamped set; `[public-surface] op=realised-census sessionId=<id8> calls=<n> disallowed=<n>` at Stop, emitted including zero so a session with no disallowed call is distinguishable from one the hook never saw. Per-call tallies are appends to `<logdir>/public-surface/<sanitised-session-id>`, removed by the census, so no counter mutex is needed. The `UserPromptSubmit` registration is the turn-start reset and emits nothing: the stuck-turn recycler kills a wedged PTY and resumes the SAME session id, so that turn's `Stop` never fires and its tally would otherwise be counted into the next turn's census (measured: three calls in a killed turn plus one call in the next reported `calls=4 disallowed=3`). **Never blocks:** exit 0 on every path, including unparseable stdin, absent `session_id`, missing `python3` and an unwritable log. **Reach on upgrade:** `provision-account-dir.sh` writes both entries only at account-provision time, so `setup-account.sh` runs `reconcile_all_accounts_public_surface` (`platform/scripts/lib/account-settings-public-surface.sh`) on every install to retrofit them onto every existing account, one `[backfill-2339] file=<f> status=<absent|no-hooks|already-set|updated|rewrite-failed>` line per account, contents never echoed.
 - `hooks/mcp-tool-missing.sh` — **PostToolUse hook on `mcp__.*` (directive 3).** Defence-in-depth for the `No such tool available: mcp__…` failure class that the name-binding is built to eliminate. Fires on any MCP tool call; no-op unless the `tool_response` carries `No such tool available` AND the qualified name resolves to a maxy plugin (read from the generated `hooks/lib/maxy-mcp-plugins.txt`). On a maxy match it logs one deterministic `[mcp-tool-missing] server=<server> tool=<tool>` line and exits 2 with a fixed envelope on stderr, so the agent relays a named server-unavailable failure instead of narrating "warming up" or blind-retrying. A missing non-maxy bridge tool (Playwright etc., upstream-owned) passes through (exit 0). The maxy-plugin list is regenerated and gate-diffed by `platform/scripts/check-canonical-tool-names.mjs`.
 - `hooks/post-tool-use-agent.sh` — **PostToolUse hook on `Agent`.** Drains any subagent hook-decision buffers under `~/.maxy-code/logs/hook-decisions/` modified since this parent's previous PostToolUse-Agent fire (cursor file keyed by parent session id), prints one `[hook-propagate]` line per record to stdout — Claude Code attaches the stdout as a `hook_success` attachment on the parent JSONL, making the records grep-queryable from the parent session alone. Rotates consumed buffers to `consumed/`. Emits one `[hook-propagate-census] parentSession=<…> subagentHooksObserved=<N> attachmentsEmitted=<M>` line per fire to stdout and server.log; `N != M` is the propagation regression signal. The companion emitter library `hooks/lib/hook-emit.sh` is sourced by `post-tool-use-agent.sh` and any other hook that records a block decision (4 KB stderr truncation, `truncated=true` set on the record).
 - `hooks/admin-authoring-observer.sh` — **PostToolUse hook on Write and Edit.** Observation only — never blocks; exits 0 on every path. Fires when the admin agent (not a specialist subagent — gated by `MAXY_SPECIALIST` env) writes or edits a file under `<accountDir>/output/`. Walks the session transcript from the latest real-user turn forward to detect any prior `Task` `tool_use` whose `subagent_type` starts with `specialists:`. Emits one stderr line `[admin-authoring] inline-write path=<rel> priorSpecialistSpawnInTurn=<true|false|unknown>`. A `false` value on a long-form prose file is the regression signal this hook was designed to make visible — the BioSymm proposal session (admin authored a customer-facing proposal inline despite content-producer being installed) is the failure mode this surfaces mechanically. Mechanical enforcement (refuse the write, force a re-spawn) is deferred per the task spec.