paseo-follow-up 0.3.6 → 0.4.0

package/OVERVIEW.md

@@ -1,15 +1,27 @@
 # Follow-up
 
-Follow-up keeps PR stacks, remaining tasks and explicit agent completion attached to a Paseo workspace. It groups workspaces by whether you or an agent can act next and retains settled PR history.
+Follow-up watches every pull request a Paseo workspace opens until the work is actually done. It shows each PR stack at a glance, gathers conflicts, failing required checks and review threads into one repair batch for the workspace's main agent, and tells you when something needs you, such as an approved PR to merge, a question the agent asked or a batch to send. Answer a question in Follow-up and the answer goes straight to the agent's chat.
 
-Requires Paseo 0.14+, Node 22+ and authenticated gh on the daemon host. Graphite CLI authentication is used for readiness and explicit Merge. The optional Send to Paseo browser companion enables Graphite's Merge when ready setting through the existing pairing, with confirmation or remembered permission for toggle changes in Chrome; it is not needed for tracking, recovery or follow-up.
+## What you see
 
-Open the sidebar or Command-K, then Track this workspace. Project settings can enroll existing and new workspaces with original main-agent ownership; Auto always starts off. The retained development default enables canonical Git repositories named hero-poc, while other projects require opt-in. Disable that project default to stop further enrollment without losing records.
+- A workspace panel that leads with status: PRs merged, what needs you, what needs fixing, a bar with one segment per PR, and what the agent is doing now.
+- A Needs you card with one button per decision: Send repairs, Merge, Resume, Retry, or Answer.
+- Questions from the main agent, each with a permanent ref (Q1, Q2…), lettered options, the agent's recommendation and what it does while it waits. Pick an option, add a note and Send it to the agent, or Copy it instead. Answered questions stay listed under their ref, and the question mode setting (Stop, Work around, Keep building) tells agents what to do until you answer.
+- A Spec link in the header to the page that sums up the workspace, usually the Claude artifact the main agent keeps up to date.
+- An Activity card: repairs sent and finished with how long they took, merges, PR actions and questions.
+- Each stack drawn top to base like Graphite, merged PRs folded away, and a sheet per PR with checks, reviewers and Merge.
+- Tasks for work that outlives a merge, manual or scheduled after a merge or deploy, with an optional delay.
+- A composer pill and a sidebar count that appear only when something needs you; the pill steps through open questions so you can answer without leaving the chat. One screen lists every tracked workspace by who is up next, and a larger view opens a workspace in two columns.
+- Compact rows for Follow-up's own tool calls in agent chats, a card for each repair batch, and a card when the agent declares Done.
 
-Every main view links to the overview, project settings and display settings. You can hide the workspace button and sidebar independently and still use Command-K. The installation id and local state directory remain follow-through for compatibility.
+## Setup
 
-Repair batches go to the original main agent after a click, or after explicit per-workspace Auto consent and fresh delivery checks. Recovery is a separate manual action. Done requires the main agent's declaration and settled requirements; merging and archiving remain your actions. Tasks are manual unless you explicitly schedule Now, After merge or After deploy, optionally with a delay. Deployment gates require serving-revision evidence; merges alone never prove deployment.
+Requires Paseo 0.14+, Node 22+ and an authenticated `gh` on the daemon host. Merge uses saved Graphite CLI authentication. Open a workspace, open Follow-up from its header or Command-K, and choose Track this workspace. Project settings can track every workspace in a project. The optional Send to Paseo browser companion adds Graphite's Merge when ready switch through its existing pairing; it is not needed for anything else.
 
-This trusted unsandboxed plugin reads selected workspace metadata, saved agent history/configuration, GitHub status and existing CLI authentication. State and private recovery evidence remain in plugin-data/follow-through. Scoped MCP registration and reversible provider hooks support tracked root sessions; contributors can register PRs from any worktree without taking main-agent authority. Successful submission receipts are discovered automatically within the workspace repository, while mentions remain unowned; Codex's trust review remains in force. Prompts and repair context are sent to your configured agent/provider. Site-specific reviewer and Cloud Run adapters only apply to the configured repository; unsupported deployments remain unknown.
+## What it does on its own, and what it never does
 
-Merge, Merge when ready and reviewer requests require explicit developer controls. Optional direct browser grants trust that machine to change the PR toggle for the allowed repository, including later pushes; the existing Send pairing permits reads for active tracked repositories, while toggle changes require confirmation in Chrome unless explicitly remembered. Auto and agent tools cannot authorize them. Follow-up has no Slack posting identity or background channel scanner. Stakeholder replies require the developer's authorization, original destination and a verified sent-message receipt from the agent.
+Auto-send starts off for every workspace. Until you turn it on, each repair batch waits for your click; with it on, Follow-up sends batches once the main agent is idle, after fresh permission and Session Guard checks. Follow-up never merges, turns on merge when ready, requests reviewers or archives on its own, and Merge always re-checks the stack and asks again. Done needs the main agent's declaration, settled PRs and tasks, and no open questions. Answers are sent only when you click Send; an answer the agent can't take yet waits and goes out on the next check, and one Paseo didn't confirm waits for you to Resend. An optional recovery agent can rebuild missed PRs and tasks from a workspace's history; it runs only when you start it and never edits code. Deployment checks and reviewer shortcuts exist only for specifically configured repositories; elsewhere deployment stays unknown.
+
+## Data and access
+
+This is a trusted, unsandboxed plugin. It reads workspace metadata, saved agent history and configuration, GitHub status and existing CLI authentication, and keeps its state in `plugin-data/follow-through` on the daemon host. It registers scoped MCP tools and reversible provider hooks only for tracked sessions. To find the spec link it reads completed Claude Artifact publish results in the workspace's root sessions, never page content, chat links or the repository; a link you set wins over the agent's, which wins over detection. Repair prompts go to your configured agent and provider. It has no Slack identity and no background channel scanning; replies to stakeholders need your authorization and a sent-message receipt from the agent.

package/README.md

@@ -1,126 +1,117 @@
-# Paseo Follow-up
+# paseo-follow-up
 
 [![npm version](https://img.shields.io/npm/v/paseo-follow-up?style=for-the-badge&color=cb3837)](https://www.npmjs.com/package/paseo-follow-up)
 [![npm downloads](https://img.shields.io/npm/dm/paseo-follow-up?style=for-the-badge&color=cb3837)](https://www.npmjs.com/package/paseo-follow-up)
 [![Paseo](https://img.shields.io/badge/Paseo-%E2%89%A5%200.14.0-8A63D2?style=for-the-badge)](https://paseo.sh)
 [![License](https://img.shields.io/github/license/tomgrin10/paseo-follow-up?style=for-the-badge&color=2563eb)](LICENSE)
 
-Keep long-lived Paseo workspaces moving through review, deployment, and completion. Follow-up retains PR stacks and remaining tasks, batches repairs for the existing main agent, and records the agent's explicit Done declaration.
+Follow-up watches every pull request a Paseo workspace opens until the work is actually done. It shows the whole stack at a glance, gathers conflicts, failing checks and review threads into one repair batch for the workspace's main agent, and tells you when something needs you: an approved PR to merge, a question the agent asked, or a batch to send. Answer a question in Follow-up and the answer goes straight to the agent's chat.
 
-![Follow-up workspace panel with sample pull requests and remaining tasks](docs/screenshots/follow-up-workspace.png)
+<picture>
+  <source media="(prefers-color-scheme: light)" srcset="docs/media/follow-up-hero-light.png">
+  <img alt="A Paseo workspace with the Follow-up panel open: a Spec link, 1 of 5 PRs merged, 4 need you, 2 to fix, a coloured stack bar, and a Needs you card with two questions from the agent, three repairs to send and Merge #418, beside the agent's chat" src="docs/screenshots/follow-up-hero.png">
+</picture>
 
 Screenshots use synthetic workspaces and PRs.
 
-## Requirements
-
-- Paseo 0.14.0 or newer and Node 22 or newer.
-- Authenticated GitHub CLI (`gh`) on the daemon host.
-- Saved Graphite CLI authentication for Graphite readiness and explicit Merge controls.
-- Optional Send to Paseo browser companion for Graphite's actual Merge when ready switch. Core tracking and follow-up work without it.
-
 ## Install
 
 ```sh
 paseo plugin install paseo-follow-up
 ```
 
-The installation ID remains `follow-through` to preserve existing development installations, saved settings and tracked work. The public name is **Follow-up**.
+Needs Node 22+ and an authenticated GitHub CLI (`gh`) on the daemon host. Merge buttons use your saved Graphite CLI authentication. The installed plugin ID stays `follow-through`, so existing settings and tracked work carry over.
 
 ## Use
 
-Open **Follow-up** from the sidebar or Command-K. The cog at the bottom opens native project settings; display settings remain in Paseo’s plugin settings. In a workspace, use the header button or the Follow-up panel and click **Track this workspace**. The original main agent owns PRs, tasks and completion; optional history recovery runs in a separate agent only after your click.
+Open a workspace, click the Follow-up icon in its header (or press ⌘K / Ctrl+K and choose **Follow-up: open for this workspace**), then **Track this workspace**. To track every workspace in a project, open the settings (the gear in the panel, or **Follow-up: project settings** in ⌘K) and turn the project on.
 
-Use **Overview**, **Project settings** and **Display settings** to move between views. Settings are also available directly from Command-K. Display settings can hide the workspace header button or sidebar entry independently; Command-K remains available.
+The panel reads top to bottom:
 
-Project settings control existing and future eligible workspaces by stable project ID. The retained development default enables canonical Git projects named `hero-poc`; other projects start off. Turning a project off stops enrollment while preserving tracked records. New enrollments always have Auto off.
+- **Status.** How many PRs have merged, how many things need you, how many PRs need fixing, and a bar with one segment per PR in merge order. Below it, what the agent is doing right now.
+- **Needs you.** One row per decision, each with its button: answer the agent's question, send repairs to the main agent, merge an approved PR, resume after you stopped the agent, or retry a batch that didn't finish.
+- **Pull requests.** Each stack drawn top to base, the way Graphite shows it, with merged PRs folded away.
+- **Tasks.** Work that outlives a merge, such as a production check or a backfill. Tasks wait for you unless you schedule them for after a merge or deploy.
+- **Activity.** What happened and how long it took: repairs sent and finished, merges, merge and reviewer actions, and every question under its ref.
 
-With **Auto** off, review and send each repair batch yourself. Auto authorizes follow-up messages only for that workspace after fresh idle, permission and Session Guard checks. It never merges PRs, enables merge when ready, requests reviewers, starts recovery or archives workspaces.
+The **Spec** chip in the header opens the page that sums up the workspace, usually the Claude artifact the main agent keeps up to date. The agent registers it with a tool call, Follow-up also picks up artifacts the workspace's sessions publish, and you can set, change or remove it under **Spec, agent and recovery**. Your link wins over the agent's, which wins over detection.
 
-Tasks default to manual. Explicit Now, After merge or After deploy triggers can include a delay; deployment tasks wait for verified serving-revision evidence. Merged PRs alone do not mean the work is Done. Agents retain evidence and record sent reply URLs for developer-authorized stakeholder updates.
+![Four Follow-up panels side by side: a workspace that needs you, one where the agent is fixing two repairs, one that has shipped, and one that is not tracked yet](docs/screenshots/follow-up-states.png)
 
-![Follow-up overview with sample workspaces](docs/screenshots/follow-up-overview.png)
+### Questions
 
-## Send to Paseo and Graphite
+When the main agent needs a decision it asks in Follow-up instead of burying it in chat. Each question gets a permanent ref (Q1, Q2…), lettered options with what each means, the agent's recommendation, and a line saying what the agent does while it waits. Pick an option, add a note if you like, and **Send to agent**: the answer goes straight into its chat, even mid-turn, and stays recorded under its ref. **Copy** puts the same answer on the clipboard instead. If the agent can't take it yet (Session Guard paused it, or a permission prompt is open) the answer waits and goes out on the next check; if Paseo doesn't confirm the message, Follow-up asks you to check before resending. A task the agent marks blocked becomes a question too.
+
+![The Q3 question dialog with three lettered options, A recommended and B selected with a note, beside the Activity card listing every question under its ref](docs/screenshots/follow-up-questions.png)
+
+The question mode in Follow-up's settings tells agents what to do until you answer: **Stop** (end the turn and wait), **Work around** (the default: build nothing the answer affects, keep working on the rest) or **Keep building** (build the recommendation and change course if you pick another). Big questions, ones that reach outside this computer or that most of the work depends on, always wait.
+
+### Everywhere else
+
+When a workspace needs you, a pill appears above its main agent's message box with the same actions. It steps through open questions ("Question 1 of 2") so you can answer without leaving the chat. The sidebar's Follow-up row counts how many workspaces are waiting, and nothing shows when nothing needs you.
+
+![The composer pill "4 need you" opened into a popover: Question 1 of 2 with an answer field, then three repairs ready to send and an approved PR](docs/screenshots/follow-up-pill.png)
+
+Tap a PR, or its segment in the bar, for a sheet with its checks, reviewers and Merge controls. When Merge isn't available yet, the sheet says what it is waiting for.
+
+![The PR sheet for a PR whose required checks failed](docs/screenshots/follow-up-pr.png)
+
+The expand icon next to the gear (or **Follow-up: open the larger view** in ⌘K) opens the workspace as a full screen, in two columns when there is room: what needs you on the left, the stacks and activity on the right. Esc or the collapse icon takes you back.
 
-With Send to Paseo installed on the same daemon, its composer can return to the agent that
-registered a PR here. New registrations record that agent; older records retain the workspace’s
-main agent. You can still choose a fresh agent in Send to Paseo. Tracking and follow-up remain
-usable without the companion.
+![The larger view: Needs you, tasks and activity on the left, pull request stacks on the right](docs/screenshots/follow-up-large.png)
 
-To control Graphite’s **Merge when ready** here, use Send to Paseo plugin/extension 2.2+ and
-Follow Up 0.3.4+, and keep Graphite open and signed in. Follow Up connects automatically through
-your existing Send to Paseo pairing and advertises the repositories of active tracked PRs.
+In the agent's chat, Follow-up's own tool calls collapse into one-line rows, your answers and repair batches show as short cards instead of raw prompts, and the agent's Done call gets a card of its own.
 
-Toggle changes require confirmation in Chrome. The confirmation can remember permission for
-future changes from that machine for the exact repository. Revoke that permission or turn off
-browser access in extension settings → **Follow Up**. This is a PR setting, including later pushes.
-See the [integration and security contract](https://github.com/tomgrin10/send-to-paseo/blob/main/docs/follow-up-integration.md).
+![Follow-up rows and cards in an agent chat](docs/screenshots/follow-up-chat.png)
 
-## Data and permissions
+**Follow-up: all tracked workspaces** (or the sidebar row) lists every tracked workspace, grouped by who's up next, with each stack's bar and its Spec link.
 
-This is a trusted, unsandboxed plugin. It reads selected workspace metadata, agent history/configuration and GitHub PR status using your existing host credentials. Local state and private recovery evidence live under `$PASEO_HOME/plugin-data/follow-through`; credentials and provider configuration are not published or transferred.
+![The tracked workspaces screen grouped into Needs you, Agent working, Waiting and Done](docs/screenshots/follow-up-overview.png)
 
-It registers scoped Claude/Codex MCP tools and reversible provider hooks for tracked root sessions. Contributor sessions receive PR registration, status and sync tools; goal, task and completion authority stays with the designated main agent. Codex keeps its normal hook trust review. Repair and recovery prompts reach your configured agent provider. Follow-up itself has no Slack posting identity and never scans channels or authorizes replies from historical mentions.
+On a phone the panel opens as a tab, and the PR sheet and pill popover open as bottom sheets.
 
-Human-operated Merge and reviewer controls perform GitHub/Graphite writes only after an explicit click and fresh eligibility checks. Unknown or uncertain results require checking before retrying. Site-specific reviewer and Cloud Run deployment adapters remain limited to their configured repository; other deployment status remains unknown rather than being inferred from a merge.
+![Follow-up at phone width: the panel, a PR sheet and the pill popover](docs/screenshots/follow-up-mobile.png)
 
-## Develop
+## How it works
+
+- The workspace's main agent owns its PRs, tasks, questions, the spec link and the Done call. Other agents in the workspace can register PRs and check status.
+- **Auto-send** is off for every newly tracked workspace, so each repair batch waits for your click. Turn it on per workspace and Follow-up sends batches itself once the agent is idle, after fresh permission and Session Guard checks.
+- Follow-up never merges, turns on merge when ready, requests reviewers or archives on its own. **Merge** re-checks the stack, lists any PRs underneath that would merge first, and asks again.
+- A merged PR is not the end: tasks such as production checks and open questions keep the workspace open until the main agent declares Done and everything has settled.
+- Answers go out only when you click Send. Follow-up never answers for you.
+
+## Send to Paseo and Graphite
+
+With [Send to Paseo](https://github.com/tomgrin10/send-to-paseo) on the same daemon, its composer picks the agent that registered the PR. With Send to Paseo 2.2+, Follow-up can also toggle Graphite's **Merge when ready** through your existing pairing, while Graphite is open and signed in. Each change is confirmed in Chrome, which can remember the permission per repository. See the [integration and security contract](https://github.com/tomgrin10/send-to-paseo/blob/main/docs/follow-up-integration.md).
+
+## Data and access
+
+Paseo plugins run trusted, unsandboxed code on the daemon host. Follow-up reads workspace metadata, agent history and GitHub PR status with your existing credentials, and keeps its state in `$PASEO_HOME/plugin-data/follow-through`. It registers scoped MCP tools and reversible provider hooks only for tracked sessions. GitHub and Graphite writes happen only after an explicit click and a fresh eligibility check.
+
+## Development
 
 ```sh
 npm ci
 npm run verify
 npm run test:install
-npm pack --dry-run
+paseo plugin reload follow-through   # after changes
 ```
 
-Integration checks use a separate Paseo home, synthetic agents and fixtures. Never restart your main daemon for verification. Reload only this plugin with `paseo plugin reload follow-through`.
-
-## Releases
+Integration checks use a separate Paseo home with synthetic agents. Version tags (`vX.Y.Z`) publish to npm through Trusted Publishing.
 
-Release tags (`vX.Y.Z`) run `.github/workflows/publish-npm.yml`. GitHub Actions verifies the plugin and packed installation, publishes through npm Trusted Publishing, verifies registry integrity, then creates the GitHub release. No npm token is stored in repository secrets.
+## License
 
-## Paseo 0.14 agent integration
+[MIT](LICENSE) © 2026 Tom Gringauz.
 
-The Follow-up MCP attaches when a root agent in a tracked workspace or an active recovery agent opens a Claude or Codex session. Other root sessions get `workspace_status`, `register_pr` and `sync_workspace`, even when the originally recorded main agent is unavailable. Normal startup no longer writes global Claude/Codex MCP settings. Existing global entries are preserved. Turn-ended discovery now fetches recent history through the SDK because Paseo 0.13+ sends an empty timeline in lifecycle events.
-
-Requires Paseo **0.14.0 or newer**. Agent tools are scoped to interactive Claude
-and Codex sessions; history-only opens receive none. They become available on
-the next idle session open after install or reload. The agent label
-`plugin-tools/enabled: "false"` opts a session out. Existing plugin data and
-settings are retained.
+Questions, question modes and the activity log are adapted from [Progress](https://github.com/stevecastaneda/paseo-plugins/tree/main/progress) by Steve Castaneda (MIT). Its notice is in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
 
 ## Other plugins
 
-Also available from [Tom Gringauz](https://github.com/tomgrin10):
-
-- [Defer](https://github.com/tomgrin10/paseo-defer) — Schedule messages to agents for later delivery.
-- [Graphite](https://github.com/tomgrin10/paseo-graphite) — Workspace stack status and PR action radar.
+- [Defer](https://github.com/tomgrin10/paseo-defer) — Schedule messages for later delivery.
 - [Send to Paseo](https://github.com/tomgrin10/send-to-paseo) — Send GitHub and Graphite PRs to Paseo from Chrome.
-- [Smart Session](https://github.com/tomgrin10/paseo-smart-session) — Context-aware compaction and plan usage insights.
-- [Vitals](https://github.com/tomgrin10/paseo-vitals) — Host, Paseo, agent and Docker health.
-- [Session Guard](https://github.com/tomgrin10/paseo-session-guard) — Pause at usage limits and resume after reset.
-- [Transfer](https://github.com/tomgrin10/paseo-transfer) — Copy or move workspaces and agent conversations between hosts.
-- [Transcript Search](https://github.com/tomgrin10/paseo-transcript-search) — Search active and archived conversations across hosts.
-
-
-Successful `gt submit` and `gh pr create` receipts in root-session history also discover submitted
-PRs automatically, including from secondary git worktrees. Discovery checks the workspace's GitHub
-repository identity; merely mentioned PRs and read-only commands do not establish ownership.
-Explicit registrations, exclusions and another tracked workspace's ownership take precedence.
-Observed GitHub base/head branches supply inferred stack relationships; explicit edits override them.
-Tracking continues after the checkout branch's PR merges, and the submitting session remains the
-recipient for Send to Paseo. Existing sessions can use the hook-provided CLI fallback before their
-next MCP session refresh. Automatic discovery does not transfer main-agent authority or enable Auto.
-
-
-Agents launched by another agent into a separate workspace can be that new workspace’s main agent.
-The creator’s parent-agent label records launch provenance; it excludes an agent from local main
-selection only when the parent belongs to the same workspace. Parent membership is checked from
-the daemon, including direct lookup when the creator is no longer in the live directory. Unknown
-membership does not grant new scope. Workspace-first creation is supported: tracking waits for an
-available local main, then applies the project default. Explicit Track also supports these launches.
-
-
-Track persists activation and returns without waiting for transcript scans or the daemon-wide PR
-refresh. Initial session attachment also uses ownership metadata only. PR/history discovery and
-status refresh continue in the background; a slow GitHub or agent observation does not hold Track.
+- [Session Guard](https://github.com/tomgrin10/paseo-session-guard) — Pause at session limits and continue after reset.
+- [Smart Session](https://github.com/tomgrin10/paseo-smart-session) — Context compaction and usage insights.
+- [Transcript Search](https://github.com/tomgrin10/paseo-transcript-search) — Search conversations across connected hosts.
+- [Transfer](https://github.com/tomgrin10/paseo-transfer) — Copy or move workspaces between hosts.
+- [Vitals](https://github.com/tomgrin10/paseo-vitals) — Host, process, agent and Docker monitoring.
+- [Workspace Switcher](https://github.com/tomgrin10/paseo-switcher) — Arc-style Ctrl+Tab between recent workspaces.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,33 @@
+# Third-party notices
+
+## Progress
+
+Follow-up's questions (the ask, record and withdraw tools, the Stop, Work around and Keep building
+question modes and their rules, the "big question" test, and the question dialog with lettered
+options, a recommendation and Copy) and the activity log are adapted from
+[Progress](https://github.com/stevecastaneda/paseo-plugins/tree/main/progress) (`@stevecastaneda/paseo-progress`
+1.14.0) by Steve Castaneda.
+
+```
+MIT License
+
+Copyright (c) 2026 Steve Castaneda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/assets/LICENSE.lucide

@@ -0,0 +1,43 @@
+ISC License
+
+Copyright (c) 2026 Lucide Icons and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+---
+
+The following Lucide icons are derived from the Feather project:
+
+airplay, alert-circle, alert-octagon, alert-triangle, aperture, arrow-down-circle, arrow-down-left, arrow-down-right, arrow-down, arrow-left-circle, arrow-left, arrow-right-circle, arrow-right, arrow-up-circle, arrow-up-left, arrow-up-right, arrow-up, at-sign, calendar, cast, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down, chevrons-left, chevrons-right, chevrons-up, circle, clipboard, clock, code, columns, command, compass, corner-down-left, corner-down-right, corner-left-down, corner-left-up, corner-right-down, corner-right-up, corner-up-left, corner-up-right, crosshair, database, divide-circle, divide-square, dollar-sign, download, external-link, feather, frown, hash, headphones, help-circle, info, italic, key, layout, life-buoy, link-2, link, loader, lock, log-in, log-out, maximize, meh, minimize, minimize-2, minus-circle, minus-square, minus, monitor, moon, more-horizontal, more-vertical, move, music, navigation-2, navigation, octagon, pause-circle, percent, plus-circle, plus-square, plus, power, radio, rss, search, server, share, shopping-bag, sidebar, smartphone, smile, square, table-2, tablet, target, terminal, trash-2, trash, triangle, tv, type, upload, x-circle, x-octagon, x-square, x, zoom-in, zoom-out
+
+The MIT License (MIT) (for the icons listed above)
+
+Copyright (c) 2013-present Cole Bemis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="256" viewBox="0 0 256 256"><title>Follow-up</title><rect width="256" height="256" rx="52" fill="#1c2229"/><svg x="52" y="52" xmlns="http://www.w3.org/2000/svg" width="152" height="152" viewBox="0 0 24 24" fill="none" stroke="#f3f0e8" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-list-checks" aria-hidden="true"><path d="M13 5h8"></path><path d="M13 12h8"></path><path d="M13 19h8"></path><path d="m3 17 2 2 4-4"></path><path d="m3 7 2 2 4-4"></path></svg></svg>

package/client/button-visibility.ts

@@ -25,7 +25,8 @@ export function withButtonVisibility(client: PluginClientContext) {
   buttons.addComposerPill = input => gated("addComposerPill", input);
   const unsubscribe = subscribeDisplay(values => {
     enableHeader = values.enable_header_button;
-    
+    // Unknown is not off: older saved documents predate the pill preference.
+    enableComposer = values.enable_composer_pill !== false;
     for (const entry of entries) entry.reconcile();
   });
   return { client: buttons, dispose() { unsubscribe(); for (const entry of [...entries]) entry.remove(); } };

package/client/chat.tsx

@@ -0,0 +1,163 @@
+import { useState } from "react";
+import { Platform, Pressable, Text, View } from "react-native";
+import type { PluginClientContext, PluginTimelineItemProps } from "@getpaseo/plugin/client";
+import { Icon, ScrollView } from "@getpaseo/plugin/client/ui";
+import { answerCardSchema, batchCardSchema, followShellCall, followToolName, parseBatchPrompt, readText, toolRow, toolRowSchema, type AnswerCard, type BatchCard, type ToolRow } from "../shared/chat";
+import { parseAnswerMessage } from "../shared/questions";
+import { Reveal } from "./motion";
+import { tint, withAlpha } from "./theme";
+
+const mono = () => (Platform.OS === "ios" ? "Menlo" : "monospace");
+const TOOL_KIND = "tool-row";
+const BATCH_KIND = "batch-card";
+const ANSWER_KIND = "answer-card";
+const TOOL_ICON: Partial<Record<ToolRow["tool"], string>> = { ask_question: "MessageCircleQuestion", record_answer: "MessageCircleReply", withdraw_question: "MessageCircleOff", set_spec: "FileText" };
+
+function record(value: unknown): value is Record<string, unknown> { return typeof value === "object" && value !== null && !Array.isArray(value); }
+
+/** Expandable full text below a row, scrolling on its own so long output never moves the chat. */
+function Expanded({ text, color, border }: { text: string; color: string; border: string }) {
+  return <View style={{ borderWidth: 1, borderTopWidth: 0, borderColor: border, borderBottomLeftRadius: 8, borderBottomRightRadius: 8, overflow: "hidden" }}>
+    <ScrollView style={[{ maxHeight: 300 }, Platform.OS === "web" ? ({ overscrollBehavior: "contain" } as object) : null]} contentContainerStyle={{ paddingHorizontal: 12, paddingVertical: 8 }}>
+      <Text selectable style={{ color, fontFamily: mono(), fontSize: 12, lineHeight: 18 }}>{text}</Text>
+    </ScrollView>
+  </View>;
+}
+
+/** Follow-up's own tool calls as one quiet line, sized like Paseo's tool rows; press to read the result. */
+function ToolRowView({ item, theme }: PluginTimelineItemProps<ToolRow>) {
+  const c = theme.colors;
+  const row = item.data;
+  const [expanded, setExpanded] = useState(false);
+  const [hovered, setHovered] = useState(false);
+  if (row.done) return <DoneCard summary={row.done.summary} theme={theme} />;
+  const color = row.tone === "danger" ? c.statusDanger : row.tone === "warning" ? c.statusWarning : row.tone === "success" ? c.statusSuccess : c.foregroundMuted;
+  const openable = row.more !== null;
+  const active = openable && (hovered || expanded);
+  const open = expanded && openable;
+  return <View style={{ marginHorizontal: -13 }}>
+    <Pressable disabled={!openable} onPress={() => setExpanded(v => !v)} onHoverIn={() => setHovered(true)} onHoverOut={() => setHovered(false)}
+      accessibilityRole={openable ? "button" : undefined} aria-expanded={openable ? expanded : undefined} aria-busy={row.state === "running"}
+      style={{ flexDirection: "row", alignItems: "center", borderRadius: 8, borderWidth: 1, borderColor: open ? c.border : "transparent", borderBottomLeftRadius: open ? 0 : 8, borderBottomRightRadius: open ? 0 : 8, backgroundColor: open ? c.surface1 : "transparent", paddingHorizontal: 8, paddingVertical: 4 }}>
+      <View style={{ width: 22, height: 22, marginRight: 4, alignItems: "center", justifyContent: "center" }}>
+        {active ? <View style={{ transform: [{ rotate: expanded ? "90deg" : "0deg" }] }}><Icon name="ChevronRight" size={14} color={c.foreground} /></View>
+          : <Icon name={row.state === "failed" ? "TriangleAlert" : TOOL_ICON[row.tool] ?? (row.tone === "warning" ? "CircleAlert" : "GitPullRequest")} size={12} color={row.tone === "muted" ? c.foregroundMuted : color} />}
+      </View>
+      <Text numberOfLines={1} style={{ flexShrink: 1, fontSize: 14, color: row.tone === "muted" ? (active || row.state === "running" ? c.foreground : c.foregroundMuted) : color, opacity: row.state === "running" ? 0.72 : 1 }}>{row.line}</Text>
+    </Pressable>
+    {open && <Expanded text={row.more!} color={row.state === "failed" ? c.statusDanger : c.foreground} border={c.border} />}
+  </View>;
+}
+
+/** The agent declared the workspace done: the one row in the chat that is allowed to be a little proud. */
+function DoneCard({ summary, theme }: { summary: string; theme: PluginTimelineItemProps["theme"] }) {
+  const c = theme.colors;
+  return <Reveal>
+    <View accessibilityRole="summary" style={{ flexDirection: "row", gap: 12, padding: 12, borderRadius: 10, backgroundColor: tint(c.statusSuccess, c), borderWidth: 1, borderColor: withAlpha(c.statusSuccess, 0.35), marginVertical: 4 }}>
+      <View style={{ width: 28, height: 28, borderRadius: 14, alignItems: "center", justifyContent: "center", backgroundColor: c.statusSuccess }}><Icon name="Check" size={16} color={c.surface0} /></View>
+      <View style={{ flex: 1, gap: 3 }}>
+        <Text style={{ color: c.foreground, fontSize: 14, lineHeight: 19, fontWeight: "600" }}>Workspace done</Text>
+        {!!summary && <Text selectable style={{ color: c.foreground, fontSize: 13, lineHeight: 19 }}>{summary}</Text>}
+        <Text style={{ color: c.foregroundMuted, fontSize: 12, lineHeight: 17 }}>Follow-up checked every PR and task. Archive the workspace when you're ready.</Text>
+      </View>
+    </View>
+  </Reveal>;
+}
+
+/** A repair batch Follow-up sent, as a card instead of a raw prompt bubble. */
+function BatchCardView({ item, theme }: PluginTimelineItemProps<BatchCard>) {
+  const c = theme.colors;
+  const card = item.data;
+  const [expanded, setExpanded] = useState(false);
+  const recovery = card.kind === "recovery";
+  return <View style={{ alignSelf: "flex-end", width: "100%", maxWidth: 560, marginVertical: 4 }}>
+    <View style={{ borderRadius: 10, borderWidth: 1, borderColor: c.border, backgroundColor: c.surface1, overflow: "hidden" }}>
+      <View style={{ flexDirection: "row", alignItems: "center", gap: 8, paddingHorizontal: 12, paddingTop: 10, paddingBottom: recovery ? 10 : 6 }}>
+        <Icon name={recovery ? "History" : "Wrench"} size={14} color={c.foregroundMuted} />
+        <Text style={{ flex: 1, color: c.foreground, fontSize: 13, lineHeight: 18, fontWeight: "600" }}>{recovery ? "Follow-up recovery brief" : `Follow-up sent ${card.tasks.length} repair${card.tasks.length === 1 ? "" : "s"}`}</Text>
+        <Pressable accessibilityRole="button" aria-expanded={expanded} accessibilityLabel={expanded ? "Hide the full message" : "Show the full message"} onPress={() => setExpanded(v => !v)} hitSlop={6}
+          style={state => ({ paddingHorizontal: 6, paddingVertical: 2, borderRadius: 4, backgroundColor: state.pressed ? c.surface2 : "transparent" })}>
+          <Text style={{ color: c.foregroundMuted, fontSize: 12 }}>{expanded ? "Hide" : "Full message"}</Text>
+        </Pressable>
+      </View>
+      {!recovery && <View style={{ paddingHorizontal: 12, paddingBottom: 10, gap: 3 }}>
+        {card.tasks.map((task, i) => <View key={i} style={{ flexDirection: "row", gap: 6 }}>
+          <Text style={{ width: 18, color: c.foregroundMuted, fontSize: 13, lineHeight: 19, fontVariant: ["tabular-nums"] }}>{i + 1}.</Text>
+          <Text selectable style={{ flex: 1, color: c.foreground, fontSize: 13, lineHeight: 19 }}>{task}</Text>
+        </View>)}
+      </View>}
+      {expanded && <View style={{ borderTopWidth: 1, borderTopColor: c.border }}>
+        <ScrollView style={[{ maxHeight: 300 }, Platform.OS === "web" ? ({ overscrollBehavior: "contain" } as object) : null]} contentContainerStyle={{ padding: 12 }}>
+          <Text selectable style={{ color: c.foregroundMuted, fontFamily: mono(), fontSize: 12, lineHeight: 18 }}>{card.text}</Text>
+        </ScrollView>
+      </View>}
+    </View>
+  </View>;
+}
+
+/** The developer's answer, sent from Follow-up: the question, the choice and their note. */
+function AnswerCardView({ item, theme }: PluginTimelineItemProps<AnswerCard>) {
+  const c = theme.colors;
+  const card = item.data;
+  const [expanded, setExpanded] = useState(false);
+  return <View style={{ alignSelf: "flex-end", width: "100%", maxWidth: 560, marginVertical: 4 }}>
+    <View style={{ borderRadius: 10, borderWidth: 1, borderColor: c.border, backgroundColor: c.surface1, overflow: "hidden" }}>
+      <View style={{ flexDirection: "row", alignItems: "center", gap: 8, paddingHorizontal: 12, paddingTop: 10, paddingBottom: 6 }}>
+        <Icon name="MessageCircleReply" size={14} color={c.statusSuccess} />
+        <Text numberOfLines={1} style={{ flex: 1, color: c.foreground, fontSize: 13, lineHeight: 18, fontWeight: "600" }}>Your answer to {card.id} · {card.title}</Text>
+        <Pressable accessibilityRole="button" aria-expanded={expanded} accessibilityLabel={expanded ? "Hide the full message" : "Show the full message"} onPress={() => setExpanded(v => !v)} hitSlop={6}
+          style={state => ({ paddingHorizontal: 6, paddingVertical: 2, borderRadius: 4, backgroundColor: state.pressed ? c.surface2 : "transparent" })}>
+          <Text style={{ color: c.foregroundMuted, fontSize: 12 }}>{expanded ? "Hide" : "Full message"}</Text>
+        </Pressable>
+      </View>
+      <View style={{ paddingHorizontal: 12, paddingBottom: 10, gap: 3 }}>
+        <Text selectable style={{ color: c.foreground, fontSize: 13, lineHeight: 19 }}><Text style={{ fontWeight: "600", fontVariant: ["tabular-nums"] }}>{card.choice}</Text>{card.label ? ` · ${card.label}` : ""}</Text>
+        {!!card.words && <Text selectable style={{ color: c.foregroundMuted, fontSize: 13, lineHeight: 19 }}>{card.words}</Text>}
+      </View>
+      {expanded && <View style={{ borderTopWidth: 1, borderTopColor: c.border }}>
+        <ScrollView style={[{ maxHeight: 300 }, Platform.OS === "web" ? ({ overscrollBehavior: "contain" } as object) : null]} contentContainerStyle={{ padding: 12 }}>
+          <Text selectable style={{ color: c.foregroundMuted, fontFamily: mono(), fontSize: 12, lineHeight: 18 }}>{card.text}</Text>
+        </ScrollView>
+      </View>}
+    </View>
+  </View>;
+}
+
+export function contributeChat(client: PluginClientContext) {
+  const removers = [
+    client.addTimelineTransformer({
+      id: "follow-tool-calls", query: { itemType: "tool_call" },
+      transform({ item }) {
+        const detail: unknown = item.detail;
+        let tool = followToolName(item.name);
+        let input: Record<string, unknown> = {};
+        let output: string | undefined;
+        if (tool) {
+          if (record(detail) && record(detail.input)) input = detail.input;
+          output = record(detail) && "output" in detail ? readText(detail.output) : undefined;
+        } else if (record(detail) && detail.type === "shell" && typeof detail.command === "string") {
+          const call = followShellCall(detail.command);
+          if (!call) return undefined;
+          tool = call.tool; input = call.input; output = typeof detail.output === "string" ? detail.output : undefined;
+        } else return undefined;
+        const error = item.status === "failed" ? readText(item.error) ?? "" : undefined;
+        if (item.status === "completed" && record(detail) && record(detail.output) && detail.output.isError === true)
+          return { items: [{ type: "plugin" as const, kind: TOOL_KIND, version: 1, data: toolRow(tool, "failed", input, undefined, output) }] };
+        return { items: [{ type: "plugin" as const, kind: TOOL_KIND, version: 1, data: toolRow(tool, item.status, input, output, error) }] };
+      },
+    }),
+    client.addTimelineTransformer({
+      id: "follow-batch-prompts", query: { itemType: "user_message" },
+      transform({ item }) {
+        const answer = parseAnswerMessage(item.text);
+        if (answer) return { items: [{ type: "plugin" as const, kind: ANSWER_KIND, version: 1, data: { ...answer, text: item.text } }] };
+        const card = parseBatchPrompt(item.text);
+        return card ? { items: [{ type: "plugin" as const, kind: BATCH_KIND, version: 1, data: card }] } : undefined;
+      },
+    }),
+    client.addTimelineRenderer({ kind: TOOL_KIND, version: 1, schema: toolRowSchema, Component: ToolRowView }),
+    client.addTimelineRenderer({ kind: BATCH_KIND, version: 1, schema: batchCardSchema, Component: BatchCardView }),
+    client.addTimelineRenderer({ kind: ANSWER_KIND, version: 1, schema: answerCardSchema, Component: AnswerCardView }),
+  ];
+  return () => { for (const remove of removers) void remove(); };
+}

package/client/display.tsx

@@ -1,4 +1,4 @@
-import type { PluginClientContext, PluginSidebarContribution, PluginSurfaceProps } from "@getpaseo/plugin/client";
+import type { PluginClientContext, PluginSidebarItemContribution, PluginSurfaceProps } from "@getpaseo/plugin/client";
 import { useSettings } from "@getpaseo/plugin/client";
 import { SettingsAction, SettingsCard, SettingsSection, SettingsSwitch } from "@getpaseo/plugin/client/ui";
 import { useEffect } from "react";
@@ -30,19 +30,14 @@ function DisplaySettings({ theme }: PluginSurfaceProps) {
     </View>
   );
 
+  const save = (patch: Partial<Display>) => void settings.save({ ...settings.values, ...patch }, settings.revision);
   return (
     <ScrollView style={{ flex: 1 }} contentContainerStyle={{ padding: 16, gap: 16 }}>
-    <SettingsSection title="Navigation">
+    <SettingsSection title="Where Follow-up appears" info="Every entry point opens the same panel. Command-K (Ctrl-K on Windows and Linux) works whatever you hide here.">
       <SettingsCard>
-        <SettingsSwitch
-          label="Show in sidebar"
-          hint="Open this plugin from Command-K (Ctrl-K on Windows and Linux) while viewing a workspace or plugin on this host."
-          value={settings.values.showSidebar}
-          disabled={settings.saving}
-          onValueChange={(showSidebar) => void settings.save({ ...settings.values, showSidebar }, settings.revision)}
-        />
-
-        <SettingsSwitch label="Show workspace header button" hint="Command-K and the sidebar remain available when this button is hidden." value={settings.values.enable_header_button} disabled={settings.saving} onValueChange={(enable_header_button) => void settings.save({ ...settings.values, enable_header_button }, settings.revision)} />
+        <SettingsSwitch label="Sidebar row" hint="Opens all tracked workspaces, with a count when some need you." value={settings.values.showSidebar} disabled={settings.saving} onValueChange={(showSidebar) => save({ showSidebar })} />
+        <SettingsSwitch label="Workspace header button" hint="An icon in each workspace header. A dot appears when that workspace needs you." value={settings.values.enable_header_button} disabled={settings.saving} onValueChange={(enable_header_button) => save({ enable_header_button })} />
+        <SettingsSwitch label="Composer pill" hint="Shows above the message box only while the workspace needs you." value={settings.values.enable_composer_pill} disabled={settings.saving} onValueChange={(enable_composer_pill) => save({ enable_composer_pill })} />
       </SettingsCard>
       {settings.saveError && <Text accessibilityRole="alert" style={{ color: theme.colors.statusDanger }}>{settings.saveError}</Text>}
     </SettingsSection>
@@ -51,22 +46,22 @@ function DisplaySettings({ theme }: PluginSurfaceProps) {
 }
 
 /** Settings notifications reach mounted screens; poll for changes made on other clients. */
-export function contributeDisplay(client: PluginClientContext, item: PluginSidebarContribution) {
-  const sidebar = sidebarVisibility(() => client.addSidebarItem(item));
+export function contributeDisplay(client: PluginClientContext, item: PluginSidebarItemContribution) {
+  const sidebar = sidebarVisibility(() => client.addSidebarHeaderItem(item));
   // Paseo 0.10.1 memoizes sidebar route resolution when an installation mounts.
   // Register synchronously, then reconcile the saved preference, so that an
   // already-open sidebar route can resolve its surface during that first render.
   sidebar.set(true);
   const Settings = DisplaySettings;
-  const removeSurface = client.addSurface("display-settings", Settings);
+  const removeSurface = client.addScreen({ id: "display-settings", title: "Follow-up display", Component: Settings });
   const removeSettings = client.addSettingsScreen({ id: "display", title: "Display", icon: "PanelLeft", Component: Settings });
   const removeCommand = client.addCommandCenterItem({
     id: "display-settings",
-    title: `${item.title}: display settings`,
+    title: "Follow-up: display settings",
     icon: "PanelLeft",
-    keywords: [item.title, "sidebar", "show", "hide", "display", "settings"],
+    keywords: ["Follow-up", "sidebar", "pill", "header", "show", "hide", "display", "settings"],
     context: "global",
-    onSelect({ openSurface }) { openSurface("display-settings"); },
+    onSelect({ openScreen }) { openScreen({ screenId: "display-settings" }); },
   });
   let disposed = false;
   let pending = false;