@kurrent/kcap 1.1.1 → 1.3.0-beta.1

package/bin/refresh.js

@@ -78,6 +78,7 @@ const PLUGIN_MCP_SERVERS = {
   "kcap-memory":    "memory",
   "kcap-workitems": "workitems",
   "kcap-plans":     "plans",
+  "kcap-artefacts": "artefacts",
   "kcap-analytics": "analytics",
 };
 

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

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

package/kcap/.codex-mcp.json

@@ -10,7 +10,8 @@
     },
     "kcap-flows": {
       "command": "kcap",
-      "args": ["mcp", "flows"]
+      "args": ["mcp", "flows"],
+      "tool_timeout_sec": 600
     },
     "kcap-memory": {
       "command": "kcap",
@@ -27,6 +28,10 @@
     "kcap-plans": {
       "command": "kcap",
       "args": ["mcp", "plans"]
+    },
+    "kcap-artefacts": {
+      "command": "kcap",
+      "args": ["mcp", "artefacts"]
     }
   }
 }

package/kcap/.mcp.json

@@ -35,6 +35,12 @@
       "cwd": "${CLAUDE_PROJECT_DIR}",
       "description": "Plan ledger — declare the plan, spec or design document this session works from (declare_plan_document), declare its task list (set_plan_tasks), record each task's status change (update_plan_task) and read the plan back after compaction (get_plan)."
     },
+    "kcap-artefacts": {
+      "command": "kcap",
+      "args": ["mcp", "artefacts"],
+      "cwd": "${CLAUDE_PROJECT_DIR}",
+      "description": "Publish a self-contained HTML page — a plan, a report, a comparison — and get back a link to share. The page is sandboxed with no network access, so inline everything as data URIs. Private until you set visibility."
+    },
     "kcap-analytics": {
       "command": "kcap",
       "args": ["mcp", "analytics"],

package/kcap/README.md

@@ -12,9 +12,14 @@ Search and recall past Kurrent Capacitor sessions from inside the agent.
 
 | Tool | Description |
 |------|-------------|
-| `search_sessions` | Free-text + author search over past sessions (and subagent transcripts), defaulted to the cwd's repo |
-| `get_session_summary` | Concise `summary_text` + `plan` for a session |
+| `search_sessions` | Keyword (one to three terms or identifiers) + author search over past sessions (and subagent transcripts), defaulted to the cwd's repo |
+| `list_repo_sessions` | List a repository's sessions you can see, running ones first |
+| `get_session_summary` | Concise `summary_text` + `plan` + `declared_plans` for a session |
+| `list_turns` | Per-turn prose outline for a session |
+| `get_turn` | One turn's full transcript, by session id and turn index |
 | `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` |
 
 Repo-aware: it resolves the cwd to a repo hash at startup, so `search_sessions` defaults to *this* repo.
 
@@ -57,6 +62,23 @@ Governed read-only SQL over the org's curated coding-agent analytics views (sess
 
 Repo-aware: defaults to the cwd's repo; pass `scope: "global"` for org-wide questions. Requires `kcap login` and a kcap-server new enough to expose the `/api/analytics` endpoints.
 
+### `kcap-artefacts`
+
+Publish a self-contained HTML page — a plan, a report, a comparison — and get back a link to share. The page is served under a sandbox with no network access, so every style, script and image has to be inlined as a data URI; an external URL renders as nothing.
+
+| Tool | Description |
+|------|-------------|
+| `publish_artefact` | Publish a page (`title`, and either `html` or a local `path`); optional `description`, `visibility`, `grants`, `session_ids`, `response_schema` to make it answerable, and `update_id` to revise an existing artefact without changing its URL |
+| `await_artefact_responses` | Block until people have answered — the human checkpoint. Returns on a respondent count, on a close, or on a timeout (which is not an error) |
+| `get_artefact_results` | Tallies and each person's current answer, without waiting |
+| `close_artefact_responses` | Freeze a version's answers; `closed: false` reopens and clears any deadline |
+| `list_my_artefacts` | The artefacts you can see — id, title, audience, latest version, URL |
+| `set_artefact_visibility` | Replace an artefact's audience (`none` / `org` / `scoped` + grants) |
+
+An artefact is private to its owner until visibility says otherwise. The current session is cited automatically from `KCAP_SESSION_ID`, so a publish is attributed to the work that produced it.
+
+Declaring a `response_schema` turns the page into a form the server validates and tallies: fields of type `choice`, `multi`, `score` or `text`, plus a `results_mode` deciding what other viewers see — `owner` (default, only you), `aggregate` (tallies, no names or free text) or `named` (who said what). Who answered is always the authenticated viewer; there is no field for it to forge. Reading, version history and takedown stay in the web UI.
+
 `kcap mcp judge` is intentionally not auto-registered. Add it with `claude mcp add kcap-judge -- kcap mcp judge` if you want it.
 
 **Hooks** — Automatically captures session activity and forwards it to the Kurrent Capacitor server:

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

@@ -22,7 +22,9 @@ Use the `kcap mcp flows` MCP tools (`start_flow`, `send_to_participant`, `get_fl
 
 ## Long rounds are normal
 
-`round_timeout` is an **inactivity** bound, not a wall-clock cap: a round only fails for taking too long if the participant goes genuinely quiet for that whole stretch — an actively-working participant can legitimately run a round for a long time. If a status check (or `start_flow`/`send_to_participant`) returns the benign "Flow still running" text, that is an expected outcome on a long round, not a problem — re-enter the wait with `get_flow_status(flow_run_id, wait: true)`, which blocks (via bounded, internally-retried checks — never a raw long-poll) until the round finishes or roughly 8 minutes pass, then call it again if it's still running. A round result of **`unclear` now genuinely means the participant went dead or silent** (no activity for the whole inactivity bound, or it crashed/was stopped) — it is no longer a symptom of a merely slow participant; see the `participant_unreachable` and `participant_died`/`participant_stopped` guardrail entries below.
+`round_timeout` is an **inactivity** bound, not a wall-clock cap: a round only fails for taking too long if the participant goes genuinely quiet for that whole stretch — an actively-working participant can legitimately run a round for a long time. If a status check (or `start_flow`/`send_to_participant`) returns the benign "Flow still running" text, that is an expected outcome on a long round, not a problem — re-enter the wait with `get_flow_status(flow_run_id, wait: true)`, which blocks (via bounded, internally-retried checks — never a raw long-poll) until the round finishes or roughly 3.5 minutes pass, then call it again if it's still running. A round result of **`unclear` now genuinely means the participant went dead or silent** (no activity for the whole inactivity bound, or it crashed/was stopped) — it is no longer a symptom of a merely slow participant; see the `participant_unreachable` and `participant_died`/`participant_stopped` guardrail entries below.
+
+**A harness tool timeout is not a flow failure.** `start_flow` and `send_to_participant` block for minutes while the participant works. If your harness aborts the call with its own tool timeout (on Codex the error reads `timed out awaiting tools/call`), the flow is still running server-side. Do not start a new flow and do not investigate — call `get_flow_status(wait: true)`. Without a `flow_run_id` it reads the newest open flow this session started (pass `session_id` for another session's), so it works even when the aborted start never handed you the id or context compaction dropped it; with several open flows it lists them for you to pick from. On a harness that gives the flows server no session identity, it reads the flows started from this workspace on this machine instead.
 
 ## Role-surface safety gate
 
@@ -137,7 +139,7 @@ After applying the role-surface safety gate, if `start_flow` / `send_to_particip
 
 ## Core rules
 
-1. **Start exactly one flow per user task.** Call `start_flow` once and hold the returned `flow_run_id`. Do NOT start a new flow for follow-up rounds — reuse the same ID.
+1. **Start exactly one flow per user task.** Call `start_flow` once and hold the returned `flow_run_id`. Do NOT start a new flow for follow-up rounds — reuse the same ID. If the id is gone (a harness timeout aborted the start, or compaction dropped it), get it back with `get_flow_status(wait: true)` — never by starting another flow.
 2. **After receiving a non-clean result**, address it, then call `send_to_participant` with the same `flow_run_id` and the updated message.
 3. **Do NOT finish the user task while the flow has unresolved results.** Keep iterating until the definition's clean/complete signal.
 4. **Only call `close_flow` after the clean signal.** The run stays open until you explicitly close it — don't rely on it closing itself. Then report completion to the user.
@@ -216,7 +218,7 @@ report completion to user
 |---|---|---|---|
 | `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. |
 | `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` | `wait` (`true`/`false`, defaults to `false`) — when `true`, blocks until the round is terminal or roughly 8 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. |
+| `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. |
 
 ## Example (custom definition)

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

@@ -0,0 +1,190 @@
+---
+name: eval-watch
+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, summarizes the first three completed evals, links to the results and
+  offers the guided tour. Not for browsing evals in general — that is the analytics
+  or 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.
+
+## The safety rule — read this first
+
+Three 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.
+
+## 1. Find the run
+
+- If the prompt carries a line `(run: <id>)`, `<id>` must match `^[0-9a-f]{32}$` before you use it
+  as a filename component. If it does not match, treat the prompt as carrying no run id at all. If
+  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
+  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.
+
+## 2. Validate the file — three layers
+
+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
+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
+`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.
+
+**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
+`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.
+
+## 3. No-handoff files
+
+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).
+
+## 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
+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.
+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). Open with:
+"Watching N sessions from this import (K landed before the handoff)" — K is
+`foreground_succeeded_ids.length`; for `partial_exact` add "the 500 most recent; 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, 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, computed from the batch rows only — never a
+separate count, never repo- or tenant-wide. Cadence: first snapshot immediately, then every 30
+seconds.
+
+**Stop**, evaluated in this order after each poll whose results have already committed:
+1. Three distinct cohort sessions have a completed eval → summarize the first three, ordered by
+   `evaluated_at` then `session_id` (the same tie-break applies to rows already present at the very
+   first snapshot, so more than three arriving at once always picks the same three).
+2. `cohort: exact`, non-empty, and every id in `session_ids` has a completed eval → summarize what
+   completed. Never fires for `partial_exact` or an empty cohort.
+3. Two consecutive failed polls → stop, reporting the failures.
+4. 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–3 first: a third distinct completion in that final poll wins over the deadline summary, and if
+   that final poll is itself the second consecutive failure, report it as the deadline stop while
+   still naming the failures.
+
+No idle early-stop — quiet polls are normal and are not a reason to stop early.
+
+**Per-session detail** (one session per query, at most 6 queries across the whole run — enough for
+the three sessions rule 1 summarizes):
+
+    SELECT category, AVG(score) AS mean FROM v_an_eval_scores WHERE session_id = '<id>' GROUP BY category
+    SELECT question_id, score FROM v_an_eval_scores WHERE session_id = '<id>' 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 score rows, → summarize that session by `overall_score` alone
+and say so; this never affects poll success or the stop rules above. When the `kcap-sessions` MCP is
+available, use it to enrich a session's title; otherwise the session id is enough.
+
+## 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."
+
+## 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.
+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/guided-tour/SKILL.md

@@ -374,12 +374,16 @@ causation, and never a savings figure.
 
 **`What did I leave unfinished in my last session?`** — `search_sessions` with `author: <user>`
 for their most recent session, then `get_session_summary`: the answer lives in the summary's
-Unfinished/Risks section. Quote it with the session id; if the summary has no such section, say
-so plainly rather than inferring one from the transcript.
+Unfinished section. Quote it with the session id. An older summary has a combined Unfinished/Risks
+section instead, which mixes risks and status notes in with the work: report only the concrete
+actions still to do from it and leave the rest out. If there is no such section, or it holds no
+action still to do, say so plainly rather than inferring one from the transcript.
 
 **`Pick up where my last session left off`** — same lookup, then actually resume: load the
-summary's context and unfinished items, restate in two sentences where the work stopped, and ask
-which item to continue with. This one is an action, not a report — end by doing, not describing.
+summary's context and its unfinished actions (found as above), restate in two sentences where the
+work stopped, and ask which action to continue with. If there are none, say no unfinished action
+was recorded and ask what they want to work on next. This one is an action, not a report — end by
+doing, not describing.
 
 **Prompt suggestions you compose** — anywhere you offer a `Prompt ❯` line of your own (rule 5
 next steps, variations, follow-ups), two rules:

package/kcap/skills/plans/SKILL.md

@@ -17,10 +17,13 @@ through the `kcap-plans` MCP tools; nothing infers it. Three rules:
 
 1. **When you write or are handed a plan, spec or design document, declare it.**
    Call `declare_plan_document` with its `kind` (`plan`, `spec` or `design`)
-   and `path`. The file is read locally, hashed, and keyed against the
-   repository root; declaring the same file again from a later session lands
-   on the same plan. When a plan implements a spec, or a spec refines a design,
-   pass the other file as `argues_from` so both attach to one plan.
+   and `path`. The file is read locally, hashed, and keyed against the repository root
+   **and the checkout it sits in**: declaring the same file again from the same
+   checkout lands on the same plan, but from a different worktree or clone it
+   starts a separate one. To continue a plan another session began, see
+   "Resuming a plan" below — do not re-declare its document. When a plan
+   implements a spec, or a spec refines a design, pass the other file as
+   `argues_from` so both attach to one plan.
 2. **When a plan has discrete steps, declare them and update each transition.**
    Call `set_plan_tasks` with the whole ordered list (`title`, optional
    `task_id`, `status`, `note`); re-send the whole list when the steps change,
@@ -28,10 +31,27 @@ through the `kcap-plans` MCP tools; nothing infers it. Three rules:
    task starts, finishes or is skipped, by `task_id` or 1-based `ordinal`, with
    `status` `pending`, `in_progress`, `completed` or `skipped` and a `note`
    when the reason matters. After compaction, `get_plan` returns the list.
+   While a plan's `is_complete` is `false`, never call `set_plan_tasks`
+   on it for any reason — the list would be rebuilt from a view that is
+   missing tasks.
 3. **Keep whatever ledger your own workflow asks for as well.** These tools
    replace the harness's task list, not your notes or any file another
    workflow tells you to maintain.
 
+## Resuming a plan
+
+To continue a plan that an earlier session left unfinished — yours or a teammate's. Finding and reading use the `kcap-sessions` tools; the only writes are the reconciling snapshot in step 3, when one is needed, and the adoption in step 5, always last.
+
+1. **Find it.** `list_repo_plans` lists this repository's open plans. Read each row's `sessions` together: a session that is `active`, not `stale`, and whose `last_touched_at` is recent may still be executing the plan — **ask the user before adopting it**. An active session whose `last_touched_at` is old has most likely moved to other work; a session stays attached to every plan it ever touched, so that alone is no reason to hold back. The default `state: "open"` lists plans with a visible unfinished task; a plan whose visible tasks are done but whose withheld tasks are not is absent from it. When the plan you expect is missing, call `list_repo_plans(state: "all")` and look for rows with `is_complete: false`.
+2. **Read it.** `get_declared_plans(plan_id: …)` for the documents and the full task list.
+3. **Compare the document.** Read the plan file from *this* checkout at its repo-relative `path` and compare it with `content_hash` — the lowercase hex SHA-256 of the file's bytes, as `shasum -a 256` prints it. If it changed, the task list may be out of date. Reconciling it means sending a new snapshot with `set_plan_tasks(plan_id: …)`, and a snapshot **replaces** the list — a task it omits is deleted, a note it omits is cleared:
+   - **`is_complete` is `true`:** reconcile now, **before** step 5, carrying every existing task's `task_id`, `status` and `note` over from step 2. Sent after step 5, the snapshot would carry the resumed task's earlier `pending` status and put it straight back.
+   - **`is_complete` is `false`: never send a snapshot.** Your view is missing someone else's tasks or notes, and a list rebuilt from it would destroy them. Carry on with `update_plan_task`, which changes one task and nothing else, and tell the user the document changed and the list could not be reconciled from your view.
+4. **Verify before continuing.** The ledger records what the earlier session *claimed*. A task left `in_progress` may be half-written: check the working tree and the history since the document's `commit_sha`, when it is set, before picking it up.
+5. **Adopt it.** `update_plan_task(plan_id: …, task_id: …, status: "in_progress")` on the task you are resuming. That attaches this session to the plan and makes it the session's current plan, so later calls can omit `plan_id`. This is always the last write of the procedure.
+
+**Do not call `declare_plan_document` for that plan's file while resuming from a different checkout** — a new worktree, another clone. It would start a second plan, point this session at it, and split the ledger: your progress would land on an empty plan while the original stops moving. Rule 1's "declare a document when you read it" does not apply here. From the same checkout path, declaring it again is harmless.
+
 ## Tool reference
 
 | Tool | Required args | Purpose |
@@ -41,6 +61,8 @@ through the `kcap-plans` MCP tools; nothing infers it. Three rules:
 | `update_plan_task` | `status` and one of `task_id` / `ordinal` (+ `note`, `plan_id`) | Record one transition; the result names the plan. |
 | `get_plan` | — (+ `plan_id`, `session_id`) | Documents, tasks with status and source, progress. |
 
+To read a plan from *another* session, or to find unfinished plans in the repository, use `get_declared_plans` and `list_repo_plans` on the `kcap-sessions` server: they are read-only and do not prompt.
+
 Without `plan_id` every tool acts on the session's current plan — the one it
 most recently wrote to; a session on no plan gets one created by
 `set_plan_tasks` and an empty result from `get_plan`. If a tool cannot resolve

package/kcap/skills/recap/SKILL.md

@@ -10,12 +10,15 @@ description: >-
   "recent changes", "recent sessions", or providing a session ID to review.
   Also covers search/recall asks: "find the session where we…", "which session
   discussed X", "did we ever debug Y", "look up the session about Z", "recall
-  the session that…", "search past sessions for…". Provides instructions for
-  retrieving and searching session history via the kcap CLI and the
-  kcap-sessions MCP tools.
+  the session that…", "search past sessions for…".
+  Also covers declared plans: "continue the plan", "resume the plan", "what's
+  left on the plan", "is the plan finished", "unfinished plans", "what was the
+  last session working through".
+  Provides instructions for retrieving and searching session history via the
+  kcap CLI and the kcap-sessions MCP tools.
 ---
 
-> **For agents:** When the `kcap-sessions` MCP server is available, prefer its tools (`search_sessions`, `list_repo_sessions`, `get_session_summary`, `list_turns`, `get_turn`, `get_session_transcript`) for retrieving past sessions. This CLI-wrapped skill remains a fallback for shell use and when MCP isn't installed.
+> **For agents:** When the `kcap-sessions` MCP server is available, prefer its tools (`search_sessions`, `list_repo_sessions`, `get_session_summary`, `list_turns`, `get_turn`, `get_session_transcript`, `list_repo_plans`, `get_declared_plans`) for retrieving past sessions and the plans they declared. This CLI-wrapped skill remains a fallback for shell use and when MCP isn't installed.
 
 # Session Recap
 
@@ -76,7 +79,8 @@ Returns AI-generated summaries from the most recent ended sessions in the curren
 2. **`## Summary`** — an AI-generated narrative covering:
    - **Context** — why the work was done
    - **Key decisions** — trade-offs and design choices that matter for future work
-   - **Unfinished/Risks** — anything deferred or left incomplete
+   - **Unfinished** — work that remains, one action per bullet
+   - **Risks** — anything flagged as risky or uncertain (older summaries combine these two as **Unfinished/Risks**)
 3. **`## Turns`** — an outline with one line per turn:
    - If the turn has a prose summary, that summary (1-3 sentences).
    - Otherwise, a truncated user-prompt excerpt plus tool/file metadata (tool names, file count).
@@ -98,6 +102,30 @@ For a plain metadata index instead of the outline (turn #, prompt excerpt, tool
 
 **MCP agents:** call `list_turns` to get a session's full turn map (`turn_index`, `prose`, `user_prompt`, `tools`, `files`, token counts), then `get_turn(session_id, turn_index)` for one turn's full transcript. Use `get_session_summary` for the whole-session narrative instead of drilling into individual turns.
 
+## Plans
+
+A session that works from a plan declares it to Capacitor: the documents, an ordered task list, and each task's status. That record outlives the session, so it is how you tell where earlier work stopped. It is reachable only through the `kcap-sessions` MCP tools — `kcap recap` does not print it, and the `## Plan` block above is the plan *text* a session captured, not its task list.
+
+**Finding one.**
+- `list_repo_plans` — the unfinished plans in this repository, most recently touched first. Start here when you have no session id: "what was left unfinished", "is there a plan to continue". The default `state: "open"` lists plans with a visible unfinished task; a plan whose visible tasks are done but whose withheld tasks are not is absent from it. When the plan you expect is missing, call `list_repo_plans(state: "all")` and look for rows with `is_complete: false`.
+- `get_session_summary` — carries `declared_plans`, one pointer per plan that session or its continuation chain declared, when it declared any.
+- `get_declared_plans` — the full task list, by `plan_id` (from either of the above) or by `session_id`.
+
+**Judging whether a plan is done.** Read `progress` and two flags, in this order:
+
+1. `progress.finished` is `true` — the plan is done.
+2. `progress.completed` is less than `progress.total` — the plan is open. What remains is every entry of `tasks` whose status is neither `completed` nor `skipped`; a `list_repo_plans` row has no `tasks`, and gives the first of them as `next_task`.
+3. `is_complete` is `false` — nothing visible remains — possibly nothing visible was declared — but the view is partial; say so and do not call the plan complete.
+4. Otherwise `progress.total_known` is `false` — the session declared documents but never a task list, so completion is unknown. That is not withheld data; do not report it as a partial view. If instead `total_known` is `true`, the server itself reports the plan unfinished — treat it as open and do not infer completion from the totals.
+
+**`is_complete` does not mean the work is done.** It means nothing was withheld from your view, and a half-finished plan usually has `is_complete: true`. `finished` is the field that answers "is it done". If `progress` has no `finished` field, the server predates it: the plan is finished only when `total_known` is true **and** `completed` equals `total` **and** `is_complete` is true.
+
+*Worked example — starting from a session.* `get_declared_plans(session_id: "4f2a…")` returns one plan with `progress: {completed: 2, total: 7, total_known: true, finished: false}` and `is_complete: true`. Branch 2: open, five tasks remain — list them from `tasks`.
+
+*Worked example — starting from a summary.* `get_session_summary` shows `declared_plans: [{plan_id: "9c1e…", completed: 7, total: 7, total_known: true, finished: false, is_complete: false, is_current: true}]`. Not branch 1, not branch 2 — branch 3: all seven visible tasks are done, but the view is partial. Report that; do not report the plan as finished. Drill down with `get_declared_plans(plan_id: "9c1e…")` to see which task and note are withheld.
+
+To pick a plan up and continue it, follow "Resuming a plan" in the `plans` skill.
+
 ## Full Output (`--full`)
 
 The complete transcript with these section types:

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

@@ -19,7 +19,9 @@ These four tools are aliases of the generic flow tools (`start_flow`, `send_to_p
 
 ## Long rounds are normal
 
-`round_timeout` is an **inactivity** bound, not a wall-clock cap: a round only fails for taking too long if the reviewer goes genuinely quiet for that whole stretch — an actively-working reviewer can legitimately run a round for a long time. If a status check (or a `submit_review_round`/`start_review_flow` call) returns the benign "Flow still running" text, that is an expected outcome on a long round, not a problem — re-enter the wait with `get_review_flow_status(flow_run_id, wait: true)`, which blocks (via bounded, internally-retried checks — never a raw long-poll) until the round finishes or roughly 8 minutes pass, then call it again if it's still running. A round result of **`unclear` now genuinely means the reviewer went dead or silent** (no activity for the whole inactivity bound, or it crashed/was stopped) — it is no longer a symptom of a merely slow reviewer, so treat it as a liveness problem (see the `participant_unreachable` and `participant_died`/`participant_stopped` entries below), not as "the review is taking a while."
+`round_timeout` is an **inactivity** bound, not a wall-clock cap: a round only fails for taking too long if the reviewer goes genuinely quiet for that whole stretch — an actively-working reviewer can legitimately run a round for a long time. If a status check (or a `submit_review_round`/`start_review_flow` call) returns the benign "Flow still running" text, that is an expected outcome on a long round, not a problem — re-enter the wait with `get_review_flow_status(flow_run_id, wait: true)`, which blocks (via bounded, internally-retried checks — never a raw long-poll) until the round finishes or roughly 3.5 minutes pass, then call it again if it's still running. A round result of **`unclear` now genuinely means the reviewer went dead or silent** (no activity for the whole inactivity bound, or it crashed/was stopped) — it is no longer a symptom of a merely slow reviewer, so treat it as a liveness problem (see the `participant_unreachable` and `participant_died`/`participant_stopped` entries below), not as "the review is taking a while."
+
+**A harness tool timeout is not a flow failure.** `start_review_flow` and `submit_review_round` block for minutes while the reviewer works. If your harness aborts the call with its own tool timeout (on Codex the error reads `timed out awaiting tools/call`), the flow is still running server-side. Do not start a new flow and do not investigate — call `get_review_flow_status(wait: true)`. Without a `flow_run_id` it reads the newest open flow this session started (pass `session_id` for another session's), so it works even when the aborted start never handed you the id or context compaction dropped it; with several open flows it lists them for you to pick from. On a harness that gives the flows server no session identity, it reads the flows started from this workspace on this machine instead.
 
 ## Role-surface safety gate
 
@@ -130,7 +132,7 @@ After applying the role-surface safety gate, if `start_review_flow` / `submit_re
 
 ## Core rules
 
-1. **Start exactly one flow per user task.** Call `start_review_flow` once and hold the returned `flow_run_id`. Do NOT start a new flow for follow-up rounds — reuse the same ID.
+1. **Start exactly one flow per user task.** Call `start_review_flow` once and hold the returned `flow_run_id`. Do NOT start a new flow for follow-up rounds — reuse the same ID. If the id is gone (a harness timeout aborted the start, or compaction dropped it), get it back with `get_review_flow_status(wait: true)` — never by starting another flow.
 2. **After receiving a `findings` result**, address every finding, then call `submit_review_round` with the updated context and the same `flow_run_id`.
 3. **Do NOT finish the user task while the flow has unresolved findings.** Keep iterating until the reviewer returns `clean`.
 4. **Only call `close_review_flow` after a `clean` result.** Then report completion to the user.
@@ -175,7 +177,7 @@ if findings:
 |---|---|---|---|
 | `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. |
 | `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` | `wait` (`true`/`false`, defaults to `false`) — when `true`, blocks until the round is terminal or roughly 8 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. |
+| `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`. |
 
 ## Example (code review)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kurrent/kcap",
-  "version": "1.1.1",
+  "version": "1.3.0-beta.1",
   "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.1.1",
-    "@kurrent/kcap-linux-arm64": "1.1.1",
-    "@kurrent/kcap-linux-musl-arm64": "1.1.1",
-    "@kurrent/kcap-linux-musl-x64": "1.1.1",
-    "@kurrent/kcap-linux-x64": "1.1.1",
-    "@kurrent/kcap-win-x64": "1.1.1"
+    "@kurrent/kcap-darwin-arm64": "1.3.0-beta.1",
+    "@kurrent/kcap-linux-arm64": "1.3.0-beta.1",
+    "@kurrent/kcap-linux-musl-arm64": "1.3.0-beta.1",
+    "@kurrent/kcap-linux-musl-x64": "1.3.0-beta.1",
+    "@kurrent/kcap-linux-x64": "1.3.0-beta.1",
+    "@kurrent/kcap-win-x64": "1.3.0-beta.1"
   },
   "files": [
     "bin/",
     "kcap/"
   ],
-  "kcapReleaseCommit": "c56b47d75d5015098627600e7c893711ba2059d8",
-  "kcapReleaseTag": "v1.1.1"
+  "kcapReleaseCommit": "f95e44d81d47ce2bd10c95d45c269951480e9d62",
+  "kcapReleaseTag": "v1.3.0-beta.1"
 }