@rubytech/create-maxy-code 0.1.331 → 0.1.333

package/payload/platform/lib/mcp-spawn-tee/src/__tests__/spawn-tee.test.ts

@@ -1,22 +1,20 @@
 import { afterEach, beforeAll, describe, expect, it } from 'vitest'
 import { execFileSync, spawn, spawnSync } from 'node:child_process'
-import {
-  existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync,
-} from 'node:fs'
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const here = dirname(fileURLToPath(import.meta.url))
 const libRoot = resolve(here, '..', '..')                 // platform/lib/mcp-spawn-tee
-const wrapper = join(libRoot, 'dist', 'index.js')
+const shim = join(libRoot, 'dist', 'index.js')
 const tsc = resolve(libRoot, '..', '..', 'node_modules', '.bin', 'tsc')
 
-// Build the real artifact once; tests then exercise the shipped wrapper, not a
+// Build the real artifact once; tests exercise the shipped shim, not a
 // re-implementation — that is what catches stdio-wiring regressions.
 beforeAll(() => {
   execFileSync(tsc, ['-p', 'tsconfig.json'], { cwd: libRoot, stdio: 'inherit' })
-  expect(existsSync(wrapper)).toBe(true)
+  expect(existsSync(shim)).toBe(true)
 })
 
 let tmp = ''
@@ -24,13 +22,13 @@ afterEach(() => { if (tmp) { rmSync(tmp, { recursive: true, force: true }); tmp
 
 function makeStub(body: string): { stub: string; logDir: string } {
   tmp = mkdtempSync(join(tmpdir(), 'spawn-tee-'))
-  const stub = join(tmp, 'stub-child.js')
+  const stub = join(tmp, 'stub-entry.js')
   writeFileSync(stub, body, 'utf8')
   return { stub, logDir: join(tmp, 'logs') }
 }
 
 function runSync(stub: string, env: Record<string, string>) {
-  return spawnSync(process.execPath, [wrapper, stub], {
+  return spawnSync(process.execPath, [shim, stub], {
     env: { ...process.env, SESSION_ID: '', PLATFORM_PORT: '', ...env },
     encoding: 'utf8',
   })
@@ -40,21 +38,28 @@ function sessionLog(logDir: string, server: string, sessionId: string): string {
   return readFileSync(join(logDir, `mcp-${server}-${sessionId}.log`), 'utf8')
 }
 
-describe('mcp-spawn-tee wrapper', () => {
-  it('captures child stderr to a per-session file and emits one op=exit on clean exit', () => {
-    const { stub, logDir } = makeStub('process.stderr.write("hello-from-child\\n"); process.exit(0)')
+describe('mcp-spawn-tee in-process shim', () => {
+  it('runs the entry in the shim process — one node runtime, not two', () => {
+    const { stub, logDir } = makeStub('process.stdout.write(String(process.pid)); process.exit(0)')
+    const r = runSync(stub, { LOG_DIR: logDir, SESSION_ID: 'pid1', MCP_SPAWN_TEE_NAME: 'stub' })
+    // The entry's process.pid equals the spawned shim's pid: same process.
+    expect(r.stdout).toBe(String(r.pid))
+  })
+
+  it('tees entry stderr to a per-session file and emits one op=exit on clean exit', () => {
+    const { stub, logDir } = makeStub('process.stderr.write("hello-from-entry\\n"); process.exit(0)')
     runSync(stub, { LOG_DIR: logDir, SESSION_ID: 'abcd1234-session', MCP_SPAWN_TEE_NAME: 'stub' })
     const log = sessionLog(logDir, 'stub', 'abcd1234-session')
-    expect(log).toContain('hello-from-child')
+    expect(log).toContain('hello-from-entry')
     const exits = log.split('\n').filter((l) => l.includes('op=exit'))
     expect(exits).toHaveLength(1)
     expect(exits[0]).toContain('code=0')
     expect(exits[0]).toMatch(/lifetimeMs=\d+/)
     expect(exits[0]).toContain('stderr-tail=')
-    expect(exits[0]).toContain('hello-from-child')
+    expect(exits[0]).toContain('hello-from-entry')
   })
 
-  it('emits op=spawn at start and op=boot on first child stderr', () => {
+  it('emits op=spawn at start and op=boot on first entry stderr', () => {
     const { stub, logDir } = makeStub('process.stderr.write("[stub] boot line\\n"); process.exit(0)')
     runSync(stub, { LOG_DIR: logDir, SESSION_ID: 'sess-0001', MCP_SPAWN_TEE_NAME: 'stub' })
     const log = sessionLog(logDir, 'stub', 'sess-0001')
@@ -72,9 +77,9 @@ describe('mcp-spawn-tee wrapper', () => {
     expect(exit).toContain('signal=—')
   })
 
-  it('op=exit carries the signal name when the child is killed', async () => {
+  it('op=exit carries the signal name when terminated by a catchable signal', async () => {
     const { stub, logDir } = makeStub('process.stderr.write("alive\\n"); setInterval(() => {}, 1000)')
-    const cp = spawn(process.execPath, [wrapper, stub], {
+    const cp = spawn(process.execPath, [shim, stub], {
       env: { ...process.env, SESSION_ID: 'sig1', PLATFORM_PORT: '', LOG_DIR: logDir, MCP_SPAWN_TEE_NAME: 'stub' },
     })
     await new Promise((res) => setTimeout(res, 500))
@@ -82,12 +87,44 @@ describe('mcp-spawn-tee wrapper', () => {
     const exitCode = await new Promise<number | null>((res) => cp.on('exit', (code) => res(code)))
     const exit = sessionLog(logDir, 'stub', 'sig1').split('\n').find((l) => l.includes('op=exit'))!
     expect(exit).toContain('signal=SIGTERM')
-    // The wrapper propagates a signal kill as 128+signum (SIGTERM=15 → 143),
-    // not a flat 128 — otherwise the signal identity is lost in the exit status.
+    // The shim propagates a catchable-signal kill as 128+signum (SIGTERM=15 → 143).
     expect(exitCode).toBe(143)
   })
 
-  it('passes child stdout through untouched (MCP transport intact)', () => {
+  it('defers to an entry-owned signal handler: a graceful exit reads code=0 signal=—, not a signal death', async () => {
+    // The entry installs its own SIGINT handler that exits cleanly — as the real
+    // MCP entries do (closeDriver then process.exit(0)). The shim must NOT stamp
+    // signal=SIGINT on that clean exit; it defers and the entry's exit wins.
+    const { stub, logDir } = makeStub(
+      'process.on("SIGINT", () => { process.stderr.write("graceful\\n"); process.exit(0) }); ' +
+      'process.stderr.write("ready\\n"); setInterval(() => {}, 1000)',
+    )
+    const cp = spawn(process.execPath, [shim, stub], {
+      env: { ...process.env, SESSION_ID: 'sigint-own', PLATFORM_PORT: '', LOG_DIR: logDir, MCP_SPAWN_TEE_NAME: 'stub' },
+    })
+    await new Promise((res) => setTimeout(res, 500))
+    cp.kill('SIGINT')
+    const exitCode = await new Promise<number | null>((res) => cp.on('exit', (code) => res(code)))
+    const exit = sessionLog(logDir, 'stub', 'sigint-own').split('\n').find((l) => l.includes('op=exit'))!
+    expect(exit).toContain('code=0')
+    expect(exit).toContain('signal=—')
+    expect(exitCode).toBe(0)
+  })
+
+  it('leaves stderr on disk but writes no op=exit when SIGKILLed (accepted gap)', async () => {
+    const { stub, logDir } = makeStub('process.stderr.write("pre-kill stderr\\n"); setInterval(() => {}, 1000)')
+    const cp = spawn(process.execPath, [shim, stub], {
+      env: { ...process.env, SESSION_ID: 'kill1', PLATFORM_PORT: '', LOG_DIR: logDir, MCP_SPAWN_TEE_NAME: 'stub' },
+    })
+    await new Promise((res) => setTimeout(res, 500))
+    cp.kill('SIGKILL')
+    await new Promise<void>((res) => cp.on('exit', () => res()))
+    const log = sessionLog(logDir, 'stub', 'kill1')
+    expect(log).toContain('pre-kill stderr')
+    expect(log).not.toContain('op=exit')
+  })
+
+  it('passes entry stdout through untouched (MCP transport intact)', () => {
     const { stub, logDir } = makeStub('process.stdout.write("JSONRPC-PAYLOAD"); process.exit(0)')
     const r = runSync(stub, { LOG_DIR: logDir, SESSION_ID: 'out1', MCP_SPAWN_TEE_NAME: 'stub' })
     expect(r.stdout).toBe('JSONRPC-PAYLOAD')

package/payload/platform/lib/mcp-spawn-tee/src/index.ts

@@ -1,46 +1,46 @@
 #!/usr/bin/env node
 /**
- * MCP spawn-tee — parent-side stderr capture + lifecycle observability.
+ * MCP spawn-tee — in-process stderr capture + lifecycle observability.
  *
  * Claude Code spawns each MCP server itself; the platform never holds a
- * ChildProcess handle. This wrapper sits between Claude Code and the real
- * MCP server: Claude Code runs `node <this> <real-entry>`, and the wrapper
- * spawns the real entry with `stdio:['inherit','inherit','pipe']` so stdin
- * and stdout (the JSON-RPC channel) pass through byte-identical. Only stderr
- * is intercepted, and only for logging.
+ * ChildProcess handle. This shim sits between Claude Code and the real MCP
+ * server: Claude Code runs `node <this> <real-entry>`, and the shim runs the
+ * real entry IN ITS OWN PROCESS via dynamic import() — one node runtime, not
+ * two. Before importing, it replaces process.stderr.write with a tee so every
+ * stderr byte the server writes is mirrored to the log sinks; stdin and stdout
+ * (the JSON-RPC channel) are never touched.
  *
- * Because the wrapper IS the helper's parent, it observes the helper's true
- * exit code, signal, and lifetime for every death mode — including a SIGKILL
- * or a transport-layer crash that an in-process handler would miss.
+ *   Claude Code CLI → shim (this file) = node running <real-entry> in-process
+ *        stdin/stdout : untouched (JSON-RPC channel)
+ *        stderr       : process.stderr.write teed → per-date + per-session + passthrough
  *
- *   Claude Code CLI → wrapper (this file) → child = node <real-entry>
- *        child stdin/stdout : inherited (Claude Code pipe, untouched)
- *        child stderr       : piped → per-date log + per-session log + passthrough
- *
- * Destinations (Task 706):
+ * Destinations (Task 706) — unchanged:
  *   - `${LOG_DIR}/mcp-<name>-stderr-<date>.log`  — per-date raw (back-compat;
  *     the in-process mcp-stderr-tee and the [mcp-init-error] probe read it).
  *   - `${LOG_DIR}/mcp-<name>-<SESSION_ID>.log`   — per-session raw + lifecycle
- *     lines; wrapper-only, so it never mixes the enumeration copy with the
- *     live copy. Authoritative sink. Absent when SESSION_ID is unset
- *     (enumeration spawn) — then the per-date file is the fallback.
+ *     lines. Authoritative sink. Absent when SESSION_ID is unset (enumeration
+ *     spawn) — then the per-date file is the fallback.
  *   - `server.log` via the loopback log-ingest route — best-effort mirror of
- *     the [mcp-helper] lifecycle lines. A dropped POST loses nothing because
- *     the per-session file already holds the line (written synchronously).
+ *     the [mcp-helper] lifecycle lines.
  *
- * Lifecycle lines, correlation key `session=<id8> server=<name>`:
+ * Lifecycle lines, correlation key `session=<id8> server=<name>` — unchanged:
  *   [mcp-helper] op=spawn ... pid= entry=
  *   [mcp-helper] op=boot  ... head=<first stderr bytes>
- *   [mcp-helper] op=exit  ... code= signal= lifetimeMs= stderr-tail=   (always)
+ *   [mcp-helper] op=exit  ... code= signal= lifetimeMs= stderr-tail=
+ *
+ * Process model (Task 989): the shim IS the server's process. op=exit fires
+ * from process.on("exit"), so it covers a normal exit, a non-zero exit, an
+ * uncaught throw (code 1), and a catchable-signal exit (SIGTERM/SIGINT/SIGHUP,
+ * whose handlers record the signal name). An external SIGKILL is uncatchable
+ * and leaves no op=exit line — the per-session stderr tail already on disk and
+ * Claude Code's own transport-drop are the evidence for that death mode.
  *
- * The wrapper never writes to fd 1 (stdout) — that is the JSON-RPC channel.
- * SIGTERM/SIGINT are forwarded to the child so a Claude Code shutdown does
- * not orphan it; the child exit code/signal is propagated verbatim.
+ * The shim never writes to fd 1 (stdout) — that is the JSON-RPC channel.
  */
 
-import { spawn } from "node:child_process";
 import { appendFileSync, mkdirSync } from "node:fs";
 import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 
 const SERVER_NAME = process.env.MCP_SPAWN_TEE_NAME ?? "unknown";
 const LOG_DIR = process.env.LOG_DIR;
@@ -51,8 +51,8 @@ const ENTRY = process.argv[2];
 const SESSION_ID8 = SESSION_ID ? SESSION_ID.slice(0, 8) : "—";
 const spawnStamp = Date.now();
 
-// Per-session raw + lifecycle log (Task 706). Wrapper-only. Empty SESSION_ID
-// (enumeration spawn) → undefined, and the per-date file is the fallback.
+// Per-session raw + lifecycle log (Task 706). Empty SESSION_ID (enumeration
+// spawn) → undefined, and the per-date file is the fallback.
 const perSessionPath = LOG_DIR && SESSION_ID
   ? resolve(LOG_DIR, `mcp-${SERVER_NAME}-${SESSION_ID}.log`)
   : undefined;
@@ -60,16 +60,28 @@ const perDatePath = LOG_DIR
   ? resolve(LOG_DIR, `mcp-${SERVER_NAME}-stderr-${new Date(spawnStamp).toISOString().slice(0, 10)}.log`)
   : undefined;
 
-// Rolling tail of child stderr for op=exit. Capped so a chatty child cannot
+// Rolling tail of entry stderr for op=exit. Capped so a chatty server cannot
 // grow the buffer without bound.
 const TAIL_CAP = 2048;
 let stderrTail = "";
 let bootEmitted = false;
+let exitEmitted = false;
+let exitSignal: NodeJS.Signals | undefined;
+
+// The real stderr writer, captured before the tee replaces it. Lifecycle lines
+// and stderr passthrough both go through this so they are never re-teed into
+// the per-date sink nor recursed back into the patched writer.
+const rawStderrWrite = process.stderr.write.bind(process.stderr);
+
+// LOG_DIR is created once, lazily, on the first successful append — not per
+// chunk. teeWrite runs on the server's own stderr hot path now, so a per-call
+// mkdirSync would be two syscalls per log line for nothing.
+let logDirReady = false;
 
 function appendSafe(path: string | undefined, data: string | Uint8Array): void {
   if (!path || !LOG_DIR) return;
   try {
-    mkdirSync(LOG_DIR, { recursive: true });
+    if (!logDirReady) { mkdirSync(LOG_DIR, { recursive: true }); logDirReady = true; }
     appendFileSync(path, data);
   } catch {
     /* unwritable destination — never mask primary output */
@@ -77,14 +89,15 @@ function appendSafe(path: string | undefined, data: string | Uint8Array): void {
 }
 
 // Best-effort mirror of a lifecycle line to server.log via the loopback
-// log-ingest route. Fire-and-forget: the per-session file is authoritative,
-// so a dropped POST (unreachable port, process exiting) loses nothing.
+// log-ingest route. Fire-and-forget: the per-session file is authoritative, so
+// a dropped POST loses nothing. On the "exit" event the loop is stopping, so
+// the op=exit mirror may not flush — the per-session line, written sync, holds.
 function postToServerLog(suffix: string, level: "info" | "error"): void {
   if (!PLATFORM_PORT) return;
   try {
     const ctrl = new AbortController();
     const t = setTimeout(() => ctrl.abort(), 500);
-    t.unref?.(); // never let the abort timer keep the wrapper's event loop alive
+    t.unref?.(); // never let the abort timer keep the shim's event loop alive
     void fetch(`http://127.0.0.1:${PLATFORM_PORT}/api/admin/log-ingest`, {
       method: "POST",
       headers: { "content-type": "application/json" },
@@ -97,13 +110,14 @@ function postToServerLog(suffix: string, level: "info" | "error"): void {
 }
 
 // Emit one [mcp-helper] lifecycle line: authoritative per-session file (sync,
-// survives process.exit), the wrapper's own stderr (journald / Claude Code
-// visibility), and a best-effort server.log mirror. `suffix` is the line body
-// after the tag and carries no newline (the log-ingest route rejects newlines).
+// survives process.exit), the shim's own stderr via the RAW writer (journald /
+// Claude Code visibility, never re-teed), and a best-effort server.log mirror.
+// `suffix` is the line body after the tag and carries no newline (the
+// log-ingest route rejects newlines).
 function emitLifecycle(suffix: string, level: "info" | "error"): void {
   const line = `[mcp-helper] ${suffix}\n`;
   appendSafe(perSessionPath, line);
-  try { process.stderr.write(line); } catch { /* stderr closed */ }
+  try { rawStderrWrite(line); } catch { /* stderr closed */ }
   postToServerLog(suffix, level);
 }
 
@@ -112,52 +126,73 @@ if (!ENTRY) {
   process.exit(2);
 }
 
-const child = spawn(process.execPath, [ENTRY], {
-  stdio: ["inherit", "inherit", "pipe"],
-  env: process.env,
-});
-
-emitLifecycle(`op=spawn session=${SESSION_ID8} server=${SERVER_NAME} pid=${child.pid ?? -1} entry=${ENTRY}`, "info");
-
-child.on("error", (err) => {
-  const msg = err instanceof Error ? err.message : String(err);
-  emitLifecycle(`op=error session=${SESSION_ID8} server=${SERVER_NAME} reason=${JSON.stringify(`spawn error: ${msg}`)}`, "error");
-  process.exit(127);
-});
-
-if (child.stderr) {
-  child.stderr.on("data", (chunk: Buffer) => {
-    appendSafe(perDatePath, chunk);     // per-date raw (back-compat)
-    appendSafe(perSessionPath, chunk);  // per-session raw (Task 706)
-    try { process.stderr.write(chunk); } catch { /* stderr closed */ } // passthrough
-    stderrTail = (stderrTail + chunk.toString("utf8")).slice(-TAIL_CAP);
-    if (!bootEmitted) {
-      bootEmitted = true;
-      const head = chunk.toString("utf8").split("\n")[0].slice(0, 200);
-      emitLifecycle(`op=boot session=${SESSION_ID8} server=${SERVER_NAME} head=${JSON.stringify(head)}`, "info");
+// Replace process.stderr.write with a tee: mirror every server stderr byte to
+// the per-date and per-session sinks, keep a rolling tail for op=exit, emit
+// op=boot on the first bytes, then pass the write through to the real stderr.
+const teeWrite = ((...args: unknown[]): boolean => {
+  const chunk = args[0] as string | Uint8Array;
+  appendSafe(perDatePath, chunk);     // per-date raw (back-compat)
+  appendSafe(perSessionPath, chunk);  // per-session raw (Task 706)
+  const text = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+  stderrTail = (stderrTail + text).slice(-TAIL_CAP);
+  if (!bootEmitted) {
+    bootEmitted = true;
+    const head = text.split("\n")[0].slice(0, 200);
+    emitLifecycle(`op=boot session=${SESSION_ID8} server=${SERVER_NAME} head=${JSON.stringify(head)}`, "info");
+  }
+  return (rawStderrWrite as (...a: unknown[]) => boolean)(...args); // passthrough
+}) as typeof process.stderr.write;
+process.stderr.write = teeWrite;
+
+// Catchable-signal handling. The shim drives the exit ONLY when it is the sole
+// listener for the signal — i.e. the imported entry installed no handler of its
+// own. In that case it records the signal (so op=exit carries signal=<sig>) and
+// exits with 128+signum, mirroring the prior wrapper's exit-status convention.
+//
+// When the entry DID install a handler, the shim defers entirely and records
+// nothing: the entry's handler decides the exit code, and op=exit reflects that
+// exit verbatim. This matches the prior two-process model, where a child that
+// caught the signal and exited cleanly was observed as code=0 signal=— (a clean
+// self-exit), not as a signal death. Setting exitSignal here unconditionally
+// would mislabel every graceful signal-driven shutdown as a signal kill.
+function onSignal(sig: NodeJS.Signals, code: number): () => void {
+  return () => {
+    if (process.listenerCount(sig) === 1) {
+      exitSignal = sig;
+      process.exit(code);
     }
-  });
+  };
 }
-
-const forward = (signal: NodeJS.Signals) => { if (!child.killed) child.kill(signal); };
-process.on("SIGTERM", () => forward("SIGTERM"));
-process.on("SIGINT", () => forward("SIGINT"));
-
-// Signal → number, so a signal-killed child propagates as 128+signum (the
-// shell convention). `code` is null on a signal exit, so `128 + (code ?? 0)`
-// would collapse every signal to 128 and lose the signal identity in the
-// wrapper's own exit status.
-const SIGNUM: Record<string, number> = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGTERM: 15 };
-
-child.on("exit", (code, signal) => {
+process.on("SIGTERM", onSignal("SIGTERM", 143));
+process.on("SIGINT", onSignal("SIGINT", 130));
+process.on("SIGHUP", onSignal("SIGHUP", 129));
+
+// op=exit, emitted once from the process "exit" event. Sync-only — the loop is
+// stopping. When a catchable signal caused the exit, report code=— signal=<sig>
+// to match the prior wrapper's format; otherwise code=<exit code> signal=—.
+process.on("exit", (code) => {
+  if (exitEmitted) return;
+  exitEmitted = true;
   const lifetimeMs = Date.now() - spawnStamp;
   const tail = stderrTail.slice(-200);
-  const level: "info" | "error" = signal || (code ?? 0) !== 0 ? "error" : "info";
+  const codeField = exitSignal ? "—" : String(code);
+  const level: "info" | "error" = exitSignal || code !== 0 ? "error" : "info";
   emitLifecycle(
-    `op=exit session=${SESSION_ID8} server=${SERVER_NAME} pid=${child.pid ?? -1} ` +
-    `code=${code ?? "—"} signal=${signal ?? "—"} lifetimeMs=${lifetimeMs} stderr-tail=${JSON.stringify(tail)}`,
+    `op=exit session=${SESSION_ID8} server=${SERVER_NAME} pid=${process.pid} ` +
+    `code=${codeField} signal=${exitSignal ?? "—"} lifetimeMs=${lifetimeMs} stderr-tail=${JSON.stringify(tail)}`,
     level,
   );
-  if (signal) process.exit(128 + (SIGNUM[signal] ?? 0));
-  process.exit(code ?? 0);
+});
+
+emitLifecycle(`op=spawn session=${SESSION_ID8} server=${SERVER_NAME} pid=${process.pid} entry=${ENTRY}`, "info");
+
+// Run the real MCP server in THIS process. Dynamic import() (not top-level
+// await — this file compiles to CommonJS) loads the ESM entry; a load-time
+// failure mirrors the old child spawn-error path (op=error, exit 127). The
+// op=exit handler is suppressed on this path so op=error stays the sole record.
+import(pathToFileURL(ENTRY).href).catch((err: unknown) => {
+  const msg = err instanceof Error ? err.message : String(err);
+  exitEmitted = true;
+  emitLifecycle(`op=error session=${SESSION_ID8} server=${SERVER_NAME} reason=${JSON.stringify(`import error: ${msg}`)}`, "error");
+  process.exit(127);
 });

package/payload/platform/neo4j/schema.cypher

@@ -1217,18 +1217,26 @@ CREATE INDEX cloudflare_hostname_account IF NOT EXISTS
 FOR (h:CloudflareHostname) ON (h.accountId);
 
 // ----------------------------------------------------------
-// Estate-agent ontology (Task 358) — Listing-centric model
+// Estate-agent ontology (Task 358) — Property-centric model
 // documented at platform/plugins/memory/references/schema-estate-agent.md.
 //
+// :Property is the obligatory top-level node: the physical property, with
+// its listing events beneath it. It carries the agency parent edge
+// (:Property)-[:LISTED_BY]->(:Organization {brandSlug}) (the ≥1-adjacency
+// write-gate parent) and (:Property)-[:HAS_LISTING]->(:Listing) to each of
+// its listing events. The pre-inversion (:Listing)-[:FOR_PROPERTY]->(:Property)
+// and (:Listing)-[:LISTED_BY]->(:Organization) edges are retired.
+//
 // These declarations exist primarily so the memory-write validator's
 // parseLabelsFromSchemaCypher() registers each label on a fresh deploy
 // where no node of the label has yet landed — without them, the first
-// :Listing write from the listing-curator agent is rejected as "unknown
-// label" against an empty db.labels() set.
+// :Property/:Listing write from the listing-curator agent is rejected as
+// "unknown label" against an empty db.labels() set.
 //
 // Idempotency contracts mirror schema-estate-agent.md:
+//   :Property                    — (accountId, slug) on the address-normalised
+//                                  slug; the obligatory hub.
 //   :Listing / :Viewing / :Offer — (accountId, sourceSystem, sourceId)
-//   :Property                    — (accountId, slug)
 //   :ImageObject                 — (accountId, listingSlug, url) for the
 //                                  estate-agent variant, (accountId, name,
 //                                  contentUrl) for the brand-asset variant.
@@ -1237,6 +1245,12 @@ FOR (h:CloudflareHostname) ON (h.accountId);
 //                                  declared at the schema level — uniqueness
 //                                  is enforced at write time by the curator
 //                                  / brand-asset writer's MERGE clause.
+//
+// :Property already carries the account index, the (accountId, slug) unique
+// constraint, and a slot in the entity_search_admin fulltext union (its
+// n.address is in the ON EACH list) — no new index is added for the hub
+// inversion. The marketing embedding stays on :Listing; semantic search
+// targets the listing blurb/description, not the structural hub.
 // ----------------------------------------------------------
 
 CREATE CONSTRAINT listing_account_source_unique IF NOT EXISTS
@@ -1266,6 +1280,46 @@ FOR (p:Property) REQUIRE (p.accountId, p.slug) IS UNIQUE;
 CREATE INDEX property_account IF NOT EXISTS
 FOR (p:Property) ON (p.accountId);
 
+// Property-hub backfill — relink listing-only estate data deployed before
+// :Property became obligatory. Three idempotent passes, mirroring the
+// conversationId one-shot migration pattern above. Installs with no :Listing
+// nodes (every non-estate brand) match nothing in any pass. The standing
+// reconcile that proves orphanListings reached 0 is emitted per-deploy by
+// platform/scripts/seed-neo4j.sh.
+//
+// Pass 1 — convert any pre-inversion (:Listing)-[:FOR_PROPERTY]->(:Property)
+// to the parent-down (:Property)-[:HAS_LISTING]->(:Listing), reusing the
+// existing :Property, then drop the retired edge. Idempotent: once
+// FOR_PROPERTY is deleted a re-run matches nothing.
+MATCH (l:Listing)-[fp:FOR_PROPERTY]->(p:Property)
+MERGE (p)-[:HAS_LISTING]->(l)
+DELETE fp;
+
+// Pass 2 — for every :Listing still lacking a :Property parent, synthesise a
+// :Property from the listing's address slug and attach
+// (:Property)-[:HAS_LISTING]->(:Listing). Idempotent: the HAS_LISTING guard
+// makes re-runs and already-migrated listings no-ops. Listings with a null
+// slug are deliberately excluded — there is no address key to MERGE on, and a
+// {slug: null} MERGE would collapse every slug-less listing into one bogus
+// (accountId, null) :Property. Such listings (a malformed pre-inversion write)
+// stay visible as orphanListings in the seed-neo4j.sh reconcile; recovering
+// them needs an address backfill, tracked in .tasks/996-estate-null-slug-listing-property-backfill.md.
+MATCH (l:Listing)
+WHERE l.slug IS NOT NULL AND NOT ( (:Property)-[:HAS_LISTING]->(l) )
+MERGE (p:Property {accountId: l.accountId, slug: l.slug})
+  ON CREATE SET p.address = coalesce(l.displayName, l.addressLine),
+                p.postcode = l.postcode
+MERGE (p)-[:HAS_LISTING]->(l);
+
+// Pass 3 — relocate the agency edge from each :Listing onto its :Property
+// parent. Bound per LISTED_BY edge (one row per edge), so the DELETE never
+// double-fires on a single relationship regardless of how many listings share
+// a :Property or how many edges a listing carries. Idempotent: once a
+// listing's LISTED_BY is moved, a re-run matches nothing.
+MATCH (p:Property)-[:HAS_LISTING]->(l:Listing)-[old:LISTED_BY]->(o:Organization)
+MERGE (p)-[:LISTED_BY]->(o)
+DELETE old;
+
 CREATE CONSTRAINT viewing_account_source_unique IF NOT EXISTS
 FOR (v:Viewing) REQUIRE (v.accountId, v.sourceSystem, v.sourceId) IS UNIQUE;