@junghanacs/entwurf 0.12.6 → 0.12.7

package/scripts/agy-hooks-config.py

@@ -0,0 +1,257 @@
+#!/usr/bin/env python3
+"""agy-hooks-config — JSON state ops for Antigravity hooks.json imprint wiring.
+
+Owns one top-level named hook, `entwurf-agy-imprint`, preserving every other
+hook. The command is the bare stable bin `entwurf-agy-imprint`.
+"""
+
+import json
+import os
+import sys
+import time
+
+HOOK_KEY = "entwurf-agy-imprint"
+LEGACY_HOOK_KEYS = (HOOK_KEY, "agy-birth-probe")
+EVENT = "PreInvocation"
+OUR_COMMAND = "entwurf-agy-imprint"
+STATE_SCHEMA_VERSION = 1
+
+
+def die(code: int, msg: str) -> None:
+    sys.stderr.write(msg.rstrip("\n") + "\n")
+    sys.exit(code)
+
+
+def atomic_write(path: str, text: str) -> None:
+    os.makedirs(os.path.dirname(os.path.abspath(path)), exist_ok=True)
+    tmp = f"{path}.tmp-{os.getpid()}"
+    with open(tmp, "w", encoding="utf-8") as fh:
+        fh.write(text)
+    os.replace(tmp, path)
+
+
+def load_json(path: str) -> dict:
+    with open(path, "r", encoding="utf-8") as fh:
+        raw = fh.read()
+    if raw.strip() == "":
+        return {}
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as err:
+        die(4, f"agy-hooks: {path} is not valid JSON: {err}")
+    if not isinstance(data, dict):
+        die(4, f"agy-hooks: {path} top-level must be a JSON object")
+    return data
+
+
+def dump(data: dict) -> str:
+    return json.dumps(data, indent=2) + "\n"
+
+
+def now() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def hook_value(command: str) -> dict:
+    return {EVENT: [{"type": "command", "command": command}]}
+
+
+def hook_command(value) -> str | None:
+    if not isinstance(value, dict):
+        return None
+    handlers = value.get(EVENT)
+    if not isinstance(handlers, list):
+        return None
+    for item in handlers:
+        if isinstance(item, dict) and item.get("type") == "command" and isinstance(item.get("command"), str):
+            return item["command"]
+    return None
+
+
+def prior_state(state_path: str, hooks_path: str) -> dict:
+    """The state of OUR FIRST install of this exact hooks file, if we are re-installing over it.
+
+    Empty when there is no prior install, or when it managed a DIFFERENT path (a re-target is a
+    fresh install for that path). See the note in cmd_install for why this exists.
+    """
+    if not os.path.exists(state_path):
+        return {}
+    prior = load_json(state_path)
+    if prior.get("managedHooksPath") != os.path.abspath(hooks_path):
+        return {}
+    return prior
+
+
+def cmd_install(hooks_path: str, command: str, state_path: str) -> None:
+    if os.path.islink(hooks_path):
+        die(3, f"agy-hooks: refusing to adopt {hooks_path} — it is a symlink to {os.readlink(hooks_path)} (someone else's SSOT).")
+    existed = os.path.exists(hooks_path)
+    if existed:
+        data = load_json(hooks_path)
+        mode = "adopt-regular-file"
+    else:
+        data = {}
+        mode = "created-new"
+    # Capture the preimage ONLY on the first install of this target. An installer is re-run on every
+    # upgrade; re-capturing here would record OUR OWN previous hook as "what was there before", and
+    # uninstall would then faithfully restore us — leaving behind the exact thing it exists to
+    # remove. Provenance is a fact about a moment that has passed: record it once, carry it forward.
+    prior = prior_state(state_path, hooks_path)
+    if prior:
+        preimage = prior.get("preimage", None)
+        mode = prior.get("detectMode", mode)
+        existed = prior.get("hooksExistedBefore", existed)
+    else:
+        preimage = data.get(HOOK_KEY, None)
+    data[HOOK_KEY] = hook_value(command)
+    atomic_write(hooks_path, dump(data))
+    state = {
+        "schemaVersion": STATE_SCHEMA_VERSION,
+        "managedHooksPath": os.path.abspath(hooks_path),
+        "hookKey": HOOK_KEY,
+        "event": EVENT,
+        "command": command,
+        "detectMode": mode,
+        "hooksExistedBefore": existed,
+        "preimage": preimage,
+        "installedAt": now(),
+    }
+    atomic_write(state_path, dump(state))
+    sys.stdout.write(f"{mode} {os.path.abspath(hooks_path)}\n")
+
+
+def cmd_uninstall(state_path: str) -> None:
+    if not os.path.exists(state_path):
+        die(2, f"agy-hooks: no install-state at {state_path} — nothing to uninstall")
+    state = load_json(state_path)
+    hooks_path = state.get("managedHooksPath")
+    if not isinstance(hooks_path, str):
+        die(4, f"agy-hooks: install-state {state_path} has no managedHooksPath")
+    if os.path.islink(hooks_path):
+        die(3, f"agy-hooks: refusing to uninstall — {hooks_path} became a symlink since install")
+    if os.path.exists(hooks_path):
+        data = load_json(hooks_path)
+        preimage = state.get("preimage", None)
+        if preimage is None:
+            data.pop(HOOK_KEY, None)
+        else:
+            data[HOOK_KEY] = preimage
+        created_new = state.get("detectMode") == "created-new" and state.get("hooksExistedBefore") is False
+        if created_new and len(data) == 0:
+            os.remove(hooks_path)
+        else:
+            atomic_write(hooks_path, dump(data))
+    os.remove(state_path)
+    sys.stdout.write(f"uninstalled {hooks_path}\n")
+
+
+def same_path(left: str, right: str) -> bool:
+    try:
+        return os.path.realpath(left) == os.path.realpath(right)
+    except Exception:
+        return os.path.abspath(left) == os.path.abspath(right)
+
+
+def legacy_owned_keys(data: dict) -> list[str]:
+    return [key for key in LEGACY_HOOK_KEYS if key in data]
+
+
+def cmd_cleanup_legacy(legacy_path: str, active_path: str) -> None:
+    if same_path(legacy_path, active_path):
+        sys.stdout.write("same-path\n")
+        return
+    if not os.path.lexists(legacy_path):
+        sys.stdout.write("absent\n")
+        return
+    if os.path.islink(legacy_path):
+        die(3, f"agy-hooks: refusing to clean legacy {legacy_path} — it is a symlink to {os.readlink(legacy_path)} (someone else's SSOT).")
+    data = load_json(legacy_path)
+    removed = legacy_owned_keys(data)
+    if not removed:
+        sys.stdout.write("clean\n")
+        return
+    for key in removed:
+        data.pop(key, None)
+    if data:
+        atomic_write(legacy_path, dump(data))
+    else:
+        os.remove(legacy_path)
+    sys.stdout.write(f"removed {','.join(removed)}\n")
+
+
+def cmd_doctor_legacy(legacy_path: str, active_path: str) -> None:
+    if same_path(legacy_path, active_path):
+        sys.stdout.write("same-path\n")
+        return
+    if not os.path.lexists(legacy_path):
+        sys.stdout.write("absent\n")
+        return
+    if os.path.islink(legacy_path):
+        sys.stdout.write(f"symlink {os.readlink(legacy_path)}\n")
+        return
+    try:
+        data = load_json(legacy_path)
+    except SystemExit:
+        sys.stdout.write("invalid-json\n")
+        return
+    owned = legacy_owned_keys(data)
+    if owned:
+        sys.stdout.write(f"owned {','.join(owned)}\n")
+        return
+    sys.stdout.write("clean\n")
+
+
+def cmd_doctor_static(hooks_path: str) -> None:
+    real = os.path.realpath(hooks_path)
+    if not os.path.exists(real):
+        sys.stdout.write("file-absent\n")
+        return
+    try:
+        with open(real, "r", encoding="utf-8") as fh:
+            data = json.loads(fh.read() or "{}")
+    except (json.JSONDecodeError, OSError):
+        sys.stdout.write("invalid-json\n")
+        return
+    if not isinstance(data, dict):
+        sys.stdout.write("invalid-json\n")
+        return
+    value = data.get(HOOK_KEY)
+    cmd = hook_command(value)
+    if not cmd:
+        sys.stdout.write("not-configured\n")
+        return
+    if cmd != OUR_COMMAND:
+        sys.stdout.write("not-ours\n")
+        return
+    sys.stdout.write(f"configured {cmd}\n")
+
+
+def main(argv: list[str]) -> None:
+    if len(argv) < 2:
+        die(5, "usage: agy-hooks-config.py <install|uninstall|doctor-static> ...")
+    if argv[1] == "install":
+        if len(argv) != 5:
+            die(5, "usage: agy-hooks-config.py install <hooks_path> <command> <state_path>")
+        cmd_install(argv[2], argv[3], argv[4])
+    elif argv[1] == "uninstall":
+        if len(argv) != 3:
+            die(5, "usage: agy-hooks-config.py uninstall <state_path>")
+        cmd_uninstall(argv[2])
+    elif argv[1] == "doctor-static":
+        if len(argv) != 3:
+            die(5, "usage: agy-hooks-config.py doctor-static <hooks_path>")
+        cmd_doctor_static(argv[2])
+    elif argv[1] == "cleanup-legacy":
+        if len(argv) != 4:
+            die(5, "usage: agy-hooks-config.py cleanup-legacy <legacy_hooks_path> <active_hooks_path>")
+        cmd_cleanup_legacy(argv[2], argv[3])
+    elif argv[1] == "doctor-legacy":
+        if len(argv) != 4:
+            die(5, "usage: agy-hooks-config.py doctor-legacy <legacy_hooks_path> <active_hooks_path>")
+        cmd_doctor_legacy(argv[2], argv[3])
+    else:
+        die(5, f"agy-hooks-config.py: unknown subcommand {argv[1]!r}")
+
+
+if __name__ == "__main__":
+    main(sys.argv)

package/scripts/agy-imprint.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Stable bin wrapper for Antigravity PreInvocation birth imprint.
+set -euo pipefail
+SELF="${BASH_SOURCE[0]}"
+if command -v readlink >/dev/null 2>&1; then
+  RESOLVED="$(readlink -f "$SELF" 2>/dev/null || printf '%s' "$SELF")"
+else
+  RESOLVED="$SELF"
+fi
+HERE="$(cd "$(dirname "$RESOLVED")" && pwd)"
+ROOT="$(cd "$HERE/.." && pwd)"
+
+# Node refuses --experimental-strip-types for raw .ts below node_modules. Dev
+# clones keep the transparent source path; installed npm/pnpm bins must use the
+# prepack-emitted JS closure, exactly like entwurf-bridge and meta-bridge hooks.
+case "$ROOT" in
+  */node_modules/*)
+    DIST="$ROOT/mcp/entwurf-bridge/dist/scripts/agy-imprint.js"
+    if [ ! -f "$DIST" ]; then
+      echo "entwurf-agy-imprint: installed package is missing prebuilt $DIST" >&2
+      exit 1
+    fi
+    exec node "$DIST"
+    ;;
+  *)
+    exec node --experimental-strip-types "$HERE/agy-imprint.ts"
+    ;;
+esac

package/scripts/agy-imprint.ts

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+/**
+ * entwurf-agy-imprint — Antigravity PreInvocation birth hook.
+ *
+ * Reads agy's camelCase PreInvocation payload from stdin, idempotently upserts an
+ * antigravity meta-session by conversationId, writes the sender marker that lets the
+ * entwurf-bridge MCP child name this conversation as the caller, and ALWAYS prints exactly
+ * the PreInvocation neutral response so the agy loop keeps running.
+ *
+ * Still deliberately thin: no transcript hydration, no cwd guessing from process.cwd(), and
+ * NO receiver marker — that is a mailbox atom, and agy is a native-push citizen with no
+ * mailbox (보정①). The record body is the authority; the sender marker is only a pid→garden
+ * hint the bridge re-validates against it.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import {
+	parentPid,
+	processStartKey,
+	upsertMetaSession,
+	writeMetaSenderMarker,
+} from "../pi-extensions/lib/meta-session.ts";
+
+const NEUTRAL_RESPONSE = '{"injectSteps":[]}';
+
+type Payload = {
+	conversationId?: unknown;
+	workspacePaths?: unknown;
+	transcriptPath?: unknown;
+	modelName?: unknown;
+};
+
+function logPath(): string {
+	const root = process.env.XDG_STATE_HOME || path.join(os.homedir(), ".local", "state");
+	return path.join(root, "entwurf", "agy-imprint.log");
+}
+
+function logLine(message: string): void {
+	try {
+		const file = logPath();
+		fs.mkdirSync(path.dirname(file), { recursive: true });
+		fs.appendFileSync(file, `${new Date().toISOString()} ${message}\n`, { encoding: "utf8", mode: 0o600 });
+	} catch {
+		// Logging is best-effort; never break agy's PreInvocation loop.
+	}
+}
+
+/**
+ * OPT-IN owner-topology trace (`ENTWURF_AGY_TRACE_OWNER=1`).
+ *
+ * The whole sender lane rests on one measured fact: this hook's parent IS the process that also
+ * parents the MCP child (both are the agy host). When a send from a birthed agy still arrives
+ * anonymous, this trace is the only thing that can say WHY — a plugin host in between, a per-turn
+ * worker, a shell wrapper. Compare it with the live bridge's own ancestry (`/proc/<pid>/stat`).
+ *
+ * OFF by default, and it must stay off: PreInvocation runs before EVERY model turn, so leaving it
+ * on would append a line and walk /proc six times per turn, forever — an unbounded trace in a log
+ * whose job is to hold birth evidence. The normal log already records the marker write (pid → gid),
+ * which is what a healthy host needs.
+ */
+function comm(pid: number): string {
+	try {
+		return fs.readFileSync(`/proc/${pid}/comm`, "utf8").trim() || "?";
+	} catch {
+		return "?";
+	}
+}
+
+function ancestry(startPid: number, depth = 6): string {
+	const steps: string[] = [];
+	let pid: number | null = startPid;
+	for (let i = 0; i < depth && typeof pid === "number" && pid > 1; i++) {
+		steps.push(`${pid}:${comm(pid)}:${processStartKey(pid) || "-"}`);
+		pid = parentPid(pid);
+	}
+	return steps.join(" < ");
+}
+
+function traceOwnerTopology(conversationId: string): void {
+	if (process.env.ENTWURF_AGY_TRACE_OWNER !== "1") return;
+	logLine(
+		`pids conversationId=${conversationId} hookPid=${process.pid} ppid=${process.ppid} chain=${ancestry(process.pid)}`,
+	);
+}
+
+function readStdin(): string {
+	try {
+		return fs.readFileSync(0, "utf8");
+	} catch (err) {
+		logLine(`read-stdin-failed ${err instanceof Error ? err.message : String(err)}`);
+		return "";
+	}
+}
+
+function firstWorkspace(value: unknown): string | null {
+	if (!Array.isArray(value)) return null;
+	const first = value[0];
+	return typeof first === "string" && first.trim() ? first : null;
+}
+
+function optionalString(value: unknown): string | null {
+	return typeof value === "string" && value.trim() ? value : null;
+}
+
+function imprint(raw: string): void {
+	let payload: Payload;
+	try {
+		const parsed = JSON.parse(raw || "{}");
+		payload = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? (parsed as Payload) : {};
+	} catch (err) {
+		logLine(`skip invalid-json ${err instanceof Error ? err.message : String(err)}`);
+		return;
+	}
+
+	const conversationId = optionalString(payload.conversationId);
+	if (!conversationId) {
+		logLine("skip missing-conversationId");
+		return;
+	}
+
+	const cwd = firstWorkspace(payload.workspacePaths);
+	if (!cwd) {
+		logLine(`skip missing-workspacePaths conversationId=${conversationId}`);
+		return;
+	}
+
+	traceOwnerTopology(conversationId);
+
+	try {
+		const result = upsertMetaSession({
+			input: {
+				backend: "antigravity",
+				nativeSessionId: conversationId,
+				cwd,
+				model: optionalString(payload.modelName),
+				transcriptPath: optionalString(payload.transcriptPath),
+			},
+		});
+		logLine(`ok ${result.action} gardenId=${result.record.gardenId} conversationId=${conversationId} cwd=${cwd}`);
+
+		// Sender marker — what lets the entwurf-bridge MCP child name WHO is calling it. The
+		// bridge and this hook are both children of the same agy process (measured: hook.ppid ==
+		// bridge.ppid == the `agy` pid, identical start-key), so that pid is the join key; the
+		// bridge looks a marker up under its own parent, finds this one, and the send goes out as
+		// a replyable garden citizen instead of anonymous external-mcp.
+		//
+		// The marker binds the pid to the conversation it is CURRENTLY invoking — not to one
+		// conversation forever. PreInvocation runs synchronously before every model turn, so a
+		// `/new` (same pid, new conversationId) rebinds the marker before that conversation can
+		// make its first tool call. Overwriting is a binding refresh, not an identity mutation:
+		// both conversations keep their meta-records.
+		//
+		// THE LIMIT, stated plainly: one pid has exactly ONE marker file per backend
+		// (`<senders>/antigravity/<pid>.json`). Two conversations invoking CONCURRENTLY under one
+		// agy process would therefore NOT leave two markers for the bridge to refuse — the second
+		// hook write silently overwrites the first, and a tool call still in flight from the first
+		// would be attributed to the second. Nothing downstream can detect that. So this binding
+		// rests on a runtime invariant: an agy process serializes its model invocations (its hook
+		// runs synchronously before each turn). Same-process concurrency is NOT supported, and
+		// there is no fail-closed guard for it — if agy ever gains it, the pid stops identifying
+		// the caller and the join key must change.
+		//
+		// Written only after the upsert above: the record store is the identity authority, and a
+		// marker pointing at a garden-id with no record would be a window of un-backed identity.
+		// A failed marker costs reply-addressability, never the session — log and move on.
+		const ownerPid = process.ppid;
+		if (typeof ownerPid === "number" && ownerPid > 0) {
+			try {
+				writeMetaSenderMarker({
+					backend: "antigravity",
+					gardenId: result.record.gardenId,
+					nativeSessionId: conversationId,
+					cwd,
+					ownerPid,
+				});
+				logLine(`sender marker ${ownerPid} -> ${result.record.gardenId} conversationId=${conversationId}`);
+			} catch (err) {
+				logLine(
+					`sender-marker-failed pid=${ownerPid} gardenId=${result.record.gardenId} ${err instanceof Error ? err.message : String(err)}`,
+				);
+			}
+		}
+	} catch (err) {
+		logLine(
+			`upsert-failed conversationId=${conversationId} ${err instanceof Error ? err.stack || err.message : String(err)}`,
+		);
+	}
+}
+
+imprint(readStdin());
+process.stdout.write(`${NEUTRAL_RESPONSE}\n`);

package/scripts/agy-statusline-bridge.sh

@@ -0,0 +1,176 @@
+#!/usr/bin/env bash
+# agy-statusline-bridge — install/uninstall/doctor for the agy (Antigravity) statusLine ownership
+# (#46 Task 1). Sets agy settings.statusLine to entwurf's stable-bin renderer so the ambient
+# status area shows driver + garden id (the claude meta-bridge statusLine symmetry, mirrored as a
+# SEPARATE agy adapter — 봉인 7). SEPARATE state from agy-bridge (mcp_config) and dev-bin.
+#
+#   install    own the WHOLE statusLine subtree of agy settings.json → {type:custom,
+#              command:entwurf-agy-statusline, enabled:true} (adopt a regular file / create /
+#              REFUSE a symlink), recording an install-state for an honest inverse. The command
+#              is a BARE stable bin — dev resolves it via `expose-dev-bin`, installed via the npm
+#              bin-link. NEVER a repo/checkout path (#46 tripwire).
+#   uninstall  honest inverse from the install-state (restore the captured statusLine preimage).
+#   doctor     STATIC: settings.json (the SINGLE root agy reads statusLine from — proven by the
+#              Task-1 capture, NOT the 2-candidate mcp_config root) resolves, parses, and carries
+#              OUR command that RESOLVES. LIVE: only when an agy process exists, else honest SKIP.
+#
+# Paths (all overridable for the isolated smoke):
+#   AGY_SETTINGS_CONFIG    install target       (default: ~/.gemini/antigravity-cli/settings.json)
+#   AGY_STATUSLINE_COMMAND command to register  (default: entwurf-agy-statusline — a stable bin)
+#   XDG_DATA_HOME          install-state root    (state at $XDG_DATA_HOME/entwurf/agy-statusline/)
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CONFIG_PY="$HERE/agy-statusline-config.py"
+
+SETTINGS="${AGY_SETTINGS_CONFIG:-$HOME/.gemini/antigravity-cli/settings.json}"
+COMMAND="${AGY_STATUSLINE_COMMAND:-entwurf-agy-statusline}"
+STATE_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/entwurf/agy-statusline"
+STATE_FILE="$STATE_DIR/install-state.json"
+
+log()  { printf '%s\n' "$*"; }
+fail() { printf 'FAIL: %s\n' "$*" >&2; exit 1; }
+
+# Is COMMAND runnable? NOTE: this checks OUR shell's PATH. The honest question is "does the bin
+# resolve in the environment AGY runs in" — agy lives at ~/.local/bin/agy, so a dev-bin link in
+# ~/.local/bin (agy's own dir) naturally shares that PATH. This check is the best local proxy; a
+# PATH divergence between our shell and agy's would still be a real (rare) gap. A bare name is
+# looked up on PATH; an absolute/relative path must be an executable file.
+command_resolvable() {
+  local cmd="$1"
+  case "$cmd" in
+    */*) [ -x "$cmd" ] ;;
+    *)   command -v "$cmd" >/dev/null 2>&1 ;;
+  esac
+}
+
+do_install() {
+  log "[agy-statusline install]"
+  log "  target:  $SETTINGS"
+  log "  command: $COMMAND"
+  log "  state:   $STATE_FILE"
+  if ! command_resolvable "$COMMAND"; then
+    log "  note: '$COMMAND' is not currently resolvable on this host — install still records it"
+    log "        (expose-dev-bin/npm bin-link provides it; doctor will FAIL until it is on PATH)."
+  fi
+  local out rc
+  set +e
+  out="$(python3 "$CONFIG_PY" install "$SETTINGS" "$COMMAND" "$STATE_FILE" 2>&1)"
+  rc=$?
+  set -e
+  case "$rc" in
+    0) log "  ok: ${out}" ;;
+    3) fail "refused (symlink) — ${out}" ;;
+    4) fail "invalid JSON — ${out}" ;;
+    *) fail "install error (rc=$rc) — ${out}" ;;
+  esac
+  log "  installed. Verify with: ./run.sh doctor-agy-statusline"
+}
+
+do_uninstall() {
+  log "[agy-statusline uninstall]"
+  log "  state: $STATE_FILE"
+  local out rc
+  set +e
+  out="$(python3 "$CONFIG_PY" uninstall "$STATE_FILE" 2>&1)"
+  rc=$?
+  set -e
+  case "$rc" in
+    0) log "  ok: ${out}" ;;
+    2) log "  note: ${out}" ;;          # no state → nothing to undo (idempotent)
+    3) fail "refused (symlink) — ${out}" ;;
+    *) fail "uninstall error (rc=$rc) — ${out}" ;;
+  esac
+}
+
+do_doctor() {
+  log "[agy-statusline doctor]"
+  local hard_fail=0 runtime_ready=0 link_note=""
+  if [ -L "$SETTINGS" ]; then
+    link_note=" [symlink → $(readlink "$SETTINGS")]"
+  fi
+
+  log "── static (settings root: the single root agy reads statusLine from)"
+  local status
+  status="$(python3 "$CONFIG_PY" doctor-static "$SETTINGS")"
+  case "$status" in
+    file-absent)    log "  settings: file absent$link_note" ;;
+    absent)         log "  settings: statusLine absent$link_note" ;;
+    invalid-json)   log "  settings: INVALID JSON$link_note"; hard_fail=1 ;;
+    not-ours)       log "  settings: statusLine present but NOT entwurf-owned (still the prior/agent-config command)$link_note" ;;
+    configured\ *)
+      local cmd="${status#configured }"
+      if command_resolvable "$cmd"; then
+        runtime_ready=1
+        log "  settings: configured → '$cmd' (resolvable)$link_note"
+      else
+        log "  settings: configured → '$cmd' DANGLING (not on PATH / not executable — run expose-dev-bin)$link_note"
+        hard_fail=1
+      fi ;;
+    *) log "  settings: unexpected status '$status'$link_note"; hard_fail=1 ;;
+  esac
+
+  # state-evidence (mirrors agy-bridge N1): install-state present ⇒ its managed settings MUST
+  # still configure OUR command. state ∧ not-configured = DRIFT (installed, then removed) → FAIL.
+  if [ -f "$STATE_FILE" ]; then
+    local managed expected_settings
+    expected_settings="$(python3 -c 'import os,sys; print(os.path.abspath(sys.argv[1]))' "$SETTINGS")"
+    if ! managed="$(python3 -c 'import json,os,sys; v=json.load(open(sys.argv[1])).get("managedSettingsPath"); assert isinstance(v,str) and os.path.isabs(v); print(os.path.abspath(v))' "$STATE_FILE" 2>/dev/null)"; then
+      # isabs: install always records an absolute path — a relative one is corrupt, and
+      # normalizing it against OUR cwd could bless whatever directory the doctor runs from.
+      log "  state: CORRUPT — install-state is unreadable or its managedSettingsPath is missing/non-absolute: $STATE_FILE"
+      hard_fail=1
+    elif [ "$managed" != "$expected_settings" ]; then
+      # The state describes a DIFFERENT settings file than the one agy reads here. The live
+      # statusLine's provenance (whose command was there before ours) is therefore NOT recorded:
+      # uninstalling would drop the key instead of restoring the operator's own command. A test
+      # run that isolated HOME but SHARED XDG_DATA_HOME produces exactly this shape.
+      log "  state: FOREIGN TARGET — install-state manages '$managed', but agy reads '$expected_settings' on this host. The live statusLine has no recorded preimage, so uninstall could not restore what was there before. Re-run install-agy-statusline against this host (and check whether an isolated test leaked its state)."
+      hard_fail=1
+    else
+      local managed_status
+      managed_status="$(python3 "$CONFIG_PY" doctor-static "$managed")"
+      case "$managed_status" in
+        configured\ *) log "  state: install-state present; its managed settings still configure entwurf-agy-statusline." ;;
+        file-absent)
+          log "  state: ORPHANED — install-state records $managed but the file is absent (HOME reset). Auto-cleaning stale state."
+          rm -f "$STATE_FILE"
+          ;;
+        *) log "  state: DRIFT — install-state records $managed but it no longer configures entwurf-agy-statusline (removed since install)."; hard_fail=1 ;;
+      esac
+    fi
+  else
+    case "$status" in
+      configured\ *) : ;;
+      *) log "  note: no install-state and statusLine not entwurf-owned (never installed — this is the '?'; run install-agy-statusline)." ;;
+    esac
+  fi
+
+  log "── live (runtime wiring)"
+  if command -v pgrep >/dev/null 2>&1 && pgrep -x agy >/dev/null 2>&1; then
+    if [ "$runtime_ready" -eq 1 ]; then
+      if [ "$hard_fail" -eq 0 ]; then
+        log "  live: agy is running AND statusLine resolves to our renderer — consistent with runtime wiring (statusline read NOT proven; agy re-reads settings on launch)."
+      else
+        log "  live: agy is running and statusLine resolves to our renderer, but ownership/state errors above keep this doctor red (statusline read NOT proven)."
+      fi
+    else
+      log "  live: agy is running but statusLine is not our resolvable command — runtime wiring is broken."
+      hard_fail=1
+    fi
+  else
+    log "  live: SKIP — no agy process (cannot check runtime wiring; NOT a pass)."
+  fi
+
+  if [ "$hard_fail" -ne 0 ]; then
+    fail "doctor found a broken statusLine (invalid JSON / dangling command / drift / broken live wiring)."
+  fi
+  log "doctor: ok."
+}
+
+case "${1:-}" in
+  install)   do_install ;;
+  uninstall) do_uninstall ;;
+  doctor)    do_doctor ;;
+  *) echo "usage: agy-statusline-bridge.sh <install|uninstall|doctor>" >&2; exit 2 ;;
+esac