feat: ephemeral agent status line and agent-presence signal in the desk (#14)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: ymansurozer

scripts/smoke.mjs

@@ -76,12 +76,27 @@ try {
     side: "additions",
     body: "why this change?",
   });
+  // No await is parked yet, so the question sits queued — the presence signal the
+  // UI renders as "No agent attached — question queued".
+  const queuedState = await getJson("/api/state");
+  assert.equal(queuedState.queuedQuestions, 1, "question queued with no listener");
+  console.log("✓ queuedQuestions reflects an undelivered question");
   const ev1 = JSON.parse(cli("await", "--repo", tmp, "--session", ID, "--timeout", "5"));
   assert.equal(ev1.kind, "question");
   assert.equal(ev1.question.body, "why this change?");
   assert.equal(ev1.question.lineNumber, 2);
   console.log("✓ await → question event");
 
+  // agent posts ephemeral activity while working → visible in the state payload
+  const status = JSON.parse(
+    cli("status", "--repo", tmp, "--session", ID, "--body", "Reading a.txt…"),
+  );
+  assert.ok(status.ok && status.live, "status accepted by the live desk");
+  const activeState = await getJson("/api/state");
+  assert.equal(activeState.agentActivity?.body, "Reading a.txt…");
+  assert.equal(activeState.queuedQuestions, 0, "question was delivered");
+  console.log("✓ status → ephemeral agentActivity in state");
+
   // agent answers via `galley comment`
   const reply = JSON.parse(
     cli(
@@ -103,7 +118,9 @@ try {
     ),
   );
   assert.ok(reply.ok && reply.commentId, "comment posted");
-  console.log("✓ comment posted (answer)");
+  const answeredState = await getJson("/api/state");
+  assert.equal(answeredState.agentActivity, null, "agent answer cleared the activity line");
+  console.log("✓ comment posted (answer) — activity cleared");
 
   // human clicks Send → `galley await` yields a review event with a ReviewResult
   await post("/api/send", await getJson("/api/state"));

skills/galley/SKILL.md

@@ -18,7 +18,7 @@ The review is the human's; the agent acts on the decisions and answers questions
 
 ## Review modes
 
-`galley` reviews in one of three modes. `await`/`comment`/`reload` auto-target the lone live desk for the repo, so you usually don't pass `--session`.
+`galley` reviews in one of three modes. `await`/`comment`/`status`/`reload` auto-target the lone live desk for the repo, so you usually don't pass `--session`.
 
 | Start command        | Mode           | What's reviewed                                                              | staging                                                                   |
 | -------------------- | -------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
@@ -38,6 +38,7 @@ The review is the human's; the agent acts on the decisions and answers questions
 | `galley …` (a mode above)                                                                        | Start the persistent desk (opens the tab, stays up until Ctrl-C). The banner prints to **stderr**; nothing is written to stdout. **Idempotent**: if a desk is already live for the repo+session, this reuses it — the open tab gets a reload (and the new `--guide`, if passed) and no second tab/port is opened.                                                                                                              |
 | `galley await [--session <id>] [--timeout <s>]`                                                  | Block until the next desk **event**, print it as a tagged JSON envelope on stdout, and exit. Loop and branch on `kind`.                                                                                                                       |
 | `galley comment [--session <id>] --path <f> --line <n> [--side additions\|deletions] --body "…"` | Post an agent reply (an answer to a question, or a note). Appears in the open tab within ~1.5s, threaded under the matching human comment.                                                                                                    |
+| `galley status [--session <id>] --body "…"`                                                      | Post an **ephemeral** one-line "what I'm doing now" (e.g. "Reading state.ts…") that shows live next to the reviewer's waiting indicator. Optional but recommended before long operations while answering a question or acting on a Send. Cleared by your next `galley comment`; goes stale after ~90s (keep posting during long work); never persisted; exits 0 even with no live desk. |
 | `galley reload [--session <id>] [--guide <file>]`                                                | Re-diff the working tree into the **live** desk so your code edits appear in the same tab — no restart needed. Decisions reconcile against the new diff (a hunk whose content you changed resets to pending; untouched decisions carry over). `--guide` swaps the attached review guide in the same round-trip. |
 
 `galley await` yields one of two events:
@@ -55,6 +56,7 @@ while ev=$(galley await --session <id>); do
   case "$(printf '%s' "$ev" | jq -r .kind)" in
     question)   # answer now, threaded at the question's location
       q=$(printf '%s' "$ev" | jq .question)
+      galley status --session <id> --body "Reading the file to answer…"  # live feedback while you work
       galley comment --session <id> \
         --path "$(jq -r .path <<<"$q")" --line "$(jq -r .lineNumber <<<"$q")" \
         --side "$(jq -r .side <<<"$q")" --body "…your answer…" ;;
@@ -109,7 +111,7 @@ Without `--timeout`, `await` holds the connection open until an event arrives. P
 }
 ```
 
-Read the file/diff for context (you have the repo), then answer with `galley comment` matching `path`/`lineNumber`/`side` so the reply threads under the question. Answer promptly — the human is waiting in the tab. Questions are resolved live and never appear in a `ReviewResult`.
+Read the file/diff for context (you have the repo), then answer with `galley comment` matching `path`/`lineNumber`/`side` so the reply threads under the question. Answer promptly — the human is waiting in the tab; if gathering the answer takes more than a moment, post `galley status --body "…"` lines so they see progress instead of a static spinner. Questions are resolved live and never appear in a `ReviewResult`.
 
 ## ReviewResult
 

skills/galley/agents-snippet.md

@@ -15,7 +15,7 @@ When the user should review a plan, a PR, or code changes you've made, hand it t
 Optionally attach an AI **guided review** so the human gets an overview + a logical, annotated file order: add `--guide guide.json` to the start command (see the skill for the JSON schema).
 
 Then loop: `galley await --session <task-id>` blocks for the next event and prints a tagged JSON envelope.
-- `{"kind":"question",…}` → answer **now** with `galley comment --path … --line … --side … --body "…"` at the question's location.
+- `{"kind":"question",…}` → answer **now** with `galley comment --path … --line … --side … --body "…"` at the question's location. While gathering the answer (or acting on a review), post brief `galley status --session <task-id> --body "Reading X…"` lines — they show live next to the reviewer's waiting indicator so they're not staring at a static spinner.
 - `{"kind":"review","result":{…}}` → act on `result`: revert **rejected**, make **requestedChanges**, leave **accepted** alone, leave **approvedFiles** (signed off as-is) untouched, don't touch **stagedFiles** unless a change requires it. (Editing an approved file invalidates its approval → it needs re-review next round.)
 
 After editing code, run `galley reload --session <task-id>` so your edits show in the open tab (add `--guide <file>` to swap in a regenerated guide), then `galley await` again for the next round. The desk stays open across rounds and the reviewer keeps **one tab**: starting is idempotent (a live desk is reused, never duplicated) and the port is stable per session, so even after a desk process dies, re-running the start command brings the same tab back to life — never open a second desk for the same session.

src/cli.ts

@@ -161,6 +161,38 @@ async function runComment(args: Record<string, string | boolean>) {
   );
 }
 
+// `galley status --body "..."` — post an ephemeral "what I'm doing now" line that
+// shows next to the reviewer's waiting indicator. Unlike comment there is no
+// offline fallback: ephemeral status is meaningless without a live desk, and it
+// must never fail the agent loop — no desk just reports { live: false }, exit 0.
+async function runStatus(args: Record<string, string | boolean>) {
+  const root = await getGitRoot(resolveRepo(args)).catch(() => resolveRepo(args));
+  const session = await resolveActionSession(root, args);
+  const body = typeof args.body === "string" ? args.body.trim() : "";
+  if (!body) {
+    console.error('Usage: galley status --body "..." [--session <id>] [--repo <path>]');
+    process.exitCode = 1;
+    return;
+  }
+  const lock = await readDeskLock(root, session);
+  if (lock) {
+    try {
+      const res = await fetch(`${lock.url}api/status`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ body }),
+      });
+      if (res.ok) {
+        process.stdout.write(JSON.stringify({ ok: true, live: true, session }) + "\n");
+        return;
+      }
+    } catch {
+      /* desk not reachable; report not-live below */
+    }
+  }
+  process.stdout.write(JSON.stringify({ ok: false, live: false, session }) + "\n");
+}
+
 // `galley await --session <id>` — block until the next desk event, then print it
 // to stdout as a tagged envelope and exit. The event is either
 //   {"kind":"question","question":{path,lineNumber,side,body,mode,session}}  — answer it now
@@ -462,6 +494,7 @@ Usage:
   galley file <path>                Review a single file or artifact (tracked or not)
   galley pr <ref|number|url>        Review a branch's commits vs its merge-base
   galley comment --path <f> --line <n> --body "..."   Post an agent reply into the desk
+  galley status --body "..."        Post an ephemeral "what I'm doing" line into the desk
   galley await [--timeout <s>]      Block for the next desk event (question | review)
   galley reload [--guide <file>]    Re-diff the working tree into the open desk
                                     (--guide swaps the attached review guide too)
@@ -497,6 +530,7 @@ async function main() {
   const positional = rest[0] && !rest[0].startsWith("--") ? rest[0] : undefined;
   const args = parseArgs(rest);
   if (sub === "comment") return runComment(args);
+  if (sub === "status") return runStatus(args);
   if (sub === "await") return runAwait(args);
   if (sub === "reload") return runReload(args);
   if (sub === "guide-spec") {
@@ -514,7 +548,7 @@ async function main() {
   if (sub === "pr") return runDesk("pr", positional, args);
   if (sub) {
     console.error(
-      `Unknown command "${sub}". Use: galley | galley file <path> | galley pr <ref|number|url> | comment | await | reload | guide-spec.`,
+      `Unknown command "${sub}". Use: galley | galley file <path> | galley pr <ref|number|url> | comment | status | await | reload | guide-spec.`,
     );
     process.exitCode = 1;
     return;

src/server.test.ts

@@ -38,15 +38,23 @@ function state(root: string): ReviewState {
 // Each test points HOME at a temp dir so the global ~/.galley/settings.json the
 // open-editor handler reads is isolated from the developer's real one.
 async function withServer(
-  run: (handle: Awaited<ReturnType<typeof startServer>>, root: string) => Promise<void>,
-  options: { runEditorCommand?: (command: string, args: string[]) => Promise<void> } = {},
+  run: (
+    handle: Awaited<ReturnType<typeof startServer>>,
+    root: string,
+    st: ReviewState,
+  ) => Promise<void>,
+  options: {
+    runEditorCommand?: (command: string, args: string[]) => Promise<void>;
+    statusTtlMs?: number;
+  } = {},
 ) {
   const root = await mkdtemp(path.join(tmpdir(), "galley-server-"));
   const oldHome = process.env.HOME;
   process.env.HOME = root;
-  const handle = await startServer({ state: state(root), open: false, ...options });
+  const st = state(root);
+  const handle = await startServer({ state: st, open: false, ...options });
   try {
-    await run(handle, root);
+    await run(handle, root, st);
   } finally {
     handle.server.close();
     process.env.HOME = oldHome;
@@ -117,6 +125,89 @@ test("open-editor runs the editor command from global settings", async () => {
   );
 });
 
+type StatePayload = ReviewState & {
+  agentActivity: { body: string; at: string } | null;
+  agentListening: boolean;
+  queuedQuestions: number;
+  queuedReviews: number;
+};
+
+const getState = (url: string) =>
+  fetch(`${url}api/state`).then((r) => r.json() as Promise<StatePayload>);
+
+const post = (url: string, pathname: string, body: unknown) =>
+  fetch(`${url}${pathname}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+test("status posts ephemeral agent activity into the state payload", async () => {
+  await withServer(async (handle) => {
+    const res = await post(handle.url, "api/status", { body: "Reading a.ts…" });
+    assert.equal(res.status, 200);
+    const st = await getState(handle.url);
+    assert.equal(st.agentActivity?.body, "Reading a.ts…");
+    assert.equal(st.agentListening, false);
+    assert.equal(st.queuedQuestions, 0);
+    assert.equal(st.queuedReviews, 0);
+  });
+});
+
+test("status rejects an empty body", async () => {
+  await withServer(async (handle) => {
+    const res = await post(handle.url, "api/status", { body: "  " });
+    const body = (await res.json()) as { code?: string };
+    assert.equal(res.status, 422);
+    assert.equal(body.code, "INVALID_STATUS");
+  });
+});
+
+test("an agent comment clears the activity line", async () => {
+  await withServer(async (handle) => {
+    await post(handle.url, "api/status", { body: "Running tests…" });
+    await post(handle.url, "api/comment", { path: "a.ts", lineNumber: 1, body: "Done — answer." });
+    const st = await getState(handle.url);
+    assert.equal(st.agentActivity, null);
+  });
+});
+
+test("activity goes stale past the TTL (checked on read, no timers)", async () => {
+  await withServer(
+    async (handle) => {
+      await post(handle.url, "api/status", { body: "Reading…" });
+      const st = await getState(handle.url);
+      assert.equal(st.agentActivity, null);
+    },
+    { statusTtlMs: 0 },
+  );
+});
+
+test("an unconsumed question surfaces as queuedQuestions", async () => {
+  await withServer(async (handle) => {
+    await post(handle.url, "api/ask", { path: "a.ts", lineNumber: 1, body: "why?" });
+    const st = await getState(handle.url);
+    assert.equal(st.queuedQuestions, 1);
+    assert.equal(st.agentListening, false);
+  });
+});
+
+test("save strips transient desk-status keys so they never persist on state", async () => {
+  await withServer(async (handle, _root, st) => {
+    const payload = await getState(handle.url);
+    // The UI posts its copy of the /api/state payload back — transient keys ride along.
+    await post(handle.url, "api/save", {
+      ...payload,
+      agentActivity: { body: "leak", at: "t" },
+      queuedQuestions: 9,
+    });
+    assert.equal("agentActivity" in st, false);
+    assert.equal("agentListening" in st, false);
+    assert.equal("queuedQuestions" in st, false);
+    assert.equal("queuedReviews" in st, false);
+  });
+});
+
 test("settings API round-trips editorCommand", async () => {
   await withServer(async (handle) => {
     await fetch(`${handle.url}api/settings`, {