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

package/OVERVIEW.md

@@ -25,10 +25,28 @@ Select **Start agent** or **Start review** on an issue. The setup page shows the
 
 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. 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
 
 Choose **Attach Linear issue** in the composer attachment menu. The agent gets the issue text with your message. This uses the default key.
 
 ## 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. 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)
 
@@ -125,11 +130,66 @@ 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. 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.
+- **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. Select one to open it. Subagents that run inside the provider, such as Claude's Agent tool, show their type, description, and status. The provider does not send their file reads, so the map shows only the files named in a subagent's prompt, and only if the panel was open when it started.
+- **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 in the Live settings. A faster, cheaper model is usually enough.
+
+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.
+- **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,8 +198,8 @@ 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 |
@@ -152,16 +212,26 @@ Linear errors, such as a rejected key or a rate limit, show in the panel or as a
 | `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/live-cursor.tsx`, `client/live-agents.tsx` | App | File map, file graph and its labels, agent cursors, and the agents list |
+| `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/links.ts` | Both | Map folders, the file graph with its layout and paths, label placement, and the parsers that find links in files |
+| `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/agent-runs.ts` | Daemon | File listing, links between files, 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 +247,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 links between files in many languages, the graph layout, 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-labels.ts

@@ -0,0 +1,137 @@
+import { type LabelRequest, labelBox, labelSides, type Placed, type Point, placeLabels } from "../shared/graph-geometry";
+import { folderCenters, type Graph, type GraphNode } from "../shared/graph-model";
+import type { IssueDetail } from "../shared/linear";
+import { todoStatus } from "../shared/todo-sync";
+import type { IssueProgress } from "./live-issues";
+
+// Which labels the graph shows and where: issues first, then folder names, then the files the
+// agent works on, then touched files. A label that fits nowhere is hidden.
+
+const SIZES = { issue: 46, subissue: 32 } as const;
+export const HOVER_GAP = 22;
+
+/** About how wide a cursor caption draws. */
+export const captionWidth = (text: string | null) => (text ? Math.min(190, text.length * 6.2 + 18) : 0);
+const MAX_LABEL = 170;
+
+export function nodeSize(node: GraphNode): number {
+  if (node.kind !== "file") return SIZES[node.kind];
+  const touched = node.tile && node.tile.touch !== "none";
+  return touched ? (node.tile?.touch === "read" ? 12 : 14) : 9;
+}
+
+function clip(text: string, max: number): string {
+  return text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;
+}
+
+export interface Label {
+  left: number;
+  top: number;
+  width: number;
+  lines: readonly [string, string | null];
+}
+
+export interface FolderLabel {
+  folder: string;
+  left: number;
+  top: number;
+  width: number;
+}
+
+export interface LabelInput {
+  graph: Graph;
+  positions: ReadonlyMap<string, Placed>;
+  issue: IssueDetail;
+  progress: IssueProgress;
+  selected: string | null;
+  /** Nodes a running agent works on. */
+  working: ReadonlySet<string>;
+  /** Where each agent hovers, with the width of its caption and the side it shows on. */
+  cursors: readonly { at: Point; caption: number; flip: boolean }[];
+  width: number;
+  height: number;
+}
+
+function linesOf(node: GraphNode, input: LabelInput): readonly [string, string | null] {
+  if (node.kind === "issue") return [node.label, clip(input.issue.title, 34)];
+  if (node.kind === "file") return [node.label, null];
+  const child = input.issue.children.find((entry) => entry.identifier.toUpperCase() === node.label);
+  const todos = input.progress.groups.get(node.label) ?? [];
+  const done = todos.filter((todo) => todoStatus(todo) === "completed").length;
+  const counts = todos.length > 0 ? `  ${done}/${todos.length}` : "";
+  const folded = node.folded > 0 ? `  +${node.folded}` : "";
+  return [`${node.label}${counts}${folded}`, clip(child?.title ?? "", 26)];
+}
+
+const textWidth = (text: string, perChar: number) => Math.min(MAX_LABEL, text.length * perChar + 4);
+
+export function graphLabels(input: LabelInput): { nodes: Map<string, Label>; folders: FolderLabel[] } {
+  const { graph, positions, selected, working } = input;
+  const order = (node: GraphNode) =>
+    node.id === selected ? 0 : node.kind === "issue" ? 1 : node.kind === "subissue" ? 2 : working.has(node.id) ? 4 : 5;
+  const wanted = graph.nodes
+    .filter((node) => node.kind !== "file" || node.id === selected || working.has(node.id) || (node.tile?.touch ?? "none") !== "none")
+    .sort((a, b) => order(a) - order(b));
+  const lines = new Map<string, readonly [string, string | null]>();
+  const requests: LabelRequest[] = [];
+  const push = (node: GraphNode) => {
+    const at = positions.get(node.id);
+    if (!at) return;
+    const text = linesOf(node, input);
+    const perChar = node.kind === "issue" ? 7.4 : 6.2;
+    const width = Math.max(textWidth(text[0], perChar), text[1] ? textWidth(text[1], 5.6) : 0);
+    const height = text[1] ? 28 : 14;
+    const spotsFor = (w: number, h: number) =>
+      labelSides(at.side).map((side) => labelBox({ ...at, side }, nodeSize(node) / 2, w, h));
+    const short = textWidth(text[0], perChar);
+    lines.set(node.id, text);
+    requests.push({
+      id: node.id,
+      width,
+      height,
+      spots: spotsFor(width, height),
+      fallback: text[1] ? { width: short, height: 14, spots: spotsFor(short, 14) } : undefined,
+    });
+  };
+  for (const node of wanted.filter((entry) => order(entry) <= 2)) push(node);
+  // Folder names sit above each neighborhood, after the issues and before single files.
+  const folderIds = new Map<string, string>();
+  for (const center of folderCenters(graph, positions)) {
+    const name = center.folder === "." ? "/" : `${center.folder}/`;
+    const width = textWidth(name, 6);
+    const id = `folder:${center.folder}`;
+    folderIds.set(id, center.folder);
+    requests.push({ id, width, height: 14, spots: [{ left: center.x - width / 2, top: center.top - 30 }, { left: center.x - width / 2, top: center.y - 7 }] });
+  }
+  for (const node of wanted.filter((entry) => order(entry) > 2)) push(node);
+  const shapes: { at: Point; radius: number }[] = graph.nodes.flatMap((node) => {
+    const at = positions.get(node.id);
+    return at ? [{ at, radius: nodeSize(node) / 2 }] : [];
+  });
+  // Keep labels out from under the agents and their captions, as a row of small circles.
+  for (const cursor of input.cursors) {
+    shapes.push({ at: cursor.at, radius: 16 });
+    for (let offset = 24; offset < cursor.caption + 24; offset += 14) {
+      shapes.push({ at: { x: cursor.at.x + (cursor.flip ? -offset : offset), y: cursor.at.y }, radius: 10 });
+    }
+  }
+  const sizes = new Map(requests.map((request) => [request.id, request]));
+  const nodes = new Map<string, Label>();
+  const folders: FolderLabel[] = [];
+  for (const [id, box] of placeLabels(requests, input.width, input.height, shapes)) {
+    const request = sizes.get(id) as LabelRequest;
+    const folder = folderIds.get(id);
+    if (folder !== undefined) {
+      folders.push({ folder, left: box.left, top: box.top, width: request.width });
+      continue;
+    }
+    const text = lines.get(id) ?? ["", null];
+    nodes.set(id, {
+      left: box.left,
+      top: box.top,
+      width: (box.short ? request.fallback?.width : request.width) ?? 0,
+      lines: box.short ? [text[0], null] : text,
+    });
+  }
+  return { nodes, folders };
+}

package/client/launch-choices.ts

@@ -2,7 +2,7 @@ import { usePaseo } from "@getpaseo/plugin/client";
 import { useQuery } from "@tanstack/react-query";
 import { useCallback, useMemo, useState } from "react";
 import type { IssueDetail } from "../shared/linear";
-import type { AgentAction, LinearSettings } from "../shared/settings";
+import { type AgentAction, type LinearSettings, projectEnabled } from "../shared/settings";
 import { type AgentPicks, resolveAgent } from "./agent-options";
 import { loadAgentPreferences } from "./agent-preferences";
 import {
@@ -41,7 +41,15 @@ export function useLaunchChoices(input: {
   target: TargetWorkspace | null;
 }) {
   const { issue, settings, action } = input;
-  const projects = useProjects();
+  const allProjects = useProjects();
+  // Projects where Linear is off are not offered as launch targets.
+  const projects = useMemo(
+    () => ({
+      ...allProjects,
+      data: allProjects.data?.filter((entry) => projectEnabled(settings.access, entry.projectId)),
+    }),
+    [allProjects, settings.access],
+  );
   const providers = useProviders();
   const { target } = input;
   const prNumber = action === "review" ? pullRequestNumber(issue) : null;
@@ -54,10 +62,13 @@ export function useLaunchChoices(input: {
   const [placementChoice, setPlacementChoice] = useState<Placement | null>(null);
   const [picks, setPicks] = useState<AgentPicks>(NO_PICKS);
   const [remembered] = useState(loadAgentPreferences);
-  const projectId =
+  const preferredId =
     projectChoice ??
     defaultProjectId({ target, teamId: issue.team.id, settings, projects: projects.data });
-  const project = projects.data?.find((entry) => entry.projectId === projectId) ?? null;
+  const project =
+    projects.data?.find((entry) => entry.projectId === preferredId) ??
+    (projectChoice ? null : (projects.data?.[0] ?? null));
+  const projectId = project?.projectId ?? preferredId;
   const placements = useMemo(
     () =>
       placementOptions({

package/client/launch-plan.ts

@@ -7,6 +7,7 @@ import {
   updateIssueRpc,
   type WorkflowState,
 } from "../shared/linear";
+import { launchAfterExploreRpc } from "../shared/live";
 import { AGENT_LABELS, agentTitle } from "../shared/prompts";
 import type { AgentAction, Isolation, LinearSettings } from "../shared/settings";
 import { type AgentSelection, agentConfig } from "./agent-options";
@@ -141,6 +142,8 @@ export interface LaunchRequest {
   started: WorkflowState | null;
   /** The Paseo project whose Linear key loaded the issue. */
   keyScope: string | null;
+  /** Maps the files with the read-only explore agent first, then starts the agent. */
+  explore: boolean;
 }
 
 export type Paseo = ReturnType<typeof usePaseo>;
@@ -213,16 +216,45 @@ export function useLaunchAgent() {
   const paseo = usePaseo();
   const updateIssue = useRpc(updateIssueRpc);
   const attachCard = useRpc(attachIssueCardRpc);
+  const launchAfterExplore = useRpc(launchAfterExploreRpc);
   return useMutation({
     mutationFn: async (request: LaunchRequest) => {
       const { issue, action } = request;
       const workspace = await openWorkspace(paseo, request);
-      const agent = await workspace.agents.create({
+      const state = request.patch.stateId && request.started ? request.started : issue.state;
+      const card = {
+        identifier: issue.identifier,
+        title: issue.title,
+        url: issue.url,
+        stateName: state.name,
+        stateColor: state.color,
+        action,
+      };
+      const agent = {
         config: agentConfig(request.agent),
         title: agentTitle(action, issue),
         prompt: request.prompt,
-        labels: { [AGENT_LABELS.issue]: issue.identifier, [AGENT_LABELS.action]: action },
-      });
+        labels: {
+          [AGENT_LABELS.issue]: issue.identifier,
+          [AGENT_LABELS.action]: action,
+          ...(request.keyScope ? { [AGENT_LABELS.project]: request.keyScope } : {}),
+        },
+      };
+      // The daemon starts the agent once the map is ready, so agentId is null until then.
+      let agentId: string | null;
+      if (request.explore && action === "implement") {
+        const launched = await launchAfterExplore({
+          workspaceId: workspace.id,
+          identifier: issue.identifier,
+          keyScope: request.keyScope,
+          agent,
+          card,
+        });
+        agentId = launched.agentId;
+      } else {
+        agentId = (await workspace.agents.create(agent)).id;
+        void attachCard({ agentId, card }).catch(() => undefined);
+      }
       lastProjectByTeam.set(issue.team.id, request.project.projectId);
       rememberLaunch({
         agent: request.agent.agent.id,
@@ -238,17 +270,7 @@ export function useLaunchAgent() {
           warning = errorMessage(error);
         }
       }
-      const state = request.patch.stateId && request.started ? request.started : issue.state;
-      const card = {
-        identifier: issue.identifier,
-        title: issue.title,
-        url: issue.url,
-        stateName: state.name,
-        stateColor: state.color,
-        action,
-      };
-      void attachCard({ agentId: agent.id, card }).catch(() => undefined);
-      return { agentId: agent.id, warning };
+      return { agentId, workspaceId: workspace.id, warning };
     },
   });
 }

package/client/launch.tsx

@@ -271,15 +271,20 @@ function LaunchComposer(props: LaunchPageProps & { issue: IssueDetail; settings:
         patch,
         started,
         keyScope,
+        explore: settings.live.enabled && settings.live.mapping === "explore",
       },
       {
-        onSuccess: ({ agentId, warning }) => {
+        onSuccess: ({ agentId, workspaceId, warning }) => {
           void queries.invalidateQueries({ queryKey: ["linear"] });
+          const started = agentId
+            ? "Agent started."
+            : "Mapping files first. The agent starts when the map is ready.";
           if (warning) {
-            toast.show(`Agent started. Linear was not updated: ${warning}`, { variant: "warning" });
-          } else toast.show("Agent started", { variant: "success" });
+            toast.show(`${started} Linear was not updated: ${warning}`, { variant: "warning" });
+          } else toast.show(started, { variant: "success" });
           onStarted();
-          navigation?.openAgent({ agentId });
+          if (agentId) navigation?.openAgent({ agentId });
+          else navigation?.openWorkspace({ workspaceId });
         },
       },
     );