@yannelli/paseo-linear-plugin 1.0.1 → 1.1.0-beta.1

package/OVERVIEW.md

@@ -23,7 +23,25 @@ To use a different Linear key for one Paseo project, add it under **Project keys
 
 Select **Start agent** or **Start review** on an issue. The setup page shows the prompt and the composer controls for the prompt template, model, thinking level, and mode. The model picker lists providers first, and its search covers all models. Choose the project and where the agent runs: a new worktree, a pull request checkout, the issue branch, an existing agent workspace, or the current workspace or project folder. You can include comments in the prompt. For Implement, you can also move the issue to In Progress and assign it to you.
 
-The prompt follows the template until you edit it. **Reset prompt** restores it. Edit the templates in **Prompts**, and add project instructions in **Projects**.
+**Agent guidance** switches add instructions to the prompt: keep Linear updated, have subagents state their issue key, and hand off work to Paseo agents. Each project keeps its choices. With the first and last switches, the agent gets the plugin's Linear tools. It edits the issue description, checks off task list items, and starts one Paseo agent for each sub-issue. It posts no comments. For Claude agents, the switches also add hooks that give subagents the issue keys. The prompt follows the template until you edit it. **Reset prompt** restores it. Edit the templates in **Prompts**, and add project instructions in **Projects**.
+
+## Linear Live
+
+Open **Linear Live** from the Linear pill in an agent's composer. It shows the issue's sub-issues with their statuses and the agent's todos, a map of the files the agent reads and edits, or a graph of those files joined by their imports and links, with the agent gliding to what it works on, the agents it starts, and its latest commands. It works with Claude, Codex, and other providers. The map comes from paths in the ticket text, or, if you choose it in **Settings → Plugins → Linear → Live**, from an explore agent that reads the repository before the agent starts. The implement agent waits for the map. The explore agent uses provider usage. Buttons on the map reload it, build it again with the explore agent, or clear it. On the graph, a button follows the running agents and zooms to their files. You can also zoom with the buttons, the wheel, or a pinch, and lock the view so the page scrolls. Agents in worktrees of the same project show on the map and the graph. Explore and setup agents are told to only read. The plugin starts Claude in Always Ask and answers the permission requests these agents raise: it allows reads and search commands in the project folder and denies the rest. Codex has no read-only mode, so it runs in its default mode, and the plugin answers only the requests Codex raises.
+
+On agents not started from an issue, the Linear pill searches Linear and sends an issue to the agent.
+
+## Update Linear from todos
+
+Turn on **Update Linear from agent todos** in the Live settings. After each turn, a todo that starts with a sub-issue key, such as `ENG-124: add the queue`, moves that sub-issue to In Progress, and then to Done when all its todos are done. The parent moves to In Review when every sub-issue is done, never to Done. Statuses only move forward.
+
+## Set up project prompts
+
+In **Projects**, select **Start** under **Set up with an agent**. An agent reads the repository's guidelines, scripts, and CI files and proposes project instructions, steps, and prompt additions. You accept each change before it is saved.
+
+## Choose projects
+
+In **Projects**, **Use Linear in** turns Linear on or off for all projects, and each project has its own switch. In a project where Linear is off, its panels show that Linear is off, its agents get no Linear pill, and the agent setup page does not offer it. Todo sync and the explore agent skip it.
 
 ## Attach an issue
 
@@ -31,4 +49,4 @@ Choose **Attach Linear issue** in the composer attachment menu. The agent gets t
 
 ## Data and permissions
 
-Only the daemon sends requests to `https://api.linear.app/graphql`. The daemon never sends a key back to the app. Paseo sends the prompt, with the issue snapshot, to the agent provider. The daemon keeps recent Linear responses in memory for up to 24 hours, and the list shows them with **Showing saved results. Updating…** while it gets new data.
+Only the daemon sends requests to `https://api.linear.app/graphql`. The daemon never sends a key back to the app. Paseo sends the prompt, with the issue snapshot, to the agent provider. Explore and setup agents read project files and send them to your agent provider. The daemon saves explore maps, and agents that wait for a map, beside the key file, and Linear Live lists and reads files only inside the agent's folder. For Claude agents, the daemon also reads the subagent transcripts Claude saves for the session, to show what each subagent does. With agent guidance on, it writes Claude Code hooks with the issue keys and titles beside the key file, and it serves the Linear tools on 127.0.0.1 with a token for each agent. Each token reaches only its issue and that issue's sub-issues. With todo sync on, the daemon changes issue statuses in Linear. The daemon keeps recent Linear responses in memory for up to 24 hours, and the list shows them with **Showing saved results. Updating…** while it gets new data.

package/README.md

@@ -13,6 +13,11 @@ A Paseo plugin for Linear. It adds a Linear screen and a workspace panel where y
 - Use a different Linear key for a Paseo project.
 - See saved results at once while the plugin gets new data from Linear.
 - Attach a Linear issue to a message in the composer.
+- Follow an agent in **Linear Live**: sub-issues, todos, and a map of the files it reads and edits.
+- Open the issue from a **Linear** pill in each agent's composer, or send an issue to any agent.
+- Let agent todos move sub-issues to In Progress and Done. This is off until you turn it on.
+- Let an agent read a project's guidelines and propose its instructions and steps.
+- Turn Linear on or off for all projects, or project by project.
 
 ![Linear screen with an issue list grouped by status on the left and issue ENG-123 open on the right](docs/images/browse.png)
 
@@ -115,7 +120,15 @@ Select **Start agent** or **Start review** in the issue view. The agent setup pa
 
    The worktree and checkout options show only for a Git project. When agents run in worktrees (the default), a review uses the pull request, then the implementation workspace, then the issue branch.
 5. Set the options: **Include comments in the prompt**, **Move the issue to In Progress**, and **Assign the issue to me**. The last two show only for Implement, and only when they would change the issue.
-6. Select **Start agent** or **Start review**.
+6. Set the **Agent guidance** switches. Each one adds instructions to the prompt. The project keeps your choices for its next launch.
+   - **Keep Linear updated:** the agent edits the issue description as it works. It checks off each task list item it finishes and updates the plan when it changes. It posts no comments. Todos start with their issue key, so todo sync can move each sub-issue.
+   - **Subagents state their issue key:** each subagent's description and prompt start with the key of the issue it works on. The subagent states the key again when its work moves to another issue.
+   - **Hand off work to Paseo agents:** the agent starts one Paseo agent for each sub-issue instead of its built-in subagents. Each one runs in the same workspace on the same provider and model, with thinking that fits its task, and checks off its own items. Linear Live shows their work.
+
+   **Keep Linear updated** and **Hand off work to Paseo agents** give the agent the plugin's `linear` MCP server. It has four tools: `read_issue` and `edit_issue` for the issue and its sub-issues, and `start_agent` and `wait_agent` for agents on the sub-issues. Agents that `start_agent` starts get only `read_issue` and `edit_issue`. Paseo allows these tools without a permission prompt.
+
+   For Claude agents, these switches also add Claude Code hooks. With **Subagents state their issue key** on, each subagent gets the issue keys when it starts. With any switch on, the agent gets the issue again after Claude compacts the conversation. The hooks only print that text.
+7. Select **Start agent** or **Start review**.
 
 The plugin starts the agent and then updates Linear. If the Linear update fails, the agent keeps running and a message shows the error. The agent's timeline gets a card that links to the issue. The issue view lists the agents started from it under **Agents on this issue**.
 
@@ -125,11 +138,71 @@ Set the default model, where agents run, the default options, and the Implement
 
 In the composer, open the attachment menu and choose **Attach Linear issue**. Type an identifier such as `ENG-123`, or words from a title. An empty search lists the 20 most recently updated issues. The agent gets the issue text with your message. The plugin takes this snapshot when you select the issue.
 
+### Turn Linear on or off per project
+
+In **Settings → Plugins → Linear → Projects**, **Use Linear in** has an **All projects** switch and one switch per Paseo project. A project switch wins over **All projects**. A project without its own switch follows **All projects**. Save to apply.
+
+In a project where Linear is off:
+
+- The workspace **Linear** panel and **Linear Live** show that Linear is off.
+- Agents get no Linear pill.
+- The agent setup page does not offer the project.
+- Todo sync and the explore agent skip the project's agents.
+
+The **Linear** screen in the sidebar is not tied to a project, so it stays available. To turn off the whole plugin, use **Settings → Plugins**.
+
+### Linear Live
+
+Linear Live is an agent panel. Open it from the Linear pill, or with **Linear: Open Linear Live** in the command center while an agent is open. It works for agents started from an issue, with Claude, Codex, and other providers.
+
+- **Sub-issues:** each sub-issue shows its Linear status and the agent's todo progress. The todos of the current sub-issue show under it. Select a sub-issue to show only its files on the map. Hide the issues column with the button on the **Issue** card to give the map or the graph the full width. The column becomes a strip with the status of each issue. Select an issue there to show only its files.
+- **Map:** files are grouped by folder. The map marks the files the agent read, edited, or created, and the file it is on now. Files the agent touched but the map did not predict have a dashed border. A folder the agent listed or searched gets a solid border, and its header shows how many of its files the agent touched. Reads through the shell count too: `cat`, `sed -n`, `head`, `grep`, `rg`, `ls`, `find`, `git show`, and redirects to files.
+- **Graph:** the files and the links between them. A line joins two files when one imports the other, a Markdown or style file links to the other, `package.json` names it, or the text of one names the path of the other. This works for TypeScript and JavaScript (with `tsconfig` paths and workspace packages), Python, Go, Rust, Ruby, CSS and Sass, Markdown, HTML, and config files. Files of one folder sit together under the folder name and take the color of their sub-issue. The issue is in the center, with its sub-issues joined to the files the map gives them. The agent hovers over what it works on: the file it reads or edits, or the sub-issue whose todo it just started. When the work moves, it glides along the links to the next node, and the lines at that node take its color. New files join without moving the rest. Agents that this agent started get their own cursor when they work in the same folder or in a worktree of the same project. An agent with no file activity yet hovers over the sub-issue whose key starts its title. Running subagents circle the agent that started them. Select a sub-issue to show only its files. Select any node to see what it is and how many files it links to. Switch between **Map** and **Graph** on the card, or set the default in **Show files as** in the Live settings.
+- **Graph view:** the icon buttons at the top right of the graph move the view. **Follow the running agents** zooms to the nodes the running agents work on and the files next to them, and moves with the agents. **Show the whole graph** zooms out. **Zoom out** and **Zoom in** change the zoom in steps. Scroll to zoom at the pointer, drag to move when zoomed in, or pinch on a touch screen. Each of these stops following. The lock button lets the wheel and drags scroll the page instead. Nodes, lines, and labels keep their size when you zoom, and more file names show when there is room. The graph keeps your follow and lock choices.
+- **Agents:** the agents that work under this agent. Paseo agents that this agent started show their status, their files, and their own markers on the map when they work in the same folder or in a worktree of the same project. Select one to open it. Subagents that run inside the provider, such as Claude's Agent tool, show their type, description, and status. For Claude, the daemon reads each subagent's transcript, also for subagents that run in the background, so a subagent shows what it does now, gets its own cursor, and adds its files to the map. Other providers do not send subagent file reads, so the map shows only the files named in the subagent's prompt.
+- **Activity:** the latest reads, edits, searches, and commands, with line counts and exit codes.
+
+The map comes from one of two sources. Choose it in **Settings → Plugins → Linear → Live**:
+
+- **Ticket text** (the default) finds file and folder paths in the issue title, description, and sub-issue titles. It costs nothing, but it finds only paths the issue names. Linear sends sub-issue titles but not their descriptions.
+- **Explore agent** maps the files first when you start an implement agent. It reads the repository and lists the files for each sub-issue. The implement agent starts when the map is ready, or with the ticket-text map if exploring fails. A saved map is used again, so each issue is explored once. The plugin archives the explore agent when it finishes. Choose its model and effort in the Live settings. A faster, cheaper model, such as Haiku, is usually enough. It lists up to 150 files.
+
+The buttons on the map card control the saved map. **Read files and links again** reloads the map, the folder lists, and the links. **Build** or **Rebuild the map with the explore agent** starts an explore run now and replaces the saved map when it finishes. **Clear the saved map** deletes it, so the map uses the ticket text until the next explore run. You cannot clear a map while an explore run makes it.
+
+The daemon starts the waiting agent, so you can close the app while the map is made. If the plugin reloads or the daemon restarts during the run, the plugin finishes it when the explore agent's turn ends. A waiting agent that has not started after one hour is dropped.
+
+Explore and setup agents are told to only read. The plugin starts them in a mode that asks before tool use when the provider has one: **Always Ask** for Claude, never a bypass mode. When such an agent asks for permission, the plugin answers. It allows file reads inside the project folder and these commands: `ls`, `find`, `rg`, `grep`, `cat`, `head`, `tail`, `wc`, `git ls-files`, and `git grep`. It denies other commands, edits, web requests, redirection, and paths outside the folder. The plugin sees only the requests the provider raises: Claude runs some read commands without asking, and Codex has no read-only mode, so it runs in its default mode and its own sandbox decides what needs a request.
+
+For implement agents on an issue with sub-issues, the prompt asks the agent to start each todo with its sub-issue key, such as `ENG-124: add the queue`. That is how todos map to sub-issues.
+
+### Linear pill
+
+Each agent's composer has a **Linear** pill. On an agent started from an issue, the pill shows the issue key. It opens the issue status, each sub-issue with its todo progress, and buttons for Linear Live, the issue, and **Sync now**. On other agents, the pill searches Linear and sends the issue text to the agent as a message.
+
+### Update Linear from agent todos
+
+Turn on **Update Linear from agent todos** in the Live settings. After each turn of an implement agent, the daemon reads the agent's todos:
+
+- A sub-issue with a todo in progress or done moves to the team's first started status, such as In Progress.
+- A sub-issue whose todos are all done moves to the team's first completed status, such as Done.
+- The parent moves to In Progress when work starts. When every sub-issue is done, it moves to a started status whose name has "review", such as In Review. It never moves to Done by itself.
+- Statuses only move forward. Canceled issues and issues outside the parent and its sub-issues never change.
+
+The daemon reads the issue from Linear before each sync, so a status you changed by hand counts. **Sync now** in the pill runs the same check at once.
+
+### Set up project prompts with an agent
+
+In **Settings → Plugins → Linear → Projects**, select **Start** under **Set up with an agent**. An agent reads the project's AGENTS.md, CLAUDE.md, CONTRIBUTING, README, scripts, and CI files. It then proposes project instructions, steps, and text to add to the Implement and Review prompts. Each change shows the current and proposed text. Turn off the ones you do not want, select **Use accepted changes**, and then save. Nothing changes until you save.
+
 ## Data and permissions
 
 - **Your key stays on the daemon host.** When you save a key, the app sends it to the daemon once. The daemon never sends a key back to the app. The app gets only the last four characters, to show which key is in use. Only the daemon sends requests to `https://api.linear.app/graphql`.
 - **Data sent to Linear:** queries for issues, teams, users, and comments, and the changes you make. When you start an agent with the options on, the plugin moves the issue to In Progress and assigns it to you.
 - **Data sent to the agent provider:** the prompt. It holds the template text and an issue snapshot: identifier, title, URL, team, status, priority, assignee, project, labels, parent, description, sub-issues, and links. It holds comments only when **Include comments in the prompt** is on. It also holds the project instructions and steps from the Projects settings. An attached issue sends the identifier, title, URL, status, priority, assignee, project, labels, and description.
+- **Linear Live and setup agents:** the explore agent gets the issue snapshot without comments, and both agents read files in the project. Your agent provider gets what they read. The map of an explore run is saved in `live-maps.json` beside the key file, for up to 200 issues. An agent that waits for a map is saved in `pending-launches.json` there until it starts. Linear Live lists files only in the folders it shows, and reads the files on the graph to find their links, inside the agent's own folder. It does not follow links that lead outside that folder. For a Claude agent with subagents, the daemon reads the tool calls in the subagent transcripts that Claude saves for that session. It sends the app only the tool names, file paths, and commands, never file text.
+- **Linear tools for agents:** the daemon runs the `linear` MCP server on `127.0.0.1` only, and only after an agent gets it. Each agent gets its own random token, and its tools reach only its issue and that issue's sub-issues. Edits use the Linear key of the project that loaded the issue. Requests from a web page are refused. `agent-tools.json` beside the key file keeps the port and a hash of each token, so agents keep their tools after a restart. The token itself is in the agent's Paseo config.
+- **Claude hooks:** when an **Agent guidance** switch is on for a Claude agent, the daemon writes a Claude Code plugin to `claude-hooks/` beside the key file, one folder for each issue and set of hooks. It holds the issue key and title and the sub-issue keys and titles. The agent starts with `--plugin-dir` set to that folder. The hooks print that text and run no other command. The daemon does not write hooks on Windows hosts.
+- **Todo sync:** when it is on, the daemon changes issue statuses in Linear with the key of the project that loaded the issue.
 - **Cached results:** the daemon keeps up to 300 recent Linear responses in memory for up to 24 hours. It groups them by a hash of the key, so two keys never share results. The app shows saved results at once with **Showing saved results. Updating…** while it gets new data. An edit clears the cached lists and issues for that key. Saving or removing a key clears the whole cache. The cache is not written to disk, and a daemon restart clears it.
 
 Linear errors, such as a rejected key or a rate limit, show in the panel or as a message.
@@ -138,30 +211,43 @@ Linear errors, such as a rejected key or a rate limit, show in the panel or as a
 
 | File | Runtime | Role |
 | --- | --- | --- |
-| `index.client.tsx` | App | Registers the Linear screen, the workspace panel, the Account, Prompts, and Projects settings, the command center items, the `/linear` command, the timeline card, and the composer attachment |
-| `index.server.ts` | Daemon | Registers the settings and the RPC handlers |
+| `index.client.tsx` | App | Registers the Linear screen, the workspace panel, the Linear Live panel, the Account, Prompts, Live, and Projects settings, the command center items, the `/linear` command, the timeline card, the composer attachment, and the Linear pill |
+| `index.server.ts` | Daemon | Registers the settings, the RPC handlers, and the todo sync hook |
 | `client/browser.tsx` | App | Screen and panel: picks the key, then shows the list, the issue, or the agent setup page |
 | `client/issue-list.tsx`, `client/issue-row.tsx`, `client/issue-tree.ts` | App | Search, filters, sort, rows, status groups, and sub-issue nesting |
 | `client/issue-detail.tsx`, `client/issue-sections.tsx`, `client/breadcrumbs.tsx` | App | Issue view: properties, breadcrumbs, sub-issues, links, agents, and comments |
 | `client/issue-description.tsx`, `client/autosave.ts` | App | Description editor, task list checkboxes, and debounced saves |
 | `client/markdown.tsx` | App | Renders Markdown |
-| `client/launch.tsx`, `client/launch-fields.tsx`, `client/launch-choices.ts`, `client/launch-plan.ts`, `client/agent-options.ts` | App | Agent setup page, Run in options, and agent start |
+| `client/launch.tsx`, `client/launch-fields.tsx`, `client/launch-guidance.tsx`, `client/launch-choices.ts`, `client/launch-plan.ts`, `client/agent-options.ts` | App | Agent setup page, Run in options, agent guidance, and agent start |
 | `client/model-browser.tsx`, `client/provider-icon.tsx` | App | Model picker and provider icons |
 | `client/create-issue.tsx`, `client/pickers.tsx` | App | New issue form and option pickers |
 | `client/connect.tsx`, `client/settings-*.tsx` | App | Key form and settings screens |
 | `client/queries.ts`, `client/store.ts`, `client/key-scope.tsx` | App | Data hooks with saved results, browser state, and the key in use |
 | `client/compat.ts` | App | Registers the screen on Paseo 0.10 and on later releases |
 | `client/timeline-card.tsx`, `client/ui.tsx`, `client/glyphs.tsx` | App | Timeline card, shared controls, and icons |
+| `client/live-panel.tsx`, `client/live-header.tsx`, `client/live-issues.tsx`, `client/live-feed.tsx`, `client/live-timeline.ts` | App | Linear Live panel, header, sub-issues, activity, and the agent timeline feed |
+| `client/live-map.tsx`, `client/live-graph.tsx`, `client/graph-labels.ts`, `client/graph-camera.tsx`, `client/live-cursor.tsx`, `client/live-agents.tsx` | App | File map, file graph with its labels and camera, agent cursors, and the agents list |
+| `client/tool-buttons.tsx`, `client/web.ts` | App | Icon buttons for the map and graph, and the wheel listener on the web |
+| `client/pill.tsx` | App | Linear pill in each agent's composer |
+| `client/project-init.tsx` | App | Project setup proposal in the Projects settings |
 | `shared/linear.ts` | Both | RPC contracts and issue schemas |
 | `shared/issues.ts` | Both | The `issues.search` RPC and the composer attachment source |
 | `shared/settings.ts` | Both | Settings schema: templates, agent defaults, and project settings |
 | `shared/prompts.ts` | Both | Default templates and the issue snapshot |
 | `shared/markdown.ts` | Both | Markdown parser and task list toggle |
+| `shared/live.ts`, `shared/activity.ts`, `shared/subagents.ts` | Both | Linear Live contracts, the ticket text map, timeline activity, and subagent runs |
+| `shared/shell-lexer.ts`, `shared/shell-activity.ts` | Both | Shell command parsing for reads, edits, and searches |
+| `shared/map-model.ts`, `shared/graph-model.ts`, `shared/graph-geometry.ts`, `shared/graph-camera.ts`, `shared/links.ts` | Both | Map folders, the file graph with its layout and paths, label placement, camera math, and the parsers that find links in files |
+| `shared/agent-hooks.ts`, `server/agent-hooks.ts` | Both, Daemon | Claude Code hooks for agent guidance, and the plugin folder the daemon writes |
+| `shared/agent-tools.ts`, `server/agent-tools.ts`, `server/mcp-http.ts` | Both, Daemon | The `linear` MCP server: its tools, tokens, and HTTP transport |
+| `shared/todo-sync.ts`, `shared/project-setup.ts` | Both | Todo keys, status moves, and setup proposals |
 | `server/handlers.ts` | Daemon | RPC handlers, key lookup, and cache use |
 | `server/credentials.ts` | Daemon | Key file and key order |
 | `server/cache.ts` | Daemon | Response cache in memory |
 | `server/graphql.ts`, `server/queries.ts` | Daemon | Linear GraphQL client, queries, and changes |
 | `server/linear.ts` | Daemon | Search and snapshot text for the composer attachment |
+| `server/live.ts`, `server/links.ts`, `server/subagent-logs.ts`, `server/agent-runs.ts` | Daemon | File listing, links between files, subagent transcripts, explore runs, and the saved maps |
+| `server/sync.ts`, `server/init.ts` | Daemon | Todo sync after each turn, and project setup runs |
 
 The client bundle holds no credentials and makes no calls to Linear.
 
@@ -177,7 +263,7 @@ npm run check
 paseo plugin add "$PWD"
 ```
 
-After you edit the source, run `paseo plugin reload paseo-linear-plugin`. `npm run check` runs the typecheck and the tests. The tests cover the Linear client, the key file, the cache, the handlers, sub-issue nesting, the Markdown parser and task list toggle, the description autosave, the agent options, and the release scripts. They use a local GraphQL server and do not call Linear.
+After you edit the source, run `paseo plugin reload paseo-linear-plugin`. `npm run check` runs the typecheck and the tests. The tests cover the Linear client, the key file, the cache, the handlers, sub-issue nesting, the Markdown parser and task list toggle, the description autosave, the agent options, the prompt guidance and its hooks, the MCP server and its tools, the links between files in many languages, the graph layout and camera, and the release scripts. They use a local GraphQL server and do not call Linear.
 
 ## Graphics
 

package/client/access.tsx

@@ -0,0 +1,66 @@
+import { type PluginAgentPanelProps, useSettings, useWorkspace } from "@getpaseo/plugin/client";
+import { type ComponentType, type ReactNode, useEffect } from "react";
+import { linearSettings, type ProjectAccess, projectEnabled } from "../shared/settings";
+import { EmptyState, type Theme } from "./ui";
+
+// Composer pills live outside React, so components that read settings share the project
+// switches here, and the pill code listens for changes.
+let current: ProjectAccess | null = null;
+const listeners = new Set<(access: ProjectAccess) => void>();
+
+export function publishAccess(access: ProjectAccess): void {
+  if (current && JSON.stringify(current) === JSON.stringify(access)) return;
+  current = access;
+  for (const listener of listeners) listener(access);
+}
+
+export function currentAccess(): ProjectAccess | null {
+  return current;
+}
+
+export function onAccessChange(listener: (access: ProjectAccess) => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** Null while settings load or when the project is unknown, so callers can wait. */
+export function useProjectEnabled(projectId: string | null | undefined): boolean | null {
+  const settings = useSettings(linearSettings);
+  const access = settings.status === "ready" ? settings.values.access : null;
+  useEffect(() => {
+    if (access) publishAccess(access);
+  }, [access]);
+  if (!access || projectId === undefined) return null;
+  return projectEnabled(access, projectId);
+}
+
+export function ProjectGate(props: {
+  theme: Theme;
+  projectId: string | null | undefined;
+  children: ReactNode;
+}) {
+  const enabled = useProjectEnabled(props.projectId);
+  if (enabled !== false) return <>{props.children}</>;
+  return (
+    <EmptyState
+      theme={props.theme}
+      icon="SquareKanban"
+      title="Linear is off for this project"
+      detail="Turn it on in Linear settings, under Projects."
+    />
+  );
+}
+
+const selectProjectId = (workspace: { projectId: string }) => workspace.projectId;
+
+/** Wraps an agent panel so it shows the off state in projects where Linear is off. */
+export function gateAgentPanel(Panel: ComponentType<PluginAgentPanelProps>) {
+  return function GatedAgentPanel(props: PluginAgentPanelProps) {
+    const projectId = useWorkspace(props.workspaceId, selectProjectId);
+    return (
+      <ProjectGate theme={props.theme} projectId={projectId}>
+        <Panel {...props} />
+      </ProjectGate>
+    );
+  };
+}

package/client/browser.tsx

@@ -11,6 +11,7 @@ import { ConnectCard } from "./connect";
 import { CreateIssueModal } from "./create-issue";
 import { IssueDetailView } from "./issue-detail";
 import { IssueList } from "./issue-list";
+import { ProjectGate } from "./access";
 import { effectiveKeyScope, KeyScopeProvider } from "./key-scope";
 import { LaunchPage, type LaunchTarget } from "./launch";
 import { useAuthStatus, useCatalog, useProjects } from "./queries";
@@ -262,14 +263,16 @@ export function LinearPanel({ theme, layout, navigation, workspaceId }: PluginWo
     if (teamId) update({ teamId, assignee: "anyone" });
   }, [settings, projectId, update]);
   return (
-    <IssueBrowser
-      theme={theme}
-      compact={layout.compact}
-      navigation={navigation}
-      scope={scope}
-      target={target}
-      keyProjectId={projectId ?? null}
-      canSwitchKey={false}
-    />
+    <ProjectGate theme={theme} projectId={projectId}>
+      <IssueBrowser
+        theme={theme}
+        compact={layout.compact}
+        navigation={navigation}
+        scope={scope}
+        target={target}
+        keyProjectId={projectId ?? null}
+        canSwitchKey={false}
+      />
+    </ProjectGate>
   );
 }

package/client/graph-camera.tsx

@@ -0,0 +1,219 @@
+import { type RefObject, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Animated, Easing, type GestureResponderHandlers, PanResponder, View } from "react-native";
+import { type Box, type Camera, clampCamera, FIT, frameBox, MAX_ZOOM, MIN_ZOOM, zoomAt } from "../shared/graph-camera";
+import { NATIVE_DRIVER } from "./live-timeline";
+import { ToolButton, ToolGroup } from "./tool-buttons";
+import type { Theme } from "./ui";
+import { listenWheel } from "./web";
+
+// Animated values move the graph canvas, so a wheel or a drag never renders the graph again.
+// Nodes, edges, and cursors scale by the inverse zoom, so they keep their size on screen.
+
+export interface CameraOptions {
+  width: number;
+  height: number;
+  /** Where auto mode looks; null shows the whole graph. */
+  focus: Box | null;
+  auto: boolean;
+  /** Wheel and drag move the page, not the camera. */
+  locked: boolean;
+  reduce: boolean;
+  /** The user moved the camera, so auto mode stops. */
+  onManual(): void;
+}
+
+type ZoomLimit = "min" | "max" | null;
+
+export interface CameraControl {
+  ref: RefObject<View | null>;
+  handlers: GestureResponderHandlers;
+  transform: [{ translateX: Animated.Value }, { translateY: Animated.Value }, { scale: Animated.Value }];
+  /** One over the zoom: the scale that keeps a canvas item its own size on screen. */
+  inverse: Animated.AnimatedInterpolation<number>;
+  limit: ZoomLimit;
+  /** The camera once it stops moving; labels are placed for it. */
+  settled: Camera;
+  zoomBy(factor: number): void;
+  fit(): void;
+}
+
+const ZOOM_STEP = 1.5;
+const DRAG_START = 6;
+const SETTLE_MS = 160;
+
+type Touch = { pageX: number; pageY: number };
+const spreadOf = (touches: readonly Touch[]) => {
+  const [a, b] = touches;
+  return a && b ? Math.hypot(a.pageX - b.pageX, a.pageY - b.pageY) : null;
+};
+
+export function useGraphCamera(options: CameraOptions): CameraControl {
+  const [values] = useState(() => ({ x: new Animated.Value(0), y: new Animated.Value(0), zoom: new Animated.Value(1) }));
+  const [inverse] = useState(() => Animated.divide<number>(new Animated.Value(1), values.zoom));
+  const [limit, setLimit] = useState<ZoomLimit>("min");
+  const [settled, setSettled] = useState<Camera>(FIT);
+  const pause = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const camera = useRef<Camera>(FIT);
+  const ref = useRef<View>(null);
+  const latest = useRef(options);
+  latest.current = options;
+
+  const apply = useCallback(
+    (next: Camera, animate: boolean) => {
+      const { width, height, reduce } = latest.current;
+      const target = clampCamera(next, width, height);
+      camera.current = target;
+      setLimit(target.zoom <= MIN_ZOOM ? "min" : target.zoom >= MAX_ZOOM ? "max" : null);
+      for (const value of [values.x, values.y, values.zoom]) value.stopAnimation();
+      if (pause.current) clearTimeout(pause.current);
+      if (!animate || reduce) {
+        values.x.setValue(target.x);
+        values.y.setValue(target.y);
+        values.zoom.setValue(target.zoom);
+        pause.current = setTimeout(() => setSettled(target), SETTLE_MS);
+        return;
+      }
+      const glide = (value: Animated.Value, toValue: number) =>
+        Animated.timing(value, { toValue, duration: 450, easing: Easing.inOut(Easing.cubic), useNativeDriver: NATIVE_DRIVER });
+      Animated.parallel([glide(values.x, target.x), glide(values.y, target.y), glide(values.zoom, target.zoom)]).start(
+        ({ finished }) => {
+          if (finished) setSettled(target);
+        },
+      );
+    },
+    [values],
+  );
+  const move = useCallback(
+    (next: Camera, animate: boolean) => {
+      if (latest.current.auto) latest.current.onManual();
+      apply(next, animate);
+    },
+    [apply],
+  );
+
+  useEffect(
+    () => () => {
+      if (pause.current) clearTimeout(pause.current);
+    },
+    [],
+  );
+
+  const { width, height, auto, locked, focus } = options;
+  const focusKey = focus ? [focus.left, focus.top, focus.right, focus.bottom].map(Math.round).join(",") : "";
+  useEffect(() => {
+    if (width === 0 || !auto) return;
+    const box = latest.current.focus;
+    apply(box ? frameBox(box, width, height) : FIT, true);
+  }, [auto, focusKey, width, height, apply]);
+  useEffect(() => {
+    if (width > 0 && !latest.current.auto) apply(camera.current, false);
+  }, [width, height, apply]);
+
+  useEffect(() => {
+    if (locked) return;
+    return listenWheel(ref.current, (point, factor) => {
+      const size = latest.current;
+      move(zoomAt(camera.current, point, factor, size.width, size.height), false);
+    });
+  }, [locked, move]);
+
+  // A drag pans once zoomed in; at full view it scrolls the page. Two fingers pinch to zoom.
+  const handlers = useMemo(() => {
+    let start = FIT;
+    let origin = { x: 0, y: 0 };
+    let fingers = 0;
+    let spread: number | null = null;
+    let lead = { x: 0, y: 0 };
+    const follow = (touches: readonly Touch[], gesture: { dx: number; dy: number }) => {
+      if (Math.min(2, touches.length) !== fingers) {
+        fingers = Math.min(2, touches.length);
+        start = camera.current;
+        origin = { x: gesture.dx, y: gesture.dy };
+        spread = spreadOf(touches);
+      }
+      const { width: w, height: h } = latest.current;
+      const now = spreadOf(touches);
+      const base = now && spread ? zoomAt(start, { x: w / 2, y: h / 2 }, now / spread, w, h) : start;
+      move({ ...base, x: base.x + gesture.dx - origin.x, y: base.y + gesture.dy - origin.y }, false);
+    };
+    return PanResponder.create({
+      onMoveShouldSetPanResponder: (_event, gesture) => {
+        if (latest.current.locked) return false;
+        lead = { x: gesture.dx, y: gesture.dy };
+        if (gesture.numberActiveTouches >= 2) return true;
+        return camera.current.zoom > MIN_ZOOM && Math.hypot(gesture.dx, gesture.dy) > DRAG_START;
+      },
+      // The grant restarts dx at zero, so the move before it is added back.
+      onPanResponderGrant: (event) => {
+        const touches = event.nativeEvent.touches;
+        fingers = Math.min(2, touches.length);
+        start = camera.current;
+        origin = { x: -lead.x, y: -lead.y };
+        spread = spreadOf(touches);
+      },
+      onPanResponderMove: (event, gesture) => follow(event.nativeEvent.touches, gesture),
+      onPanResponderTerminationRequest: () => false,
+    }).panHandlers;
+  }, [move]);
+
+  const transform = useMemo(
+    (): CameraControl["transform"] => [{ translateX: values.x }, { translateY: values.y }, { scale: values.zoom }],
+    [values],
+  );
+  const zoomBy = useCallback(
+    (factor: number) => {
+      const size = latest.current;
+      move(zoomAt(camera.current, { x: size.width / 2, y: size.height / 2 }, factor, size.width, size.height), true);
+    },
+    [move],
+  );
+  const fit = useCallback(() => move(FIT, true), [move]);
+  return { ref, handlers, transform, inverse, limit, settled, zoomBy, fit };
+}
+
+export function CameraButtons(props: {
+  theme: Theme;
+  camera: CameraControl;
+  auto: boolean;
+  locked: boolean;
+  onAuto(): void;
+  onLock(): void;
+}) {
+  const { theme, camera, auto, locked } = props;
+  const style = useMemo(() => ({ position: "absolute", top: 8, right: 8 }) as const, []);
+  return (
+    <View style={style}>
+      <ToolGroup theme={theme}>
+        <ToolButton
+          theme={theme}
+          icon="LocateFixed"
+          label={auto ? "Stop following the running agents" : "Follow the running agents"}
+          active={auto}
+          onPress={props.onAuto}
+        />
+        <ToolButton theme={theme} icon="Maximize" label="Show the whole graph" onPress={camera.fit} />
+        <ToolButton
+          theme={theme}
+          icon="Minus"
+          label="Zoom out"
+          disabled={camera.limit === "min"}
+          onPress={() => camera.zoomBy(1 / ZOOM_STEP)}
+        />
+        <ToolButton
+          theme={theme}
+          icon="Plus"
+          label="Zoom in"
+          disabled={camera.limit === "max"}
+          onPress={() => camera.zoomBy(ZOOM_STEP)}
+        />
+        <ToolButton
+          theme={theme}
+          icon={locked ? "Lock" : "LockOpen"}
+          label={locked ? "Let the wheel and drags move the graph" : "Let the wheel and drags scroll the page"}
+          active={locked}
+          onPress={props.onLock}
+        />
+      </ToolGroup>
+    </View>
+  );
+}