@junghanacs/entwurf 0.39.0 → 0.41.0

package/mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-send.js

@@ -0,0 +1,259 @@
+/**
+ * remote-pair-send — the SENDING half of #107's one declared remote pair (rail 2a).
+ *
+ * It sits in front of the local v2 decider, at the surface. With no route declaration, or a target
+ * the declaration does not name, the local path runs unchanged. When the declaration names the
+ * target, any local trace of that gid (a record entry in any state, or anything at its control
+ * socket path) fails closed as an ambiguity before transport. Otherwise the call runs over one
+ * transport call: no synthetic record, no new backend, no new rail plan, and no retry.
+ *
+ * Sender: only the caller's authoritative envelope becomes the claim. It must be the declared local
+ * citizen; an anonymous envelope or another gid is refused before transport. The model chooses
+ * neither host nor command: both come from the operator's declaration.
+ *
+ * Remote command: ssh joins the remote words into one shell string. So the alias and the remote
+ * declaration path are held to a narrow POSIX-safe charset that needs no quoting, and the command
+ * is the fixed `entwurf remote-pair-receive --pair <path>`. There is no quoting engine here.
+ *
+ * Receipt: a result is decided only when the exit code and the one stdout JSON line agree
+ * (see {@link classifyRemoteReceipt}). Everything else is `remote-indeterminate`: the other host
+ * may or may not have enqueued. Read and answer stay unknown until a reply arrives.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { controlSocketPathIn } from "./control-socket-path.js";
+import { defaultMetaSessionsDir, metaRecordExistsByGardenId, requireGardenId } from "./meta-session.js";
+import { inspectControlSocketPath } from "./socket-discovery.js";
+export class RemoteRouteDeclarationError extends Error {
+}
+const SSH_ALIAS = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const REMOTE_PATH = /^\/[A-Za-z0-9._/-]+$/;
+const CONNECT_TIMEOUT_SECONDS = 10;
+export const REMOTE_SEND_TIMEOUT_MS = 30_000;
+const PAIR_REJECT_REASONS = ["remote-pair-from-mismatch", "remote-pair-target-mismatch"];
+export function parseRemoteRouteDeclaration(text) {
+    const what = "remote route declaration";
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (err) {
+        throw new RemoteRouteDeclarationError(`${what}: not JSON (${err instanceof Error ? err.message : String(err)})`);
+    }
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new RemoteRouteDeclarationError(`${what}: must be a JSON object`);
+    }
+    const obj = raw;
+    const want = ["localGardenId", "remoteGardenId", "remotePairFile", "ssh"];
+    const got = Object.keys(obj).sort();
+    if (got.length !== want.length || got.some((k, i) => k !== want[i])) {
+        throw new RemoteRouteDeclarationError(`${what}: keys must be exactly ${want.join(", ")} (got ${got.join(", ")})`);
+    }
+    const { ssh, remotePairFile } = obj;
+    if (typeof ssh !== "string" || !SSH_ALIAS.test(ssh)) {
+        throw new RemoteRouteDeclarationError(`${what}: "ssh" must be an alias matching ${SSH_ALIAS}`);
+    }
+    if (typeof remotePairFile !== "string" ||
+        !REMOTE_PATH.test(remotePairFile) ||
+        remotePairFile.split("/").includes("..")) {
+        throw new RemoteRouteDeclarationError(`${what}: "remotePairFile" must be an absolute path matching ${REMOTE_PATH} with no ".." segment`);
+    }
+    return {
+        remoteGardenId: requireGardenId(obj.remoteGardenId),
+        ssh,
+        localGardenId: requireGardenId(obj.localGardenId),
+        remotePairFile,
+    };
+}
+/** The one argv the transport runs. Every word is inside the no-quoting charset above. */
+export function remoteReceiveArgv(route) {
+    return [
+        "ssh",
+        "-o",
+        "BatchMode=yes",
+        "-o",
+        `ConnectTimeout=${CONNECT_TIMEOUT_SECONDS}`,
+        route.ssh,
+        "entwurf",
+        "remote-pair-receive",
+        "--pair",
+        route.remotePairFile,
+    ];
+}
+function tail(s) {
+    return s.length > 400 ? s.slice(-400) : s;
+}
+/**
+ * Decide only on agreement. 0 + dispatched/!isError = accepted; 3 + rejected(pair reason) = pair
+ * refused; 4 + dispatched/isError = the other host reported an error while processing (its own text
+ * says what is known, e.g. `retry-safe: false` after a possible write; this line infers neither
+ * delivery nor non-delivery); 2 + invalid = it refused our
+ * input. Any other exit, a signal, a timeout, no line, more than one line, non-JSON, or a JSON
+ * kind/field that disagrees with the exit is indeterminate.
+ */
+export function classifyRemoteReceipt(r) {
+    const indeterminate = (why) => ({
+        kind: "remote-indeterminate",
+        why,
+        exitCode: r.exitCode,
+        stderrTail: tail(r.stderr),
+    });
+    if (r.timedOut)
+        return indeterminate("timed out");
+    if (r.signal !== null)
+        return indeterminate(`ended by signal ${r.signal}`);
+    if (r.exitCode === null) {
+        return indeterminate(r.stderr.startsWith("spawn failed")
+            ? "the transport did not start (spawn failed)"
+            : "did not exit (no exit code)");
+    }
+    if (![0, 2, 3, 4].includes(r.exitCode))
+        return indeterminate(`exit ${r.exitCode}`);
+    const nl = r.stdout.indexOf("\n");
+    if (nl === -1 || nl !== r.stdout.length - 1)
+        return indeterminate("stdout is not exactly one line");
+    let j;
+    try {
+        j = JSON.parse(r.stdout);
+    }
+    catch {
+        return indeterminate("stdout is not JSON");
+    }
+    if (j === null || typeof j !== "object" || Array.isArray(j))
+        return indeterminate("stdout is not a JSON object");
+    const o = j;
+    const keys = Object.keys(o).sort().join(",");
+    if (r.exitCode === 0 && keys === "isError,kind,text" && o.kind === "dispatched" && o.isError === false) {
+        if (typeof o.text === "string")
+            return { kind: "remote-accepted", text: o.text };
+    }
+    if (r.exitCode === 4 && keys === "isError,kind,text" && o.kind === "dispatched" && o.isError === true) {
+        if (typeof o.text === "string")
+            return { kind: "remote-reported-error", text: o.text };
+    }
+    if (r.exitCode === 3 && keys === "detail,kind,reason" && o.kind === "rejected") {
+        if (typeof o.reason === "string" && PAIR_REJECT_REASONS.includes(o.reason) && typeof o.detail === "string") {
+            return { kind: "remote-pair-refused", reason: o.reason, detail: o.detail };
+        }
+    }
+    if (r.exitCode === 2 && keys === "detail,kind" && o.kind === "invalid" && typeof o.detail === "string") {
+        return { kind: "remote-invalid", detail: o.detail };
+    }
+    return indeterminate(`exit ${r.exitCode} disagrees with its receipt`);
+}
+function render(route, o) {
+    const via = `via ${route.ssh}`;
+    switch (o.kind) {
+        case "remote-accepted":
+            return {
+                isError: false,
+                text: `entwurf_v2 remote ${via} → accepted by the other host (its fact; read/answer unknown until a reply arrives; paths below are on the other host)\n${o.text}`,
+            };
+        case "remote-reported-error":
+            // The other host's dispatch returned isError. That can follow a write (an enqueue whose
+            // stamp or signal then threw is `retry-safe: false`), so this header claims neither
+            // non-delivery nor safety to resend: the other host's own text below is the fact.
+            return {
+                isError: true,
+                text: `entwurf_v2 remote ${via} → the other host reported an error while processing; read its receipt below, delivery is not inferred from this line; not retried (paths below are on the other host)\n${o.text}`,
+            };
+        case "remote-pair-refused":
+            return {
+                isError: true,
+                text: `entwurf_v2 remote ${via} → refused by the other host's pair: ${o.reason} (${o.detail})`,
+            };
+        case "remote-invalid":
+            return { isError: true, text: `entwurf_v2 remote ${via} → the other host refused the input: ${o.detail}` };
+        case "remote-indeterminate":
+            return {
+                isError: true,
+                text: `entwurf_v2 remote ${via} → indeterminate: ${o.why}. The other host may or may not have enqueued; ` +
+                    `not retried.${o.stderrTail ? `\n${o.stderrTail}` : ""}`,
+            };
+    }
+}
+function refuse(text) {
+    return { isError: true, text: `entwurf_v2 rejected: ${text}` };
+}
+export async function runEntwurfV2WithRemoteRoute(params, opts) {
+    const route = opts.route;
+    if (route === null || params.target !== route.remoteGardenId) {
+        return opts.runLocal(params, { senderProvider: opts.senderProvider });
+    }
+    if (await opts.localTrace(route.remoteGardenId)) {
+        return refuse(`remote-route-local-conflict: ${route.remoteGardenId} is declared remote ${`via ${route.ssh}`} but this host also has a local trace of it; not choosing`);
+    }
+    const sender = opts.senderProvider();
+    if (!sender || sender.origin === "external-mcp" || sender.sessionId !== route.localGardenId) {
+        return refuse(`remote-sender-not-declared: only ${route.localGardenId} may send over this route (sender: ${sender ? sender.sessionId : "none"})`);
+    }
+    const claim = {
+        from: sender.sessionId,
+        fromAgentId: sender.agentId,
+        fromCwd: sender.cwd,
+        target: route.remoteGardenId,
+        message: params.message,
+        wantsReply: params.wants_reply ?? false,
+    };
+    const result = await opts.transport.run(remoteReceiveArgv(route), JSON.stringify(claim), opts.timeoutMs ?? REMOTE_SEND_TIMEOUT_MS);
+    return render(route, classifyRemoteReceipt(result));
+}
+/**
+ * The production local-trace fact: the store's own record-entry inspection (absent vs anything
+ * else — readable, unreadable, symlinked or drifted all count) and the control-socket path
+ * inspection, in EVERY socket dir the caller names. The bridge's `ENTWURF_DIR` can differ from the
+ * decider's canonical dir, so both are passed and a trace in either one means this host already
+ * answers to the gid.
+ */
+export function makeLocalTraceFact(dirs) {
+    const socketDirs = [...new Set(dirs.controlSocketDirs.map((d) => path.resolve(d)))];
+    return async (gardenId) => {
+        if (metaRecordExistsByGardenId(gardenId, dirs.sessionsDir))
+            return true;
+        for (const dir of socketDirs) {
+            const inspection = await inspectControlSocketPath(controlSocketPathIn(dir, gardenId));
+            if (inspection.kind !== "absent")
+                return true;
+        }
+        return false;
+    };
+}
+/** The operator's opt-in file name. One per host; it declares that host's one remote pair. */
+export const REMOTE_PAIR_OPT_IN_FILE = "entwurf-remote-pair.json";
+/**
+ * Where the opt-in file lives: beside the meta-record store, i.e. the pi agent dir unless an
+ * `ENTWURF_META_SESSIONS_DIR` override relocates the store (then the file follows the store it
+ * pairs). Read-only reuse of the existing root resolution; nothing here writes.
+ */
+export function remotePairOptInPath() {
+    return path.join(path.dirname(defaultMetaSessionsDir()), REMOTE_PAIR_OPT_IN_FILE);
+}
+/**
+ * Read the opt-in file once, at the moment of use (no cache). Absent is the ONLY "off". A
+ * symlink, a non-regular entry, an unreadable file or an invalid declaration throws: the operator
+ * opted in, so a broken opt-in is refused rather than read as off.
+ *
+ * The bridge this declares is the operator's to build and secure (for example a private network
+ * such as Tailscale, plus SSH authentication and permissions). Entwurf only walks the declared
+ * route: it installs, configures, discovers and verifies none of it, and never retries.
+ */
+export function readRemotePairOptIn(file) {
+    let st;
+    try {
+        st = fs.lstatSync(file);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+    if (!st.isFile()) {
+        throw new RemoteRouteDeclarationError(`remote pair opt-in ${file} must be a regular non-symlink file`);
+    }
+    try {
+        return parseRemoteRouteDeclaration(fs.readFileSync(file, "utf8"));
+    }
+    catch (err) {
+        throw new RemoteRouteDeclarationError(`${file}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}

package/mcp/entwurf-bridge/dist/pi-extensions/lib/remote-pair-transport.js

@@ -0,0 +1,80 @@
+/**
+ * remote-pair-transport — the production process adapter behind #107's `RemoteTransport` (rail 2c).
+ *
+ * One child per send: `spawn(argv[0], argv.slice(1))` with no shell, stdin written once and closed,
+ * stdout and stderr captured separately. On the bound it signals ITS OWN child only (TERM, then KILL
+ * after a short grace); if the pipes are still held after one more grace, it closes its own read ends
+ * and settles as a timeout rather than waiting for a close that may never come. It is not a process manager: it tracks no
+ * other process, scans nothing, and never retries. Classification belongs to
+ * `classifyRemoteReceipt`; this module only reports what the child did.
+ */
+import { spawn } from "node:child_process";
+const CAPTURE_CAP = 64 * 1024;
+const KILL_GRACE_MS = 2000;
+const FINAL_GRACE_MS = 2000;
+function capped(chunks, size, chunk) {
+    if (size.n >= CAPTURE_CAP)
+        return;
+    const room = CAPTURE_CAP - size.n;
+    const piece = chunk.length > room ? chunk.subarray(0, room) : chunk;
+    chunks.push(piece);
+    size.n += piece.length;
+}
+export const processTransport = {
+    run(argv, stdin, timeoutMs) {
+        return new Promise((resolve) => {
+            const out = [];
+            const err = [];
+            const outN = { n: 0 };
+            const errN = { n: 0 };
+            let timedOut = false;
+            let spawnError = null;
+            let settled = false;
+            const child = spawn(argv[0], argv.slice(1), { shell: false, stdio: ["pipe", "pipe", "pipe"] });
+            let killTimer;
+            let finalTimer;
+            const settle = (code, signal) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(bound);
+                if (killTimer)
+                    clearTimeout(killTimer);
+                if (finalTimer)
+                    clearTimeout(finalTimer);
+                const stderr = Buffer.concat(err).toString("utf8");
+                resolve({
+                    exitCode: spawnError ? null : code,
+                    signal: spawnError ? null : signal,
+                    timedOut,
+                    stdout: Buffer.concat(out).toString("utf8"),
+                    stderr: spawnError ? `spawn failed: ${spawnError}${stderr ? `\n${stderr}` : ""}` : stderr,
+                });
+            };
+            const bound = setTimeout(() => {
+                timedOut = true;
+                child.kill("SIGTERM");
+                killTimer = setTimeout(() => {
+                    child.kill("SIGKILL");
+                    // Something else may still hold our stdout/stderr pipes (an inherited descendant,
+                    // an ssh ControlMaster). We do not chase it: after one more grace we close OUR read
+                    // ends and settle as a timeout, which the receipt reads as indeterminate.
+                    finalTimer = setTimeout(() => {
+                        child.stdout.destroy();
+                        child.stderr.destroy();
+                        settle(child.exitCode, child.signalCode);
+                    }, FINAL_GRACE_MS);
+                }, KILL_GRACE_MS);
+            }, timeoutMs);
+            child.stdout.on("data", (c) => capped(out, outN, c));
+            child.stderr.on("data", (c) => capped(err, errN, c));
+            child.on("error", (e) => {
+                spawnError = e.message;
+            });
+            // A child that exits before reading stdin closes the pipe; that is its outcome, not ours.
+            child.stdin.on("error", () => { });
+            child.on("close", (code, signal) => settle(code, signal));
+            child.stdin.end(stdin);
+        });
+    },
+};

package/mcp/entwurf-bridge/dist/pi-extensions/lib/resume-launch-identity.js

@@ -1,27 +1,33 @@
 /**
- * resume-launch-identity — the RECORD-AUTHORITATIVE half of resuming a pi citizen,
- * kept after the visible-first cut removed everything that used to call it.
+ * resume-launch-identity — the RECORD-AUTHORITATIVE half of a visible same-id resume: garden id →
+ * the meta-record → which native session is this citizen's, and where it lives.
  *
- * It was the preamble of the `spawn-bg` watcher's `spawnChild` (entwurf-v2-spawn-production.ts,
- * deleted with that transport): garden id → the meta-record → the transcript that record
- * claims → the provider/model/cwd that transcript's own header carries. None of that is
- * about being hidden or visible. It is the answer to "which being is this, and which
- * conversation is theirs", and it is the same answer a VISIBLE resume will need.
+ * It began as the preamble of the retired `spawn-bg` watcher (garden id → the meta-record → the
+ * transcript that record claims → the provider/model/cwd that transcript's own header carries).
+ * None of that is about being hidden or visible; it is the answer to "which being is this, and
+ * which conversation is theirs". `entwurf-v2-visible-resume` is its consumer, and
+ * `check-resume-launch-identity` holds the record-integrity rules below — the transcript header id
+ * must equal `record.nativeSessionId`, an addressable read (#52) rather than a plain targeted one,
+ * a recorded ACP provider must resolve its bridge.
  *
- * So this leaf is preserved deliberately, with no consumer in the shipped tree today.
- * `check-resume-launch-identity` holds its contract so the record-integrity rules below —
- * the transcript header id must equal `record.nativeSessionId`, an addressable read
- * (#52) rather than a plain targeted one, a recorded ACP provider must resolve its
- * bridge — cannot rot while they wait.
+ * The domain is pi and claude-code (#147 L2). Both own their transcript and re-attach to the same
+ * record when their native session reopens; this leaf only names that session. For pi it reads
+ * the transcript header (the launch needs its provider/model/cwd). For claude-code it reads no
+ * transcript at all — the vendor owns it, and `claude --resume <id>` needs nothing from it — and
+ * checks only that the recorded path is an absolute file that still exists. Every other backend
+ * is a named refusal: native-push citizens have no resume authority (AGENTS Hard Rule 10), and a
+ * durable host is not reopened through Entwurf.
  *
  * It takes a bare garden id, not a plan: the plan type it used to destructure belonged to
  * the removed transport, and the identity question never needed the rest of it.
  */
-import { existsSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import path from "node:path";
 import { AcpModelNotCuratedError, isCuratedAcpModelId, PROVIDER_ID } from "./acp/model-ids.js";
 import { getEntwurfExplicitExtensions, readSessionIdentity } from "./entwurf-core.js";
 import { readAddressableMetaIdentity } from "./meta-session.js";
+/** The backends with a visible same-id resume. A closed set: nothing outside it is reopened. */
+export const RESUME_BACKENDS = ["pi", "claude-code"];
 /**
  * One of the TWO expected refusals on this leaf: the target is a citizen of a backend that has no
  * same-id resume at all. The other is `AcpModelNotCuratedError` (#128, `acp/model-ids.js`).
@@ -31,23 +37,64 @@ import { readAddressableMetaIdentity } from "./meta-session.js";
  * bridge — and those keep their bare cause-rich `Error`, because a caller cannot act on them
  * except by looking. A Claude Code or agy garden id is different in kind: nothing is broken,
  * the operator simply asked a capability boundary to do something it does not cover, and the
- * honest answer is a named refusal rather than an error report about a store that is fine.
+ * honest answer is a named refusal rather than an error report about a store that is fine. Since
+ * #147 L2 the boundary is `RESUME_BACKENDS`; a Codex, agy, Copilot, OMP or pi-durable garden id is
+ * this refusal.
  *
  * It carries a `reason` so the caller matches on a FIELD. Parsing the message string would make
  * the wording load-bearing, and re-reading the record to ask "was it pi?" would read an address
  * twice and could answer differently the second time.
  */
 export class ResumeBackendUnsupportedError extends Error {
-    reason = "target-not-pi";
+    reason = "target-backend-unsupported";
     backend;
     constructor(gardenId, backend) {
         super(`resume-launch-identity: ${gardenId} is a ${backend} citizen — same-id resume is a host-adapter relaunch ` +
-            `capability, and its domain currently contains backend pi only (only pi stands a control socket up). ` +
-            `This is a capability boundary, not the control-socket rail and not citizen rank.`);
+            `capability, and its domain is ${RESUME_BACKENDS.join(" and ")}. ` +
+            `This is a capability boundary, not citizen rank.`);
         this.name = "ResumeBackendUnsupportedError";
         this.backend = backend;
     }
 }
+/**
+ * Claude Code's session id grammar: a lowercase UUID. The value becomes an argv token after
+ * `--resume`, so anything else — a leading `-`, whitespace, a path — is refused as a bad record
+ * rather than handed to the vendor CLI as something it would parse differently.
+ */
+const CLAUDE_SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** A claude-code record → its resume facts. Throws, with its own cause, on a record that cannot be resumed. */
+function resolveClaudeCodeLaunchIdentity(gardenId, record) {
+    if (!CLAUDE_SESSION_ID.test(record.nativeSessionId)) {
+        throw new Error(`resume-launch-identity: ${gardenId} records nativeSessionId ${JSON.stringify(record.nativeSessionId)}, ` +
+            `which is not a Claude Code session id (lowercase UUID) — refusing to hand it to claude --resume.`);
+    }
+    const transcript = record.transcriptPath;
+    if (!transcript || !path.isAbsolute(transcript)) {
+        throw new Error(`resume-launch-identity: ${gardenId} records no absolute transcriptPath (${JSON.stringify(transcript)}) — ` +
+            `the birth hook writes one for every Claude Code session, so this record cannot name a session to resume.`);
+    }
+    let isFile = false;
+    try {
+        isFile = statSync(transcript).isFile();
+    }
+    catch {
+        isFile = false;
+    }
+    if (!isFile) {
+        throw new Error(`resume-launch-identity: ${gardenId} recorded transcriptPath "${transcript}" is not a file on disk — ` +
+            `the session's transcript is gone, so claude --resume would open nothing.`);
+    }
+    if (!path.isAbsolute(record.cwd)) {
+        throw new Error(`resume-launch-identity: ${gardenId} records a relative cwd ${JSON.stringify(record.cwd)}.`);
+    }
+    return {
+        backend: "claude-code",
+        nativeSessionId: record.nativeSessionId,
+        cwd: record.cwd,
+        createdAt: record.createdAt,
+        attachIncarnation: record.attachIncarnation,
+    };
+}
 /**
  * Resolve launch identity for a resume. The TARGET is now resolved through the
  * meta-record (#50 C2): `gardenId → record.transcriptPath`. It used to be a global
@@ -79,6 +126,8 @@ export class ResumeBackendUnsupportedError extends Error {
  */
 export function resolveResumeLaunchIdentity(gardenId) {
     const record = readAddressableMetaIdentity(gardenId);
+    if (record.backend === "claude-code")
+        return resolveClaudeCodeLaunchIdentity(gardenId, record);
     if (record.backend !== "pi") {
         throw new ResumeBackendUnsupportedError(gardenId, record.backend);
     }
@@ -136,6 +185,7 @@ export function resolveResumeLaunchIdentity(gardenId) {
     if (provider === PROVIDER_ID && !isCuratedAcpModelId(model))
         throw new AcpModelNotCuratedError(model);
     return {
+        backend: "pi",
         sessionFile,
         cwd: identity.cwd,
         explicitExtensionArgs: explicitExtensions.args,