@junghanacs/entwurf 0.14.2 → 0.15.0

package/pi-extensions/lib/copilot-fresh-preflight.ts

@@ -0,0 +1,251 @@
+/**
+ * copilot-fresh-preflight — the pre-mutation capability check a Copilot fresh call needs
+ * (#82 RAIL 9, `docs/adding-a-harness.md` step 9 clauses 3 and 4).
+ *
+ * ── Why this is a leaf and not a doctor ──
+ *
+ * A doctor answers "is this host correctly wired?" and is allowed to be slow, to spawn the
+ * vendor CLI, and to read live processes. This is not that. It answers ONE narrower question
+ * at ONE moment: *before* `mux-fresh-call` mutates the operator's tmux session, are the four
+ * things the fresh contract requires actually in place on this filesystem?
+ *
+ *   birth            — without the birth plugin the session mints no record, so the callback
+ *                      would carry no garden id and the sibling never becomes addressable.
+ *   MCP hand         — without the bridge server the callback tool does not exist in that
+ *                      session, and the first turn has nothing to call.
+ *   receive          — without the receiver unit the sibling can be launched and can call
+ *                      home, and then nothing can ever be delivered TO it.
+ *   visible identity — without the custom footer the citizen has a garden id nobody can see,
+ *                      which step 4 refuses to call lifecycle parity.
+ *
+ * ── Ordering is the whole point ──
+ *
+ * `scripts/copilot-launch.sh` already fails closed on the receiver, and that check is kept as
+ * it is: it guards every manual `entwurf copilot`, whose accepted contract stays receive-only.
+ * But a launcher runs INSIDE the window tmux just made, so its refusal leaves a dead window
+ * behind and the caller reads a launch receipt for a sibling that never was. `mux-fresh-call`'s
+ * rule is that nothing above the single mutation may leave a window behind, so the fresh lane
+ * decides the same facts one layer earlier. The overlap on the receiver axis is deliberate and
+ * each side names the other; the other three axes are the FRESH lane's requirement only.
+ *
+ * ── What this deliberately does NOT claim ──
+ *
+ * Ownership/configuration truth only: entwurf's units are installed and the settings the
+ * vendor will read say what they must say. It does NOT prove the Copilot CLI loaded the
+ * plugin, connected the MCP server, scanned the extension, or rendered a garden id in its
+ * footer — that is runtime truth, and it belongs to `doctor-copilot-*` (which may spawn the
+ * vendor) and to the step 9 clause 7 LIVE receipt. A green preflight is a statement about this
+ * filesystem, not a prediction about the next process.
+ *
+ * Every predicate below MIRRORS the shipped adapter that owns that file, deliberately
+ * including its environment seams — a preflight that resolved a path its own installer never
+ * writes would refuse a correctly installed host and send the operator hunting.
+ *
+ * No vendor spawn, no network, no await, no mutation.
+ */
+
+import { accessSync, constants, existsSync, lstatSync, readFileSync, statSync } from "node:fs";
+import * as path from "node:path";
+
+/** One reason per capability. These strings are stable contract — they cross the public
+ * surfaces as `entwurf_fresh_call` refusals, so a caller can act on them. */
+export type CopilotPreflightRejectReason =
+	| "copilot-birth-unit-missing"
+	| "copilot-mcp-hand-missing"
+	| "copilot-receive-unit-missing"
+	| "copilot-visible-identity-missing";
+
+const BIRTH_PLUGIN = "entwurf-meta-receive-copilot";
+const RECEIVE_UNIT = "entwurf-receive";
+const MCP_SERVER_KEY = "entwurf-bridge";
+/** Same default and same env seam as `scripts/copilot-statusline-bridge.sh`. */
+const DEFAULT_STATUSLINE_COMMAND = "entwurf-copilot-statusline";
+
+function dataHome(env: NodeJS.ProcessEnv): string | null {
+	const xdg = env.XDG_DATA_HOME;
+	if (typeof xdg === "string" && xdg.length > 0) return xdg;
+	const home = env.HOME;
+	if (typeof home === "string" && home.length > 0) return path.join(home, ".local", "share");
+	return null;
+}
+
+/** A JSON object or nothing. Failure to read, parse, or find an object is the SAME answer
+ * here — absent — because the caller's next move is identical in all of them: run the
+ * installer. Telling a corrupt state file apart from a missing one is the doctor's job. */
+function readJsonObject(file: string): Record<string, unknown> | null {
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(file, "utf8"));
+		return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+			? (parsed as Record<string, unknown>)
+			: null;
+	} catch {
+		// Bounded environment probing, Hard Rule 15's stated exception.
+		return null;
+	}
+}
+
+function isDir(p: string): boolean {
+	try {
+		return statSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+function isSymlink(p: string): boolean {
+	try {
+		return lstatSync(p).isSymbolicLink();
+	} catch {
+		return false;
+	}
+}
+
+/** Same DEST the managed launcher will arm from (`scripts/copilot-launch.sh`).
+ * `COPILOT_EXTENSIONS_DIR` wins; otherwise `$HOME/.copilot/extensions/<unit>`.
+ * String equality, not realpath: the launcher compares with `[ = ]`. */
+function receiveDest(env: NodeJS.ProcessEnv): string | null {
+	const override = env.COPILOT_EXTENSIONS_DIR;
+	if (typeof override === "string" && override.length > 0) {
+		return path.join(override, RECEIVE_UNIT);
+	}
+	const home = env.HOME;
+	if (typeof home !== "string" || home.length === 0) return null;
+	return path.join(home, ".copilot", "extensions", RECEIVE_UNIT);
+}
+
+function isExecutableFile(p: string): boolean {
+	try {
+		// `X_OK` for THIS user, which is what `command -v` answers and what Copilot will need.
+		// A mode-bit test would call a root-owned 0700 binary executable for everyone.
+		accessSync(p, constants.X_OK);
+		return statSync(p).isFile();
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * The statusline command as the shipped adapter resolves it: a value containing a separator is
+ * a path and must be executable; a bare name is looked up on PATH. This is a small local
+ * search rather than `mux-launch`'s resolver because the import fence keeps `mux-launch` to
+ * exactly two importers — a third would be a decision, and this leaf does not need one.
+ */
+function commandResolvable(command: string, env: NodeJS.ProcessEnv): boolean {
+	if (command.includes("/")) return isExecutableFile(command);
+	const raw = env.PATH;
+	if (typeof raw !== "string" || raw.length === 0) return false;
+	for (const dir of raw.split(path.delimiter)) {
+		if (dir.length === 0) continue;
+		if (isExecutableFile(path.join(dir, command))) return true;
+	}
+	return false;
+}
+
+/**
+ * The visible-identity axis, step 9 clause 4. The subject is the EFFECTIVE settings the vendor
+ * will read, not entwurf's ownership record: a host can carry a correct footer configuration
+ * with no install-state (measured on the acceptance host, 2026-08-24 — `doctor-copilot-statusline`
+ * reported `settings: configured (resolvable)` / `state: absent` / rc=0), and refusing that host
+ * would be refusing a working visible identity because of a missing receipt.
+ *
+ * The install-state, when present, is checked for the ONE thing it can still contradict: that
+ * it manages the very file Copilot reads. A state pointing somewhere else means two settings
+ * files disagree about who owns the footer, and which one wins is not decidable from here.
+ */
+function visibleIdentityMissing(env: NodeJS.ProcessEnv, data: string): boolean {
+	const command = env.COPILOT_STATUSLINE_COMMAND || DEFAULT_STATUSLINE_COMMAND;
+	const configured = env.COPILOT_SETTINGS_CONFIG;
+	let settingsPath: string;
+	if (typeof configured === "string" && configured.length > 0) {
+		settingsPath = configured;
+	} else {
+		const home = env.HOME;
+		if (typeof home !== "string" || home.length === 0) return true;
+		settingsPath = path.join(home, ".copilot", "settings.json");
+	}
+	// A symlinked settings file is somebody else's SSOT; the adapter refuses to touch it and
+	// this refuses to certify it.
+	if (isSymlink(settingsPath)) return true;
+	const settings = readJsonObject(settingsPath);
+	if (settings === null) return true;
+	const statusLine = settings.statusLine;
+	if (typeof statusLine !== "object" || statusLine === null || Array.isArray(statusLine)) return true;
+	if ((statusLine as Record<string, unknown>).command !== command) return true;
+	const footer = settings.footer;
+	if (typeof footer !== "object" || footer === null || Array.isArray(footer)) return true;
+	// `showCustom` must be exactly true. A truthy string would render nothing.
+	if ((footer as Record<string, unknown>).showCustom !== true) return true;
+	if (!commandResolvable(command, env)) return true;
+
+	const state = readJsonObject(path.join(data, "entwurf", "copilot-statusline", "install-state.json"));
+	if (state === null) return false; // absent state is not drift — see the doc comment above
+	const managed = state.managedSettingsPath;
+	if (typeof managed !== "string" || !path.isAbsolute(managed)) return true;
+	return path.resolve(managed) !== path.resolve(settingsPath);
+}
+
+/**
+ * Answer for ONE fresh Copilot launch. `null` means every required capability is in place on
+ * this filesystem; anything else is the first missing one, in the order the fresh contract
+ * consumes them: be born, hold the hand, be reachable, be visible.
+ */
+export function copilotFreshPreflight(env: NodeJS.ProcessEnv = process.env): CopilotPreflightRejectReason | null {
+	const data = dataHome(env);
+	// With no HOME and no XDG_DATA_HOME there is no place any of these could be installed.
+	// Report the FIRST capability rather than inventing a fifth reason for "no home".
+	if (data === null) return "copilot-birth-unit-missing";
+
+	// 1. Birth. The assembly is what the installer bakes and what the birth doctor certifies
+	// statically; `hooks.json` is what makes it a hook unit rather than a directory. There is
+	// no install-state for this unit — the artifact IS its ownership record.
+	const birthUnit = path.join(data, "entwurf", "meta-bridge-copilot", ".assembled", BIRTH_PLUGIN);
+	if (!isDir(birthUnit) || !existsSync(path.join(birthUnit, "hooks", "hooks.json"))) {
+		return "copilot-birth-unit-missing";
+	}
+
+	// 2. MCP hand. The install-state names the config it owns, so the config path is READ from
+	// ownership truth rather than re-derived — a preflight that guessed would refuse a
+	// correctly installed host whose config lives somewhere else.
+	const mcpState = readJsonObject(path.join(data, "entwurf", "copilot-mcp", "install-state.json"));
+	if (mcpState === null || mcpState.serverKey !== MCP_SERVER_KEY) return "copilot-mcp-hand-missing";
+	const managedConfigPath = mcpState.managedConfigPath;
+	if (typeof managedConfigPath !== "string" || !path.isAbsolute(managedConfigPath)) return "copilot-mcp-hand-missing";
+	const servers = readJsonObject(managedConfigPath)?.mcpServers;
+	if (typeof servers !== "object" || servers === null || Array.isArray(servers)) return "copilot-mcp-hand-missing";
+	// The state can be current while the config drifted (hand-edited, restored from a backup,
+	// replaced by another tool). The server key present in the file the CLI actually reads is
+	// the fact the first turn depends on.
+	if (!Object.hasOwn(servers as Record<string, unknown>, MCP_SERVER_KEY)) return "copilot-mcp-hand-missing";
+
+	// 3. Receive. The same facts `scripts/copilot-launch.sh` checks — unit name, recorded
+	// path, DEST equality against this env's extensions root, then the entry file.
+	const recvState = readJsonObject(path.join(data, "entwurf", "copilot-receive", "install-state.json"));
+	if (recvState === null || recvState.unit !== RECEIVE_UNIT) return "copilot-receive-unit-missing";
+	const recvPath = recvState.path;
+	if (typeof recvPath !== "string" || !path.isAbsolute(recvPath)) return "copilot-receive-unit-missing";
+	// Mirror the launcher's path-mismatch predicate PRE-MUTATION. A state that names a
+	// real unit in a different extensions root than this env will scan still opens a
+	// window today if we only check that the files exist — then `entwurf copilot`
+	// refuses inside it and the caller holds a launch receipt for a dead sibling.
+	const dest = receiveDest(env);
+	if (dest === null || recvPath !== dest) return "copilot-receive-unit-missing";
+	if (!isDir(recvPath) || !existsSync(path.join(recvPath, "extension.mjs"))) return "copilot-receive-unit-missing";
+
+	// 4. Visible identity.
+	if (visibleIdentityMissing(env, data)) return "copilot-visible-identity-missing";
+
+	return null;
+}
+
+/** Repair text, one line per reason. A reason a caller cannot act on is a reason they will
+ * guess about — each names the exact command that installs the missing capability. */
+export const COPILOT_PREFLIGHT_HINT: Record<CopilotPreflightRejectReason, string> = {
+	"copilot-birth-unit-missing":
+		"the Copilot BIRTH plugin is not installed here, so the sibling would mint no record and its callback would carry no garden id — run: entwurf install-copilot-bridge",
+	"copilot-mcp-hand-missing":
+		"the entwurf-bridge MCP server is not registered in the Copilot config this host owns, so the callback tool would not exist in that session — run: entwurf install-copilot-mcp",
+	"copilot-receive-unit-missing":
+		"the Copilot RECEIVER extension is not installed here, so the sibling could call home but nothing could ever be delivered to it — run: entwurf install-copilot-receive",
+	"copilot-visible-identity-missing":
+		"Copilot's custom footer is not configured to entwurf's resolvable statusline command (or an install-state manages a different settings file), so the sibling's garden id would be visible nowhere — run: entwurf doctor-copilot-statusline, then entwurf install-copilot-statusline",
+};

package/pi-extensions/lib/meta-sender-identity.ts

@@ -48,8 +48,16 @@ import {
 } from "./meta-session.ts";
 import { type NativePushAdapter, resolveNativePushAdapter } from "./native-push/adapter.ts";
 
-/** Every native backend that mints a garden-id from its own hook and writes a sender marker. */
-export const META_SENDER_BACKENDS: readonly MetaBackend[] = ["claude-code", "antigravity"];
+/** Every native backend that mints a garden-id from its own hook and writes a sender marker.
+ *
+ * WRITER AND READER OPEN TOGETHER OR NOT AT ALL. A backend listed here whose hook writes no
+ * marker costs one wasted directory read; a backend whose hook writes a marker but is absent
+ * here is INVISIBLE — the bridge holds the owner pid, never looks in that directory, and the
+ * citizen's sends are refused as anonymous for a reason nothing in the log names. That was
+ * exactly the #46 defect on agy, and copilot joined the list only once its own hook wrote one
+ * (#82 RAIL 5b). Membership says a marker may EXIST, never that a reply can land: the reply
+ * rail is chosen from `nativePushSupported` at the bridge, not from this list. */
+export const META_SENDER_BACKENDS: readonly MetaBackend[] = ["claude-code", "antigravity", "copilot"];
 
 /** A marker that passed BOTH guards, together with the record that vouches for it. */
 export interface TrustedMetaSender {

package/pi-extensions/lib/meta-session.ts

@@ -12,8 +12,8 @@
  *   1. RECORD functions + types (mint / serialize / parse / certifyActiveStore /
  *      decideUpsert), the backend-agnostic authority. Pure beyond an injected
  *      `now`; backend capability (wakeMode/deliveryLevel) comes from the packaged
- *      registry via a cached fs read (loadMetaCapabilityRegistry) — see that seam
- *      below.
+ *      registry, re-read on every load (loadMetaCapabilityRegistry holds NO cache, so a
+ *      grade moved on disk is visible to a long-lived process) — see that seam below.
  *   2. The thin FS-BOUND STORE (step 3): `upsertMetaSession` wraps the pure core
  *      (readdir → `certifyActiveStore` → `decideUpsert` → atomic write) with the real
  *      filesystem. It lives in this module (not a sibling `*-store.ts`) on purpose:
@@ -74,12 +74,14 @@ export class MetaRecordError extends Error {
 // ---------------------------------------------------------------------------
 
 /**
- * The three native meta-bridge backends, declared from the start so the
- * per-backend adapter seam is forced (a different native layout each — that
- * difference is the whole reason for a thin adapter). Discriminator field on
- * every record.
+ * Native meta-bridge backends. Discriminator on every record. Adding a member
+ * is a sibling-reader redeploy (`./run.sh install-meta-bridge` and the matching
+ * sibling install), not a store archive: writers certify the whole active store
+ * against THIS set, so a deployed plugin still carrying the old set refuses
+ * every write, including its own. `./run.sh doctor-meta-bridge` already flags a
+ * stale deployed writer — run it after the change.
  */
-export const META_BACKENDS = ["claude-code", "antigravity", "codex"] as const;
+export const META_BACKENDS = ["claude-code", "antigravity", "codex", "copilot"] as const;
 export type MetaBackend = (typeof META_BACKENDS)[number];
 
 /**
@@ -127,6 +129,47 @@ export const META_BACKEND_DESCRIPTORS: Record<MetaBackend, MetaBackendDescriptor
 		deliveryLevel: "D6",
 		nativeIdLabel: "threadId",
 	},
+	// SELF-FETCH citizen since #82 RAIL 5. Copilot CLI 1.0.80 runs our plugin hook (birth,
+	// garden address, who-sent) AND forks our first-party extension, whose `joinSession()`
+	// holds an `fs.watch` on the garden mailbox signal and can `session.send()` a doorbell
+	// into an idle session. That is the same shape Claude's mailbox has, reached through a
+	// different vendor surface. Hence:
+	//   wakeMode  self-fetch — the doorbell announces, the model drains its own inbox with
+	//             `entwurf_inbox_read`, and THAT read is the receipt. The extension never
+	//             injects the body, so this label promises exactly what happens. It was
+	//             `direct-inject` while no doorbell existed (measured 2026-08-20: no
+	//             `FileChanged`, `asyncRewake` or `watchPaths` in the bundle) — that
+	//             absence was never a claim about the vendor's other surfaces, and the
+	//             extension rail is the one it missed. Copilot is still NOT a
+	//             `nativePushSupported` backend and has no native-push adapter.
+	//   D6        the PRODUCT grade, earned by the managed LIVE acceptance of 2026-08-23
+	//             (garden 20260823T181316-d9f6ba, native 20fe30c8-b2bc-4600-91a0-8a409131be51,
+	//             CLI 1.0.80): the receive log joins that native id and arms that garden id,
+	//             the mailbox state stamps lastEnqueuedAt 09:23:41.235Z and lastReadAt
+	//             09:23:56.480Z, and the model answered on the SAME record/native/gid chain.
+	//             This is still the PRODUCT grade and not the raw probe's: the earlier
+	//             transport probe was evidence about the mechanism, and it did not move this
+	//             number — a managed round trip did.
+	//             D7 is PARTIAL, deliberately: the reply and the read receipt were observed,
+	//             but the completion taxonomy as a whole and any long-haul operation were
+	//             not, and the reply envelope itself reaches this comment as an INHERITED
+	//             fact (it was not re-read from a transcript when this was written). D8 is
+	//             unproven and D3 (managed second-session isolation) is pending — its
+	//             decisive log was lost to a scratch cleanup before it could be preserved.
+	//             The route stays fail-closed on both ends: with no armed receiver marker
+	//             every dispatch is still refused `mailbox-undeliverable`, so replyability
+	//             is a fact about a live marker and never a constant of this backend.
+	//   sessionId the native join key, measured to be ONE id across all three surfaces:
+	//             the hook envelope, `record.nativeSessionId`, and the SDK's
+	//             `session.sessionId` (record 20260823T112003-9d069a ==
+	//             `ARMED sessionId=4fc16d8d-473d-4258-a1fd-f99d3cb375e9`, CLI 1.0.80).
+	//             That agreement is what lets the extension bind its arm to the record.
+	copilot: {
+		backend: "copilot",
+		wakeMode: "self-fetch",
+		deliveryLevel: "D6",
+		nativeIdLabel: "sessionId",
+	},
 };
 
 // ---------------------------------------------------------------------------
@@ -140,9 +183,9 @@ export function requireNonEmptyString(value: unknown, field: string): string {
 	return value;
 }
 
-/** Validate the 3-backend NATIVE bridge axis (sender/receiver markers, capability
+/** Validate the native-bridge backend axis (sender/receiver markers, capability
  * drift guard). Not a record-schema validator: identity records take
- * `requireCitizenBackend` (which admits `pi`). Markers stay native-3 because the
+ * `requireCitizenBackend` (which admits `pi`). Markers stay on this set because the
  * pi adapter carries its record-established garden id into children via env rather
  * than using the native-hook pid marker rail. */
 export function requireBackend(value: unknown): MetaBackend {
@@ -210,7 +253,7 @@ function isoNow(now: Date): string {
 export const META_SCHEMA_VERSION_V3 = 3 as const;
 
 /** Every backend admitted by the one V3 record-citizen schema. */
-export const META_CITIZEN_BACKENDS = ["claude-code", "antigravity", "codex", "pi"] as const;
+export const META_CITIZEN_BACKENDS = ["claude-code", "antigravity", "codex", "copilot", "pi"] as const;
 export type MetaCitizenBackend = (typeof META_CITIZEN_BACKENDS)[number];
 
 /**
@@ -655,19 +698,30 @@ export function metaCapabilitiesFilePath(): string {
 // the rest of `delivery{}`, so today the registry is the sole home.
 // ---------------------------------------------------------------------------
 
-/** Memoized packaged registry; the file is immutable at runtime, so caching is honest (not stateful lying). */
-let cachedMetaCapabilities: MetaCapabilityRegistry | null = null;
-
 /**
- * Load + memoize the packaged capability registry — the live source of backend
- * honesty metadata as of 3D-3. A missing/corrupt file throws (the registry is a
- * packaged invariant; check-pack guarantees its presence).
+ * Load the packaged capability registry — the live source of backend honesty metadata
+ * as of 3D-3. A missing/corrupt file throws (the registry is a packaged invariant;
+ * check-pack guarantees its presence).
+ *
+ * NO CACHE, deliberately. This used to memoize into a process-lifetime singleton on the
+ * argument that "the file is immutable at runtime". That argument was false for the one
+ * process that matters: the entwurf-bridge MCP child lives as long as its harness
+ * session, so a grade or wakeMode moved by an install/upgrade was invisible to every
+ * already-running dispatcher until the operator restarted it — and nothing anywhere
+ * said so. The symptom is a citizen answering with last week's capability, which is the
+ * silent-wrong-answer class this repo refuses; "restart your session" is an instruction
+ * to work around a defect, not a fix for it (#82 RAIL 7).
+ *
+ * The subtraction is the whole repair, and it is deliberately not an invalidation
+ * scheme. Stat-based invalidation (mtime+size) cannot see an atomic same-size,
+ * same-timestamp replacement, so it would trade a certain staleness bug for an
+ * intermittent one; content hashing would have to read the file anyway. The registry is
+ * a few hundred bytes and both production callers — the v2 decider and production
+ * deliverability — reach it once per dispatch, not in a loop, so reading it there is
+ * cheaper than being wrong.
  */
 export function loadMetaCapabilityRegistry(): MetaCapabilityRegistry {
-	if (cachedMetaCapabilities === null) {
-		cachedMetaCapabilities = parseMetaCapabilityRegistry(fs.readFileSync(metaCapabilitiesFilePath(), "utf8"));
-	}
-	return cachedMetaCapabilities;
+	return parseMetaCapabilityRegistry(fs.readFileSync(metaCapabilitiesFilePath(), "utf8"));
 }
 
 /**
@@ -928,15 +982,18 @@ export function certifyActiveStoreDir(dir: string): ActiveStoreCertification & {
 
 /**
  * The refusal an uncertifiable ACTIVE store earns, in the words both the runtime
- * writers and the install doctor use. One prescription, both invocation forms —
- * every defect kind (previous generation, corruption, drift, duplicate, symlink)
- * is answered by archiving the generation, so there is nothing to branch on.
+ * writers and the install doctor use. Rotten records (previous generation,
+ * corruption, drift, duplicate, symlink) are answered by archiving. An
+ * unknown-backend defect is a stale reader, not a rotten store — the listed
+ * defect says so; this headline tells the operator to distinguish. No branch:
+ * both sentences always print.
  */
 export function activeStoreRefusal(cert: ActiveStoreCertification & { dir: string }, shown = 3): string {
 	const headline =
 		`meta-record store ${cert.dir} holds ${cert.defects.length} entry/entries this generation cannot certify — ` +
 		`refusing to write (the active store is v3-only and carries no cross-generation continuity). ` +
-		`Archive the generation and open a fresh one with ${FRESH_CUT_PRESCRIPTION}.`;
+		`Archive the generation and open a fresh one with ${FRESH_CUT_PRESCRIPTION}. ` +
+		`If a listed defect says "backend" must be one of this reader's known set, the reader is stale — redeploy the sibling unit (the matching doctor names the install verb); do not archive those records.`;
 	// `shown = 0` is for a caller that ALREADY printed every cause per entry (the
 	// store-doctor): repeating them here doubles the wall on a large previous
 	// generation, which is exactly the aggregation lesson F8 taught. The count and
@@ -1608,12 +1665,28 @@ export function readMetaSenderMarker(opts: ReadMetaSenderMarkerOptions): MetaSen
 // ── meta-receiver presence marker (SE-2 active-receiver signal) ──────────────
 
 /**
- * The arm-capable hook events. Only these can emit watchPaths (and therefore arm
- * the idle-wake), so only these write a receiver presence marker. UserPromptSubmit
- * is deliberately absent: it can backfill the record but cannot re-arm the watch, so
- * it must NOT mint or refresh an "active receiver" claim it cannot back.
+ * The arm-capable events, across every backend that can arm an idle wake.
+ *
+ * CLAUDE (`session-start`, `cwd-changed`, `file-changed`): only these hook events can
+ * emit watchPaths (and therefore arm the idle-wake), so only these write a receiver
+ * presence marker. UserPromptSubmit is deliberately absent: it can backfill the record
+ * but cannot re-arm the watch, so it must NOT mint or refresh an "active receiver"
+ * claim it cannot back.
+ *
+ * COPILOT (`extension-join`): the same rule, one backend over. Copilot's arm is not a
+ * hook at all — the CLI forks a first-party extension and the extension's own
+ * `joinSession()` is what puts a live `fs.watch` on the garden mailbox signal and gives
+ * it a `session.send()` channel to ring. The membership test is unchanged and is about
+ * capability, not event vocabulary: this provenance is admitted because the process that
+ * writes it holds the watch and can start a turn on an idle session. A Copilot hook event
+ * has neither, which is why the birth hook still arms nothing (#82 RAIL 5).
  */
-export const META_RECEIVER_ARM_PROVENANCES = ["session-start", "cwd-changed", "file-changed"] as const;
+export const META_RECEIVER_ARM_PROVENANCES = [
+	"session-start",
+	"cwd-changed",
+	"file-changed",
+	"extension-join",
+] as const;
 export type MetaReceiverArmProvenance = (typeof META_RECEIVER_ARM_PROVENANCES)[number];
 
 function requireArmProvenance(value: unknown): MetaReceiverArmProvenance {

package/pi-extensions/lib/mux-fresh-call.ts

@@ -47,6 +47,11 @@
 
 import { randomBytes } from "node:crypto";
 import { classifyTmuxCwd, type TmuxCwdRejectReason } from "./classify-tmux-cwd.ts";
+import {
+	COPILOT_PREFLIGHT_HINT,
+	type CopilotPreflightRejectReason,
+	copilotFreshPreflight,
+} from "./copilot-fresh-preflight.ts";
 import {
 	assertLaunchTarget,
 	LaunchPreconditionError,
@@ -66,27 +71,47 @@ import {
 	type WindowHandle,
 } from "./mux-placement.ts";
 
-/** The two backends this rail can open. Fixed set, not a profile — a third one is a decision,
- * not a config entry. */
-export const FRESH_CALL_BACKENDS = ["pi", "claude-code"] as const;
+/** The backends this rail can open. Fixed set, not a profile — a further one is a decision,
+ * not a config entry. `copilot` was added by #82 RAIL 9 under the step 9 admission contract. */
+export const FRESH_CALL_BACKENDS = ["pi", "claude-code", "copilot"] as const;
 export type FreshCallBackend = (typeof FRESH_CALL_BACKENDS)[number];
 
-/** The fixed runtime each backend resolves on PATH. Same reason `mux-launch` uses PATH rather
+/**
+ * The fixed runtime each backend resolves on PATH. Same reason `mux-launch` uses PATH rather
  * than a compiled-in location: the official binary is whatever the operator's environment gives
- * when they type the name. */
+ * when they type the name.
+ *
+ * `copilot` resolves `entwurf`, NOT the vendor CLI, and that is the contract rather than a
+ * convenience. Step 9 clause 1 requires ONE fixed MANAGED runtime path, and a bare `copilot`
+ * is not one: it would start without the `COPILOT_CLI_ENABLED_FEATURE_FLAGS=EXTENSIONS` token
+ * whose absence skips the extension scan SILENTLY, so the sibling would look launched and could
+ * never be delivered to. `entwurf copilot` is the accepted managed invocation that owns that
+ * flag, its recursion fence and its receiver precondition; fresh call reaches Copilot only
+ * through it. The cost is named: a Copilot fresh call needs a current `entwurf` on PATH, the
+ * way a pi fresh call needs `pi`.
+ */
 export const FRESH_CALL_RUNTIME: Record<FreshCallBackend, string> = {
 	pi: "pi",
 	"claude-code": "claude",
+	copilot: "entwurf",
 };
 
 /**
  * The callback tool NAME differs per backend and that is not cosmetic: native pi exposes the
- * capability directly (`entwurf_v2`), while a Claude Code session reaches it through the MCP
- * bridge under its namespaced name. Naming the wrong one costs the whole first turn.
+ * capability directly (`entwurf_v2`), while an MCP-hosted session reaches it under whatever
+ * name that harness composes. Naming the wrong one costs the whole first turn.
+ *
+ * `[측정]` Copilot CLI 1.0.80 composes `<mcpServerName>-<mcpToolName>` — NOT Claude Code's
+ * `mcp__<server>__<tool>`. Read from two independent sessions' own event logs
+ * (`~/.copilot/session-state/<id>/events.jsonl`): `assistant.message.toolRequests[].name` and
+ * `tool.execution_start.toolName` both carry `entwurf-bridge-entwurf_v2`, with
+ * `mcpServerName`/`mcpToolName` beside them as the parts. Derive-and-measure, never copy a
+ * sibling's spelling (`docs/adding-a-harness.md` step 5).
  */
 export const FRESH_CALL_CALLBACK_TOOL: Record<FreshCallBackend, string> = {
 	pi: "entwurf_v2",
 	"claude-code": "mcp__entwurf-bridge__entwurf_v2",
+	copilot: "entwurf-bridge-entwurf_v2",
 };
 
 /** Mirrors the `entwurf_v2` message bound. This is an INTERFACE cap for symmetry with the
@@ -112,12 +137,41 @@ export function isSafeFreshCallModel(model: string): boolean {
  *                 Flag-first submitted no message; Pi rejects the equals form for `--model`.
  *   claude-code — prompt, then `--allowedTools=` and `--model=` as ONE token each. The space form
  *                 for allowedTools is variadic and eats the prompt as an option value.
+ *   copilot     — the managed VERB first, then the prompt as the value of `-i/--interactive`,
+ *                 `--model`, value as two tokens, and the policy as the explicit `--yolo`
+ *                 token. Measured from `copilot --help` (1.0.80).
  *
- * Both failures looked identical from outside: window open, record and socket minted, no turn.
+ * Both pi/claude failures looked identical from outside: window open, record and socket minted,
+ * no turn.
  *
- * The equals form is NOT a permission guarantee — on the measured host the tool was already
- * permitted, so the option's effect was unobservable. What was observed is that it does no harm
- * to the argv. Permission stays a documented host precondition.
+ * For pi and claude-code the equals form is NOT a permission guarantee — on the measured host
+ * the tool was already permitted, so the option's effect was unobservable. What was observed is
+ * that it does no harm to the argv. Permission stays a documented host precondition there.
+ *
+ * Copilot is the backend where the policy IS carried explicitly (step 9 clause 2), and three of
+ * its argv facts are load-bearing:
+ *
+ *   - `copilot` is argv[0] of the RUNTIME `entwurf`, i.e. the managed verb — see
+ *     `FRESH_CALL_RUNTIME`. Everything after it is forwarded byte-identical by
+ *     `scripts/copilot-launch.sh`.
+ *   - the prompt rides `--interactive`, never `-p/--prompt`: `-p` runs the prompt and EXITS,
+ *     which would close the window on a sibling that is supposed to stay open and be delivered
+ *     to. `--interactive <prompt>` is non-variadic, so the space form is safe here.
+ *   - the policy token is `--yolo`, STATED HERE rather than left to the launcher: the launcher
+ *     injects `--yolo` only when the argv names no policy, and step 9 clause 2 requires the
+ *     fresh composition to state its model and permission policy explicitly, never to rely
+ *     invisibly on someone else's default.
+ *
+ * `--yolo` is a GLG operator decision, not a drifted default. The first cut passed a
+ * callback-only `--allow-tool=entwurf-bridge(entwurf_v2)` grant, and GLG's 2026-08-25 operator
+ * LIVE measured the consequence: the fresh sibling's footer showed no `YOLO`, and every tool
+ * its task needed stopped on a confirmation prompt, which made the sibling impractical to work
+ * with. GLG then set the policy explicitly: a fresh Copilot sibling carries the same managed
+ * `--yolo` profile a human-typed `entwurf copilot` gets. (Copilot 1.0.80 help: `--yolo` = all
+ * tools + all paths + all URLs.) The permission GRAMMAR lesson from that first cut — Copilot's
+ * `--allow-tool` takes `<mcp-server-name>(tool-name?)`, a different dialect from the
+ * model-facing tool name — stays recorded in `docs/adding-a-harness.md` step 9's worked
+ * example; it is a measured vendor fact even though this argv no longer uses it.
  */
 export function buildBackendArgs(backend: FreshCallBackend, prompt: string, model: string): string[] {
 	switch (backend) {
@@ -125,6 +179,8 @@ export function buildBackendArgs(backend: FreshCallBackend, prompt: string, mode
 			return [prompt, "--entwurf-control", "--model", model];
 		case "claude-code":
 			return [prompt, `--allowedTools=${FRESH_CALL_CALLBACK_TOOL["claude-code"]}`, `--model=${model}`];
+		case "copilot":
+			return ["copilot", "--interactive", prompt, "--model", model, "--yolo"];
 	}
 }
 
@@ -167,6 +223,7 @@ export type FreshCallRejectReason =
 	| PlacementRejectReason
 	| LaunchRejectReason
 	| TmuxCwdRejectReason
+	| CopilotPreflightRejectReason
 	| "caller-identity-unavailable"
 	| "model-empty"
 	| "model-invalid"
@@ -270,6 +327,17 @@ export function freshCall(
 		throw err;
 	}
 
+	// Backend capability, still PRE-MUTATION (step 9 clause 3). It runs AFTER the runtime is
+	// proven, because "entwurf is not on PATH" is the more fundamental answer — telling an
+	// operator to run `entwurf install-copilot-bridge` when they have no `entwurf` at all sends
+	// them to the wrong repair. It runs BEFORE placement for the reason this whole ordering
+	// exists: a refusal here cannot leave a window behind, while the launcher's own equivalent
+	// check (receiver only, manual `entwurf copilot`) necessarily runs after one is open.
+	if (params.backend === "copilot") {
+		const missing = copilotFreshPreflight(env);
+		if (missing) return { ok: false, reason: missing };
+	}
+
 	const inspected = inspectPlacement(env);
 	if (!inspected.ok) return { ok: false, reason: inspected.reason };
 	const placement = inspected.placement;
@@ -319,6 +387,9 @@ export function freshCall(
 /** Why each refusal happened, in the caller's terms. A reason a caller cannot act on is a reason
  * they will guess about. */
 const REJECT_HINT: Record<FreshCallRejectReason, string> = {
+	// The Copilot capability reasons keep their repair text on the leaf that decides them, so
+	// the sentence an operator reads cannot drift away from the predicate that produced it.
+	...COPILOT_PREFLIGHT_HINT,
 	"no-tmux-context": "this agent is not running inside tmux, so there is no session to open a sibling beside",
 	"anchor-malformed": "TMUX_PANE is not a native pane id",
 	"anchor-unresolved": "tmux resolved no pane for this agent's anchor",