@paigy/harness 0.3.17 → 0.3.29

package/README.md

@@ -1,5 +1,16 @@
 # paigy-harness
 
+Phone launches persist their selected harness and Paigy session identity with the local slot.
+Recovery uses that runtime, never a default Claude process. Older slots need a known named
+runtime or a Claude transcript; otherwise the host logs a missing-runtime blocker.
+
+The Antigravity adapter reconnects once after its specific `subscriber fell behind updates`
+failure, using the conversation ID reported by `agy`. It asks the resumed agent to inspect
+existing results before continuing, rather than replaying the original task. Missing IDs,
+other errors, and a failed recovery remain visible failures. Diagnostics name the conversation,
+recovery attempt, and outcome. This mitigates the vendor stream failure; it does not repair
+Antigravity's internal broadcaster. Keep verbose command output in files and read bounded summaries.
+
 Runs Claude Code and Codex on your machine, mirrors every turn to your Paigy inbox, and
 — when you ask it to — **rings your phone when an agent is blocked** (#804).
 
@@ -22,15 +33,14 @@ without a desktop app. Two things need a process that actually owns the agent:
 The point isn't notifications, it's a conversation with an agent that happens to be
 running on your laptop. Both directions close (`paigy/conversation.ts`):
 
-- **Answering.** The agent's turn ends on a question → it banners → your reply goes
-  straight back into stdin as the next turn. Without this the loop is one-directional
-  and dies at the first idle.
-- **Initiating.** You say something unprompted from your phone → it arrives as a
-  `request` on the thread → same stdin. You never have to wait to be asked.
-
-Both ride the same thread, so the phone shows one conversation. `endsWithQuestion` is
-what decides "the agent is waiting on you" versus "here's your history", and it is
-deliberately conservative: a false positive buzzes someone who was never asked anything.
+- **Answering.** The agent asks through Paigy's `contact` — its only channel to you; the
+  harness never relays its terminal output (`companion.md` Part 4, one channel) → your
+  reply lands on its Goal and goes straight back into stdin as the next turn. Without this
+  the loop is one-directional and dies at the first idle.
+- **Initiating.** You say something unprompted from your phone → it arrives on the agent's
+  Goal → same stdin. You never have to wait to be asked. A Claude agent in the middle of a task
+  sees your words right after its next tool call, and gets them again as its next turn
+  (`companion.md` Part 4, words reach a running turn).
 
 Answers are read out of whatever shape they arrive in (`spokenText`) — a tapped option,
 a spoken sentence, a whole call log — because the words are what the agent needs, not
@@ -63,10 +73,8 @@ silent history from "answer me now" is `urgency`, not a second store:
 
 | Event | Level | Why |
 | --- | --- | --- |
-| a turn (agent or user) | `inbox` | lands, never buzzes; searchable, handoff-able history |
 | a blocked action | `banner` | claims attention; escalates on its own if unanswered |
 | a blocked **destructive** action | `call` | `rm -rf` doesn't get to wait for the escalation ladder |
-| a turn that **asked you something** | `banner` | a question filed silently is a conversation that dies |
 | a turn that failed | `push` | worth knowing soon, not worth a sound |
 | our own parse failure | — | not on the rail at all; it's our problem, not yours |
 
@@ -162,7 +170,7 @@ src/harness/   events.ts   the neutral HarnessEvent the driver produces
                catalog.ts  which harnesses exist, detection, auth probes, installs
                session.ts  spawn, line-split, lifecycle — the only impure file here
 src/paigy/     level.ts        event → NotifyLevel
-               bridge.ts       mirror turns, ask permissions/questions, setup nudges
+               bridge.ts       permission asks, cannot-work notices, the turn's end as Goal progress
                conversation.ts the round trip — your words into a running agent's stdin
 src/triage/    evidence.ts the deterministic signals; judge.ts the one model boundary
                verdict.ts  the prompt + its defensive parser; triage.ts the sweep itself
@@ -227,7 +235,9 @@ curl -fsSL https://paigy.ai/install | sh
 
 Installs the npm CLI (one self-contained file — the workspace libs are bundled) and
 runs `paigy-harness setup`: QR-pairs the machine, hatches each detected agent's
-identity (no codes), registers the MCP + statusline, grants a workspace, installs
+identity (no codes), registers the Paigy MCP in every harness it runs (`MCP_WIRES` —
+Claude Code, Codex, Antigravity: an agent's only channel to you) + the statusline,
+grants a workspace, installs
 the host service. `paigy-harness service` installs a
 macOS launchd agent so hosting survives reboots — the host loop IS the service,
 launchd just keeps it alive (the old "no daemon" note was about the WAKE channel,
@@ -292,7 +302,9 @@ LAST, after the hooks are gone.
 - **Protocol churn is the standing risk.** Neither `stream-json` nor ACP adapter
   behavior is a stability contract. Every driver fails soft by design: an unrecognized
   frame is skipped, never fatal. If mirroring goes quiet after a CLI update, re-verify
-  the frame names in the driver doc comments first.
+  the frame names in the driver doc comments first. An adapter can also leave a prompt
+  unanswered for good (claude-agent-acp#1145); the driver cancels one after a long quiet
+  with no tool running (`companion.md` Part 4, one way in).
 - **Auth probes are vendor commands** (`claude auth status`, `codex login status`) and
   can drift with CLI releases; a probe failure reads as "needs login", so drift shows
   up as a nagging hint, not a broken start.

package/dist/agy-acp.js

@@ -22,6 +22,13 @@ var AgyAcp = class {
   bypass = false;
   started = false;
   promptId;
+  conversation;
+  dropped = false;
+  retried = false;
+  /** The vendor can fail on stderr without a result frame. Never retry other failures. */
+  diagnostic(text) {
+    if (text.includes("subscriber fell behind updates")) this.dropped = true;
+  }
   /** A frame from the harness. */
   fromClient(msg) {
     const out = { client: [], agy: [] };
@@ -50,6 +57,8 @@ var AgyAcp = class {
           out.start = { cwd: this.cwd, args: agyArgs(this.bypass) };
         }
         this.promptId = msg.id;
+        this.dropped = false;
+        this.retried = false;
         out.agy.push(JSON.stringify({ event: "user", message: { role: "user", content } }));
         return out;
       }
@@ -68,6 +77,10 @@ var AgyAcp = class {
       return out;
     }
     const update = (body) => out.client.push(frame({ method: "session/update", params: { sessionId: this.sessionId, update: body } }));
+    if (ev.event === "init" && typeof ev.conversation_id === "string" && /^[0-9a-f-]{36}$/i.test(ev.conversation_id)) {
+      this.conversation = ev.conversation_id;
+      out.diagnostic = `agy conversation=${this.conversation} recovery=${this.retried ? 1 : 0} connected`;
+    }
     if (ev.event === "step_update") {
       const s = ev.step_update ?? {};
       if (s.step_type === "agent_response" && typeof s.text_delta === "string" && s.text_delta) {
@@ -79,6 +92,9 @@ var AgyAcp = class {
     }
     if (ev.event === "result" && this.promptId !== void 0) {
       const r = ev.result ?? {};
+      if (r.status !== "SUCCESS") this.diagnostic(String(r.error ?? ""));
+      if (r.status !== "SUCCESS" && this.dropped && this.conversation && !this.retried) return out;
+      if (this.retried) out.diagnostic = `agy conversation=${this.conversation} recovery=1 outcome=${r.status === "SUCCESS" ? "success" : "failed"}`;
       const denied = Array.isArray(r.denied_actions) ? r.denied_actions : [];
       if (denied.length) {
         const names = denied.map((d) => d.display_name ?? d.action ?? "a tool").join(", ");
@@ -96,10 +112,20 @@ Antigravity cannot ask for permission when it runs in the background, so it was
     return out;
   }
   /** `agy` exited: a turn still open fails by name rather than hanging the harness. */
-  exited(code) {
+  exited(code, recover = true) {
     const out = { client: [], agy: [] };
+    if (recover && this.promptId !== void 0 && this.dropped && this.conversation && !this.retried) {
+      this.retried = true;
+      this.dropped = false;
+      out.start = { cwd: this.cwd, args: [...agyArgs(this.bypass), "--conversation", this.conversation] };
+      out.agy.push(JSON.stringify({ event: "user", message: { role: "user", content: "The update stream disconnected. Inspect this conversation and existing command results before continuing the unfinished work. Do not repeat completed actions or blindly rerun the previous command. Redirect verbose command output to a file and read only a bounded summary. If the outcome of an action is uncertain, verify it before retrying; report a blocker if you cannot do so safely." } }));
+      out.diagnostic = `agy conversation=${this.conversation} recovery=1 reason=subscriber_lag exit=${code} reconnecting`;
+      return out;
+    }
     if (this.promptId !== void 0) {
-      out.client.push(frame({ id: this.promptId, error: { code: -32e3, message: `agy exited ${code ?? "by signal"}` } }));
+      const message = this.retried ? `Antigravity stream recovery failed for conversation ${this.conversation}; inspect its results before retrying` : `agy exited ${code ?? "by signal"}`;
+      out.client.push(frame({ id: this.promptId, error: { code: -32e3, message } }));
+      out.diagnostic = `agy conversation=${this.conversation ?? "unknown"} recovery=${this.retried ? 1 : 0} outcome=failed exit=${code}`;
       this.promptId = void 0;
     }
     return out;
@@ -108,22 +134,31 @@ Antigravity cannot ask for permission when it runs in the background, so it was
 function main() {
   const adapter = new AgyAcp();
   let agy;
+  let closed = false;
   const apply = (out) => {
+    if (out.diagnostic) process.stderr.write(`${out.diagnostic}
+`);
     for (const f of out.client) process.stdout.write(`${f}
 `);
     if (out.start) {
       agy = spawn("agy", out.start.args, { cwd: out.start.cwd, stdio: ["pipe", "pipe", "pipe"], env: process.env });
+      agy.stdin.on("error", () => {
+      });
       createInterface({ input: agy.stdout }).on("line", (l) => apply(adapter.fromAgy(l)));
-      agy.stderr.on("data", (chunk) => process.stderr.write(chunk));
-      agy.on("exit", (code) => {
-        apply(adapter.exited(code));
-        process.exit(code ?? 1);
+      let diagnosticTail = "";
+      agy.stderr.on("data", (chunk) => {
+        adapter.diagnostic(diagnosticTail + String(chunk));
+        diagnosticTail = (diagnosticTail + String(chunk)).slice(-512);
+        process.stderr.write(chunk);
+      });
+      agy.on("close", (code) => {
+        const next = adapter.exited(code, !closed);
+        apply(next);
+        if (!next.start) process.stdout.write("", () => process.exit(code ?? 1));
       });
       agy.on("error", (e) => {
         process.stderr.write(`agy: ${e.message}
 `);
-        apply(adapter.exited(null));
-        process.exit(1);
       });
     }
     for (const l of out.agy) agy?.stdin?.write(`${l}
@@ -135,6 +170,7 @@ function main() {
     } catch {
     }
   }).on("close", () => {
+    closed = true;
     agy?.stdin?.end();
     if (!agy) process.exit(0);
   });