@pi-unipi/unipi 3.0.0-alpha.40 → 3.0.0-alpha.42

package/CHANGELOG.md

@@ -6,6 +6,29 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [3.0.0-alpha.42] — 2026-10-16
+
+### Added
+- `skill:browser`: the agent uses the PC's browser, the one you see in the UniPi app, with `agent-browser`. While the browser is on, UniPi points agent-browser at it (`AGENT_BROWSER_CDP`), so `agent-browser open <url>` just works, with no start or connect step. The browser is CloakBrowser, a stealthy Chromium shown only in the app; the agent's clicks and typing look human, and you can take over. Needs UniPi host 0.5.0. (UNI-295, UNI-303)
+- The agent sees `skill:browser` and a one-line note only while the PC's browser is on. Turning it off hides both from the next prompt, and `/skill:browser` explains how to turn it on. Any skill can now be shown only when a condition holds (`registerSkillCondition`). (UNI-300)
+- The work tray has a hint again: while it has items, one dim line under the input reads, for example, "Background tasks 1 running · Subagents 2 · ↓ open". (UNI-291)
+- App: "Start from here" on one of your messages puts that message, with its images, back in the app's input, like `/tree` in the terminal. (UNI-290)
+
+## [3.0.0-alpha.41] — 2026-10-13
+
+### Changed
+- Graph and swarm now follow Maka's agent graph. The model adds work with dependencies, and pi runs each step as a background subagent. Before, the model had to start every subagent and report back by hand, and weaker models skipped it. The model yields while steps run, and pi wakes it once at each checkpoint (a failure, nothing left to run, or everything settled). A graph closes only when the model finishes it with the results it chose. Swarm is the same graph with Maka's swarm instructions. New tools: `update_agent_graph` (`add_work` / `stop` / `finish`), `view_agent_graph`, `yield_agent_graph`, `agent_output`, `agent_swarm_status`. Removed: `swarm_report`, `swarm_status`, `swarm_yield`, `graph_output`, and the declare-once `update_agent_graph`. (UNI-279, UNI-280, UNI-281)
+
+### Added
+- The agent graph is saved in the project's state folder. It survives restarts: steps that were running when pi closed resume once in their own subagent session. `/unipi:graph history` and `/unipi:swarm history` list past graphs, and a new graph can reuse results a finished one selected. (UNI-279, UNI-280)
+- The UniPi app's Progress sheet shows finished and past graphs with their chart. It adds each step's details, its full result and its subagent session, plus Stop graph and a picker for earlier runs. The app can also open any subagent's transcript. (UNI-282)
+- Goal: the next continuation is saved before it is sent. If pi crashes, the next start sends it again, up to 2 times, then pauses the goal. A completion claim while the todo list still has open items gets a task reminder first, up to 2 times. (UNI-283)
+
+### Fixed
+- `/unipi:ralph start` from an empty prompt started the loop but never ran the first iteration. (UNI-283)
+- After a restart, `ralph_done` failed with "no active loop". Prompts and tools also pointed the model at the wrong task-file path. (UNI-283)
+- Stopping a ralph loop with `/unipi:regular` left its goal active, so the next `/unipi:goal` resumed the old checklist. (UNI-283)
+
 ## [3.0.0-alpha.40] — 2026-10-12
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/unipi",
-  "version": "3.0.0-alpha.40",
+  "version": "3.0.0-alpha.42",
   "description": "All-in-one extension suite for Pi coding agent",
   "type": "module",
   "license": "MIT",
@@ -80,28 +80,28 @@
     "typebox": "^1.1.38"
   },
   "dependencies": {
-    "@pi-unipi/app-bridge": "3.0.0-alpha.40",
-    "@pi-unipi/ask-user": "3.0.0-alpha.40",
-    "@pi-unipi/background-tasks": "3.0.0-alpha.40",
-    "@pi-unipi/btw": "3.0.0-alpha.40",
-    "@pi-unipi/command-enchantment": "3.0.0-alpha.40",
-    "@pi-unipi/compactor": "3.0.0-alpha.40",
-    "@pi-unipi/core": "3.0.0-alpha.40",
-    "@pi-unipi/dream": "3.0.0-alpha.40",
-    "@pi-unipi/footer": "3.0.0-alpha.40",
-    "@pi-unipi/fusion": "3.0.0-alpha.40",
-    "@pi-unipi/info-screen": "3.0.0-alpha.40",
-    "@pi-unipi/input-shortcuts": "3.0.0-alpha.40",
-    "@pi-unipi/kanboard": "3.0.0-alpha.40",
-    "@pi-unipi/mcp": "3.0.0-alpha.40",
-    "@pi-unipi/memory": "3.0.0-alpha.40",
-    "@pi-unipi/notify": "3.0.0-alpha.40",
-    "@pi-unipi/skill-registry": "3.0.0-alpha.40",
-    "@pi-unipi/subagents": "3.0.0-alpha.40",
-    "@pi-unipi/updater": "3.0.0-alpha.40",
-    "@pi-unipi/utility": "3.0.0-alpha.40",
-    "@pi-unipi/web-api": "3.0.0-alpha.40",
-    "@pi-unipi/workflow": "3.0.0-alpha.40",
+    "@pi-unipi/app-bridge": "3.0.0-alpha.42",
+    "@pi-unipi/ask-user": "3.0.0-alpha.42",
+    "@pi-unipi/background-tasks": "3.0.0-alpha.42",
+    "@pi-unipi/btw": "3.0.0-alpha.42",
+    "@pi-unipi/command-enchantment": "3.0.0-alpha.42",
+    "@pi-unipi/compactor": "3.0.0-alpha.42",
+    "@pi-unipi/core": "3.0.0-alpha.42",
+    "@pi-unipi/dream": "3.0.0-alpha.42",
+    "@pi-unipi/footer": "3.0.0-alpha.42",
+    "@pi-unipi/fusion": "3.0.0-alpha.42",
+    "@pi-unipi/info-screen": "3.0.0-alpha.42",
+    "@pi-unipi/input-shortcuts": "3.0.0-alpha.42",
+    "@pi-unipi/kanboard": "3.0.0-alpha.42",
+    "@pi-unipi/mcp": "3.0.0-alpha.42",
+    "@pi-unipi/memory": "3.0.0-alpha.42",
+    "@pi-unipi/notify": "3.0.0-alpha.42",
+    "@pi-unipi/skill-registry": "3.0.0-alpha.42",
+    "@pi-unipi/subagents": "3.0.0-alpha.42",
+    "@pi-unipi/updater": "3.0.0-alpha.42",
+    "@pi-unipi/utility": "3.0.0-alpha.42",
+    "@pi-unipi/web-api": "3.0.0-alpha.42",
+    "@pi-unipi/workflow": "3.0.0-alpha.42",
     "@resvg/resvg-wasm": "^2.6.2",
     "beautiful-mermaid": "^1.1.3"
   },

package/packages/app-bridge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/app-bridge",
-  "version": "3.0.0-alpha.40",
+  "version": "3.0.0-alpha.42",
   "description": "Live bridge between a pi TUI session and the UniPi phone app — streaming chat, prompts, steering and dialogs from the phone",
   "type": "module",
   "main": "index.ts",
@@ -31,7 +31,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.40"
+    "@pi-unipi/core": "3.0.0-alpha.42"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.87.1",

package/packages/app-bridge/src/bridge.ts

@@ -14,7 +14,7 @@ import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync
 import { homedir } from "node:os";
 import { join, relative, resolve as resolvePath } from "node:path";
 import { DialogHub, wrapUi } from "./dialogs.js";
-import { ENTRIES_BUDGET, HELLO_ENTRIES_BUDGET, LINE_BUDGET, fitLine, historyPage, jsonBytes, phoneSafe, snapshotEntries, clipText, editedAway, wantedEntry } from "./snapshot.js";
+import { ENTRIES_BUDGET, HELLO_ENTRIES_BUDGET, LINE_BUDGET, fitLine, historyPage, jsonBytes, phoneSafe, snapshotEntries, clipText, editedAway, wantedEntry, treeGoRestore, type TreeGoRestore } from "./snapshot.js";
 import { searchSession } from "./search.js";
 import {
   BRIDGE_PROTOCOL,
@@ -44,7 +44,7 @@ import { setRemoteDialogs } from "./remote.js";
 import { fileSuggestions } from "./files.js";
 import { statPaths } from "./paths.js";
 import { registerPath, resolveMedia } from "./media.js";
-import { listWorkItems, stopWorkItem, backgroundWorkItem, workLogPage } from "./work.js";
+import { listWorkItems, stopWorkItem, backgroundWorkItem, workLogPage, workTranscript } from "./work.js";
 import { bus, callCommandRunner, commandArgCompleters, pendingWorkLabel, silenceCommandEcho, subscribePendingWork, UNIPI_EVENTS } from "@pi-unipi/core";
 import type { BtwListPage } from "./wire.js";
 
@@ -62,6 +62,8 @@ export function recordLhMode(state: LhModeInfo | undefined): { lhMode: string |
 
 /** UNI-269: long-horizon's command runner behind `set_lh_mode` (packages/long-horizon/src/commands.ts). */
 export const LH_MODE_RUNNER = "unipi:lh-mode";
+/** UNI-282: long-horizon's agent graph ops runner (packages/long-horizon/index.ts). */
+export const LH_GRAPH_RUNNER = "unipi:lh-graph";
 /** UNI-118: dream_status pushes coalesce within this window. */
 export const DREAM_COALESCE_MS = 250;
 
@@ -1508,11 +1510,18 @@ export function createBridge(pi: ExtensionAPI, deps: BridgeDeps = defaultDeps) {
       case "tree_go": {
         if (!(await ensureIdle(msg.force))) return write(sock, { t: "error", message: "pi is busy. Stop the current run first.", code: "busy", ref: msg.ref });
         try {
+          let restore: TreeGoRestore | undefined;
           await runCommandOp(async (cctx) => {
+            // Read before navigating: the target is a user message → pi moves
+            // the leaf to just before it, and (like /tree) its text goes back
+            // to the composer (UNI-290).
+            const target = cctx.sessionManager.getEntry?.(msg.id);
             const result = await cctx.navigateTree(msg.id, { summarize: msg.summarize });
             if (result.cancelled) throw new Error("Cancelled");
+            const leaf = cctx.sessionManager.getLeafId?.() ?? null;
+            restore = treeGoRestore(target, (result as { editorText?: unknown }).editorText, leaf);
           });
-          ack();
+          write(sock, { t: "ack", ref: msg.ref, ...(restore ?? {}) });
         } catch (error) {
           fail(error instanceof Error ? error.message : String(error));
         }
@@ -1581,6 +1590,26 @@ export function createBridge(pi: ExtensionAPI, deps: BridgeDeps = defaultDeps) {
         }
         return;
       }
+      case "lh_graph": {
+        try {
+          const out = await callCommandRunner<{ ok: boolean; reason?: string; output?: { text?: string }; runs?: unknown[] }>(LH_GRAPH_RUNNER, ctx, { op: msg.op, id: msg.id, graphId: msg.graphId });
+          if (!out.found) return fail("The agent graph needs a newer unipi on this PC.");
+          if (!out.result?.ok) return fail(out.result?.reason ?? "The graph op failed.");
+          if (msg.op === "stop") {
+            ack();
+            return;
+          }
+          if (msg.op === "output") {
+            const o = out.result.output ?? {};
+            write(sock, { t: "lh_graph", op: "output", output: { ...o, ...(typeof o.text === "string" ? { text: clipText(o.text, 256 * 1024) } : {}) }, ref: msg.ref });
+            return;
+          }
+          write(sock, { t: "lh_graph", op: "history", runs: out.result.runs ?? [], ref: msg.ref });
+        } catch (error) {
+          fail(error instanceof Error ? error.message : String(error));
+        }
+        return;
+      }
       case "dream_get":
         write(sock, { t: "dream_status", status: dreamStatus(), ref: msg.ref });
         return;
@@ -1640,10 +1669,14 @@ export function createBridge(pi: ExtensionAPI, deps: BridgeDeps = defaultDeps) {
         return;
       }
       case "work_transcript": {
-        // Subagent mini-transcripts need @pi-unipi/subagents' transcript
-        // builder (TUI-flavoured); UNI-160 ships the live-log half (bg tasks)
-        // first and reports this a known gap (see the task report).
-        fail("Subagent transcripts aren't available yet.");
+        // UNI-282: a subagent's mini-transcript (work id `agent-<id>` or a
+        // graph step's operator id) from @pi-unipi/subagents' builder.
+        const out = workTranscript(msg.id);
+        if ("error" in out) return fail(out.error);
+        const items = out.items.slice(-400).map((item) =>
+          item.kind === "tool" ? { ...item, output: clipText(item.output, 8 * 1024) } : { ...item, text: clipText(item.text, 32 * 1024) },
+        );
+        write(sock, { t: "work_transcript", id: msg.id, items, ...(out.report !== undefined ? { report: clipText(out.report, 256 * 1024) } : {}), ref: msg.ref });
         return;
       }
       case "work_stop": {

package/packages/app-bridge/src/snapshot.ts

@@ -273,3 +273,29 @@ export function historyPage(branch: readonly unknown[], before: string, budget =
   }
   return { entries: out.reverse(), more };
 }
+
+/** UNI-290: what goes back into the app's composer after `tree_go` to a user
+ * message — its text (pi's own `editorText` when the runtime passes it on,
+ * else read off the entry, joined the same way pi does) and its images as
+ * the usual phone-safe refs (inline thumbnail or a `mediaRef`). */
+export type TreeGoRestore = { restore: { text: string; images?: Array<{ mime: string; data?: string; mediaRef?: string; bytes?: number }> } };
+
+/** The ack extras for a `tree_go` that landed: only when `target` is a user
+ * message and pi really moved the leaf off it (to its parent) — a no-op
+ * navigation (already there) restores nothing. */
+export function treeGoRestore(target: unknown, editorText: unknown, leafAfter: string | null): TreeGoRestore | undefined {
+  const e = target as { id?: string; type?: string; message?: { role?: string; content?: unknown } } | null | undefined;
+  if (!e || e.type !== "message" || e.message?.role !== "user") return undefined;
+  if (leafAfter !== null && leafAfter === e.id) return undefined;
+  const content = e.message.content;
+  const parts = Array.isArray(content) ? (content as Array<{ type?: string; text?: unknown }>) : [];
+  const fromEntry = typeof content === "string" ? content : parts.filter((p) => p?.type === "text" && typeof p.text === "string").map((p) => p.text as string).join("");
+  const text = typeof editorText === "string" ? editorText : fromEntry;
+  const images = parts
+    .filter((p) => p?.type === "image")
+    .map((p) => phoneSafe(p) as { mime?: string; data?: string; mediaRef?: string; bytes?: number } | null)
+    .filter((p): p is { mime?: string; data?: string; mediaRef?: string; bytes?: number } => !!p && (typeof p.data === "string" || typeof p.mediaRef === "string"))
+    .map((p) => ({ mime: p.mime ?? "image/*", ...(p.data ? { data: p.data } : {}), ...(p.mediaRef ? { mediaRef: p.mediaRef } : {}), ...(typeof p.bytes === "number" ? { bytes: p.bytes } : {}) }));
+  if (!text && !images.length) return undefined;
+  return { restore: { text: clipText(text, TEXT_CLIP), ...(images.length ? { images } : {}) } };
+}

package/packages/app-bridge/src/wire.ts

@@ -275,8 +275,11 @@ export type OutMsg =
   | { t: "btw_list"; pages: BtwListPage[]; complete?: true; ref?: string }
   /** `code: "busy"`: new/resume/fork/tree_go while pi is running — the phone may retry with `force:true`. */
   | { t: "error"; message: string; ref?: string; code?: "busy" }
-  /** `as: "command"`: the prompt ran an extension command (no chat message follows). */
-  | { t: "ack"; ref?: string; as?: "command" }
+  /** `as: "command"`: the prompt ran an extension command (no chat message follows).
+   * `restore` (UNI-290, `tree_go` only): the target was a user message, so pi
+   * moved the leaf to just before it — its text (and images, phone-safe refs)
+   * go back into the phone's composer, like /tree puts it in the TUI editor. */
+  | { t: "ack"; ref?: string; as?: "command"; restore?: { text: string; images?: Array<{ mime: string; data?: string; mediaRef?: string; bytes?: number }> } }
   /** The session is being replaced (new/resume/fork/reload): reconnect to get the new session's hello. */
   | { t: "reconnect"; reason: string }
   /** A page of older entries (oldest first) ending right before `before`. */
@@ -325,6 +328,8 @@ export type OutMsg =
   | { t: "lh_progress"; progress: LhProgressInfo | undefined; ref?: string }
   /** UNI-269: the working mode changed (pushed to every client, coalesced). */
   | { t: "lh_mode"; mode: LhModeInfo | undefined }
+  /** UNI-282: reply to `lh_graph` (stop replies `ack` instead). */
+  | { t: "lh_graph"; op: "output" | "history"; output?: unknown; runs?: unknown[]; ref?: string }
   /** UNI-118: Dream status changed (pushed to every client, coalesced), or the
    *  reply to `dream_get` (`ref`). `status` undefined = the dream module isn't loaded. */
   | { t: "dream_status"; status: DreamStatusInfo | undefined; ref?: string }
@@ -464,6 +469,11 @@ export type InMsg =
   /** UNI-269: switch the working mode (no prompt); `none` = /unipi:regular.
    *  Replies `ack` (then an `lh_mode` push) or `error{message}`. */
   | { t: "set_lh_mode"; mode: LhModeId; ref?: string }
+  /** UNI-282: agent graph ops for the Progress sheet. `output` = one step's
+   *  full committed result (`id` = work id or result id, `graphId?` for a past
+   *  graph); `stop` = stop the running graph; `history` = past graphs as runs.
+   *  Replies `lh_graph{op, output? | runs?, ref}` or `error`. */
+  | { t: "lh_graph"; op: "output" | "stop" | "history"; id?: string; graphId?: string; ref?: string }
   /** UNI-118: the current Dream status; replies `dream_status{status, ref}`. */
   | { t: "dream_get"; ref?: string }
   /** UNI-118: one run's report + trajectory; replies `dream_detail` (or `error`). */
@@ -510,6 +520,7 @@ const IN_TYPES = new Set([
   "work_background",
   "lh_progress_get",
   "set_lh_mode",
+  "lh_graph",
   "dream_get",
   "dream_detail",
   "dream_action",
@@ -654,6 +665,17 @@ export function parseIn(line: string): InMsg | { bad: string; ref?: string } | u
         return { bad: "set_lh_mode.mode must be goal|ralph|swarm|graph|none", ref };
       }
       return { t: "set_lh_mode", mode: m.mode as LhModeId, ref };
+    case "lh_graph": {
+      if (m.op !== "output" && m.op !== "stop" && m.op !== "history") return { bad: "lh_graph.op must be output|stop|history", ref };
+      if (m.op === "output" && (typeof m.id !== "string" || !m.id)) return { bad: "lh_graph output needs id", ref };
+      return {
+        t: "lh_graph",
+        op: m.op,
+        ...(typeof m.id === "string" && m.id ? { id: m.id } : {}),
+        ...(typeof m.graphId === "string" && m.graphId ? { graphId: m.graphId } : {}),
+        ref,
+      };
+    }
     case "dream_get":
       return { t: "dream_get", ref };
     case "dream_detail":

package/packages/app-bridge/src/work.ts

@@ -11,6 +11,7 @@ export {
   stopWorkItem,
   backgroundWorkItem,
   workLogPage,
+  workTranscript,
   type WorkItem,
   type WorkDot,
 } from "@pi-unipi/core";

package/packages/ask-user/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/ask-user",
-  "version": "3.0.0-alpha.40",
+  "version": "3.0.0-alpha.42",
   "description": "Structured user input tool for Pi coding agent — single-select, multi-select, freeform",
   "type": "module",
   "main": "index.ts",
@@ -42,7 +42,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.40"
+    "@pi-unipi/core": "3.0.0-alpha.42"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.87.1",

package/packages/autocomplete/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/command-enchantment",
-  "version": "3.0.0-alpha.40",
+  "version": "3.0.0-alpha.42",
   "description": "Enhanced TUI autocomplete for /unipi:* commands — colored, sorted, and grouped by package",
   "type": "module",
   "main": "src/index.ts",

package/packages/background-tasks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/background-tasks",
-  "version": "3.0.0-alpha.40",
+  "version": "3.0.0-alpha.42",
   "description": "Background tasks for UniPi — durable shell jobs and delegated background agents with a footer dock",
   "type": "module",
   "main": "src/index.ts",
@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@earendil-works/pi-ai": "^0.87.1",
-    "@pi-unipi/core": "3.0.0-alpha.40",
+    "@pi-unipi/core": "3.0.0-alpha.42",
     "turndown": "^7.2.4"
   },
   "devDependencies": {

package/packages/btw/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/btw",
-  "version": "3.0.0-alpha.40",
+  "version": "3.0.0-alpha.42",
   "description": "A pi extension for parallel side conversations with /unipi:btw — part of the Unipi suite",
   "type": "module",
   "main": "extensions/btw.ts",
@@ -37,7 +37,7 @@
     "@earendil-works/pi-tui": "^0.87.1"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.40"
+    "@pi-unipi/core": "3.0.0-alpha.42"
   },
   "pi": {
     "extensions": [

package/packages/compactor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/compactor",
-  "version": "3.0.0-alpha.40",
+  "version": "3.0.0-alpha.42",
   "description": "Compaction for Pi — lossless zero-LLM or model summaries, rebuilt from full history, with session recall",
   "type": "module",
   "main": "src/index.ts",
@@ -33,8 +33,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.40",
-    "@pi-unipi/info-screen": "3.0.0-alpha.40",
+    "@pi-unipi/core": "3.0.0-alpha.42",
+    "@pi-unipi/info-screen": "3.0.0-alpha.42",
     "@earendil-works/pi-agent-core": "^0.87.1"
   },
   "peerDependencies": {

package/packages/core/bus.ts

@@ -58,6 +58,17 @@ export interface LhProgressItem {
   /** The committed result / failure note, clipped. */
   summary?: string;
   attempts?: number;
+  /** UNI-282 (graph/swarm): the subagent that runs/ran it (opens its transcript). */
+  operatorId?: string;
+  /** Committed result id (`r-<id>`) — read the full text with the graph output op. */
+  resultId?: string;
+  /** Subagent profile (graph/swarm). */
+  profile?: string;
+  startedAt?: number;
+  endedAt?: number;
+  toolCalls?: number;
+  /** Input + output tokens of the child run (settled). */
+  tokens?: number;
 }
 
 /** One long-horizon run (the current one or the last finished one). */
@@ -73,6 +84,10 @@ export interface LhProgressRun {
   ralph?: { name: string; iteration: number; maxIterations: number; checked: number; total: number };
   goal?: { objective: string; status: string; turn: number; maxTurns: number; percent?: number; summary?: string; estimatedAt?: number };
   endedAt?: number;
+  /** UNI-282 (graph/swarm): the durable graph id (history / output ops). */
+  graphId?: string;
+  /** Graph/swarm: result ids the supervisor's finish selected. */
+  selected?: string[];
 }
 
 /** One line of the shared progress log, generated from state transitions (never hand-written). */

package/packages/core/index.ts

@@ -54,3 +54,4 @@ export * from "./src/hints/store.js";
 export { CRAB_14_LINES_256, CRAB_14_LINES_TRUECOLOR, CRAB_22_LINES_256, CRAB_22_LINES_TRUECOLOR } from "./src/hints/crab-data.js";
 export * from "./harness-messages.js";
 export * from "./remote-dialogs.js";
+export * from "./src/skill-conditions.js";

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/core",
-  "version": "3.0.0-alpha.40",
+  "version": "3.0.0-alpha.42",
   "description": "Shared utilities, event types, and constants for Unipi extension suite",
   "type": "module",
   "license": "MIT",

package/packages/core/src/skill-conditions.ts

@@ -0,0 +1,68 @@
+/**
+ * @pi-unipi/core — skill visibility conditions (UNI-300)
+ *
+ * A generic, tiny gate any module can use to hide one of its bundled
+ * skills from the model when some runtime fact says it can't be used
+ * right now (e.g. the PC's browser is off). Skill-registry (and anything
+ * else shaping `options.skills`) calls `skillConditionsPass` per skill
+ * name; a module that owns the fact calls `registerSkillCondition` once
+ * at load time with a cheap, synchronous predicate.
+ *
+ * Deliberately process-global like the rest of core's small registries
+ * (command-runner, settings): modules load once per process, and this
+ * needs no session/ctx threading. A condition must never throw or block;
+ * callers treat a throwing condition as "false" (hidden) defensively but
+ * conditions should fail open themselves when unsure.
+ */
+
+export type SkillCondition = () => boolean;
+
+const conditions = new Map<string, SkillCondition>();
+
+/** Registers (or replaces) the visibility condition for a skill name. */
+export function registerSkillCondition(skillName: string, condition: SkillCondition): void {
+  conditions.set(skillName, condition);
+}
+
+export function unregisterSkillCondition(skillName: string): void {
+  conditions.delete(skillName);
+}
+
+/** True when the skill has no registered condition, or its condition returns true. A throwing
+ *  condition counts as false (hidden) — safer than crashing the turn to show a broken skill. */
+export function skillConditionPasses(skillName: string): boolean {
+  const condition = conditions.get(skillName);
+  if (!condition) return true;
+  try {
+    return condition();
+  } catch {
+    return false;
+  }
+}
+
+/** Reason a skill is currently hidden (for a clear `/skill:name` refusal), or undefined when
+ *  it isn't gated by a condition, or its condition is registered but no reason was given. */
+export type SkillConditionReason = () => string | undefined;
+
+const reasons = new Map<string, SkillConditionReason>();
+
+/** Optional: a human reason shown when `/skill:name` is blocked because the condition is false. */
+export function registerSkillConditionReason(skillName: string, reason: SkillConditionReason): void {
+  reasons.set(skillName, reason);
+}
+
+export function skillConditionReason(skillName: string): string | undefined {
+  const fn = reasons.get(skillName);
+  if (!fn) return undefined;
+  try {
+    return fn();
+  } catch {
+    return undefined;
+  }
+}
+
+/** Test hook. */
+export function resetSkillConditionsForTests(): void {
+  conditions.clear();
+  reasons.clear();
+}

package/packages/core/src/work/index.ts

@@ -272,6 +272,27 @@ export async function workLogPage(
   }
 }
 
+/** UNI-282: a subagent's mini-transcript (published by @pi-unipi/subagents). */
+export type WorkTranscriptItem =
+  | { kind: "task"; text: string }
+  | { kind: "text"; text: string }
+  | { kind: "tool"; name: string; arg: string; output: string; isError: boolean; running: boolean; durationMs?: number };
+
+const SUBAGENT_TRANSCRIPT_KEY = Symbol.for("unipi.subagents.transcript");
+
+/** Transcript items + final report of a subagent (work id `agent-<id>`, or a bare subagent id). */
+export function workTranscript(id: string): { items: WorkTranscriptItem[]; report?: string; status?: string } | { error: string } {
+  const [kind, rest] = splitId(id);
+  const agentId = kind === "agent" ? rest : kind === "bg" || kind === "sidekick" ? undefined : id;
+  if (agentId === undefined) return { error: "Only subagents have a transcript." };
+  const read = (globalThis as unknown as Record<symbol, unknown>)[SUBAGENT_TRANSCRIPT_KEY] as
+    | ((id: string) => { items: WorkTranscriptItem[]; report?: string; status?: string } | undefined)
+    | undefined;
+  if (!read) return { error: "Subagents are not available." };
+  const out = read(agentId);
+  return out ?? { error: "That subagent is gone." };
+}
+
 // ── change signal ────────────────────────────────────────────────────────
 //
 // A cheap "something in the work list might have changed" notifier so a TUI

package/packages/core/src/work/tray.ts

@@ -6,7 +6,10 @@
  *   ── ▌Background tasks (2 · 1 running)▐  Subagents (3) ───── ←→ tabs · esc close
  *   <the active tab's pane: the bg task list/logs, or the subagent list/transcript>
  *
- * Nothing is drawn while the tray is closed (no strip, no spinners).
+ * While the tray is closed and has items, ONE dim hint line sits under the
+ * editor (UNI-291) — `Background tasks 1 running · Subagents 2 · ↓ open` —
+ * so ↓ is discoverable; nothing at all when the tray is empty or open (no
+ * strip chrome, no per-item spinners).
  *
  * Owners register a tab (`registerWorkTrayTab`) and supply the pane; this
  * module owns the tab strip, ←/→ switching, the ↓ key and the open/close
@@ -63,11 +66,9 @@ export interface WorkTrayTab {
 
 export type TrayTheme = Pick<Theme, "fg" | "bold">;
 
-/** A zero-line widget: only there to learn the TUI (for the ↓ focus check).
- *  The tray draws NOTHING while closed — no strip, no spinners (the user
- *  found the always-on "◆ Background tasks … · ↓ open" + per-agent spinner
- *  lines messy); the footer's single "Working… · ↓ open" line is the only
- *  hint that wake-capable work is pending. */
+/** The below-editor widget: learns the TUI (for the ↓ focus check) and draws
+ *  the one-line hint while the tray is closed and has items (UNI-291). The
+ *  old "◆ …" strip + per-agent spinner lines stay gone (5b7f2e1: messy). */
 const STRIP_KEY = "work-tray-strip";
 export const TRAY_HINT = "←→ tabs · esc close";
 
@@ -261,6 +262,47 @@ export class WorkTray implements Component {
   }
 }
 
+// ── hint line (below the editor while the tray is closed) ─────────────────────
+
+export const TRAY_OPEN_HINT = "↓ open";
+
+/** One tab's part of the hint: `Label N`, `Label N running` (all running) or
+ *  `Label N (k running)`; level 1 uses the short label, level 2 also the
+ *  compact `Short N/k` (k running of N). */
+function hintPart(tab: WorkTrayTab, c: WorkTrayCounts, level: number): string {
+  const label = level > 0 ? (tab.shortLabel ?? tab.label) : tab.label;
+  const n = String(c.total);
+  if (c.running <= 0) return `${label} ${n}`;
+  if (level >= 2) return `${label} ${n}/${String(c.running)}`;
+  return c.running >= c.total ? `${label} ${n} running` : `${label} ${n} (${String(c.running)} running)`;
+}
+
+/** The plain hint text (no colour) for `width` columns, or undefined when no
+ *  visible tab has items. Full labels, then short labels, then compact
+ *  counts; past that the counts are cut so "↓ open" always stays visible. */
+export function trayHintText(list: readonly WorkTrayTab[], width: number): string | undefined {
+  const items = list.map((tab) => ({ tab, c: safeCounts(tab) })).filter(({ c }) => c.total > 0);
+  if (items.length === 0 || width <= 0) return undefined;
+  const suffix = ` · ${TRAY_OPEN_HINT}`;
+  let line = "";
+  for (const level of [0, 1, 2]) {
+    line = items.map(({ tab, c }) => hintPart(tab, c, level)).join(" · ");
+    if (visibleWidth(line) + visibleWidth(suffix) <= width) return `${line}${suffix}`;
+  }
+  const room = width - visibleWidth(suffix);
+  if (room < 4) return truncateToWidth(TRAY_OPEN_HINT, width, "");
+  return `${truncateToWidth(line, room, "…")}${suffix}`;
+}
+
+/** The below-editor hint: [] when the tray is open or empty, else one dim
+ *  line one column short of the terminal (exactly-full-width lines desync
+ *  wrapping terminals — footer issue #31), indented like the editor text. */
+export function renderTrayHint(theme: TrayTheme, list: readonly WorkTrayTab[], width: number, open = false): string[] {
+  if (open || width <= 2) return [];
+  const text = trayHintText(list, width - 2);
+  return text === undefined ? [] : [` ${theme.fg("dim", text)}`];
+}
+
 // ── registration + lifecycle ────────────────────────────────────────────────
 
 /** True while the tray is open. */
@@ -301,10 +343,29 @@ function ensureWorkTray(pi: ExtensionAPI): void {
       unsubInput?.();
       unsubInput = undefined;
       if (!ctx.hasUI) return;
-      // Zero-line widget: only captures the TUI ref for the ↓ focus check.
-      ctx.ui.setWidget(STRIP_KEY, (tui) => {
+      // The hint line under the editor (UNI-291), also the TUI ref for the
+      // ↓ focus check. Renders nothing with no items, so idle sessions show
+      // no line; work changes re-render it (the TUI diffs, so an unchanged
+      // line costs nothing and never moves focus).
+      ctx.ui.setWidget(STRIP_KEY, (tui, theme) => {
         tuiRef = tui;
-        return { render: () => [], invalidate() {} };
+        let unsub: () => void = () => {};
+        try {
+          unsub = subscribeWorkChanges(() => tui.requestRender());
+        } catch {
+          /* the line is still right on the next render */
+        }
+        return {
+          render: (width: number) => {
+            try {
+              return renderTrayHint(theme, sortedTabs(), width, openTray !== undefined);
+            } catch {
+              return [];
+            }
+          },
+          invalidate() {},
+          dispose: () => unsub(),
+        };
       }, { placement: "belowEditor" });
       unsubInput = ctx.ui.onTerminalInput(onTerminalInput);
     } catch {