@rubytech/create-maxy-code 0.1.182 → 0.1.183

package/payload/platform/lib/graph-search/src/__tests__/vector-index-coverage.test.ts

@@ -0,0 +1,198 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Doctrine test — pins the per-identity-label vector-index coverage
+ * invariant so future identity labels added to schema-base.md cannot
+ * silently drift into BM25-only semantic ranking (Task 483).
+ *
+ * Pre-Task-483 the :Organization label carried `embedding` from the
+ * ingest writer but no vector index, so hybrid() fell through to
+ * BM25-only for Organization-only queries (Task 478 made the
+ * fallback honest). Without a coverage gate, the next analogous gap
+ * — a new identity label written with embeddings but no index —
+ * would silently degrade the same way.
+ *
+ * Doctrine: every identity label declared in schema-base.md's
+ * `## Node Types` table is either (a) covered by a
+ * `CREATE VECTOR INDEX … FOR (n:<Label>) ON (n.embedding)` declaration
+ * in schema.cypher, or (b) explicitly listed in
+ * `BM25_ONLY_IDENTITY_LABELS` below with a one-line rationale. A new
+ * identity label that satisfies neither condition fails this test
+ * and points the author at the decision they have to make.
+ */
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCHEMA_CYPHER_PATH = resolve(__dirname, "../../../../neo4j/schema.cypher");
+const SCHEMA_BASE_PATH = resolve(
+  __dirname,
+  "../../../../plugins/memory/references/schema-base.md",
+);
+
+/**
+ * Identity labels documented in schema-base.md that legitimately rank
+ * via BM25 only — no vector index is declared, and none is intended.
+ *
+ * The rationale per label is the doctrinal record: it answers the
+ * question a future reader will ask ("why doesn't <Label> get
+ * semantic ranking?") without forcing them to re-derive it from
+ * scratch. Removing a label from this set without adding the
+ * corresponding `CREATE VECTOR INDEX` (or vice versa) fails the
+ * test below.
+ */
+const BM25_ONLY_IDENTITY_LABELS: ReadonlyMap<string, string> = new Map([
+  // Structured business records — looked up by deterministic key
+  // (orderNumber / confirmationNumber / address), not by semantic
+  // similarity. No `body`-like free-text writer.
+  ["Order", "structured business record; deterministic key lookup"],
+  ["Invoice", "structured business record; deterministic key lookup"],
+  ["PostalAddress", "structured fields only; no free-text writer"],
+  ["OpeningHoursSpecification", "structured fields only"],
+  // Identity nodes accessed via composite key, never semantic search.
+  ["UserProfile", "always queried by (accountId, userId)"],
+  ["AccessGrant", "always queried by (contactValue, agentSlug, accountId) or magicToken"],
+  // CDM-only labels — declared in schema-base for vertical extension
+  // hooks; no writer in the current platform.
+  ["Lead", "CDM-only declaration; no platform writer"],
+  ["Case", "CDM-only declaration; no platform writer"],
+  // Catalogue / branding nodes — small fixed populations, accessed by
+  // accountId + purpose / name, not by semantic similarity.
+  ["FAQPage", "container node; child :Question nodes carry semantic content"],
+  ["ImageObject", "binary asset; alt-text not currently indexed"],
+  // Legacy / retired writers (kept for read compatibility).
+  ["CloudflareTunnel", "legacy projection (Task 288); writer retired"],
+  ["CloudflareHostname", "legacy projection (Task 288); writer retired"],
+  ["WhatsAppConversation", "legacy; superseded by :ConversationArchive (Task 397)"],
+  ["WhatsAppMessage", "legacy; superseded by :ConversationArchive (Task 397)"],
+  // Authored-content history — looked up by accountId + datePublished
+  // / runAt; semantic search lives on the parent or downstream report.
+  ["SocialPost", "authored-content record; lookup by accountId + datePublished"],
+  ["AEOAudit", "audit-history record; lookup by accountId + runAt"],
+  // Voice-mirror records — keyed by (accountId, adminUserId).
+  ["VoiceProfile", "always queried by (accountId, adminUserId)"],
+  ["VoiceEdit", "always queried by parent VoiceProfile"],
+]);
+
+interface VectorIndexDeclaration {
+  name: string;
+  label: string;
+}
+
+/**
+ * Extract every `CREATE VECTOR INDEX <name> IF NOT EXISTS FOR (<alias>:<Label>) ON (<alias>.embedding)`
+ * declaration from schema.cypher. The alias and label vary across
+ * declarations (`p:Person`, `b:LocalBusiness`, `o:Organization` …),
+ * so the regex captures both and we keep only the label.
+ *
+ * Line comments are stripped first so a commented-out historical
+ * declaration cannot inject a phantom label.
+ */
+function parseVectorIndexes(cypher: string): VectorIndexDeclaration[] {
+  const stripped = cypher.replace(/^\s*\/\/.*$/gm, "");
+  const decls: VectorIndexDeclaration[] = [];
+  const re = /CREATE\s+VECTOR\s+INDEX\s+(\w+)\s+IF\s+NOT\s+EXISTS\s+FOR\s+\(\w+:(\w+)\)/g;
+  for (const m of stripped.matchAll(re)) {
+    decls.push({ name: m[1], label: m[2] });
+  }
+  return decls;
+}
+
+/**
+ * Extract every documented identity label from schema-base.md's
+ * `## Node Types` table — column 2 of each table row, stripped of
+ * backticks and any trailing `{property:'value'}` qualifier.
+ *
+ * Parser scope: the first markdown table that appears under
+ * `## Node Types`. Stops at the first non-table line (blank line or
+ * a paragraph), so explanatory prose under the table cannot leak
+ * pseudo-labels.
+ */
+function parseIdentityLabels(md: string): Set<string> {
+  const heading = md.indexOf("## Node Types");
+  if (heading < 0) {
+    throw new Error(
+      "parseIdentityLabels: could not find '## Node Types' heading in schema-base.md. " +
+        "Schema-base layout drifted; update the doctrine test.",
+    );
+  }
+  const after = md.slice(heading);
+  const lines = after.split("\n");
+  const labels = new Set<string>();
+  let inTable = false;
+  for (const line of lines) {
+    if (line.startsWith("|")) {
+      // Header row + separator row both contain `|`; skip them.
+      if (line.includes("Entity") && line.includes("Neo4j Label")) {
+        inTable = true;
+        continue;
+      }
+      if (/^\|\s*-+/.test(line)) continue;
+      if (!inTable) continue;
+      const cols = line.split("|").map((c) => c.trim());
+      // `| Entity | Neo4j Label | ... |` → cols = ["", "Entity", "Neo4j Label", ..., ""]
+      const labelCell = cols[2];
+      if (!labelCell) continue;
+      // Strip backticks and trailing `{...}` property qualifier.
+      const cleaned = labelCell.replace(/`/g, "").replace(/\s*\{.*\}\s*$/, "").trim();
+      // Defensive: only accept PascalCase identifiers. Anything else
+      // (multi-label decoration, prose, etc.) is skipped — the test's
+      // job is to gate identity-label coverage, not to police table
+      // formatting.
+      if (/^[A-Z][A-Za-z0-9]*$/.test(cleaned)) labels.add(cleaned);
+    } else if (inTable && line.trim().length === 0) {
+      // Blank line ends the table.
+      break;
+    }
+  }
+  return labels;
+}
+
+describe("vector-index coverage — every identity label is vector-indexed or explicitly BM25-only (Task 483)", () => {
+  const cypher = readFileSync(SCHEMA_CYPHER_PATH, "utf-8");
+  const schemaBase = readFileSync(SCHEMA_BASE_PATH, "utf-8");
+
+  const declarations = parseVectorIndexes(cypher);
+  const vectorIndexed = new Set(declarations.map((d) => d.label));
+  const identityLabels = parseIdentityLabels(schemaBase);
+
+  it("parsers extracted non-trivial sets — sanity floor", () => {
+    expect(declarations.length).toBeGreaterThanOrEqual(15);
+    expect(identityLabels.size).toBeGreaterThanOrEqual(20);
+  });
+
+  it("every identity label in schema-base.md is either vector-indexed or in BM25_ONLY_IDENTITY_LABELS", () => {
+    const uncovered: string[] = [];
+    for (const label of identityLabels) {
+      if (vectorIndexed.has(label)) continue;
+      if (BM25_ONLY_IDENTITY_LABELS.has(label)) continue;
+      uncovered.push(label);
+    }
+    // Failure here means a new identity label was added to schema-base.md
+    // without either declaring a vector index in schema.cypher or adding
+    // it to BM25_ONLY_IDENTITY_LABELS with a one-line rationale. Pick
+    // one — the silent gap is the failure mode.
+    expect(uncovered).toEqual([]);
+  });
+
+  it("BM25_ONLY_IDENTITY_LABELS does not overlap with vector-indexed labels", () => {
+    const overlap: string[] = [];
+    for (const label of BM25_ONLY_IDENTITY_LABELS.keys()) {
+      if (vectorIndexed.has(label)) overlap.push(label);
+    }
+    // A label cannot legitimately appear in both sets: the allowlist
+    // documents the *absence* of a vector index. If the index was
+    // added later, remove the label from the allowlist.
+    expect(overlap).toEqual([]);
+  });
+
+  it(":Organization carries a vector index (Task 483 acceptance)", () => {
+    // Pin the load-bearing assertion of this task explicitly so a
+    // regression that re-removed the declaration would fail with a
+    // pointed message rather than as a generic coverage gap.
+    expect(vectorIndexed.has("Organization")).toBe(true);
+    const orgDecl = declarations.find((d) => d.label === "Organization");
+    expect(orgDecl?.name).toBe("organization_embedding");
+  });
+});

package/payload/platform/lib/graph-search/src/index.ts

@@ -203,6 +203,48 @@ export interface Bm25OnlyParams {
    * guard); admin route enforces non-empty `labels` as a precondition.
    */
   labels?: string[];
+  /**
+   * Task 485 — per-visitor slice ringfence. When set, the scope filter
+   * widens from `(scope IS NULL OR scope IN $allowedScopes)` to
+   * `(sliceToken = $sliceToken OR scope IS NULL OR scope IN $allowedScopes)`
+   * so a gated public-agent read sees its visitor's user-scoped nodes in
+   * addition to public-scope rows. Skipped on every admin and open-mode
+   * public call; the env var `ACCESS_SLICE_TOKEN` populates it on the
+   * memory MCP server side.
+   */
+  sliceToken?: string;
+}
+
+/**
+ * Build the scope-and-slice WHERE fragment + params. Centralises the three
+ * cypher composition sites (bm25, vector, prop) so the gated/non-gated
+ * behaviour does not drift between them. Returns empty strings when no
+ * filter applies.
+ */
+function buildScopeAndSliceClause(
+  allowedScopes: readonly string[] | undefined,
+  sliceToken: string | undefined,
+  alias: string = "node",
+): { clause: string; params: Record<string, unknown> } {
+  const hasSlice = typeof sliceToken === "string" && sliceToken.length > 0;
+  const hasScopes = Array.isArray(allowedScopes) && allowedScopes.length > 0;
+  if (!hasSlice && !hasScopes) return { clause: "", params: {} };
+  if (hasSlice && hasScopes) {
+    return {
+      clause: `AND (${alias}.sliceToken = $sliceToken OR ${alias}.scope IS NULL OR ${alias}.scope IN $allowedScopes)`,
+      params: { sliceToken, allowedScopes },
+    };
+  }
+  if (hasSlice) {
+    return {
+      clause: `AND (${alias}.sliceToken = $sliceToken OR ${alias}.scope IS NULL)`,
+      params: { sliceToken },
+    };
+  }
+  return {
+    clause: `AND (${alias}.scope IS NULL OR ${alias}.scope IN $allowedScopes)`,
+    params: { allowedScopes },
+  };
 }
 
 export interface HybridParams extends Bm25OnlyParams {
@@ -388,10 +430,9 @@ export async function bm25Only(
   session: Session,
   params: Bm25OnlyParams,
 ): Promise<SearchHit[]> {
-  const { query, accountId, limit, allowedScopes, agentSlug, keywords, keywordMatch, labels } = params;
-  const scopeClause = allowedScopes
-    ? "AND (node.scope IS NULL OR node.scope IN $allowedScopes)"
-    : "";
+  const { query, accountId, limit, allowedScopes, agentSlug, keywords, keywordMatch, labels, sliceToken } = params;
+  const scope = buildScopeAndSliceClause(allowedScopes, sliceToken);
+  const scopeClause = scope.clause;
   const agentClause = agentSlug
     ? "AND node.agents IS NOT NULL AND $agentSlug IN node.agents"
     : "";
@@ -420,7 +461,7 @@ export async function bm25Only(
         query: escaped,
         accountId,
         limit: int(limit),
-        ...(allowedScopes ? { allowedScopes } : {}),
+        ...scope.params,
         ...(agentSlug ? { agentSlug } : {}),
         ...(labels && labels.length > 0 ? { labels } : {}),
         ...(keywordFilter?.params ?? {}),
@@ -486,6 +527,7 @@ export async function hybrid(
     accountId,
     limit,
     allowedScopes,
+    sliceToken,
     keywords,
     keywordMatch = "any",
     agentSlug,
@@ -579,31 +621,35 @@ export async function hybrid(
   const labelToIndex = await discoverIndexes(session);
 
   // --- Resolve vector indexes from the effective label set ---
+  //
+  // Task 478: when `effectiveLabels` is set but none resolve to a vector index
+  // (e.g. `labels:["Organization"]` — universal BM25 covers it, no vector
+  // index declared), proceed with `indexesToQuery=[]`. The vector loop below
+  // runs zero iterations and the BM25 half still runs with the label filter,
+  // so search returns rows whose existence the rest of the platform asserts.
+  // Pre-fix this branch returned an empty result, hiding ingest-created
+  // Organization rows that BM25 would have found — the deadlock recorded in
+  // .tasks/archive/478-*.md. The labels-without-vector list is emitted as an
+  // observability line so a future analogous gap stays visible.
   let indexesToQuery: string[];
   if (effectiveLabels && effectiveLabels.length > 0) {
     indexesToQuery = effectiveLabels
       .map((l) => labelToIndex.get(l))
       .filter((idx): idx is string => idx !== undefined);
     if (indexesToQuery.length === 0) {
-      return {
-        mode: useRrf ? "rrf" : "hybrid",
-        results: [],
-        expandMs: 0,
-        rawMerged: 0,
-        suppressed: 0,
-        bm25Bypass: 0,
-        threshold: params.vectorThreshold ?? null,
-        stageCounts: emptyStageCounts,
-      };
+      const missing = effectiveLabels.filter((l) => !labelToIndex.has(l));
+      process.stderr.write(
+        `[graph-search] labels-without-vector-index=${missing.join(",")} ` +
+          `accountId=${(accountId ?? "").slice(0, 8)} — falling through to BM25-only for these labels\n`,
+      );
     }
   } else {
     indexesToQuery = [...new Set(labelToIndex.values())];
   }
 
-  const scopeClause = allowedScopes
-    ? "AND (node.scope IS NULL OR node.scope IN $allowedScopes)"
-    : "";
-  const scopeParams = allowedScopes ? { allowedScopes } : {};
+  const hybridScope = buildScopeAndSliceClause(allowedScopes, sliceToken);
+  const scopeClause = hybridScope.clause;
+  const scopeParams = hybridScope.params;
   const agentClause = agentSlug
     ? "AND node.agents IS NOT NULL AND $agentSlug IN node.agents"
     : "";
@@ -752,6 +798,7 @@ export async function hybrid(
         accountId,
         limit,
         allowedScopes,
+        sliceToken,
       });
       if (kwHits.length === 0) continue;
       const rawScores = kwHits.map((h) => h.score);
@@ -761,23 +808,21 @@ export async function hybrid(
       }
     }
 
-    const propScopeClause = allowedScopes
-      ? "AND (node.scope IS NULL OR node.scope IN $allowedScopes)"
-      : "";
+    const propScope = buildScopeAndSliceClause(allowedScopes, sliceToken);
     const propResult = await session.run(
       `MATCH (node)
        WHERE node.accountId = $accountId
        AND ${notTrashed("node")}
        AND node.keywords IS NOT NULL
        AND ANY(kw IN $kwSubs WHERE ANY(nk IN node.keywords WHERE toLower(nk) = kw))
-       ${propScopeClause}
+       ${propScope.clause}
        RETURN node, labels(node) AS nodeLabels, elementId(node) AS nodeId
        LIMIT $limit`,
       {
         accountId,
         kwSubs: keywordSubscriptions,
         limit: int(limit),
-        ...(allowedScopes ? { allowedScopes } : {}),
+        ...propScope.params,
       },
     );
     for (const record of propResult.records) {
@@ -808,6 +853,7 @@ export async function hybrid(
         accountId,
         limit,
         allowedScopes,
+        sliceToken,
       });
       if (kwHits.length === 0) continue;
       const rawScores = kwHits.map((h) => h.score);
@@ -817,23 +863,21 @@ export async function hybrid(
       }
     }
 
-    const propScopeClause = allowedScopes
-      ? "AND (node.scope IS NULL OR node.scope IN $allowedScopes)"
-      : "";
+    const propScope = buildScopeAndSliceClause(allowedScopes, sliceToken);
     const propResult = await session.run(
       `MATCH (node)
        WHERE node.accountId = $accountId
        AND ${notTrashed("node")}
        AND node.keywords IS NOT NULL
        AND ANY(kw IN $kwSubs WHERE ANY(nk IN node.keywords WHERE toLower(nk) = kw))
-       ${propScopeClause}
+       ${propScope.clause}
        RETURN node, labels(node) AS nodeLabels, elementId(node) AS nodeId
        LIMIT $limit`,
       {
         accountId,
         kwSubs: keywordSubscriptions,
         limit: int(limit),
-        ...(allowedScopes ? { allowedScopes } : {}),
+        ...propScope.params,
       },
     );
     for (const record of propResult.records) {

package/payload/platform/neo4j/schema.cypher

@@ -135,6 +135,24 @@ OPTIONS {
   }
 };
 
+// :Organization carries `embedding` from the ingest writer
+// (memory-ingest.ts writeRelatedNode). Pre-Task-483 no vector index
+// existed, so hybrid() fell through to BM25-only for Organization-only
+// queries (Task 478 made that fallback honest). The index restores
+// semantic-similarity ranking parity with the other identity labels —
+// a query like "the company that does antimicrobial coatings" surfaces
+// BioSymm via cosine similarity rather than relying on literal BM25
+// token matching. Neo4j populates the index against existing rows on
+// CREATE; no manual reindex required.
+CREATE VECTOR INDEX organization_embedding IF NOT EXISTS
+FOR (o:Organization) ON (o.embedding)
+OPTIONS {
+  indexConfig: {
+    `vector.dimensions`: 768,
+    `vector.similarity_function`: 'cosine'
+  }
+};
+
 CREATE VECTOR INDEX price_embedding IF NOT EXISTS
 FOR (p:PriceSpecification) ON (p.embedding)
 OPTIONS {
@@ -878,6 +896,24 @@ FOR (ag:AccessGrant) ON (ag.magicToken);
 CREATE INDEX access_grant_status IF NOT EXISTS
 FOR (ag:AccessGrant) ON (ag.status);
 
+// Slice token (Task 485) — per-visitor ringfence key for gated public agents.
+// Indexed on AccessGrant for revoke-eviction lookups and on every label that
+// the session-end reviewer writes through (via database-operator), so
+// memory-search can filter `n.sliceToken = $sliceToken OR n.scope = "public"`
+// without a label scan. New labels added to the reviewer's surface gain a
+// twin index here.
+CREATE INDEX access_grant_slice_token IF NOT EXISTS
+FOR (ag:AccessGrant) ON (ag.sliceToken);
+
+CREATE INDEX person_slice_token IF NOT EXISTS
+FOR (n:Person) ON (n.sliceToken);
+
+CREATE INDEX preference_slice_token IF NOT EXISTS
+FOR (n:Preference) ON (n.sliceToken);
+
+CREATE INDEX idea_slice_token IF NOT EXISTS
+FOR (n:Idea) ON (n.sliceToken);
+
 // ----------------------------------------------------------
 // Agent node — projection of file-based public agents
 //

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

@@ -126,6 +126,7 @@ Tools are available via the `admin` MCP server.
 | Manage plugins and settings | User asks to install, enable, disable, or configure plugins, or change account settings | `skills/plugin-management/SKILL.md` |
 | Manage specialists | User asks to install or remove a specialist subagent, or activate/deactivate premium plugin agents | `skills/specialist-management/SKILL.md` |
 | Generate print-quality PDF | User asks to create a PDF document, one-pager, brochure, or any HTML intended for print/download | `skills/a4-print-documents/SKILL.md` |
+| 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` |
 | Plain-English explanation | User asks to explain, define, or pre-empts ("explain in plain English", "what does X mean", "define X", "I don't understand", "what is this"), or admin is about to return a reply containing a term not in the operator's prior turn | `skills/plainly/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` |
@@ -139,6 +140,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/session-end-retrospective.sh` — **Stop hook.** Fires on every assistant end_turn but exits 0 with `trigger-skipped reason=<role-not-admin|is-specialist|empty-stdin|missing-transcript|no-intent-match>` on every path EXCEPT when the operator's latest real-user message carries an end-intent token (`/end`, `/archive`, `end session`, `archive this session`, case-insensitive, must match the whole message or a standalone line — not embedded in prose). On that path the hook blocks (exit 2 + structured retrospective instruction on stderr per Stop-hook contract) and emits `[session-retrospective] gate-blocked sessionId=<id> reason=sentinel-absent` until the admin agent calls the `session-retrospective-mark-complete` MCP sentinel tool. Completion is recognised by greping the operator's own JSONL (`transcript_path` on the Stop envelope) for a `tool_use` block whose `name` equals that exact string — never by parsing prose ([[feedback_no_stdout_parsing_for_control_flow]], [[feedback_doctrine_paragraph_is_not_a_gate]]). The sentinel-grep doubles as the re-entry guard: every Stop after the sentinel call sees it and exits 0 with `gate-released sessionId=<id>`. Recursion guard: any session whose `MAXY_SPECIALIST` env is set (specialist subagent dispatched via Task tool) skips the gate. The Sidebar archive button POSTs `/:sessionId/archive` directly to the manager which kills the PTY — no Stop fires after that, so clicking archive is the operator's current escape hatch (opt-out remains deferred per the task spec). All emits go through `POST /api/admin/log-ingest`; the only stderr writer is the gate-blocked path (the instruction block the agent reads). The retrospective itself runs as one or more additional turns inside the operator's existing admin session — Task-tool delegation to `database-operator` is the existing IDENTITY.md "Recording" route, not a parallel admin session ([[feedback_deterministic_means_remove_llm]]).
+- `hooks/admin-authoring-observer.sh` — **PostToolUse hook on Write and Edit (Task 486).** 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 Task 486 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/turn-completed-graph-write.sh` — **Dormant since Task 214** — the Stop-hook registration is no longer written to account settings.json; admin delegates graph writes to `database-operator` via the Task tool. The script, envelope walker, loopback `/api/admin/claude-sessions` 127.0.0.1 bypass, `[turn-recorder]` emitters, recorder-auto-archive subscriber, and `initialMessage` envelope spec are preserved as reusable infrastructure for any future autonomous post-turn flow. Historical contract (still describes the dormant path): Stop hook fired once per completed admin-agent turn. Gates on `MAXY_SESSION_ROLE=admin` + `MAXY_SPECIALIST!=database-operator` so it never recurses into the recorder PTY or fires on public sessions. **Task 147** — the recorder is spawned via the same route Sidebar uses. ONE POST to `POST /api/admin/claude-sessions`, body carries `{specialist:'database-operator', model:'haiku', initialMessage:<json-envelope>, adminSessionId:<op>}` — no synthetic `senderId: 'turn-recorder'` marker. The Hono wrapper bypasses cookie auth on this exact method+path when the request originates from `127.0.0.1` (same trust boundary the claude-session-manager itself relies on), looks up the operator's senderId from the manager's `/<adminSessionId>/meta`, and forwards a Sidebar-shape spawn body. The `/recorder-spawn` sibling route is gone. The hook reads its UI port from `MAXY_UI_INTERNAL_PORT` (stamped on the manager systemd unit) — no fallback; absence emits `[turn-recorder] spawn-failed reason=missing-env env=MAXY_UI_INTERNAL_PORT` to stderr instead of silently 19199-ing. **Task 177** — `initialMessage` is a JSON-stringified envelope; the schema lives in [`platform/plugins/docs/references/admin-session.md`](../docs/references/admin-session.md) under "`initialMessage` JSON envelope (Task 177)". Top-level keys exactly: `turns`, `sessionId`, `accountId`, `occurredAt`. `turns` is the full conversation transcript, oldest first, newest last, with each entry `{ role: "user"|"assistant", text, ts, toolCalls? }`. No windowing, no truncation. Multi-record assistant messages collapse on `message.id`. `tool_use` and matching `tool_result` blocks attach as a single `toolCalls` entry on the owning assistant turn; the user record carrying only the `tool_result` does not create a separate user turn. No leading instruction prose. `toolCalls[].input` and `toolCalls[].output` are native JSON values, never re-stringified. (Replaces Task 175's `(operatorMessage, assistantReply)` pair, which asserted a temporal Q→A relationship the walker never enforced.) One observability line `[turn-recorder] envelope sessionId=<op> turnsCount=<n> userTurns=<n> assistantTurns=<n> toolCallTurns=<n>` precedes `spawn-request`. The envelope rides on the `/spawn` body as a trailing positional argv to `claude`, so the database-operator session's JSONL first `role=user` line is the JSON object verbatim. No separate `POST /:id/input` call, no bracketed-paste, no keystroke injection. The recorder-auto-archive subscriber stops the recorder PTY as soon as its JSONL contains an assistant message with `stop_reason === "end_turn"`. **Task 129** — every emit goes through `POST /api/admin/log-ingest` so the lines land in `server.log` keyed by the operator session id. The chain is `trigger` → `spawn-request` → `spawn-success` → `input-delivered` → `tool-call` × N → `tool-result` × N → `write-complete` → `auto-archive`; each gated-off path emits one `trigger-skipped reason=<role-not-admin|is-recorder|empty-stdin|missing-transcript|conversation-empty>` line. Failure modes — `spawn-failed`, `tool-surface-missing`, `input-failed`, `write-empty`, `auto-archive reason=stale-recorder` — each emit one named line; absence is itself a defect.
 
 ## Session identifiers (Task 135)

package/payload/platform/plugins/admin/hooks/admin-authoring-observer.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+# Admin-authoring observer (Task 486).
+#
+# Observation-only PostToolUse hook. When the admin agent (not a specialist
+# subagent) writes or edits a file under <accountDir>/output/, emit one
+# stderr line capturing whether a specialist was dispatched earlier in the
+# current turn. A `priorSpecialistSpawnInTurn=false` value on a long-form
+# prose file is the regression signal Task 486 was designed to make visible
+# without relying on operator complaint — it surfaces the same failure mode
+# the BioSymm proposal session exhibited (admin authored a customer-facing
+# proposal inline despite content-producer being installed).
+#
+# This hook never blocks. Exit code is always 0.
+#
+# Output line shape (on stderr, no stdout):
+#   [admin-authoring] inline-write path=<rel> priorSpecialistSpawnInTurn=<true|false|unknown>
+
+set -uo pipefail
+
+# Empty stdin (terminal invocation) — silent no-op for safety in tests.
+if [ -t 0 ]; then
+  exit 0
+fi
+INPUT=$(cat)
+
+# Only PostToolUse on Write or Edit is observed.
+HOOK_EVENT=$(printf '%s' "$INPUT" | python3 -c '
+import sys, json
+try:
+    print(json.load(sys.stdin).get("hook_event_name", "") or "")
+except Exception:
+    print("")
+' 2>/dev/null)
+TOOL_NAME=$(printf '%s' "$INPUT" | python3 -c '
+import sys, json
+try:
+    print(json.load(sys.stdin).get("tool_name", "") or "")
+except Exception:
+    print("")
+' 2>/dev/null)
+if [ "$HOOK_EVENT" != "PostToolUse" ]; then
+  exit 0
+fi
+if [ "$TOOL_NAME" != "Write" ] && [ "$TOOL_NAME" != "Edit" ]; then
+  exit 0
+fi
+
+# Subagent writes are out of scope. pty-spawner stamps MAXY_SPECIALIST on
+# every specialist process; only the admin process sees it empty.
+if [ -n "${MAXY_SPECIALIST:-}" ]; then
+  exit 0
+fi
+
+FILE_PATH=$(printf '%s' "$INPUT" | python3 -c '
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    print((d.get("tool_input", {}) or {}).get("file_path", "") or "")
+except Exception:
+    print("")
+' 2>/dev/null)
+[ -z "$FILE_PATH" ] && exit 0
+
+# Resolve to absolute. The hook fires in the account dir (PWD), which is the
+# claude project root (each account has its own .git).
+case "$FILE_PATH" in
+  /*) ABS="$FILE_PATH" ;;
+  *)  ABS="$PWD/$FILE_PATH" ;;
+esac
+
+# Only files under <accountDir>/output/ are in scope.
+case "$ABS" in
+  "$PWD/output/"*) REL="${ABS#$PWD/}" ;;
+  *) exit 0 ;;
+esac
+
+TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | python3 -c '
+import sys, json
+try:
+    print(json.load(sys.stdin).get("transcript_path", "") or "")
+except Exception:
+    print("")
+' 2>/dev/null)
+# Test override so the .test.sh suite can pin a fixture transcript.
+if [ -n "${ADMIN_AUTHORING_TRANSCRIPT_PATH:-}" ]; then
+  TRANSCRIPT_PATH="$ADMIN_AUTHORING_TRANSCRIPT_PATH"
+fi
+
+if [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+  echo "[admin-authoring] inline-write path=${REL} priorSpecialistSpawnInTurn=unknown" >&2
+  exit 0
+fi
+
+# Walk the transcript: from the latest real-user turn forward, find any
+# assistant `tool_use` whose `name == "Task"` and whose
+# `input.subagent_type` starts with `specialists:`.
+PRIOR=$(TRANSCRIPT_PATH="$TRANSCRIPT_PATH" python3 - <<'PY'
+import os, json, sys
+
+path = os.environ["TRANSCRIPT_PATH"]
+records = []
+try:
+    with open(path, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                records.append(json.loads(line))
+except Exception:
+    print("unknown"); sys.exit(0)
+
+def is_real_user(d):
+    if d.get("type") != "user":
+        return False
+    msg = d.get("message", {}) or {}
+    if msg.get("role") != "user":
+        return False
+    content = msg.get("content")
+    if isinstance(content, str):
+        return True
+    if isinstance(content, list):
+        for b in content:
+            if isinstance(b, dict) and b.get("type") != "tool_result":
+                return True
+        return False
+    return True
+
+last_user = -1
+for i in range(len(records) - 1, -1, -1):
+    if is_real_user(records[i]):
+        last_user = i
+        break
+
+for d in records[last_user + 1:]:
+    if d.get("type") != "assistant":
+        continue
+    msg = d.get("message", {}) or {}
+    if msg.get("role") != "assistant":
+        continue
+    for b in (msg.get("content") or []):
+        if not isinstance(b, dict):
+            continue
+        if b.get("type") != "tool_use":
+            continue
+        if b.get("name") != "Task":
+            continue
+        sub = (b.get("input") or {}).get("subagent_type")
+        if isinstance(sub, str) and sub.startswith("specialists:"):
+            print("true"); sys.exit(0)
+
+print("false")
+PY
+)
+
+echo "[admin-authoring] inline-write path=${REL} priorSpecialistSpawnInTurn=${PRIOR}" >&2
+exit 0

package/payload/platform/plugins/admin/skills/access-manager/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: access-manager
-description: "Manage per-agent access grants — invite visitors by email or phone, list who has access, revoke or extend access, resend invitations, and set agent access modes (open, gated, paid)."
+description: "Manage per-agent access grants for gated public agents — invite visitors by email, list who has access, revoke or extend access, resend invitations, and set agent access modes (open, gated)."
 ---
 
 # Access Manager
 
-Applies when the business owner wants to control who can access a gated or paid public agent.
+Applies when the business owner wants to control who can access a gated public agent.
 
 ## When to Activate
 
-- Admin asks to invite someone to a gated agent (by email or phone number)
+- Admin asks to invite someone to a gated agent (always by email)
 - Admin asks who has access, or to list access grants for an agent
 - Admin asks to revoke or extend someone's access
-- Admin asks to set an agent's access mode (open, gated, paid)
+- Admin asks to set an agent's access mode (open or gated)
 - Admin asks to resend an invitation
 
 ## Constraints
@@ -20,7 +20,9 @@ Applies when the business owner wants to control who can access a gated or paid
 - **Admin-scope only.** Every AccessGrant node lands with `scope: "admin"`. Credential data must never be visible to public agents — the recorder enforces the scope tag on its write turn.
 - **Agent must exist.** Before any grant operation, verify the target agent directory exists under `agents/` and read its `config.json`.
 - **Confirm before mutating.** Present a `confirm` component before grants are created, access is revoked, or access modes change. The recorder writes off the confirmed transcript.
-- **Domain required for email invitations.** Resolve the public hostname via `tunnel-status`. Without a confirmed hostname, magic link URLs cannot be constructed.
+- **Domain required.** Resolve the public hostname via `tunnel-status`. Without a confirmed hostname, magic link URLs cannot be constructed.
+- **`sliceToken` is immutable.** Stamped at create as a UUIDv4; revoke / extend / resend never mutate it. The same visitor across multiple invitations has the same person record but distinct sliceTokens per grant.
+- **Revoke evicts active sessions.** After the cypher revoke succeeds, POST loopback `/api/admin/access-session-evict?grantId=<elementId>` so any in-flight `__access_session` cookie for that grant is dropped from the UI server's session map.
 - **Deterministic grant queries.** AccessGrant nodes are not vector-indexed. Query them via `cypher-shell` (password at `~/.maxy/.neo4j-password`), not via `memory-search`.
 
 ## Operations