@rubytech/create-maxy-code 0.1.581 → 0.1.583

package/payload/platform/lib/telegram-reach/src/index.ts

@@ -0,0 +1,262 @@
+/**
+ * Task 2625 — which Telegram chats a registered bot can already message.
+ *
+ * Telegram does not let a bot open a conversation: the person must message it
+ * first (core.telegram.org/bots). So "can I reach X" is answerable only from
+ * what has already arrived, and the record of that is the message store the
+ * webhook writes. Before this module nothing enumerated it, and the agent
+ * refused a send that one telegram-card call would have made.
+ *
+ * Shared rather than duplicated plugin-side, unlike the live-location and card
+ * stores: BOTH callers need this same walk — the MCP tool answers one account on
+ * demand, the hourly census counts every account — so duplicating it would mean
+ * writing the walk twice and holding it together with a boundary test. The
+ * filename rule lives here too, and `ui/app/lib/telegram/message-store.ts`
+ * re-exports it, so the store that writes a filename and the walk that reads one
+ * cannot disagree.
+ *
+ * Path-free by construction: the caller passes `storeDir`. The plugin derives it
+ * from PLATFORM_ROOT and the server from the brand config dir, and neither
+ * derivation belongs in a library that must not know what a brand is.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Is this a channel key that can safely become a path segment?
+ *
+ * Both halves of an admin key are Telegram numeric ids (a bot id is positive; a
+ * chat or sender id is an integer and is negative for groups), so requiring
+ * exactly that is both the truthful shape check and a complete traversal guard:
+ * no `.`, `/` or `\` can survive it.
+ *
+ * Task 2615 — the business shape `<botId>:biz:<senderId>` joins the guard rather
+ * than bypassing it. Both alternatives are anchored and admit only digits, an
+ * optional leading minus and the literal `biz`, so neither can carry a `.`, `/`
+ * or `\` either.
+ */
+export function isStorableChannelKey(channelKey: string): boolean {
+  return /^-?\d+:-?\d+$/.test(channelKey) || /^-?\d+:biz:-?\d+$/.test(channelKey);
+}
+
+/** Task 2615 — is this the three-part business shape?
+ *
+ *  Its own predicate rather than a `.includes(':biz:')` at each caller: a
+ *  business conversation is reached through the business-connection send route
+ *  and its 24-hour window, not by addressing a chat id, so anything that answers
+ *  "can we message this person now" has to be able to tell the two apart. */
+export function isBusinessChannelKey(channelKey: string): boolean {
+  return /^-?\d+:biz:-?\d+$/.test(channelKey);
+}
+
+/** The filename stem for a channel key.
+ *
+ *  Throws on a key that is neither two numeric ids nor the business shape.
+ *  Refusing loudly is correct here: every caller reaches this with a key it has
+ *  already validated, so an unstorable key means a caller skipped its guard, and
+ *  silently sanitising it would build a path nobody asked for. */
+export function channelKeyToFileStem(channelKey: string): string {
+  if (!isStorableChannelKey(channelKey)) {
+    throw new Error(
+      `telegram-message-store: refusing unstorable channelKey ${JSON.stringify(channelKey)}`,
+    );
+  }
+  // Task 2615 — every colon, not only the first: a business key has two.
+  return channelKey.replaceAll(":", "_");
+}
+
+/** The inverse of `channelKeyToFileStem`.
+ *
+ *  Task 2615 — a stem whose second segment is exactly `biz` is a three-part
+ *  business key. Otherwise only the FIRST `_` is a separator, because both halves
+ *  of an admin key are numeric Telegram ids and nothing later in that stem is
+ *  one. */
+export function fileStemToChannelKey(stem: string): string {
+  const i = stem.indexOf("_");
+  if (i <= 0) return stem;
+  const rest = stem.slice(i + 1);
+  if (rest.startsWith("biz_")) {
+    return `${stem.slice(0, i)}:biz:${rest.slice("biz_".length)}`;
+  }
+  return `${stem.slice(0, i)}:${rest}`;
+}
+
+/** One registered bot, as much of it as reachability needs. `adminUsers` is
+ *  present on an admin entry only; absent reads as none. */
+export interface ReachBotInput {
+  id: string;
+  role: string;
+  adminUsers?: number[];
+}
+
+export interface ReachChat {
+  /** Null for an adminUsers entry that has never messaged: there is no chat. */
+  chatId: string | null;
+  senderId: string;
+  /** From the newest inbound row. Null when that row carried no name, and null
+   *  for a sender who has never messaged. */
+  displayName: string | null;
+  /** ISO 8601 of the newest inbound row; null means never messaged. */
+  lastInbound: string | null;
+  /** This sender is an adminUsers entry on this bot. Allowlisted is a DIFFERENT
+   *  fact from having started the chat, which is why both are carried. */
+  admin: boolean;
+  /** True exactly when `lastInbound` is non-null. */
+  reachable: boolean;
+}
+
+export interface ReachBot {
+  botId: string;
+  role: string;
+  adminUsers: number[];
+  /** Reachable chats newest first, then never-messaged admins in listed order. */
+  chats: ReachChat[];
+}
+
+export interface ReachResult {
+  bots: ReachBot[];
+  /** Message rows this call actually read, across EVERY conversation file in the
+   *  directory — including files belonging to a bot the caller did not name.
+   *  That is deliberate: `chats=0` with `storeRows>0` is then the signature of a
+   *  wrong bot list or a wrong account scope, which is the failure this number
+   *  exists to expose. */
+  storeRows: number;
+}
+
+/** The fields of a store row this walk reads. Declared structurally rather than
+ *  imported from the store: importing would invert the dependency, since the
+ *  store imports the key helpers from here. */
+interface StoreRowLike {
+  kind?: unknown;
+  origin?: unknown;
+  chatId?: unknown;
+  senderId?: unknown;
+  senderName?: unknown;
+  dateSent?: unknown;
+}
+
+function parseLines(raw: string): StoreRowLike[] {
+  const out: StoreRowLike[] = [];
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      out.push(JSON.parse(line) as StoreRowLike);
+    } catch {
+      // A partial write from a crash mid-append is skipped, never fatal: one
+      // corrupt line must not hide every other chat in the account.
+    }
+  }
+  return out;
+}
+
+/** Every conversation file's newest inbound PRIVATE row, keyed
+ *  `<botId>:<senderId>`, plus the message rows read getting there. */
+function scanStore(storeDir: string): {
+  newest: Map<
+    string,
+    { chatId: string; senderId: string; senderName: string | null; dateSent: string }
+  >;
+  storeRows: number;
+} {
+  const newest = new Map<
+    string,
+    { chatId: string; senderId: string; senderName: string | null; dateSent: string }
+  >();
+  let storeRows = 0;
+  if (!storeDir || !existsSync(storeDir)) return { newest, storeRows };
+  let entries: string[];
+  try {
+    entries = readdirSync(storeDir);
+  } catch {
+    return { newest, storeRows };
+  }
+  for (const entry of entries) {
+    if (!entry.endsWith(".jsonl")) continue;
+    const stem = entry.slice(0, -".jsonl".length);
+    const channelKey = fileStemToChannelKey(stem);
+    if (!isStorableChannelKey(channelKey)) continue;
+    // Task 2615's business conversations are skipped entirely, rows included.
+    // A business chat is NOT reached by addressing a chat id: it needs the
+    // business-connection send route and its own 24-hour window, which Task 2625
+    // put out of scope. Listing one here would report it as sendable with
+    // telegram-card, which is the same wrong answer in the opposite direction to
+    // the refusal this tool exists to prevent.
+    if (isBusinessChannelKey(channelKey)) continue;
+    const botId = channelKey.slice(0, channelKey.indexOf(":"));
+    let raw: string;
+    try {
+      raw = readFileSync(join(storeDir, entry), "utf8");
+    } catch {
+      continue;
+    }
+    for (const row of parseLines(raw)) {
+      // An update row is a patch, not a message: counting it would inflate
+      // storeRows and it carries no sender at all.
+      if (row.kind === "update") continue;
+      storeRows += 1;
+      if (row.origin !== "inbound") continue;
+      const chatId = typeof row.chatId === "string" ? row.chatId : null;
+      const senderId = typeof row.senderId === "string" ? row.senderId : null;
+      const dateSent = typeof row.dateSent === "string" ? row.dateSent : null;
+      if (chatId === null || senderId === null || dateSent === null) continue;
+      // Private chats only. A DM chat id equals the sender id; a group's differs
+      // (telegram-gateway.ts:66-68). A group is not a route to a person.
+      if (chatId !== senderId) continue;
+      const key = `${botId}:${senderId}`;
+      const prev = newest.get(key);
+      if (prev !== undefined && prev.dateSent.localeCompare(dateSent) >= 0) continue;
+      newest.set(key, {
+        chatId,
+        senderId,
+        senderName: typeof row.senderName === "string" ? row.senderName : null,
+        dateSent,
+      });
+    }
+  }
+  return { newest, storeRows };
+}
+
+/** Reachability for one account: every registered bot, the private chats that
+ *  have messaged it, and the allowlisted people who have not. */
+export function collectTelegramReach(input: {
+  storeDir: string;
+  bots: ReachBotInput[];
+}): ReachResult {
+  const { newest, storeRows } = scanStore(input.storeDir);
+  const bots: ReachBot[] = input.bots.map((bot) => {
+    const adminUsers = bot.adminUsers ?? [];
+    const adminSet = new Set(adminUsers.map((u) => String(u)));
+    const chats: ReachChat[] = [];
+    const seen = new Set<string>();
+    for (const [key, row] of newest) {
+      if (key.slice(0, key.indexOf(":")) !== bot.id) continue;
+      seen.add(row.senderId);
+      chats.push({
+        chatId: row.chatId,
+        senderId: row.senderId,
+        displayName: row.senderName,
+        lastInbound: row.dateSent,
+        admin: adminSet.has(row.senderId),
+        reachable: true,
+      });
+    }
+    chats.sort((a, b) => (b.lastInbound ?? "").localeCompare(a.lastInbound ?? ""));
+    for (const user of adminUsers) {
+      const senderId = String(user);
+      if (seen.has(senderId)) continue;
+      // Listed, never messaged. Reported rather than omitted, because "we are
+      // allowed to talk to them" and "they have opened the chat" are different
+      // facts and only the second one makes a send possible.
+      chats.push({
+        chatId: null,
+        senderId,
+        displayName: null,
+        lastInbound: null,
+        admin: true,
+        reachable: false,
+      });
+    }
+    return { botId: bot.id, role: bot.role, adminUsers, chats };
+  });
+  return { bots, storeRows };
+}

package/payload/platform/lib/telegram-reach/tsconfig.json

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

package/payload/platform/lib/telegram-reach/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    globals: false,
+    include: ["src/__tests__/**/*.test.ts"],
+  },
+});

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/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/canonical-instant/tsconfig.json && tsc -p lib/dispatch-read/tsconfig.json && tsc -p lib/dispatch-write/tsconfig.json && tsc -p lib/learning-constants/tsconfig.json && tsc -p lib/telegram-media/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 && tsc -p lib/canonical-instant/tsconfig.json && tsc -p lib/dispatch-read/tsconfig.json && tsc -p lib/dispatch-write/tsconfig.json && tsc -p lib/telegram-media/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/canonical-instant/tsconfig.json && tsc -p lib/dispatch-read/tsconfig.json && tsc -p lib/dispatch-write/tsconfig.json && tsc -p lib/learning-constants/tsconfig.json && tsc -p lib/telegram-media/tsconfig.json && tsc -p lib/telegram-managed-bot/tsconfig.json && tsc -p lib/telegram-reach/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 && tsc -p lib/canonical-instant/tsconfig.json && tsc -p lib/dispatch-read/tsconfig.json && tsc -p lib/dispatch-write/tsconfig.json && tsc -p lib/telegram-media/tsconfig.json && tsc -p lib/telegram-managed-bot/tsconfig.json && tsc -p lib/telegram-reach/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

@@ -290,7 +290,7 @@ Tools are available via the `admin` MCP server.
 - `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.
 - `hooks/prompt-optimiser-directive.sh` — **UserPromptSubmit hook.** Injects the standing prompt-optimiser restatement directive plus the per-turn four-rung routing ladder as `additionalContext`: **(1)** delegate to the specialist that owns the deliverable via the Agent tool, where the brief states the outcome plus binding constraints, never lines/anchors/literal text; **(2)** only if none fits, load an admin-usable skill with `skill-load`; **(3)** only if the deliverable recurs and no specialist or skill owns it, author its owning skill via `skill-builder` (or `agent-builder` for a worker agent) and produce through it; **(4)** only if it is a genuine one-off, author inline as the named last resort. Re-emits the full agent roster (`agents/admin/AGENTS.md`) and the full admin-usable skills list (`agents/admin/ADMIN-SKILLS.md`) every turn by reading the two generated files from the account dir (the hook fires with the account dir as cwd); it never walks the plugins tree per turn. Fail-open is **visible**: a missing list logs `[prompt-optimiser] missing=<AGENTS.md\|ADMIN-SKILLS.md> emitting-partial` to stderr and the ladder still injects. The trivial-turn skip (one-word confirmation, slash-command, direct continuation) is unchanged. **Staleness:** `ADMIN-SKILLS.md` is regenerated only by `setup-account.sh`; a plugin add/remove since the last setup leaves the list stale — compare `ADMIN-SKILLS.md` mtime against the newest `SKILL.md` mtime and re-run setup to refresh. The list generator is `platform/scripts/lib/admin-skills-bootstrap.sh`; it logs `[admin-skills] scanned=<N> admin-usable=<M> no-declaration=<K>` (failure signature: `admin-usable=0` while `scanned>0`, or any `missing-declaration` line). The directive also carries a standing CAPABILITY-QUESTIONS-ARE-OWNED-WORK clause (how-to / "do you have instructions for X" / config questions about platform features are answered from the owning specialist or plugin tool/reference, never from training memory), and the hook appends a durable `<ts> [prompt-optimiser-directive] injected len=<n> session=<id>` breadcrumb to `$LOG_DIR/prompt-optimiser-directive.log` so per-turn injection is greppable, not stderr-only. The directive is also **suppressed on native channel turns** — when the parsed `.prompt` starts with the `<channel source=` event marker, the hook logs `[prompt-optimiser-directive] skipped reason=channel-turn session=<id>` to stderr and exits without injecting, because the channel service already reframes the inbound into a select-and-dispatch turn (`composeAdminContent`, see `.docs/whatsapp-inbound-lifeline.md`). Marker-matched at start-of-prompt only, so an admin/Terminal prompt that merely mentions "channel" still gets the directive; fail-open injects if the prompt cannot be parsed.
-- `hooks/preference-consult-directive.sh` — **UserPromptSubmit hook.** Injects a standing `<preference-adherence>` block naming the two-layer preference architecture (layer 1 the fixed block already in front of the agent every turn; layer 2 the account's own saved `Preference` records, read with `profile-read`, holding signature policy, header, naming and styling) and two directives: consult the relevant layer-2 preferences with `profile-read` before any customer-facing document deliverable, and store finished deliverables under `documents/` or the project folder because `output/` is scratch of last resort. Prompt-independent and always exit 0 (fail-open). Breadcrumb (stderr): `[pref-wrapper] op=inject`. This is the advisory companion to the `preference-consult-gate` hard gate.
+- `hooks/preference-consult-directive.sh` — **UserPromptSubmit hook.** Injects a standing `<preference-adherence>` block naming the two-layer preference architecture (layer 1 the fixed block already in front of the agent every turn; layer 2 the account's own saved `Preference` records, read with `profile-read`, holding signature policy, header, naming and styling) and two directives: consult the relevant layer-2 preferences with `profile-read` before any customer-facing document deliverable, and store finished deliverables under `documents/` or the project folder because `output/` is scratch of last resort. It also carries the standing filing rules: records and files kept in step unprompted, client or engagement material in that project's folder with the matching project record created in the same pass, a person's own folder under `contacts/` with the record pointing at that copy, `documents/` as account-wide reference against `uploads/` as intake and never a home, an entity folder holding its current version at the top with superseded versions moved into `archive/` beneath rather than deleted, and any create, move or rename finished in the same session with every reference repointed and named briefly in the reply. Because it is a `UserPromptSubmit` hook it reaches all four doors, which is why the filing rules are not duplicated in `IDENTITY.md` or in the four channel reframe literals. Prompt-independent and always exit 0 (fail-open). Breadcrumb, stderr **and** `$LOG_DIR/preference-consult-directive.log`: `<ts> [pref-wrapper] op=inject len=<n> session=<id>`. The log file not growing while sessions run is the failure signature, because a broken directive literal fails the heredoc silently at exit 0 and stderr alone cannot answer the question after the fact. Registration is audited by the standing reconcile as `UserPromptSubmit:preference-consult-directive.sh`. This is the advisory companion to the `preference-consult-gate` hard gate.
 - `hooks/datetime-inject.sh` — **UserPromptSubmit hook.** Injects a fresh `<datetime>` block as `additionalContext` on every turn (`refresh=per-turn`), so the agent always has the current instant — date, time, timezone, weekday, and the raw UTC ISO — without hand-computing it and without depending on Claude Code's spawn-time "Today's date" line going stale. The instant is computed fresh each turn; the timezone is **not** computed here — it is the operator's own zone, resolved from their `UserProfile.timezone` on the graph once per admin spawn and stamped into `MAXY_ACCOUNT_TZ` (see `platform/services/claude-session-manager/src/account-timezone.ts`). When `MAXY_ACCOUNT_TZ` is empty (a non-admin turn, an unset profile timezone, or a neo4j hiccup at spawn) the block falls back to the server's own zone and labels the source, so a reader can always tell which clock the agent saw. This is the current-time surface the `datetime` skill points at. **Fail-open** on every path (missing `python3` or `node`, any formatting error → exit 0, empty stdout — the turn is never blocked). The hook appends `<ts> [datetime-inject] injected tz=<zone> source=<graph|server-fallback> refresh=per-turn session=<id>` to `$LOG_DIR/datetime-inject.log` so "did the agent have the right time this turn, and from which clock?" is answerable from logs without reproduction.
 - `hooks/mailbox-inject.sh` — **UserPromptSubmit hook.** Injects a `<mailboxes>` block as `additionalContext` on every turn (`refresh=per-turn`), naming every Outlook mailbox attached to this account and the plugin that holds it, so a session never learns attachment state by polling one mail plugin and reading that plugin's miss as an account-wide fact (the incident it exists for: a WhatsApp session called `email-status`, got the IMAP plugin's miss, and told a customer the account had no access to a mailbox the outlook plugin had read that morning). Reads `$ACCOUNT_DIR/secrets/outlook/` directly as a **read-only observer** — it never writes there, and never performs the rename `MailboxRegistry.migrateLegacy()` does. Signed-in mailboxes come from `mailboxes/<key>/tokens.enc` plus the pre-migration top-level `tokens.enc`, keeping only directories that actually contain a blob (the registry's own gate — the revocation path unlinks the blob and leaves the directory). Delegated mailboxes come from the plaintext `delegated.json`, keyed by normalised address so two keys differing only in case or space collapse to one line exactly as `DelegatedStore.read()` collapses them, with the delegator resolved against the **readable** set exactly as `MailboxRegistry.resolve()` does, so a delegated line never promises a mailbox every `outlook-*` call would refuse. A legacy blob whose `graphUserId` already has a `mailboxes/` directory is skipped rather than listed twice, mirroring the branch of `migrateLegacy()` that unlinks it. Every rendered subject is stripped of control characters and angle brackets and length-bounded, so the block's frame holds by construction rather than by the upstream invariants that currently keep them out. Three fields leave the decrypt — `mail`, `graphUserId`, `refreshTokenExpiry` — and **no token value is ever emitted, logged or written**; the `node` reader carries `2>/dev/null` and try/catches every read and parse, because node prints the entire parsed source text on an uncaught exception. **Fail-open** on every path. **Env asymmetry:** `ACCOUNT_DIR` is stamped unconditionally on the rc-spawn path (`buildRcChildEnv`) but only for admin and specialist spawns on the pty-spawner path, and `LOG_DIR` exists on the rc path only — so the hook resolves the account dir from `$PWD` when the stamp is absent (the spawn cwd is the account dir on both paths) and walks `$LOG_DIR` → `$CLAUDE_SESSION_MANAGER_PERSIST_DIR/logs` → `<accountDir>/logs` for its breadcrumb. **Reach on upgrade:** the provision-time writer re-runs for the house account only, so `reconcile_all_accounts_settings` converges every account against `platform/templates/account-settings.json` — which carries this `UserPromptSubmit` entry — from `setup-account.sh` on every install, one `[settings-reconcile] account=<id> status=…` line per account. (The four per-hook backfill libs this converge replaced have been retired.) The breadcrumb is `<ts> [mailbox-inject] injected account=<id> outlook=<n> delegated=<n> usable=<n> expired=<n> unreadable=<n> degraded=<yes|no> imap=not-read source=disk refresh=per-turn session=<id>` in `<logDir>/mailbox-inject.log`, with `op=skip reason=<no-account-dir|unreadable-source|reader-failed>` and `op=degrade reason=delegated-unreadable` on the degraded paths. `imap=not-read`, never `imap=0`: IMAP mailboxes are not surveyed at all by this hook, and a literal zero in a field shaped like the two measured counts would be read in a later incident review as a census. No address is written to the log, because `/api/admin/logs` serves every account's log dir to any LAN caller without auth. A missing `node` or `python3` exits 0 before the breadcrumb block, so a PATH regression produces **no line at all** rather than a `reason=no-node` line.
 - `hooks/prompt-optimiser-compliance.sh` — **Stop hook.** After each admin turn, reads the just-finished turn from `transcript_path` and appends `<ts> [prompt-optimiser-compliance] directive-fired no-route-taken session=<id8> prompt="<clip>"` to `$LOG_DIR/prompt-optimiser-directive.log` (and stderr) when the routing directive fired, the prompt was non-trivial (not a slash-command, not a one-word confirmation), and the turn took **no route** — no `Agent` dispatch, no `Skill` load, no `ToolSearch`, no `mcp__*` tool call. This is the standing compliance signal that surfaces the session-`da0b12d4` failure class (agent answers a capability question from memory) as a visible event instead of a silent stale answer. Directive-fired is detected by the marker `PROMPT-OPTIMISER DIRECTIVE` in the turn slice, so it is robust to the CC-version difference in how `UserPromptSubmit` `additionalContext` is recorded (`attachment`/`hook_success` vs `hook_additional_context`). **Known limitation:** "direct continuation of the prior turn" is not detectable from the transcript, so a continuation turn that legitimately needs no route can be flagged; treat the log as a review signal, not a gate. **Fail-open:** no python3, no `transcript_path`, or an unreadable transcript → exit 0, no output. Lives in the same log as the directive breadcrumb, so a single `grep` interleaves "fired" and "no-route" into one per-session timeline; cross-check via `platform/scripts/logs-read.sh <sessionKey>`. This is a lightweight transcript read, not a per-turn spawn (contrast the turn recorder below).

package/payload/platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh

@@ -19,6 +19,9 @@
 #  15. Write into a sibling dir with no account.json       -> ALLOW (not an account)
 #  16. Symlink under this account resolving into a sibling -> BLOCK cross-account
 #  17. MultiEdit reaches every fence and the refusal ledger -> BLOCK / record
+#  18. Write to projects/acme/archive/x.pdf (one archive)  -> ALLOW
+#  19. Write to contacts/jane-doe/archive/x.pdf            -> ALLOW
+#  20. Write to projects/acme/archive/old/x.pdf (deeper)   -> BLOCK over-deep
 set -u
 
 HOOK="$(cd "$(dirname "$0")/.." && pwd)/fs-schema-guard.sh"
@@ -107,6 +110,12 @@ run_case "loose document allow"  "$(mkenv Write file_path 'documents/a.pdf')"
 run_case "tool-owned deep allow" "$(mkenv Write file_path 'output/deep/nested/x.png')"         0 ""
 run_case "over-deep block"       "$(mkenv Write file_path 'projects/acme/deploy/sources/a.txt')" 2 "fs-guard. blocked path=projects/acme/deploy/sources/a.txt reason=over-deep"
 run_case "over-deep one block"   "$(mkenv Write file_path 'projects/acme/deploy/a.txt')"       2 "reason=over-deep"
+# archive/ is the ONE permitted child of an entity folder: it holds superseded
+# versions, which is what the per-turn filing directive tells the agent to do.
+# Any other name at depth 4, and anything at depth 5, is still refused.
+run_case "archive project allow" "$(mkenv Write file_path 'projects/acme/archive/quote-v1.pdf')"   0 ""
+run_case "archive contact allow" "$(mkenv Write file_path 'contacts/jane-doe/archive/profile.pdf')" 0 ""
+run_case "archive nested block"  "$(mkenv Write file_path 'projects/acme/archive/old/quote.pdf')"  2 "reason=over-deep"
 run_case "top-level block"       "$(mkenv Write file_path 'whim/x.txt')"                       2 "fs-guard. blocked path=whim/x.txt reason=top-level"
 run_case "outside acct allow"    "$(mkenv Write file_path '/etc/passwd')"                      0 ""
 run_case "notebook over-deep"    "$(mkenv NotebookEdit notebook_path 'projects/acme/deploy/n.ipynb')" 2 "reason=over-deep"

package/payload/platform/plugins/admin/hooks/__tests__/preference-consult-directive.test.sh

@@ -16,6 +16,32 @@ check '! printf "%s" "$OUT" | grep -q "—"' "no em-dash"
 OUT_PUB=$(printf '{"session_id":"x","prompt":"hi"}' | MAXY_PUBLIC_ALLOWED_TOOLS='mcp__channel__reply' bash "$HOOK" 2>/dev/null); RC_PUB=$?
 check '[ "$RC_PUB" = "0" ]' "public turn exits 0"
 check '[ -z "$OUT_PUB" ]' "public turn emits nothing on stdout"
+
+# The six filing clauses. The hook is the only surface that reaches all four
+# doors, so a clause dropped here is a clause no admin turn carries.
+check 'printf "%s" "$OUT" | grep -q "in step"'           "clause a: records and files in step"
+check 'printf "%s" "$OUT" | grep -q "project.s folder"'  "clause b: engagement material in the project folder"
+check 'printf "%s" "$OUT" | grep -q "contacts/"'         "clause c: a person gets a contacts folder"
+check 'printf "%s" "$OUT" | grep -q "intake tray"'       "clause d: uploads is intake, never a home"
+check 'printf "%s" "$OUT" | grep -q "archive/"'          "clause e: superseded versions move to archive"
+check 'printf "%s" "$OUT" | grep -q "indistinguishable"' "clause f: finish and name the move"
+check 'printf "%s" "$OUT" | python3 -c "import json,sys; json.load(sys.stdin)"' "valid JSON envelope"
+
+# Durable breadcrumb: the stderr line alone cannot answer "did the directive fire
+# on this turn" after the fact, and a broken literal fails the heredoc silently at
+# exit 0. The log file not growing while sessions run is that failure's signature.
+LOGD=$(mktemp -d)
+printf '{"session_id":"sess-abc","prompt":"hi"}' | LOG_DIR="$LOGD" bash "$HOOK" >/dev/null 2>&1
+check '[ -s "$LOGD/preference-consult-directive.log" ]'                     "breadcrumb file written"
+check 'grep -q "op=inject len=" "$LOGD/preference-consult-directive.log"'   "breadcrumb carries len"
+check 'grep -q "session=sess-abc" "$LOGD/preference-consult-directive.log"' "breadcrumb carries session"
+rm -rf "$LOGD"
+
+# An unwritable LOG_DIR never blocks the turn.
+OUT_RO=$(printf '{"session_id":"x","prompt":"hi"}' | LOG_DIR=/nonexistent-dir-2620 bash "$HOOK" 2>/dev/null); RC_RO=$?
+check '[ "$RC_RO" = "0" ]'                                   "unwritable LOG_DIR still exits 0"
+check 'printf "%s" "$OUT_RO" | grep -q "hookSpecificOutput"' "unwritable LOG_DIR still injects"
+
 echo "----- $PASS passed, $FAIL failed -----"
 for f in "${FAILED[@]:-}"; do [ -n "$f" ] && echo "  $f"; done
 [ "$FAIL" -eq 0 ]

package/payload/platform/plugins/admin/hooks/fs-schema-guard.sh

@@ -16,8 +16,13 @@
 #     though that name is in the allowed set: the allowed set is a layout list,
 #     and a declared file is written whole by its owning plugin;
 #   - a target under an operator-data bucket (projects/ contacts/) may be at
-#     most <bucket>/<entity>/<file> deep; documents/ may be at most
+#     most <bucket>/<entity>/<file> deep, with one exception:
+#     <bucket>/<entity>/archive/<file>, which holds superseded versions and is
+#     the ONLY permitted child of an entity folder; documents/ may be at most
 #     <bucket>/<folder>/<file> deep. Tool-owned dirs pass at any depth.
+#     The same five rules run on the file-write/file-edit MCP route, in
+#     plugins/filesystem/mcp/src/lib/account-schema.ts — an MCP tool name matches
+#     none of the four matchers below, so that route needs its own copy.
 #
 # The hook governs this account's dir, and refuses any target inside a SIBLING
 # account under the same accounts root (reason=cross-account) for every session,
@@ -202,9 +207,21 @@ depth=$(printf '%s' "$REL" | awk -F/ '{print NF}')
 case "$SEG0" in
   projects|contacts)
     # Allowed: <bucket>/<entity>/<file> = 3 segments max; <bucket>/<file> = 2 ok.
-    if [ "$depth" -gt 3 ]; then
+    # One exception: <bucket>/<entity>/archive/<file> = 4 segments. An entity
+    # folder holds its current version at the top and its superseded versions in
+    # archive/ beneath, which is the standing filing rule the per-turn directive
+    # states and SCHEMA.md's version rule now points at. It is the ONLY permitted
+    # child of an entity folder: any other name at depth 4, and anything at depth
+    # 5, still has no basis in the graph ontology and is refused. `archive`
+    # already satisfies the folder name rule below, so that check needs no
+    # exception of its own.
+    ARCHIVE_OK=0
+    if [ "$depth" -eq 4 ] && [ "$(printf '%s' "$REL" | cut -d/ -f3)" = "archive" ]; then
+      ARCHIVE_OK=1
+    fi
+    if [ "$depth" -gt 3 ] && [ "$ARCHIVE_OK" -eq 0 ]; then
       echo "[fs-guard] blocked path=$REL reason=over-deep" >&2
-      echo "Blocked: $SEG0/ is flat — one folder per entity, then files. '$REL' nests a subtree under an entity folder, which has no basis in the graph ontology. Keep files directly under $SEG0/<name>/, or route a reorganisation through the data-manager specialist." >&2
+      echo "Blocked: $SEG0/ is flat: one folder per entity, then files, with archive/ the one permitted subfolder for superseded versions. '$REL' nests a subtree that has no basis in the graph ontology. Keep files directly under $SEG0/<name>/ or in $SEG0/<name>/archive/, or route a reorganisation through the data-manager specialist." >&2
       exit 2
     fi
     ;;

package/payload/platform/plugins/admin/hooks/preference-consult-directive.sh

@@ -1,8 +1,15 @@
 #!/usr/bin/env bash
 # preference-consult-directive — UserPromptSubmit hook. Injects a standing line
-# naming the two-layer preference architecture and two adherence directives:
-# consult layer-2 preferences (profile-read) before any customer document, and
-# promote finished deliverables out of output/. Prompt-independent; fail-open.
+# naming the two-layer preference architecture, two adherence directives (consult
+# layer-2 preferences with profile-read before any customer document, and promote
+# finished deliverables out of output/), and the standing filing rules: records
+# and files kept in step, engagement material in its project folder with the
+# matching record, a person's own folder under contacts/, documents/ as lasting
+# reference against uploads/ as intake, a superseded version moved into archive/
+# rather than deleted, and any move finished and named in the same session.
+# Because this is a UserPromptSubmit hook it reaches all four doors, which is why
+# the filing rules live here and not in IDENTITY.md or the channel reframe
+# literals. Prompt-independent; fail-open.
 set -uo pipefail
 HOOK_INPUT=$(cat 2>/dev/null || true)
 # Task 2424 — a public visitor's turn carries only its agent's authored
@@ -15,7 +22,10 @@ if [ -n "${MAXY_PUBLIC_ALLOWED_TOOLS:-}" ]; then
 fi
 echo "[public-prompt-gate] op=gate hook=preference-consult-directive.sh public=0" >&2
 command -v python3 >/dev/null 2>&1 || exit 0
-python3 - <<'PY' 2>/dev/null || exit 0
+# The envelope is captured rather than printed straight through, so its
+# additionalContext can be measured for the breadcrumb below. Nothing else about
+# the emission changed: the same JSON reaches stdout, unmodified.
+ENVELOPE=$(python3 - <<'PY' 2>/dev/null || true
 import json
 ctx = (
 "<preference-adherence>\n"
@@ -26,9 +36,44 @@ ctx = (
 "attachment), read the relevant layer-2 preferences with profile-read and apply them. "
 "Store finished deliverables under documents/ or the project folder. output/ is scratch of last resort, "
 "rebuilt on the next tool write, and never the home a graph reference points at.\n"
+"Keep the account's records and its files in step, and keep both tidy, without being asked. "
+"Client or engagement material goes in that project's folder, and the matching project record is created in the same pass. "
+"A person gets a folder under contacts/ named after them, and the record points at that copy. "
+"documents/ is account-wide reference that outlives an engagement; uploads/ is an intake tray and never a home. "
+"An entity folder holds the current version at its top level, and a superseded version moves into archive/ beneath it rather than being deleted. "
+"Finish any create, move or rename in the same session, filed and with every reference repointed, and name it briefly in your reply, because doing it silently is indistinguishable from not doing it.\n"
 "</preference-adherence>"
 )
 print(json.dumps({"hookSpecificOutput": {"hookEventName": "UserPromptSubmit", "additionalContext": ctx}}))
 PY
-echo "[pref-wrapper] op=inject" >&2
+)
+# A broken literal makes the heredoc fail with no stdout. Exit 0 in silence, as
+# before: the hook never blocks a turn. The absence of a breadcrumb line while
+# sessions run is what makes that state visible, which is the whole reason the
+# log below exists.
+[ -z "$ENVELOPE" ] && exit 0
+printf '%s\n' "$ENVELOPE"
+
+CTXLEN=$(printf '%s' "$ENVELOPE" | python3 -c 'import json,sys
+try:
+    print(len(json.load(sys.stdin)["hookSpecificOutput"]["additionalContext"]))
+except Exception:
+    print(0)' 2>/dev/null || echo 0)
+SID=$(printf '%s' "$HOOK_INPUT" | python3 -c 'import json,sys
+try:
+    print(json.load(sys.stdin).get("session_id","") or "")
+except Exception:
+    print("")' 2>/dev/null)
+SID=${SID:-?}
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# Durable breadcrumb. stderr alone cannot answer "did the directive fire on this
+# turn" after the fact, which is the gap prompt-optimiser-directive.sh closed with
+# its own log file. Best-effort: an unwritable path never blocks the turn.
+if [ -n "${LOG_DIR:-}" ] && [ -d "$LOG_DIR" ]; then
+  printf '%s [pref-wrapper] op=inject len=%s session=%s\n' "$TS" "$CTXLEN" "$SID" \
+    >> "$LOG_DIR/preference-consult-directive.log" 2>/dev/null || true
+fi
+
+echo "[pref-wrapper] op=inject len=$CTXLEN session=$SID" >&2
 exit 0