@kurrent/kcap 1.3.0-beta.6 → 1.3.0-beta.7

package/bin/refresh.js

@@ -1,6 +1,6 @@
-// Refreshes kcap's user-scope coding-agent installs so users pick up new or updated
-// skills, Codex/Cursor/Copilot hook commands, the Pi live-ingest extension, and
-// Claude plugin registration.
+// Refreshes kcap's user-scope coding-agent installs after an install or upgrade, by running
+// `kcap refresh` — the native binary owns the refresh list and the Claude plugin's .mcp.json patch,
+// so every installer (npm, the install scripts, a script install's `kcap update`) runs the same one.
 //
 // Shared by:
 // - postinstall.js — runs after `npm install -g @kurrent/kcap` (incl. upgrades),
@@ -10,152 +10,34 @@
 //
 // This file must never require kcap.js: during `kcap update`, runUpdate executes
 // before kcap.js's final module.exports assignment, so it would observe partial
-// exports. Shared platform/binary resolution lives in resolve.js instead.
+// exports.
 
 const { spawnSync } = require("child_process");
-const path = require("path");
-const fs = require("fs");
 
-// One entry per agent. Order is independent — each refresh is gated by its own
-// marker via `--if-installed`, which no-ops unless the user has previously
-// opted in (marker file present OR pre-marker install detected). A vendor entry
-// also refreshes the shared ~/.agents/skills tree, but only tops up one that is
-// already there: `plugin remove --skills` must survive an upgrade. The daemon
-// entry needs no marker: it acts only on service units that are already installed.
-const REFRESHES = [
-  ["plugin", "install", "--skills",  "--if-installed"],
-  ["plugin", "install", "--codex",   "--if-installed"],
-  ["plugin", "install", "--cursor",  "--if-installed"],
-  ["plugin", "install", "--copilot", "--if-installed"],
-  ["plugin", "install", "--pi",      "--if-installed"], // Pi extension (~/.pi/agent/extensions/kcap.ts)
-  ["plugin", "install", "--opencode", "--if-installed"], // OpenCode plugin (~/.config/opencode/plugins/kcap.ts)
-  ["plugin", "install", "--gemini",  "--if-installed"], // Gemini hooks/MCP/instructions (~/.gemini)
-  ["plugin", "install", "--kiro",    "--if-installed"], // Kiro agent hooks (~/.kiro/agents/kcap.json)
-  ["plugin", "install", "--antigravity", "--if-installed"], // Antigravity hooks (~/.gemini/config/plugins/kcap)
-  ["plugin", "install",              "--if-installed"], // Claude
-  ["daemon", "service", "refresh"],
-];
+// Above the binary's own worst case: eleven steps, each bounded at 60s.
+const REFRESH_TIMEOUT_MS = 15 * 60_000;
 
-// Runs each refresh via the given launcher (an absolute path to kcap.js).
-// Each refresh runs independently: a failure, timeout, or unexpected exit code
-// from one never prevents the others and never throws to the caller — a failed
-// refresh must never break `npm install` or report `kcap update` as failed.
-function runRefreshes(launcherPath) {
-  // Point the shipped Claude plugin's MCP entries at the native binary. Runs
-  // here because runRefreshes fires at exactly the two moments the plugin dir
-  // has just been (re)written by npm: postinstall and `kcap update`.
-  patchPluginMcpConfig(launcherPath);
-
-  for (const argv of REFRESHES) {
-    try {
-      spawnSync(process.execPath, [launcherPath, ...argv], {
-        stdio: "ignore",
-        env: process.env,
-        // Hard ceiling so a stalled child can never hang the caller.
-        timeout: 60_000,
-        killSignal: "SIGKILL",
-        windowsHide: true,
-      });
-    } catch {
-      // Never fail the caller.
-    }
-  }
-}
-
-// ── Claude plugin .mcp.json patch ───────────────────────────────────────────
-//
-// The plugin ships `"command": "kcap"`, which resolves to the node wrapper —
-// one resident Node runtime per MCP server per open Claude session (~25 MB
-// idle each). Rewriting the command to the resolved native binary makes Claude
-// spawn the binary directly. Best-effort: on any failure the shipped value
-// stays in place, which still works via the wrapper.
-
-// The servers shipped in the plugin's .mcp.json, keyed by canonical
-// `["mcp", <suffix>]` args. Only these exact name/args pairs are patched —
-// anything else in the file is preserved verbatim.
-const PLUGIN_MCP_SERVERS = {
-  "kcap-review":    "review",
-  "kcap-sessions":  "sessions",
-  "kcap-flows":     "flows",
-  "kcap-memory":    "memory",
-  "kcap-workitems": "workitems",
-  "kcap-plans":     "plans",
-  "kcap-artefacts": "artefacts",
-  "kcap-analytics": "analytics",
-  "kcap-knowledge": "knowledge",
-  "kcap-handoff":   "handoff",
-};
-
-// A command this patcher may rewrite: the shipped literal "kcap", or an
-// absolute path whose basename is the kcap binary (a previous patch that has
-// gone stale after an npm re-layout). Handles both path flavors so a stale
-// Windows path is still recognized. Anything else is a customization → keep.
-function isPatchableKcapCommand(command) {
-  if (command === "kcap") return true;
-  if (typeof command !== "string") return false;
-  if (!path.posix.isAbsolute(command) && !path.win32.isAbsolute(command)) return false;
-  const base = command.split(/[\\/]/).pop().toLowerCase();
-  return base === "kcap" || base === "kcap.exe";
-}
-
-// Pure: rewrites in place the canonical plugin entries of `cfg` whose command
-// is patchable, returning whether anything changed. Throws on a shape that
-// isn't the plugin config (caller turns that into the single warning).
-function patchPluginMcpServers(cfg, binaryPath) {
-  if (!cfg || typeof cfg !== "object" || Array.isArray(cfg)) {
-    throw new Error("config is not an object");
-  }
-  const servers = cfg.mcpServers;
-  if (!servers || typeof servers !== "object" || Array.isArray(servers)) {
-    throw new Error("mcpServers is not an object");
-  }
-
-  let changed = false;
-  for (const [name, suffix] of Object.entries(PLUGIN_MCP_SERVERS)) {
-    const entry = servers[name];
-    if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
-    if (!Array.isArray(entry.args) || entry.args.length !== 2 ||
-        entry.args[0] !== "mcp" || entry.args[1] !== suffix) continue; // customized args → keep
-    if (!isPatchableKcapCommand(entry.command)) continue;              // customized command → keep
-    if (entry.command === binaryPath) continue;                        // already current
-    entry.command = binaryPath;
-    changed = true;
-  }
-  return changed;
-}
-
-// Rewrites the plugin's shipped .mcp.json (a sibling `kcap/` dir of the
-// launcher's `bin/`) so Claude spawns the native binary directly. Validates
-// before writing, writes a sibling temp file, then renames atomically — the
-// original survives any pre-rename failure. Never throws; on failure it emits
-// ONE concise warning and leaves the shipped `"command": "kcap"` in place.
-// `binaryPath` is a test seam; real callers let it resolve.
-function patchPluginMcpConfig(launcherPath, binaryPath) {
-  let mcpJsonPath;
+// Runs `kcap refresh` through the given launcher (an absolute path to kcap.js), so the NEW
+// launcher and the NEW binary run it after an upgrade. Never throws and never fails the caller:
+// a failed refresh must never break `npm install` or report `kcap update` as failed. Its stderr
+// (which steps failed, a plugin patch that could not be written) is passed on through `warn`.
+function runRefreshes(launcherPath, warn = console.warn) {
   try {
-    binaryPath = binaryPath || require("./resolve").resolveNativeBinary();
-    if (!binaryPath) return; // unsupported platform / package missing — wrapper keeps working
-
-    mcpJsonPath = path.join(path.dirname(launcherPath), "..", "kcap", ".mcp.json");
-    if (!fs.existsSync(mcpJsonPath)) return; // dev checkout / plugin not shipped
-
-    const cfg = JSON.parse(fs.readFileSync(mcpJsonPath, "utf8"));
-    if (!patchPluginMcpServers(cfg, binaryPath)) return; // already patched / nothing canonical
-
-    const tmp = `${mcpJsonPath}.tmp-${process.pid}-${Date.now()}`;
-    try {
-      fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2) + "\n");
-      fs.renameSync(tmp, mcpJsonPath);
-    } catch (e) {
-      try { fs.unlinkSync(tmp); } catch {}
-      throw e;
-    }
-  } catch (e) {
-    console.warn(
-      `kcap: could not point the Claude plugin MCP entries at the native binary` +
-      ` (${e && e.message ? e.message : e}); they will keep launching via the node wrapper.`,
-    );
+    const result = spawnSync(process.execPath, [launcherPath, "refresh"], {
+      stdio: ["ignore", "ignore", "pipe"],
+      encoding: "utf8",
+      env: process.env,
+      timeout: REFRESH_TIMEOUT_MS,
+      killSignal: "SIGKILL",
+      windowsHide: true,
+    });
+    const stderr = (result.stderr || "").trim();
+    if (stderr) warn(stderr);
+    if (result.status !== 0)
+      warn("kcap: some agent integrations were not refreshed; run `kcap refresh` to retry.");
+  } catch {
+    // Never fail the caller.
   }
 }
 
-module.exports = { runRefreshes, patchPluginMcpConfig, patchPluginMcpServers, isPatchableKcapCommand };
+module.exports = { runRefreshes };

package/bin/resolve.js

@@ -1,10 +1,5 @@
-// Side-effect-free platform/native-binary resolution, shared by kcap.js (the
-// launcher) and refresh.js (postinstall / `kcap update` refresh).
-//
-// This lives in its OWN module — refresh.js must never require kcap.js: during
-// `kcap update`, runUpdate executes BEFORE kcap.js's final module.exports
-// assignment, so a refresh.js → kcap.js require would observe partial exports
-// exactly on that path. Requiring this module has no side effects.
+// Side-effect-free platform/native-binary resolution for kcap.js (the launcher).
+// Requiring this module has no side effects.
 
 const path = require("path");
 const fs = require("fs");

package/kcap/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "kcap",
-  "version": "1.3.0-beta.6",
+  "version": "1.3.0-beta.7",
   "description": "Records and visualizes Claude Code sessions via kcap CLI hooks"
 }

package/kcap/README.md

@@ -20,6 +20,7 @@ Search and recall past Kurrent Capacitor sessions from inside the agent.
 | `get_session_transcript` | Speaker-tagged transcript window, with `around_event` drill-in for search hits |
 | `list_repo_plans` | List a repository's declared plans you can see, most recently touched first |
 | `get_declared_plans` | A plan's documents and full task list, by `plan_id` or `session_id` |
+| `get_session_evals` | Eval state and scores for up to 25 sessions by id; works on every plan |
 
 Repo-aware: it resolves the cwd to a repo hash at startup, so `search_sessions` defaults to *this* repo.
 

package/kcap/hooks/hooks.json

@@ -79,6 +79,16 @@
             "async": true
           }
         ]
+      },
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "kcap hook --claude --plan-read --no-update-check",
+            "timeout": 3
+          }
+        ]
       }
     ],
     "PostToolUseFailure": [

package/kcap/skills/agent-flows/SKILL.md

@@ -1,25 +1,23 @@
 ---
 name: agent-flows
 description: >-
-  This skill should be used ONLY when the user explicitly asks to run a
-  structured agent *flow* by name or definition id — e.g. "start a flow",
-  "run the code-review flow", "run the X flow", "use flow definition X",
-  "kick off an agent flow", or wants an iterative loop run by a separate
-  hosted participant agent that continues until sign-off. It covers the same
-  underlying tools as the `review-flows` skill (`start_review_flow` etc. are
-  aliases of the generic tools documented here) — use `review-flows` for the
-  two built-in review kinds (`spec-review`, `code-review`) and this skill for
-  any other flow definition, or when the user names a `definition_id`
-  explicitly. Do NOT use this skill (and do NOT call the flows MCP tools) for
-  an ordinary request such as "review my PR", "do X for me", or "check this
-  over" where the user just wants you to do the work yourself — perform that
-  work directly instead. To start a hosted agent that works on its own, use
-  `start-agents`.
+  Use this skill to drive a structured agent *flow*: a separate hosted
+  participant agent runs a definition from the server's flow catalogue and
+  iterates with you until sign-off. Use it when the user names a flow or
+  definition id ("run the code-review flow", "start a flow", "use flow
+  definition X"), when the user accepts a flow you offered, or when you are
+  about to offer one listed under "Flows you may offer" in your session
+  context because its when-to-use applies. Before starting a flow, call
+  get_flow_definition and follow its guide. Do NOT use this skill (and do NOT
+  call the flows MCP tools) for an ordinary request such as "review my PR",
+  "do X for me", or "check this over" where the user wants you to do the work
+  yourself — do it directly instead. To start a hosted agent that works on its
+  own, use `start-agents`.
 ---
 
 # Agent Flows
 
-Use the `kcap mcp flows` MCP tools (`list_flow_definitions`, `start_flow`, `send_to_participant`, `get_flow_status`, `close_flow`) to run a structured agent **flow**: your work is handed to a **separate, hosted participant agent** driven by a flow definition from the server's catalog, which returns a result (kind `findings` with the participant's result text, or `clean`); you address a `findings` result and keep iterating until the clean signal. This is a deliberate, heavier workflow — use it only when the user explicitly opts into it.
+Use the `kcap mcp flows` MCP tools (`list_flow_definitions`, `get_flow_definition`, `start_flow`, `send_to_participant`, `get_flow_status`, `close_flow`) to run a structured agent **flow**: your work is handed to a **separate, hosted participant agent** driven by a flow definition from the server's catalog, which returns a result (kind `findings` with the participant's result text, or `clean`); you address a `findings` result and keep iterating until the clean signal. This is a deliberate, heavier workflow — use it when the user asks for a flow or accepts one you offered, never on your own initiative.
 
 ## Long rounds are normal
 
@@ -39,15 +37,14 @@ and end the reviewer turn. The hosted-reviewer contract wins over driver-looking
 
 These tools do **not** perform the work themselves — they hand it off to a separate hosted participant agent running a named flow definition. If the user simply asked *you* to do something in a normal session — e.g. "review my PR", "review this diff", "check this spec", "do X" — just do it yourself and report the result directly. Do **NOT** call `start_flow` / `send_to_participant` for an ordinary request; that would spin up a hosted agent the user did not ask for.
 
-Only start a flow when the user explicitly asks for a flow — e.g. "start a flow", "run the code-review flow", "use flow definition X", or "re-review after I address the findings" via a flow.
+Only start a flow when the user explicitly asks for one — e.g. "start a flow", "run the code-review flow", "use flow definition X", or "re-review after I address the findings" via a flow — or accepts a flow you offered. Offer a flow only when your session context lists it under **Flows you may offer** and its when-to-use applies to what just happened; ask, and never start it before the user says yes. Skip the offer when the user asked you to do the work yourself, or while you are mid-task.
 
 ## Choosing the flow definition
 
-Once the user has explicitly opted into a flow (see above), pick the `definition_id`:
+Once the user has asked for a flow or accepted one you offered (see above), pick the `definition_id`:
 
-- Spec or design document → `definition_id: "spec-review"` (built-in; same as `review-flows`' `spec-review` kind)
-- Code changes or a pull request → `definition_id: "code-review"` (built-in; same as `review-flows`' `code-review` kind)
-- Anything else → the definition id the user named, or one from `list_flow_definitions` (read-only), which lists every definition this server can start — operator-published ones included — with its version, description, participant roles and their authored vendor and model, and whether it is single- or multi-participant. Call it whenever the user has not named a definition, or named one you have not seen listed: a definition it does not list is disabled, deleted or unknown, and `start_flow` will refuse it. If several fit, ask the user rather than guessing. A server that answers that it cannot list definitions only predates the tool — the two built-ins and any id the user names still work.
+- The flow the user named, or the one you offered and they accepted.
+- If the user has not named one → choose from `list_flow_definitions` (read-only), which lists every definition this server can start — operator-published ones included — with its version, description, participant roles and their authored vendor and model, and whether it is single- or multi-participant. Call it whenever the user has not named a definition, or named one you have not seen listed: a definition it does not list is disabled, deleted or unknown, and `start_flow` will refuse it. If several fit, ask the user rather than guessing. A server that answers that it cannot list definitions only predates the tool — the two built-ins and any id the user names still work.
 
 For the reserved `spec-review` and `code-review` aliases, reviewer-vendor language is role-bound:
 pass the one vendor explicitly named as the reviewer, ignore driver-harness mentions, honor
@@ -88,6 +85,10 @@ vendor supports this: the daemon must advertise a runtime model resolver for the
 (Claude and Codex today; other vendors keep vendor-only overrides with no model choice) or the
 server rejects the override outright.
 
+## Read the flow's guide first
+
+Before a catalogue start (`definition_id`), call `get_flow_definition(definition_id)`. The guide is written by whoever published the flow: what to put in `context`, which target to name, how to iterate on its results and when to close. Where it differs from the generic rules below, follow the guide. A server that does not publish guides says so; then work from the definition's description and the rules below. A flow started with an inline `definition_yaml` has no catalogue id and no guide: drive it by the generic rules and its own YAML.
+
 ## Composing a dynamic flow
 
 If nothing `list_flow_definitions` shows fits — no `definition_id` covers the roles or workflow you need — compose one inline instead: pass `definition_yaml` to `start_flow` in place of `definition_id`. Provide exactly one of the two, never both. (`start_review_flow` / `submit_review_round` stay catalog-only — this only applies to the generic `start_flow`.)
@@ -147,7 +148,7 @@ After applying the role-surface safety gate, if `start_flow` / `send_to_particip
 5. **If participant output is unclear or requires user input**, pause and ask the user before proceeding.
 6. **Never start a nested flow.** If you are the hosted participant (see above), do not call these tools yourself.
 7. **Address each role independently.** A flow definition declares one or more participant roles in its `participants` map (single-participant definitions use `reviewer`). A multi-participant `start_flow` returns no round — nothing has launched yet. Call `send_to_participant(flow_run_id, participant=<role>, message=…)` naming the role you want to address; its first message launches that role's agent lazily. Only one round is in flight per role at a time — sending to a role that's still working on a round gets a `409` naming the busy round — but every OTHER role stays addressable in the meantime. Sending an unknown role is rejected by the server, which names the valid roles in its error.
-8. **For a code review flow (`definition_id: "code-review"`), do NOT ask the participant to run tests.** CI covers test execution; participant feedback is on correctness, design, and adherence to conventions.
+8. **Ask the participant only for what the flow's guide allows.** If the guide says CI covers tests, do not ask the participant to run them; participant feedback is on what the flow exists to judge.
 9. **State where your changes live.** The participant's worktree is mirrored from **this session's project directory**, not from the directory you are working in, and no tool parameter can redirect it. So if you changed directory, are a subagent in another checkout, or the changeset lives in another worktree/repo/machine, the participant will NOT see it: say so in `context`/`message`, give it an explicit commit range (never `git diff origin/main...HEAD`), and inline the diffs — or pass `mode: "context-only"` to make your context the sole source of truth. The participant flags referenced changes it cannot find; incomplete context wastes a full round.
 
 ## Pending messages
@@ -170,10 +171,17 @@ The server enforces per-run budgets; watch for these in tool error responses:
 
 ## Workflow
 
+A catalogue flow (`definition_id`) starts with its guide; an inline `definition_yaml` flow skips this step:
+
+```
+get_flow_definition(definition_id)
+  → read the driver guide; prepare the context it asks for
+```
+
 Single-participant definitions start eagerly — round 1 runs as part of `start_flow`:
 
 ```
-start_flow(definition_id, target_kind, target_ref, target_title, context)
+start_flow(definition_id, target_kind, target_ref, target_title, session_title, context)
   → participant returns a result: kind findings (with the result text) | kind clean
 
 if clean:
@@ -192,7 +200,7 @@ if findings:
 Multi-participant definitions start round-less — you address each role yourself, and the run is clean only in aggregate:
 
 ```
-start_flow(definition_id, target_kind, target_ref, target_title, context)
+start_flow(definition_id, target_kind, target_ref, target_title, session_title, context)
   → no round yet — roles have not launched
 
 send_to_participant(flow_run_id, participant="reviewer", message=…)
@@ -218,7 +226,8 @@ report completion to user
 | Tool | Required args | Optional args | When to call |
 |---|---|---|---|
 | `list_flow_definitions` | — | — | Before `start_flow`, whenever the user has not named a definition or named one you have not seen listed. Read-only: returns each runnable definition's id, version, description, whether it is single- or multi-participant, and its participants' role, authored vendor and model. A `server_catching_up` error is retryable — do not read it as an empty catalog. |
-| `start_flow` | Exactly one of `definition_id` (catalog id, e.g. `spec-review`, `code-review`, or a custom catalog id) or `definition_yaml` (inline dynamic definition — see "Composing a dynamic flow"); plus `target_kind` (what is being worked on: `spec`, `code`, `pr`, `branch`, `file`, etc.), `target_ref` (a path, branch name, or PR URL/number that identifies the target), `target_title` (short human-readable title), `context` (background context: what to focus on, constraints, definition of done) | `vendor` (reserved aliases only — explicit reviewer vendor; omit to use the definition's authored vendor, or your saved `flows.reviewer_vendor` preference if it declares none), `model` (reserved aliases only — explicit reviewer model override; REQUIRES `vendor`, rejected on dynamic/multi-participant starts), `instructions`, `mode` (`context-only` — optional; by default the participant's worktree is mirrored from THIS SESSION's project directory, not from the directory you are working in. Pass `context-only` to opt out and treat the submitted context as authoritative) | Once, at the start of a flow task. |
+| `get_flow_definition` | `definition_id` | — | Before every catalogue (`definition_id`) `start_flow`. Read-only: returns the definition's participants and when to use it, then its authored driver guide (what to submit, how to iterate, when to close). An unknown, disabled or deleted id is an error; an older server reports that it publishes no guides. |
+| `start_flow` | Exactly one of `definition_id` (catalog id, e.g. `spec-review`, `code-review`, or a custom catalog id) or `definition_yaml` (inline dynamic definition — see "Composing a dynamic flow"); plus `target_kind` (what is being worked on: `spec`, `code`, `pr`, `branch`, `file`, etc.), `target_ref` (a path, branch name, or PR URL/number that identifies the target), `target_title` (short human-readable title), `session_title` (the participant session's title: a short phrase naming this piece of work, specific enough to tell it apart from other sessions — it replaces the definition's generic opening instruction as the name), `context` (background context: what to focus on, constraints, definition of done) | `vendor` (reserved aliases only — explicit reviewer vendor; omit to use the definition's authored vendor, or your saved `flows.reviewer_vendor` preference if it declares none), `model` (reserved aliases only — explicit reviewer model override; REQUIRES `vendor`, rejected on dynamic/multi-participant starts), `instructions`, `mode` (`context-only` — optional; by default the participant's worktree is mirrored from THIS SESSION's project directory, not from the directory you are working in. Pass `context-only` to opt out and treat the submitted context as authoritative) | Once, at the start of a flow task. |
 | `send_to_participant` | `flow_run_id`, `participant` (role name declared in the flow definition's `participants` map; single-participant definitions use `reviewer` — an unknown role is rejected, naming the valid ones), `message` | `instructions`, `async` (defaults to `true`) | After addressing a non-clean result for that role, or to launch a role for the first time. Pass the same `flow_run_id`, the role's name, and the updated message. |
 | `get_flow_status` | — | `flow_run_id` (omit to read the newest open flow this session started, or on a harness without a session identity the newest one started from this workspace; several open flows are listed instead), `session_id` (look up another session's flows; defaults to this session), `wait` (`true`/`false`, defaults to `false`) — when `true`, blocks until the round is terminal or roughly 3.5 minutes pass, instead of returning the current snapshot immediately | Poll or check the current status of a flow run (running, waiting, completed, failed). Use `wait: true` to ride out a long round instead of polling repeatedly yourself, and omit `flow_run_id` to recover a flow whose id you never received or lost. |
 | `close_flow` | `flow_run_id` | — | Only after the definition's clean signal — or when abandoning the task early; the run otherwise stays open until closed. |
@@ -226,13 +235,14 @@ report completion to user
 ## Example (custom definition)
 
 ```
-# Step 1 — start (all five required args required; the participant sees a mirror of THIS SESSION's
+# Step 1 — start (all six args required; the participant sees a mirror of THIS SESSION's
 # project directory, not of the directory you are working in — pass mode="context-only" to opt out)
 start_flow(
   definition_id="code-review",
   target_kind="branch",
   target_ref="feature/add-null-check",
   target_title="Add null check on user input",
+  session_title="Review the null check on user input",
   context="Review the diff on this branch for correctness and adherence to project conventions."
 )
 # → returns flow_run_id, e.g. "flow_abc123"
@@ -261,6 +271,7 @@ start_flow(
   target_kind="branch",
   target_ref="feature/add-null-check",
   target_title="Add null check on user input",
+  session_title="Review and test the null check on user input",
   context="Review the diff on this branch and write/run tests for the new code path."
 )
 # → returns flow_run_id, e.g. "flow_xyz789"; no round in the response

package/kcap/skills/eval-watch/SKILL.md

@@ -4,38 +4,31 @@ description: >-
   Follow a kcap import that setup just started and the evals landing on it —
   "Follow my kcap import" (the prompt `kcap setup` hands to your agent), "watch my
   import", "how is my import going", "are my evals done yet". Reads the handoff file
-  setup wrote, polls Capacitor analytics for exactly the sessions that import
-  created, waits for the sessions that imported while the user watched to be
-  evaluated, summarizes their evals, links to the results and offers the guided
-  tour. Not for browsing evals in general — that is the analytics or guided-tour
-  skill.
+  setup wrote, polls the eval state of exactly the sessions that import created,
+  waits for the sessions that imported while the user watched to be evaluated,
+  summarizes their evals, links to the results and offers the guided tour. Works on
+  every plan. Not for browsing evals in general — that is the guided-tour skill.
 ---
 
 # Eval watch
 
-You follow ONE import: the sessions listed in a handoff file `kcap setup` wrote. Every query you
-issue names only those sessions — never a repo-wide or tenant-wide read, and never a query without
-an `IN (...)` or `session_id = '...'` bound to this cohort. If a response ever includes a row for a
-session id outside the cohort, discard that row: never count it, link it, or mention it.
+You follow ONE import: the sessions listed in a handoff file `kcap setup` wrote. Every lookup you
+make names only those sessions — never a repo-wide or tenant-wide read. If a response ever carries
+an entry for a session id outside the cohort, discard it: never count it, link it, or mention it.
+
+Eval state comes from `get_session_evals` in the `kcap-sessions` MCP — never from the
+`kcap-analytics` MCP, which is a paid feature the workspace may not have.
 
 ## The safety rule — read this first
 
-Three grammars gate everything below:
+Two grammars gate everything below:
 - **Run id** (a `(run: <id>)` token, and the file's own `run_id`): `^[0-9a-f]{32}$`.
-- **Session id** (`session_ids`, `foreground_succeeded_ids`, and any id you place in a query):
-  `^[A-Za-z0-9_-]{1,128}$`.
-- **Repo hash** (the `repo_hash` field an analytics response returns, used only in the repo-scoped
-  link form): `^[0-9a-f]{16}$`. A `repo_hash` that fails this never reaches a link — fall back to
-  the no-repo-hash link form (section 7).
-
-The `kcap-analytics` MCP takes raw SQL text with no parameter binding, so the session-id grammar is
-the SQL-safety boundary, not just a format check. The class excludes quote, backslash, whitespace
-and `;`, so a value that matches it can never close a string literal or open a new statement — a
-matching id is emitted as a single-quoted literal (`'<id>'`) with **no escaping**, because none is
-needed and none should be attempted. A run of hyphens such as `--` matches the grammar and is safe
-to emit this way: inside a quoted literal it is data, not a SQL comment. An id that fails either
-grammar is **never** placed in SQL, a path, or a link — reject it and move on (section 2 below says
-what each layer's rejection does); never sanitize or escape an id into something that would pass.
+- **Session id** (`session_ids`, `foreground_succeeded_ids`, and any id you pass to a tool or put
+  in a link): `^[A-Za-z0-9_-]{1,128}$`.
+
+An id that fails its grammar is **never** placed in a tool call, a path, or a link — reject it and
+move on (section 2 below says what each layer's rejection does); never sanitize or escape an id
+into something that would pass.
 
 ## 1. Find the run
 
@@ -44,12 +37,12 @@ what each layer's rejection does); never sanitize or escape an id into something
   it does match, the run is bound: read ONLY `<config>/import-handoff-<id>.json`, where `<config>`
   is `$KCAP_CONFIG_DIR` when set, else `~/.config/kcap`, and check it against every Layer A rule in
   section 2, plus one more: its `run_id` field must equal `<id>` exactly. Missing, unreadable, or
-  failing any of those checks → say so and CLOSE (section 7) with no query. **Never fall through to
+  failing any of those checks → say so and CLOSE (section 7) with no lookup. **Never fall through to
   another run's file** — a different run's cohort does not belong to the run the user asked for.
 - Otherwise list `<config>/import-handoff-*.json`, keep the locator-valid ones (section 2) that are
-  watchable (`handoff_offered` true, or `handoff_suppressed` is `skill_not_installed` or
-  `no_agent_detected`), pick the newest `written_at`, and say which others you passed over.
-- Nothing qualifies → say you found no import to follow and CLOSE with no query.
+  watchable (`handoff_offered` true, or `handoff_suppressed` is `analytics_not_in_plan`,
+  `skill_not_installed` or `no_agent_detected`), pick the newest `written_at`, and say which others you passed over.
+- Nothing qualifies → say you found no import to follow and CLOSE with no lookup.
 
 ## 2. Validate the file — three layers
 
@@ -57,24 +50,25 @@ A failure at a lower layer never re-opens the file for a higher one.
 
 **Layer A** (may this file be selected at all): JSON parses; `schema_version` is 1; `run_id` matches
 `^[0-9a-f]{32}$`; `written_at` parses as ISO-8601 and is within the last 24 hours; `handoff_offered`
-is a boolean. Fail → not selectable; try the next candidate file, or close with no query if none
+is a boolean. Fail → not selectable; try the next candidate file, or close with no lookup if none
 remain.
 
 **Layer B** (may its ids drive data): `cohort` ∈ {exact, partial_exact, unknown}; `background` ∈
 {not_needed, running, exited_zero, failed}; `foreground_certainty` ∈ {complete, incomplete};
 `handoff_suppressed` is null or one of import_failed, no_new_sessions, nothing_landed,
-analytics_not_in_plan, skill_not_installed, no_agent_detected; every entry of `session_ids` and
+analytics_not_in_plan, skill_not_installed, no_agent_detected (older setups write
+`analytics_not_in_plan`); every entry of `session_ids` and
 `foreground_succeeded_ids` matches `^[A-Za-z0-9_-]{1,128}$`; `unattributed_on_disk` is a
 non-negative integer. Fail → **no data**: the file stays selected, but say the record is unreadable
-and CLOSE with links only (section 7), no query.
+and CLOSE with links only (section 7), no lookup.
 
 **Layer C** (may it supply links): `server_url` starts with `http://` or `https://`. Fail → no
-file-sourced links (fall back to `kcap whoami` per section 7) and no query — an unverifiable
+file-sourced links (fall back to `kcap whoami` per section 7) and no lookup — an unverifiable
 `server_url` also means the server-binding check in section 4 cannot run. `background_log` and
 `profile` are shown as plain text — never as a link or a command to run — only when they contain no
 control characters and are under 512 characters; otherwise omit them.
 
-Never splice an unvalidated value into SQL, a path, or a link.
+Never splice an unvalidated value into a tool call, a path, or a link.
 
 ## 3. No-handoff files
 
@@ -82,144 +76,113 @@ If `handoff_offered` is false, branch on `handoff_suppressed` and CLOSE:
 - `no_new_sessions` → "nothing to watch — that import found no new sessions".
 - `nothing_landed` → "the sessions that import selected were skipped at import time"; point at
   `kcap import --all` for per-session reasons; no retry.
-- `analytics_not_in_plan` → the plan sentence (section 6); the import ran; no retry.
 - `import_failed` → "that import did not get running"; name `kcap import --all --yes` and the
   `background_log` when displayable.
-- `skill_not_installed` / `no_agent_detected` → the import ran and you evidently have the skill
-  now: continue as if offered, watching the file's cohort as usual (sections 4–5).
+- `analytics_not_in_plan` / `skill_not_installed` / `no_agent_detected` → the import ran and you
+  can follow it now: continue as if offered, watching the file's cohort as usual (sections 4–5).
 
 ## 4. Bind to the server — fail closed
 
 If the selected file's `cohort` is `unknown`, skip this check and go straight to section 5 — there
-is no cohort to query either way, and the mismatch remediation below would be misleading when
+is no cohort to look up either way, and the mismatch remediation below would be misleading when
 watching was never possible.
 
 Otherwise, run `kcap whoami` and compare its server URL to `server_url`: lowercase scheme and host,
 drop a default port (80 for http, 443 for https only), trim a trailing slash, compare the path
-as-is. Match → continue to section 5. Mismatch or `whoami` failure → issue **NO** analytics query.
+as-is. Match → continue to section 5. Mismatch or `whoami` failure → make **NO** eval lookup.
 CLOSE with the file's links and this remediation: start your agent from a shell where `kcap whoami`
 reports `<server_url>` — set `KCAP_PROFILE=<profile>`, unset `KCAP_URL`, and set `KCAP_CONFIG_DIR`
 if kcap uses a custom config directory — then prompt again.
 
 ## 5. Watch the cohort
 
-Cohort = `session_ids` (`cohort: unknown` or empty → CLOSE with links, no query). Foreground =
-the entries of `foreground_succeeded_ids` that are also in `session_ids`: the sessions that
-imported while the user watched setup, and the ones this watch waits on. K is the foreground
-count. A foreground entry missing from `session_ids` is never queried; when any are missing, say
-"M of the sessions that imported first are outside the 500 this watch can query". Open with:
-"Watching N sessions from this import; waiting for the K that imported first to be evaluated";
-for `partial_exact` add "the sessions that imported first and the most recent others, 500 at
-most; older ones may land and evaluate unobserved"; if `unattributed_on_disk` > 0 add the
+Cohort = `session_ids` (`cohort: unknown` or empty → CLOSE with links, no lookup); N is its size.
+Foreground = the entries of `foreground_succeeded_ids` that are also in `session_ids`, in file
+order: the sessions that imported while the user watched setup, and the ones this watch waits on.
+K is the foreground count. A foreground entry missing from `session_ids` is never looked up; when
+any are missing, say "M of the sessions that imported first are outside the 500 this import
+recorded".
+
+**Watched set** W, at most 25 sessions: the first 25 foreground sessions, then — only while fewer
+than 25 — the other cohort sessions in file order. Open with: "Watching W of the N sessions from
+this import; waiting for the K that imported first to be evaluated". When K > 25 add "the first 25
+of them"; for `partial_exact` add "the sessions that imported first and the most recent others,
+500 at most; older ones may land and evaluate unobserved"; if `unattributed_on_disk` > 0 add the
 sentence from section 7.
 
-Every query uses `query_analytics` with `scope: 'global'` (the MCP defaults to the caller's cwd
-repo and will not widen on its own), **ONE call at a time — never two in flight** — and names only
-cohort ids, each already validated against the grammar above, as single-quoted literals in an
-`IN (...)` list or `session_id = '...'`. If a response ever includes a row whose `session_id` is
-not in `session_ids`, drop that row before using the response for anything.
-
-**Request budget:** at most 20 cohort queries per poll. `floor = ceil(N / 20)`. The FIRST poll uses
-batch size `floor` exactly — no probing at a smaller size first. Every batch passes `max_rows`
-equal to its own size:
-
-    SELECT s.session_id, s.repo_hash, s.vendor, s.model, s.duration_min, s.event_count,
-           e.eval_run_id, e.evaluated_at, e.overall_score, e.judge_model
-    FROM v_an_sessions s LEFT JOIN v_an_eval_summaries e ON e.session_id = s.session_id
-    WHERE s.session_id IN ('<id>', '<id>', ...)
-
-A row = arrived; a non-null `eval_run_id` = completed. Each response body carries `max_rows`, the
-server's effective cap. After the first poll: if any body reported `max_rows < floor`, fail closed
-at once — say the server's row cap is below what watching this many sessions needs, and CLOSE,
-having spent no more than the 20-query budget. Otherwise raise the batch to `min(100, max_rows)`
-for later polls. Any batch that comes back `truncated: true`, in the first poll or any later one,
-fails that poll — the cap decides, not the truncation flag alone.
-
-One poll = every batch it needs, each non-truncated. A failed or truncated batch discards the whole
-poll — nothing from it commits — and counts as one failure toward the two-failure stop rule.
-
-A 429 fails the poll. If its text matches `retry after (\d+)s`, wait that many seconds before the
-next poll; otherwise wait 60 seconds. Never poll sooner than the 30-second cadence either way. HTTP
-403 with `analytics_not_in_plan` → CLOSE immediately with the plan sentence (section 6); no
-polling, no retry, no wait.
-
-Progress = cohort ids that arrived / cohort size, and foreground ids evaluated / K, both computed
-from the batch rows only — never a separate count, never repo- or tenant-wide. Cadence: first
-snapshot immediately, then every 30 seconds. Say the progress after each poll.
-
-**Baseline**: the first snapshot's rows. An eval present there is *pre-existing*; one whose
-`eval_run_id` was null or absent there and non-null in a later poll *completed during this watch*.
-Every summary labels each session with one of those two phrases.
+**One poll** = ONE `get_session_evals` call with `session_ids` set to W — never two in flight. Each
+entry's `state` is one of:
+- `not_found` — not ingested yet (or not visible to you);
+- `not_evaluated` — arrived, no eval yet;
+- `queued` — arrived, eval waiting for a worker or a retry (`queue_position`, `next_attempt_at`);
+- `running` — arrived, eval in progress (`questions_done` of `total_questions`);
+- `completed` — arrived and evaluated: `eval_run_id`, `evaluated_at`, `overall_score` (out of 5),
+  `judge_model`, `summary`, `categories`, `weakest_questions`;
+- `failed` — arrived, the eval run failed (`failure_reason`);
+- `error` — this lookup failed.
+
+Arrived = any state but `not_found` and `error`. A tool error (including a login prompt), or any
+`error` entry, fails the poll: nothing from it commits, and it counts toward the two-failure stop
+rule. If the tool is missing — no `kcap-sessions` MCP, or one without `get_session_evals` — this
+kcap is older than the skill: say to update kcap and restart the agent, then CLOSE.
+
+Progress = watched sessions arrived / W and foreground sessions evaluated / min(K, 25), from the
+poll's entries only. Cadence: first snapshot immediately, then every 30 seconds. Say the progress
+after each poll.
+
+**Baseline**: the first snapshot. A session `completed` there is *pre-existing*; one that was not
+`completed` there, or completed with a different `eval_run_id`, and is `completed` in a later poll
+*completed during this watch*. Every summary labels each session with one of those two phrases.
 
 **Stop**, evaluated in this order after each poll whose results have already committed:
-1. K > 0 and every foreground session has a completed eval → summarize all of them, ordered by
+1. K > 0 and every watched foreground session is `completed` → summarize all of them, ordered by
    `evaluated_at` then `session_id`. A pre-existing eval counts: the wait is for these sessions to
    be evaluated, whenever that happened.
-2. K = 0 and three distinct cohort sessions completed during this watch → summarize those three,
-   ordered by `evaluated_at` then `session_id`. Pre-existing evals never satisfy this rule: on a
-   re-import they belong to an earlier run, and stopping on them would end the watch before this
-   import produced anything.
-3. `cohort: exact`, non-empty, and every id in `session_ids` has a completed eval → summarize the
-   foreground sessions, or with K = 0 the three with the newest `evaluated_at` (ties by
-   `session_id`). This rule may fire on the first snapshot with nothing but pre-existing evals:
-   a cohort that is already fully evaluated has nothing left to wait for, and the labels say so.
-   Never fires for `partial_exact` or an empty cohort.
+2. K = 0 and three watched sessions completed during this watch → summarize those three, ordered by
+   `evaluated_at` then `session_id`. Pre-existing evals never satisfy this rule: on a re-import they
+   belong to an earlier run, and stopping on them would end the watch before this import produced
+   anything.
+3. `cohort: exact`, N ≤ 25, and every cohort session is `completed` → summarize the foreground
+   sessions, or with K = 0 the three with the newest `evaluated_at` (ties by `session_id`). This
+   rule may fire on the first snapshot with nothing but pre-existing evals: a cohort that is
+   already fully evaluated has nothing left to wait for, and the labels say so.
 4. Two consecutive failed polls → stop, reporting the failures.
 5. 10 minutes since the first snapshot → stop. No new poll starts after the deadline, but a poll
    already dispatched before it finishes normally, and its outcome is still checked against rules
    1–4 first. On a deadline stop, summarize the foreground sessions that did complete and name the
-   ones still pending, with whether each has arrived; if none of them completed, summarize instead
-   up to three cohort sessions with the newest `evaluated_at` (ties by `session_id`).
+   ones still pending, with their state; if none of them completed, summarize instead up to three
+   watched sessions with the newest `evaluated_at` (ties by `session_id`).
 
 No idle early-stop — quiet polls are normal and are not a reason to stop early. Evals take minutes
 per session, and the foreground sessions are the newest, so they are usually the last to complete.
 
-**Per-session detail** (one session per query, 2 queries per detailed session, at most 10 across
-the whole run). A foreground pass takes whole session chains, so K can exceed five: the first five
-sessions in summary order get detail; every later one gets a one-line entry — link, label and
-`overall_score` — and no detail query. Both queries pass `max_rows` explicitly — a query left at
-the agent's guess truncates on the category list and throws the detail away:
-
-    -- max_rows: 25
-    SELECT category, ROUND(AVG(score), 2) AS mean FROM v_an_eval_scores
-    WHERE session_id = '<id>' AND outcome = 'assessed' GROUP BY category
-    -- max_rows: 2
-    SELECT question_id, score FROM v_an_eval_scores
-    WHERE session_id = '<id>' AND outcome = 'assessed' ORDER BY score ASC, question_id ASC LIMIT 2
-
-Strongest = highest mean, weakest = lowest, ties alphabetical by category. A truncated or failed
-detail query, or a session with no assessed rows, → summarize that session by `overall_score` alone
-and say so; this never affects poll success or the stop rules above.
-
-**What a detailed session summary says**, one short paragraph each: the link (section 7), the
-baseline label, then vendor and model, length (`duration_min`, rounded, and `event_count`),
-`overall_score` out of 5 and the judge model, strongest and weakest category with their means, and
-the two weakest questions with their scores. When the `kcap-sessions` MCP is available, call `get_session_summary` once per
-summarized session and lead with its title or first sentence when it returns one; an empty summary
-is left out silently, never called "no summary".
-
-**Cohort facts**, one line after the summaries, from the last committed poll's rows only: sessions
-arrived out of N, sessions evaluated, and the mean `overall_score` across the evaluated ones.
+**What a session summary says.** The first five sessions in summary order get one short paragraph
+each: the link (section 7), the baseline label, `overall_score` out of 5 and the judge model, the
+strongest and weakest of `categories` by `score` (ties alphabetical by name), the two
+`weakest_questions` with their scores, and the gist of the judge's `summary`. When
+`get_session_summary` returns a title or a first sentence for the session, lead with it; an empty
+summary is left out silently, never called "no summary". Every later session gets a one-line entry
+— link, label and `overall_score`. A completed entry with no categories is summarized by
+`overall_score` alone; say so.
+
+**Cohort facts**, one line after the summaries, from the last committed poll only: watched
+sessions arrived out of W, sessions evaluated, and the mean `overall_score` across the evaluated
+ones.
 
 ## 6. When little or nothing completes
 
 Explain the real gates plainly: auto-eval may be off for a repository; the server needs an eval
 agent configured; sessions under the minimum event count are skipped; already-evaluated sessions
-are not re-run; a recovery sweep runs hourly. If the analytics MCP is absent entirely, close
-immediately with the block below.
-
-Plan sentence (used here and from sections 3 and 5): "Insights isn't in this workspace's plan, so
-evals can't be followed from here; your import continues and evals appear in the Capacitor UI."
+are not re-run; a recovery sweep runs hourly. A `failed` session names its `failure_reason`.
 
 ## 7. CLOSE — always
 
 1. How to keep watching: prompt `Follow my kcap import` again (with the same `(run: <id>)` line
    when you were bound to one).
-2. Links: with a `repo_hash` matching `^[0-9a-f]{16}$`, `<server_url>/repo/<repo_hash>/sessions/<session_id>?tab=evaluation`;
-   otherwise (no `repo_hash`, or one that fails the grammar) `<server_url>/sessions/<session_id>?tab=evaluation`;
-   all results `<server_url>/sessions`. No valid file → `server_url` from `kcap whoami`; if that
-   fails too, say the results live in the Capacitor server UI and that `kcap whoami` prints the URL
-   once logged in.
+2. Links: `<server_url>/sessions/<session_id>?tab=evaluation` per session; all results
+   `<server_url>/sessions`. No valid file → `server_url` from `kcap whoami`; if that fails too, say
+   the results live in the Capacitor server UI and that `kcap whoami` prints the URL once logged
+   in.
 3. When `unattributed_on_disk` > 0: "N sessions on disk had no repository match; any of them that
    imported show without one — `kcap remap` places them."
 4. Offer the guided tour with the exact prompt `Start kcap guided tour`.

package/kcap/skills/review-flows/SKILL.md

@@ -8,7 +8,8 @@ description: >-
   this skill (and do NOT call the flows MCP tools) for an ordinary review
   request such as "review my PR", "review this diff/spec/design", or "code
   review" where the user just wants you to review it yourself — perform that
-  review directly instead.
+  review directly instead. For any other catalogue flow, or a flow offered
+  from your session context, use `agent-flows`.
 ---
 
 # Review Flows
@@ -156,7 +157,10 @@ After applying the role-surface safety gate, if `start_review_flow` / `submit_re
 ## Workflow
 
 ```
-start_review_flow(kind, target_kind, target_ref, target_title, context)
+get_flow_definition(kind)
+  → follow its guide: what to submit, how to iterate (a server that publishes no guides says so; the rest of this skill applies)
+
+start_review_flow(kind, target_kind, target_ref, target_title, session_title, context)
   → reviewer returns a result: findings (with the findings text) | clean
 
 if clean:
@@ -176,7 +180,7 @@ if findings:
 
 | Tool | Required args | Optional args | When to call |
 |---|---|---|---|
-| `start_review_flow` | `kind` (`spec-review`\|`code-review`), `target_kind` (what is being reviewed: `spec`, `code`, `pr`, `branch`, `file`, etc.), `target_ref` (a path, branch name, or PR URL/number that identifies the target), `target_title` (short human-readable title, e.g. spec name or PR title), `context` (background context: what to focus on, constraints, definition of done) | `vendor` (explicit reviewer vendor; omit to use the definition's authored vendor, or your saved `flows.reviewer_vendor` preference if it declares none), `model` (explicit reviewer model override — REQUIRES `vendor`; only pass it when the user named a model), `instructions`, `mode` (`context-only` — optional) | Once, at the start of a review task. |
+| `start_review_flow` | `kind` (`spec-review`\|`code-review`), `target_kind` (what is being reviewed: `spec`, `code`, `pr`, `branch`, `file`, etc.), `target_ref` (a path, branch name, or PR URL/number that identifies the target), `target_title` (short human-readable title, e.g. spec name or PR title), `session_title` (the reviewer session's title: a short phrase naming this review, specific enough to tell it apart from other sessions — it replaces the generic "Review this PR/code" name), `context` (background context: what to focus on, constraints, definition of done) | `vendor` (explicit reviewer vendor; omit to use the definition's authored vendor, or your saved `flows.reviewer_vendor` preference if it declares none), `model` (explicit reviewer model override — REQUIRES `vendor`; only pass it when the user named a model), `instructions`, `mode` (`context-only` — optional) | Once, at the start of a review task. |
 | `submit_review_round` | `flow_run_id`, `context` | `instructions` | After addressing findings. Pass the same `flow_run_id` and the updated context. |
 | `get_review_flow_status` | — | `flow_run_id` (omit to read the newest open flow this session started, or on a harness without a session identity the newest one started from this workspace; several open flows are listed instead), `session_id` (look up another session's flows; defaults to this session), `wait` (`true`/`false`, defaults to `false`) — when `true`, blocks until the round is terminal or roughly 3.5 minutes pass, instead of returning the current snapshot immediately | Poll or check the current status of a flow (running, waiting, completed, failed). Use `wait: true` to ride out a long round instead of polling repeatedly yourself, and omit `flow_run_id` to recover a flow whose id you never received or lost. |
 | `close_review_flow` | `flow_run_id` | — | Only after the reviewer returns `clean`. |
@@ -184,13 +188,14 @@ if findings:
 ## Example (code review)
 
 ```
-# Step 1 — start (all five required args required; the reviewer sees a mirror of THIS SESSION's
+# Step 1 — start (all six args required; the reviewer sees a mirror of THIS SESSION's
 # project directory, not of the directory you are working in — pass mode="context-only" to opt out)
 start_review_flow(
   kind="code-review",
   target_kind="branch",
   target_ref="feature/add-null-check",
   target_title="Add null check on user input",
+  session_title="Review the null check on user input",
   context="Review the diff on this branch for correctness and adherence to project conventions."
 )
 # → returns flow_run_id, e.g. "flow_abc123"

package/kcap/skills/start-agents/SKILL.md

@@ -88,6 +88,10 @@ Call `start_agent` once for each agent.
   should work in. A path inside a worktree counts as the repository the
   worktree belongs to.
 - `prompt`: the whole task. See the next section.
+- `title`: required. A short phrase naming this agent's task, specific
+  enough to tell its session apart from the others in the repository. It is
+  the session's title from the start, and titles generated later do not
+  replace it.
 - `work_item`: required, and there is no default. Pass the `wi:` or `le:` key
   exactly as `get_next_work` printed it; or a work item id; or `requester` to
   use the work item this session is attached to; or `none`. Leaving it out is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kurrent/kcap",
-  "version": "1.3.0-beta.6",
+  "version": "1.3.0-beta.7",
   "description": "CLI companion for Kurrent Capacitor — records and visualizes Claude Code sessions",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -14,17 +14,17 @@
     "postinstall": "node bin/postinstall.js"
   },
   "optionalDependencies": {
-    "@kurrent/kcap-darwin-arm64": "1.3.0-beta.6",
-    "@kurrent/kcap-linux-arm64": "1.3.0-beta.6",
-    "@kurrent/kcap-linux-musl-arm64": "1.3.0-beta.6",
-    "@kurrent/kcap-linux-musl-x64": "1.3.0-beta.6",
-    "@kurrent/kcap-linux-x64": "1.3.0-beta.6",
-    "@kurrent/kcap-win-x64": "1.3.0-beta.6"
+    "@kurrent/kcap-darwin-arm64": "1.3.0-beta.7",
+    "@kurrent/kcap-linux-arm64": "1.3.0-beta.7",
+    "@kurrent/kcap-linux-musl-arm64": "1.3.0-beta.7",
+    "@kurrent/kcap-linux-musl-x64": "1.3.0-beta.7",
+    "@kurrent/kcap-linux-x64": "1.3.0-beta.7",
+    "@kurrent/kcap-win-x64": "1.3.0-beta.7"
   },
   "files": [
     "bin/",
     "kcap/"
   ],
-  "kcapReleaseCommit": "8d206456092389199b94600180c4ff9cbe936794",
-  "kcapReleaseTag": "v1.3.0-beta.6"
+  "kcapReleaseCommit": "ea55466b11f901d54ed75d89900f6b316e86dd33",
+  "kcapReleaseTag": "v1.3.0-beta.7"
 }

package/kcap/skills/suggest-review-flow/SKILL.md

@@ -1,94 +0,0 @@
----
-name: suggest-review-flow
-description: >-
-  Use this skill when implementation is complete — a feature or bugfix is functionally
-  finished, tests pass, or you are about to commit / open a PR / merge — or when a spec is
-  finalized. At that moment, proactively OFFER an independent second-harness review even if
-  the user did not ask, because a fresh, separate reviewer catches what the author's own model
-  misses. It calls list_reviewer_vendors to recommend a reviewer that will actually run for
-  this repo, offers a spec-review or code-review flow, and hands off to the review-flows skill
-  only after the user accepts — it never starts a flow itself. Do NOT use it when the user
-  asks you to review something yourself ("review this", "code review this", "look over my
-  spec"), or mid-task before the work is finished.
----
-
-# Suggest a review flow
-
-You have reached a milestone where an **independent** review adds real value: a
-separate coding-agent session, with none of this session's context, reviews the
-work — and a different model catches what the author's own model glossed over.
-Most people never think to do this. Your job here is to **offer** it at the
-right moment, recommend a reviewer that will actually run, and — only if the
-user says yes — hand off to the `review-flows` skill. **This skill never starts
-a review flow itself.**
-
-## When to offer (and when not to)
-
-Offer at exactly two milestones:
-
-- **Spec complete** — you just produced AND presented a finalized spec/design
-  this session → offer a `spec-review` flow.
-- **Implementation complete** — the change is functionally finished (you say so,
-  or you are about to commit / open a PR / merge) → offer a `code-review` flow.
-
-Do NOT offer (stay silent) when:
-
-- The user asked you to **review something yourself** ("review this", "code
-  review this", "look over the spec"). Just perform that review locally — no
-  offer, no flow.
-- You are only part-way through: rough mid-stream brainstorming, a partial plan,
-  a routine edit, or work whose known checks are still failing.
-- A review flow for this artifact is already engaged, active, or just completed.
-- Another skill (brainstorming, writing-plans, finishing-a-development-branch,
-  requesting-code-review) is mid-flow — let it finish; offer at the seam.
-
-**Offer at most once per artifact.** Key the offer on (milestone type + the
-target's identity + its revision): the same spec or the same change never gets
-offered twice, but a materially revised artifact may be offered again, and a
-second, different artifact of the same kind may be offered on its own. If the
-user declines or moves on, stay silent for that artifact. A failed availability
-lookup counts as the one prompt for that artifact — do not re-prompt.
-
-## How to recommend a reviewer
-
-1. Call **`list_reviewer_vendors`** (read-only; safe to call before offering).
-   It returns `reviewers[]` (vendors that can actually run for this repo now),
-   `driver_vendor` (the harness you are running in, or absent if unknown), and
-   `diagnostics`.
-2. **Prefer a reviewer different from the driver.** A different model is the
-   highest-value review. If one non-driver reviewer is available, recommend it;
-   if several, offer a short choice — never assert one vendor is "better".
-3. **If the only available reviewer is your own vendor, still offer it** —
-   framed as an independent, context-free reviewer session. The value is the
-   clean second look, not necessarily a different model.
-4. **If `driver_vendor` is absent (unknown)**, do NOT claim "a different model";
-   frame the offer as "a separate, independent reviewer session" and offer a
-   choice from `reviewers[]`.
-5. **If `reviewers[]` is empty**, read `diagnostics.reason` and give one line of
-   guidance instead of a dead end:
-   - `no_daemons_connected` → start a daemon (`kcap daemon start -d`).
-   - `no_repo_hosting_daemon` → run a daemon on a machine that has this repo.
-   - `no_unattended_reviewer` → install/certify a second harness as a reviewer.
-   - `repo_unresolved` → the current directory isn't a recognized repo.
-   - `lookup_failed` → couldn't reach the server; suggest checking `kcap status`.
-   - `schema_skew` → the kcap client/server is out of date; suggest updating.
-
-## Handing off (only after the user accepts)
-
-- You MAY run the read-only `list_reviewer_vendors` lookup automatically, but you
-  **MUST NOT start a review flow until the user affirmatively accepts THIS
-  offer.**
-- On acceptance, invoke the **`review-flows`** skill to run it, preserving the
-  chosen `kind` (spec-review / code-review), the target, and the chosen reviewer
-  vendor.
-- If the reviewer vendor turns out to be unavailable at start (a snapshot race),
-  `review-flows` surfaces the reason — do not silently substitute another vendor;
-  re-recommend and get fresh consent.
-
-## If `list_reviewer_vendors` is not available
-
-Your harness caches the kcap MCP tool list when it connects. If kcap was
-upgraded mid-session, `list_reviewer_vendors` may be missing from this session.
-Do NOT guess availability and do NOT shell out as a workaround — tell the user
-to restart the harness (or reconnect the `kcap-flows` MCP server) so the tool
-appears, then offer again.