@junghanacs/entwurf 0.12.6 → 0.12.7

package/scripts/check-native-push-adapter.ts

@@ -0,0 +1,319 @@
+/**
+ * check-native-push-adapter — deterministic gate for the native-push adapter LEAF
+ * (봉인 3/8). Drives `createAntigravityAdapter` with a FAKE runner (no real agy / ss /
+ * pgrep), so probe + send are gate-provable without a live host.
+ *
+ * Proves:
+ *   - FULL pid scan (NOT head -1): with two host pids where only the SECOND serves the
+ *     conversation, probe still finds the route — the raw-agy-send.sh:16 single-pid
+ *     assumption is corrected.
+ *   - dead vs indeterminate: no host process → dead; host(s) alive but no LS port served
+ *     the conversation → indeterminate (never coerced to dead).
+ *   - VOLATILE route / no cache (봉인 3): a repeated probe re-runs pgrep + ss + metadata
+ *     and re-discovers the (changed) route — the adapter never stores it.
+ *   - send argv + env: send-message argv === [binary, agentapi, send-message, conv, body]
+ *     with ANTIGRAVITY_LS_ADDRESS === the route; a non-zero exit THROWS (fail-loud).
+ *   - NO retry in the adapter: send is a single attempt (the 1-shot re-probe→re-send is
+ *     the executor hand's job, step ⑥) — a failed send throws immediately, no re-probe.
+ *   - resolver fail-fast: resolveNativePushAdapter("antigravity") resolves; unknown throws.
+ *
+ * Pure; no backend, no socket, no real process.
+ */
+
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+	AGY_METADATA_TIMEOUT_MS,
+	AGY_SEND_TIMEOUT_MS,
+	antigravityAdapter,
+	createAntigravityAdapter,
+	type NativePushRunner,
+	resolveNativePushAdapter,
+} from "../pi-extensions/lib/native-push/adapter.ts";
+
+let passed = 0;
+function ok(label: string, cond: boolean): void {
+	assert.ok(cond, label);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+function eq(label: string, actual: unknown, expected: unknown): void {
+	assert.deepStrictEqual(actual, expected, label);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+
+const FAKE_BINARY = "/fake/bin/agy";
+const CONV = "conv-abc-123";
+
+interface ExecCall {
+	argv: string[];
+	env?: Record<string, string>;
+	timeoutMs?: number;
+}
+
+/** A recorded ss -lntp fixture line for a localhost listener owned by `pid`. */
+function ssLine(port: number, pid: number): string {
+	return `LISTEN 0 4096 127.0.0.1:${port} 0.0.0.0:* users:(("agy",pid=${pid},fd=7))`;
+}
+
+interface FakeConfig {
+	pids: number[];
+	ss: string;
+	/** which (lsAddress, conv) answer get-conversation-metadata as the serving route. */
+	serving: (lsAddress: string, conv: string) => boolean;
+	/** exit codes for successive send-message calls (default: all 0). */
+	sendCodes?: number[];
+	/** simulate a TIMEOUT kill (code 124) on every get-conversation-metadata call. */
+	metadataTimeout?: boolean;
+}
+
+function makeFakeRunner(config: FakeConfig): { runner: NativePushRunner; calls: ExecCall[] } {
+	const calls: ExecCall[] = [];
+	let sendIdx = 0;
+	const runner: NativePushRunner = {
+		async exec(argv, opts) {
+			calls.push({ argv: [...argv], env: opts?.env, timeoutMs: opts?.timeoutMs });
+			const a = [...argv];
+			if (a[0] === "pgrep") {
+				const code = config.pids.length > 0 ? 0 : 1;
+				return { code, stdout: config.pids.length ? `${config.pids.join("\n")}\n` : "", stderr: "" };
+			}
+			if (a[0] === "ss") {
+				return { code: 0, stdout: config.ss, stderr: "" };
+			}
+			if (a.includes("get-conversation-metadata")) {
+				if (config.metadataTimeout) {
+					return { code: 124, stdout: "", stderr: "" }; // timeout kill (bounded, no hang)
+				}
+				const conv = a[a.length - 1];
+				const ls = opts?.env?.ANTIGRAVITY_LS_ADDRESS ?? "";
+				const serves = config.serving(ls, conv);
+				return {
+					code: serves ? 0 : 1,
+					stdout: serves ? '{"conversationMetadata":{"id":"x"}}' : "",
+					stderr: serves ? "" : "conversation not found",
+				};
+			}
+			if (a.includes("send-message")) {
+				const code = config.sendCodes ? (config.sendCodes[sendIdx++] ?? 0) : 0;
+				return { code, stdout: "", stderr: code === 0 ? "" : "send failed" };
+			}
+			return { code: 127, stdout: "", stderr: `unknown command ${a[0]}` };
+		},
+	};
+	return { runner, calls };
+}
+
+// ── FULL pid scan (not head -1): only the 2nd pid serves the conversation ────
+{
+	const { runner, calls } = makeFakeRunner({
+		pids: [123, 456],
+		ss: `${ssLine(5001, 123)}\n${ssLine(5002, 456)}`,
+		serving: (ls) => ls === "127.0.0.1:5002", // only pid 456's port serves it
+	});
+	const adapter = createAntigravityAdapter({ runner, binary: FAKE_BINARY });
+	const result = await adapter.probe(CONV);
+	ok("full-scan: probe finds the route on the SECOND pid (not head -1)", result.status === "alive");
+	eq(
+		"full-scan: route is pid 456's port (5002)",
+		result.status === "alive" ? result.route.lsAddress : "(dead)",
+		"127.0.0.1:5002",
+	);
+	// proof it did NOT stop at pid 123: it probed BOTH 5001 (miss) and 5002 (hit).
+	const metaTargets = calls
+		.filter((c) => c.argv.includes("get-conversation-metadata"))
+		.map((c) => c.env?.ANTIGRAVITY_LS_ADDRESS);
+	ok("full-scan: probed pid 123's port 5001 before pid 456 (no head -1)", metaTargets.includes("127.0.0.1:5001"));
+	ok("full-scan: probed pid 456's serving port 5002", metaTargets.includes("127.0.0.1:5002"));
+	// pgrep scanned WITHOUT `head -1` — the adapter never invokes head, it parses all pids.
+	ok(
+		"full-scan: pgrep invoked as `pgrep -x agy` (no head)",
+		calls.some((c) => c.argv.join(" ") === "pgrep -x agy"),
+	);
+}
+
+// ── dead: no host process ────────────────────────────────────────────────────
+{
+	const { runner } = makeFakeRunner({ pids: [], ss: "", serving: () => false });
+	const adapter = createAntigravityAdapter({ runner, binary: FAKE_BINARY });
+	const result = await adapter.probe(CONV);
+	ok("no-host: probe → dead", result.status === "dead");
+	ok(
+		"no-host: dead reason names the missing host process",
+		result.status === "dead" && /no live agy process/.test(result.reason),
+	);
+}
+
+// ── indeterminate: host alive but no LS port serves the conversation ─────────
+{
+	const { runner } = makeFakeRunner({
+		pids: [123],
+		ss: ssLine(5001, 123),
+		serving: () => false, // agy up, but the conv is nowhere
+	});
+	const adapter = createAntigravityAdapter({ runner, binary: FAKE_BINARY });
+	const result = await adapter.probe(CONV);
+	ok("host-no-conv: probe → indeterminate (NOT dead)", result.status === "indeterminate");
+	ok(
+		"host-no-conv: indeterminate reason names the unserved conversation",
+		result.status === "indeterminate" && /no LS port served/.test(result.reason),
+	);
+}
+
+// ── VOLATILE route / no cache (봉인 3): a repeated probe re-discovers a CHANGED route ──
+{
+	let servingPort = 5002;
+	const { runner, calls } = makeFakeRunner({
+		pids: [123],
+		ss: `${ssLine(5002, 123)}\n${ssLine(5003, 123)}`,
+		serving: (ls) => ls === `127.0.0.1:${servingPort}`,
+	});
+	const adapter = createAntigravityAdapter({ runner, binary: FAKE_BINARY });
+
+	const r1 = await adapter.probe(CONV);
+	eq("volatile-route: probe #1 route = 5002", r1.status === "alive" ? r1.route.lsAddress : "(dead)", "127.0.0.1:5002");
+	const pgrepAfter1 = calls.filter((c) => c.argv[0] === "pgrep").length;
+
+	// the LS port shifts (per-process, volatile) — a fresh probe must RE-DISCOVER it.
+	servingPort = 5003;
+	const r2 = await adapter.probe(CONV);
+	eq(
+		"volatile-route: probe #2 RE-DISCOVERS the changed route = 5003 (no cache)",
+		r2.status === "alive" ? r2.route.lsAddress : "(dead)",
+		"127.0.0.1:5003",
+	);
+	ok(
+		"volatile-route: probe #2 re-ran the pgrep scan (route never stored across dispatches)",
+		calls.filter((c) => c.argv[0] === "pgrep").length === pgrepAfter1 + 1,
+	);
+	ok("volatile-route: probe #2 re-ran the ss scan", calls.filter((c) => c.argv[0] === "ss").length === 2);
+}
+
+// ── send: argv + env; single attempt; non-zero exit throws (fail-loud) ───────
+{
+	const { runner, calls } = makeFakeRunner({ pids: [123], ss: ssLine(5002, 123), serving: () => true });
+	const adapter = createAntigravityAdapter({ runner, binary: FAKE_BINARY });
+	await adapter.send({ lsAddress: "127.0.0.1:5002" }, CONV, "hello world");
+	const sendCall = calls.find((c) => c.argv.includes("send-message"));
+	eq("send: argv === [binary, agentapi, send-message, conv, content]", sendCall?.argv, [
+		FAKE_BINARY,
+		"agentapi",
+		"send-message",
+		CONV,
+		"hello world",
+	]);
+	eq("send: env ANTIGRAVITY_LS_ADDRESS === the route", sendCall?.env?.ANTIGRAVITY_LS_ADDRESS, "127.0.0.1:5002");
+}
+{
+	const { runner, calls } = makeFakeRunner({
+		pids: [123],
+		ss: ssLine(5002, 123),
+		serving: () => true,
+		sendCodes: [1], // first (and only) attempt fails
+	});
+	const adapter = createAntigravityAdapter({ runner, binary: FAKE_BINARY });
+	let threw = false;
+	try {
+		await adapter.send({ lsAddress: "127.0.0.1:5002" }, CONV, "hi");
+	} catch (err) {
+		threw = true;
+		ok("send-fail: error names the non-zero exit", /native-push send failed/.test((err as Error).message));
+	}
+	ok("send-fail: a non-zero exit THROWS (fail-loud)", threw);
+	// NO retry in the adapter: exactly ONE send-message call, no re-probe.
+	eq(
+		"send-fail: adapter makes exactly ONE send attempt (retry is executor-owned, not here)",
+		calls.filter((c) => c.argv.includes("send-message")).length,
+		1,
+	);
+	ok(
+		"send-fail: adapter did NOT re-probe after failure (no pgrep/ss triggered by send)",
+		!calls.some((c) => c.argv[0] === "pgrep"),
+	);
+}
+
+// ── Q12: bounded agy calls — no hang on a stalled LS route ───────────────────
+{
+	// every get-conversation-metadata + send-message call carries a timeout bound.
+	const { runner, calls } = makeFakeRunner({ pids: [123], ss: ssLine(5002, 123), serving: () => true });
+	const adapter = createAntigravityAdapter({ runner, binary: FAKE_BINARY });
+	await adapter.probe(CONV);
+	await adapter.send({ lsAddress: "127.0.0.1:5002" }, CONV, "hi");
+	const metaCall = calls.find((c) => c.argv.includes("get-conversation-metadata"));
+	const sendCall = calls.find((c) => c.argv.includes("send-message"));
+	eq("timeout: get-conversation-metadata carries the metadata timeout", metaCall?.timeoutMs, AGY_METADATA_TIMEOUT_MS);
+	eq("timeout: send-message carries the send timeout", sendCall?.timeoutMs, AGY_SEND_TIMEOUT_MS);
+	ok(
+		"timeout: pgrep is unbounded (fast local scan)",
+		calls.find((c) => c.argv[0] === "pgrep")?.timeoutMs === undefined,
+	);
+}
+{
+	// a metadata TIMEOUT (code 124) on the only port → probe INDETERMINATE (never hangs, never dead).
+	const { runner } = makeFakeRunner({
+		pids: [123],
+		ss: ssLine(5002, 123),
+		serving: () => true,
+		metadataTimeout: true,
+	});
+	const adapter = createAntigravityAdapter({ runner, binary: FAKE_BINARY });
+	const result = await adapter.probe(CONV);
+	ok(
+		"timeout: metadata timeout → probe indeterminate (bounded, not a hang, not dead)",
+		result.status === "indeterminate",
+	);
+}
+{
+	// a send TIMEOUT (code 124) → throws (fail-loud; executor owns the 1-shot re-probe).
+	const { runner } = makeFakeRunner({ pids: [123], ss: ssLine(5002, 123), serving: () => true, sendCodes: [124] });
+	const adapter = createAntigravityAdapter({ runner, binary: FAKE_BINARY });
+	let threw = false;
+	try {
+		await adapter.send({ lsAddress: "127.0.0.1:5002" }, CONV, "hi");
+	} catch {
+		threw = true;
+	}
+	ok("timeout: send timeout (124) → throws (fail-loud)", threw);
+}
+
+// ── resolver fail-fast (mirror resolveAcpBackendAdapter) ─────────────────────
+eq("resolve: antigravity → the antigravity adapter", resolveNativePushAdapter("antigravity").id, "antigravity");
+eq("adapter id: antigravityAdapter.id === antigravity", antigravityAdapter.id, "antigravity");
+{
+	let threw = false;
+	try {
+		resolveNativePushAdapter("codex");
+	} catch {
+		threw = true;
+	}
+	ok("resolve: unknown backend (codex) → throw (no silent default)", threw);
+}
+{
+	let threw = false;
+	try {
+		resolveNativePushAdapter("bogus");
+	} catch {
+		threw = true;
+	}
+	ok("resolve: bogus backend → throw", threw);
+}
+
+// ── Q13 (보정① long-term defense): the native-push file group never reaches for a ──
+// mailbox atom. If either the adapter leaf OR the send hand imported
+// computeMetaReceiverActive / readMetaReceiverMarker / mailboxConversationalDeliverable, a
+// future edit could quietly fold mailbox liveness (watchArmed) into the native-push axis.
+{
+	const libDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "pi-extensions", "lib");
+	const FORBIDDEN = ["computeMetaReceiverActive", "readMetaReceiverMarker", "mailboxConversationalDeliverable"];
+	for (const rel of ["native-push/adapter.ts", "entwurf-v2-native-push.ts", "native-push/register.ts"]) {
+		const src = readFileSync(path.join(libDir, rel), "utf8");
+		for (const atom of FORBIDDEN) {
+			ok(`axis-guard: ${rel} does NOT reference the mailbox atom ${atom} (보정①)`, !src.includes(atom));
+		}
+	}
+}
+
+console.log(`\ncheck-native-push-adapter: ${passed} assertions passed`);

package/scripts/check-native-push-register.ts

@@ -0,0 +1,130 @@
+/**
+ * check-native-push-register — deterministic gate for registerNativeConversation (봉인 5),
+ * the core of the `entwurf_register_native` MCP tool. Drives it with a FAKE adapter (no live
+ * agy) and an ISOLATED temp meta-record store (never the real ~/.pi).
+ *
+ * Proves:
+ *   - live probe → CREATE: a fresh live conversation mints a garden citizen whose meta-record
+ *     carries the backend / nativeSessionId / caller-stated cwd; the action is "create".
+ *   - re-register → ATTACH: the same conversation resolves to the SAME garden id and REFRESHES
+ *     the cwd (봉인 5) — it never mints a second id.
+ *   - not-live probe → REFUSE: a dead / indeterminate probe THROWS and writes NO record (no
+ *     garden id is engraved onto a pointer that does not resolve to a live host).
+ *   - RECEIVER-MARKER ABSTINENCE (보정①): the register source references NO receiver-marker
+ *     writer — a native-push citizen has no idle-wake watch, so arming one would smuggle
+ *     native-push liveness into the mailbox deliverability atom.
+ *
+ * Deterministic (fake adapter); the only IO is an isolated mkdtemp store (like the meta gates).
+ */
+
+import assert from "node:assert/strict";
+import { mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readMetaIdentityByGardenId } from "../pi-extensions/lib/meta-session.ts";
+import type { NativePushAdapter, NativePushProbeResult } from "../pi-extensions/lib/native-push/adapter.ts";
+import { registerNativeConversation } from "../pi-extensions/lib/native-push/register.ts";
+
+let passed = 0;
+function ok(label: string, cond: boolean): void {
+	assert.ok(cond, label);
+	console.log(`  ok    ${label}`);
+	passed++;
+}
+
+const REPO_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+/** A fake native-push adapter whose probe returns a fixed result and whose send is unused. */
+function fakeAdapter(probe: NativePushProbeResult): NativePushAdapter {
+	return {
+		id: "antigravity",
+		async probe() {
+			return probe;
+		},
+		async send() {
+			throw new Error("register gate: adapter.send must not be called during registration");
+		},
+	};
+}
+
+const ALIVE: NativePushProbeResult = { status: "alive", route: { lsAddress: "127.0.0.1:5599" } };
+
+async function main(): Promise<void> {
+	const dir = mkdtempSync(path.join(os.tmpdir(), "entwurf-register-"));
+	try {
+		// ── live probe → CREATE ───────────────────────────────────────────────────
+		const created = await registerNativeConversation(
+			{ backend: "antigravity", nativeSessionId: "conv-abc", cwd: "/work/one" },
+			{ resolveAdapter: () => fakeAdapter(ALIVE), sessionsDir: dir },
+		);
+		ok("create: action = create", created.action === "create");
+		ok("create: gardenId shaped YYYYMMDDTHHMMSS-xxxxxx", /^\d{8}T\d{6}-[0-9a-f]{6}$/.test(created.gardenId));
+		ok("create: backend antigravity", created.backend === "antigravity");
+		ok("create: nativeSessionId echoed", created.nativeSessionId === "conv-abc");
+		ok("create: cwd = caller-stated", created.cwd === "/work/one");
+		// the on-disk record agrees (read back through the authority).
+		const rec = readMetaIdentityByGardenId(created.gardenId, dir);
+		ok("create: record backend antigravity", rec.backend === "antigravity");
+		ok("create: record nativeSessionId bound", rec.nativeSessionId === "conv-abc");
+		ok("create: record cwd recorded", rec.cwd === "/work/one");
+
+		// ── re-register same conversation → ATTACH (same gid, cwd refreshed) ───────
+		const reattached = await registerNativeConversation(
+			{ backend: "antigravity", nativeSessionId: "conv-abc", cwd: "/work/two" },
+			{ resolveAdapter: () => fakeAdapter(ALIVE), sessionsDir: dir },
+		);
+		ok("attach: action = attach", reattached.action === "attach");
+		ok("attach: SAME garden id (no second mint)", reattached.gardenId === created.gardenId);
+		ok(
+			"attach: cwd REFRESHED to the new value",
+			reattached.gardenId === created.gardenId && reattached.cwd === "/work/two",
+		);
+		const rec2 = readMetaIdentityByGardenId(created.gardenId, dir);
+		ok("attach: on-disk cwd refreshed", rec2.cwd === "/work/two");
+		// exactly ONE record file for this conversation (no duplicate mint).
+		const records = readdirSync(dir).filter((f) => f.endsWith(".meta.json"));
+		ok("attach: exactly ONE meta-record (no duplicate garden id)", records.length === 1);
+
+		// ── not-live probe → REFUSE (throw), NO record written ────────────────────
+		for (const probe of [
+			{ status: "dead", reason: "no host" } as const,
+			{ status: "indeterminate", reason: "no port served" } as const,
+		]) {
+			const before = readdirSync(dir).length;
+			let threw = false;
+			try {
+				await registerNativeConversation(
+					{ backend: "antigravity", nativeSessionId: "conv-ghost", cwd: "/work/x" },
+					{ resolveAdapter: () => fakeAdapter(probe), sessionsDir: dir },
+				);
+			} catch (err) {
+				threw = true;
+				ok(
+					`refuse(${probe.status}): error names the non-live probe`,
+					new RegExp(probe.status).test((err as Error).message),
+				);
+			}
+			ok(`refuse(${probe.status}): THROWS (no garden id for a non-live conversation)`, threw);
+			ok(`refuse(${probe.status}): NO record written`, readdirSync(dir).length === before);
+		}
+	} finally {
+		rmSync(dir, { recursive: true, force: true });
+	}
+
+	// ── RECEIVER-MARKER ABSTINENCE (보정①): source references no marker writer ───
+	const src = readFileSync(path.join(REPO_DIR, "pi-extensions", "lib", "native-push", "register.ts"), "utf8");
+	ok("no-marker: register source does NOT call writeMetaReceiverMarker", !/writeMetaReceiverMarker/.test(src));
+	ok("no-marker: register source does NOT reference armProvenance", !/armProvenance/i.test(src));
+	ok(
+		"no-marker: register source does NOT reference META_RECEIVER_ARM_PROVENANCES",
+		!/META_RECEIVER_ARM_PROVENANCES/.test(src),
+	);
+	// it DOES reuse the upsert authority (봉인 5) and the adapter probe.
+	ok("wiring: register reuses upsertMetaSession", /upsertMetaSession/.test(src));
+	ok("wiring: register probes the adapter before minting", /\.probe\(/.test(src));
+
+	console.log(`\ncheck-native-push-register: ${passed} assertions passed`);
+}
+
+void main();

package/scripts/dev-bin.sh

@@ -0,0 +1,195 @@
+#!/usr/bin/env bash
+# dev-bin — expose entwurf's STABLE bins on PATH for a DEV checkout (막힘 ②). A CONSUMER (npm
+# install) gets these bins on PATH from package.json "bin" bin-linking; a DEV checkout does NOT,
+# because pnpm does not self-link a package's own bins. `./run.sh setup` is the dev install
+# command, so setup owns this exposure via MANAGED symlinks
+#   <BIN_DIR>/<name>  ->  <target in this checkout>
+# each recorded in its OWN checkout-OUTSIDE install-state (<name>.install-state.json) for an
+# honest inverse.
+#
+# Managed bins (both are BARE names that configs record — no repo/checkout path is EVER written
+# into any config; this only makes the bare name RESOLVE in a dev checkout):
+#   entwurf-bridge          -> mcp/entwurf-bridge/start.sh    (agy mcp_config command)
+#   entwurf-agy-statusline  -> scripts/agy-statusline.sh      (agy settings.statusLine command)
+#   entwurf-agy-imprint     -> scripts/agy-imprint.sh         (agy PreInvocation birth hook)
+#
+# Ownership discipline (mirrors the agy adopt/refuse rule, 봉인 7), applied PER BIN:
+#   - create/refresh ONLY a link that is OURS — absent, or a symlink into our target, or the
+#     exact link our state recorded (target may have moved checkouts).
+#   - a FOREIGN target (regular file / dir / symlink pointing elsewhere) is REFUSED, never
+#     clobbered (someone else's SSOT).
+#
+# Legacy migration (pre-multi-bin, honest): a single `install-state.json` meant entwurf-bridge.
+# On expose it is ADOPTED as `entwurf-bridge.install-state.json` ONLY when its content is
+# entwurf-bridge's (linkPath basename == entwurf-bridge); corrupt/foreign → refuse+report (never
+# guess). New name appears first (atomic rename), old name is gone after. A re-appearing legacy
+# name on a later expose is re-reported (drift visibility).
+#
+#   expose [name]   create/refresh managed link(s) (idempotent; REFUSE foreign → exit 3).
+#                   no name = all managed bins.
+#   remove [name]   honest inverse from state (remove only OUR link; REFUSE if it became foreign).
+#                   no name = all managed bins.
+#
+# Overridable for the isolated smoke:
+#   ENTWURF_DEV_BIN_DIR            link location (default: ~/.local/bin — where agy itself lives)
+#   ENTWURF_BRIDGE_TARGET         entwurf-bridge target (default: $REPO/mcp/entwurf-bridge/start.sh)
+#   ENTWURF_AGY_STATUSLINE_TARGET entwurf-agy-statusline target (default: $REPO/scripts/agy-statusline.sh)
+#   ENTWURF_AGY_IMPRINT_TARGET    entwurf-agy-imprint target (default: $REPO/scripts/agy-imprint.sh)
+#   XDG_DATA_HOME                 state root (states under $XDG_DATA_HOME/entwurf/dev-bin/)
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_DIR="$(cd "$HERE/.." && pwd)"
+
+BIN_DIR="${ENTWURF_DEV_BIN_DIR:-$HOME/.local/bin}"
+STATE_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/entwurf/dev-bin"
+LEGACY_STATE="$STATE_DIR/install-state.json"   # pre-multi-bin single state == entwurf-bridge
+
+MANAGED_BINS="entwurf-bridge entwurf-agy-statusline entwurf-agy-imprint"
+
+log()  { printf '%s\n' "$*"; }
+warn() { printf '%s\n' "$*" >&2; }
+fail() { printf 'FAIL: %s\n' "$*" >&2; exit 1; }
+
+bin_target() {  # $1 = name → prints target path (env-overridable for smoke)
+  case "$1" in
+    entwurf-bridge)         echo "${ENTWURF_BRIDGE_TARGET:-$REPO_DIR/mcp/entwurf-bridge/start.sh}" ;;
+    entwurf-agy-statusline) echo "${ENTWURF_AGY_STATUSLINE_TARGET:-$REPO_DIR/scripts/agy-statusline.sh}" ;;
+    entwurf-agy-imprint)    echo "${ENTWURF_AGY_IMPRINT_TARGET:-$REPO_DIR/scripts/agy-imprint.sh}" ;;
+    *) return 1 ;;
+  esac
+}
+state_file_for() { echo "$STATE_DIR/$1.install-state.json"; }
+
+state_link() {  # $1 = state file → recorded linkPath, or empty
+  [ -f "$1" ] || { echo ""; return 0; }
+  python3 -c 'import json,sys
+try: print(json.load(open(sys.argv[1])).get("linkPath",""))
+except Exception: print("")' "$1" 2>/dev/null || echo ""
+}
+state_target() {  # $1 = state file → recorded target, or empty
+  [ -f "$1" ] || { echo ""; return 0; }
+  python3 -c 'import json,sys
+try: print(json.load(open(sys.argv[1])).get("target",""))
+except Exception: print("")' "$1" 2>/dev/null || echo ""
+}
+
+# Is $link ours to manage? ours = truly absent OR a symlink into our target OR the exact link our
+# state recorded AND still pointing where we recorded it (moved-checkout relink stays ours; a
+# foreign symlink SWAPPED IN at our recorded path is refused — GPT R). $1=link $2=target $3=state.
+link_is_ours() {
+  local link="$1" target="$2" sf="$3"
+  if [ ! -e "$link" ] && [ ! -L "$link" ]; then return 0; fi   # truly absent (not even dangling)
+  if [ -L "$link" ]; then
+    local cur; cur="$(readlink "$link")"
+    [ "$cur" = "$target" ] && return 0
+    [ "$(state_link "$sf")" = "$link" ] && [ "$cur" = "$(state_target "$sf")" ] && return 0
+    return 1                                                    # foreign symlink
+  fi
+  return 1                                                      # regular file / dir → foreign
+}
+
+path_has_bindir() { case ":$PATH:" in *":$BIN_DIR:"*) return 0 ;; *) return 1 ;; esac; }
+
+write_state() {  # $1=state_file $2=link $3=target $4=detect
+  mkdir -p "$STATE_DIR"
+  python3 - "$1" "$2" "$3" "$4" <<'PY'
+import json, os, sys, tempfile, time
+state, link, target, detect = sys.argv[1:5]
+doc = {"schemaVersion": 1, "linkPath": link, "target": target, "detectMode": detect,
+       "stampedAt": time.strftime("%Y-%m-%dT%H:%M:%S%z")}
+d = os.path.dirname(state)
+fd, tmp = tempfile.mkstemp(dir=d, prefix=".install-state.", suffix=".json")
+with os.fdopen(fd, "w") as f:
+    json.dump(doc, f, indent=2)
+    f.write("\n")
+os.replace(tmp, state)   # atomic
+PY
+}
+
+# Adopt a pre-multi-bin single install-state.json as entwurf-bridge's, content-checked.
+migrate_legacy() {
+  [ -f "$LEGACY_STATE" ] || return 0
+  local new; new="$(state_file_for entwurf-bridge)"
+  [ "$LEGACY_STATE" = "$new" ] && return 0   # defensive (names differ by construction)
+  local verdict
+  verdict="$(python3 - "$LEGACY_STATE" <<'PY'
+import json, os, sys
+try:
+    d = json.load(open(sys.argv[1]))
+    print("yes" if os.path.basename(d.get("linkPath", "")) == "entwurf-bridge" else "no")
+except Exception:
+    print("corrupt")
+PY
+)"
+  case "$verdict" in
+    yes) : ;;
+    no)  fail "dev-bin legacy migration REFUSE: $LEGACY_STATE is not an entwurf-bridge state (linkPath basename != entwurf-bridge). Resolve by hand — refusing to guess." ;;
+    *)   fail "dev-bin legacy migration REFUSE: $LEGACY_STATE is corrupt/unreadable. Resolve by hand." ;;
+  esac
+  if [ -f "$new" ]; then
+    warn "[dev-bin] legacy $LEGACY_STATE re-appeared alongside $new — dropping legacy (already migrated; investigate if recurring)."
+    rm -f "$LEGACY_STATE"
+  else
+    mv "$LEGACY_STATE" "$new"   # atomic rename: new name is present, old is gone
+    log "[dev-bin] migrated legacy dev-bin state → $(basename "$new")"
+  fi
+}
+
+expose_one() {  # $1 = name
+  local name="$1" target link sf detect
+  target="$(bin_target "$name")" || fail "unknown managed bin: $name"
+  link="$BIN_DIR/$name"; sf="$(state_file_for "$name")"
+  log "[dev-bin expose] $name"
+  log "  link:   $link"
+  log "  target: $target"
+  [ -x "$target" ] || fail "target is not an executable file: $target (is this a dev checkout?)"
+  if ! link_is_ours "$link" "$target" "$sf"; then
+    warn "[dev-bin] REFUSE ($name): $link exists and is NOT ours (a foreign file/symlink — e.g. a real npm consumer bin). Not clobbering someone else's SSOT."
+    exit 3
+  fi
+  detect="created-new"; [ -L "$link" ] && detect="refresh-ours"
+  mkdir -p "$BIN_DIR"
+  ln -sfn "$target" "$link"
+  write_state "$sf" "$link" "$target" "$detect"
+  log "  ok: $name → this checkout ($detect)"
+  if ! path_has_bindir; then
+    warn "[dev-bin] WARN: $BIN_DIR is not on PATH — the bare name '$name' will NOT resolve yet. Add it to PATH (we do not touch your profile). doctor stays FAIL until then."
+  fi
+}
+
+remove_one() {  # $1 = name
+  local name="$1" target link sf recorded
+  target="$(bin_target "$name")" || fail "unknown managed bin: $name"
+  link="$BIN_DIR/$name"; sf="$(state_file_for "$name")"
+  log "[dev-bin remove] $name"
+  recorded="$(state_link "$sf")"
+  if [ -z "$recorded" ]; then log "  note: no state for $name — nothing to undo (idempotent)."; return 0; fi
+  if [ -L "$recorded" ]; then
+    if [ "$(readlink "$recorded")" = "$target" ]; then
+      rm -f "$recorded"; log "  removed managed link: $recorded"
+    else
+      fail "refused: $recorded is now a symlink to something else (foreign) — not removing it."
+    fi
+  elif [ -e "$recorded" ]; then
+    fail "refused: $recorded is no longer our symlink (became a regular file/dir) — not removing it."
+  else
+    log "  note: managed link already gone: $recorded"
+  fi
+  rm -f "$sf"
+  rmdir "$STATE_DIR" 2>/dev/null || true
+}
+
+do_expose() {  # $1 = optional bin name
+  migrate_legacy
+  if [ -n "${1:-}" ]; then expose_one "$1"; else for b in $MANAGED_BINS; do expose_one "$b"; done; fi
+}
+do_remove() {  # $1 = optional bin name
+  if [ -n "${1:-}" ]; then remove_one "$1"; else for b in $MANAGED_BINS; do remove_one "$b"; done; fi
+}
+
+case "${1:-}" in
+  expose) shift; do_expose "${1:-}" ;;
+  remove) shift; do_remove "${1:-}" ;;
+  *) echo "usage: dev-bin.sh <expose|remove> [bin-name]" >&2; exit 2 ;;
+esac