@yannelli/paseo-linear-plugin 1.0.0 → 1.1.0-alpha.0

package/server/live.ts

@@ -0,0 +1,371 @@
+import { readdir, realpath } from "node:fs/promises";
+import path from "node:path";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { z } from "zod";
+import { relativePath } from "../shared/activity";
+import { knowledgeLines, liveProjectRpc, type ProjectKnowledge, resolvePaths, toAreaRef } from "../shared/knowledge";
+import { type IssueDetail, ISSUE_CARD_KIND } from "../shared/linear";
+import {
+  ExploreResultSchema,
+  exploreRpc,
+  type IssueMap,
+  type Job,
+  type LaunchInput,
+  launchAfterExploreRpc,
+  clearMapRpc,
+  listFilesRpc,
+  subagentLogsRpc,
+  liveMapRpc,
+  MAX_DIR_ENTRIES,
+  MAX_EXPLORE_FILES,
+} from "../shared/live";
+import { AGENT_LABELS, issueSnapshot } from "../shared/prompts";
+import { type LinearSettings, projectEnabled } from "../shared/settings";
+import {
+  createJobStore,
+  finishInternalRun,
+  type Paseo,
+  READ_ONLY_RULES,
+  startInternalRun,
+} from "./agent-runs";
+import type { LinearAccess } from "./handlers";
+import { type KnowledgeService, knowledgeFor } from "./knowledge";
+import { subagentLogs } from "./subagent-logs";
+import type { LaunchQueue, MapStore } from "./stores";
+
+const EXPLORE_TIMEOUT_MS = 20 * 60_000;
+const RECOVER_INTERVAL_MS = 30_000;
+const EXPLORE_TITLE = /^Explore ([A-Za-z][A-Za-z0-9]*-\d+)$/;
+const SKIPPED_ENTRIES = new Set([".git", "node_modules", ".DS_Store"]);
+
+export interface AgentInfo {
+  id: string;
+  cwd: string;
+  workspaceId: string | null;
+  /** Paseo project of the agent's workspace, when the workspace is known. */
+  projectId: string | null;
+  provider: string;
+  /** The provider's session, such as Claude's session id. */
+  sessionId: string | null;
+  labels: Record<string, string>;
+}
+
+export async function agentInfo(paseo: Paseo, agentId: string): Promise<AgentInfo> {
+  const handle = paseo.agents.ref(agentId);
+  await handle.refresh();
+  const agent = handle.current();
+  if (!agent) throw new Error("The agent was not found");
+  const workspaceId = agent.workspaceId ?? null;
+  const workspace = workspaceId
+    ? await paseo.workspaces
+        .ref(workspaceId)
+        .refresh()
+        .catch(() => null)
+    : null;
+  return {
+    id: agent.id,
+    cwd: agent.cwd,
+    workspaceId,
+    projectId: workspace?.projectId ?? null,
+    provider: agent.provider,
+    sessionId: agent.runtimeInfo?.sessionId ?? null,
+    labels: agent.labels ?? {},
+  };
+}
+
+// The client names directories, never a root: the root is the agent's own folder, and a
+// directory that resolves outside it, through ".." or a symlink, is skipped.
+export async function listDirectories(cwd: string, dirs: readonly string[]) {
+  const root = await realpath(cwd);
+  const results: { dir: string; files: string[]; truncated: boolean }[] = [];
+  for (const dir of new Set(dirs)) {
+    const relative = dir === "" ? "" : relativePath(dir, root);
+    if (relative === null) continue;
+    const resolved = await realpath(path.resolve(root, relative)).catch(() => null);
+    if (!resolved || (resolved !== root && !resolved.startsWith(`${root}${path.sep}`))) continue;
+    const entries = await readdir(resolved, { withFileTypes: true }).catch(() => []);
+    const files = entries
+      .filter((entry) => entry.isFile() && !SKIPPED_ENTRIES.has(entry.name))
+      .map((entry) => entry.name)
+      .sort((a, b) => a.localeCompare(b));
+    results.push({
+      dir,
+      files: files.slice(0, MAX_DIR_ENTRIES),
+      truncated: files.length > MAX_DIR_ENTRIES,
+    });
+  }
+  return results;
+}
+
+export function explorePrompt(issue: IssueDetail, knowledge: ProjectKnowledge | null = null): string {
+  const keys = [issue.identifier, ...issue.children.map((child) => child.identifier)];
+  const map = knowledgeLines(knowledge);
+  return [
+    `Map this repository for Linear issue ${issue.identifier}: ${issue.title}`,
+    "",
+    ...READ_ONLY_RULES,
+    "",
+    issueSnapshot(issue, { includeComments: false }),
+    "",
+    ...(map.length > 0 ? [...map, ""] : []),
+    "List the files an engineer will most likely read or change for this issue and each sub-issue.",
+    `Include files that will probably be created, at their expected path. List at most ${MAX_EXPLORE_FILES} files.`,
+    `Set "issue" to the sub-issue key the file belongs to, or ${issue.identifier} for the whole issue.`,
+    `Valid keys: ${keys.join(", ")}.`,
+    "Reply with only a JSON object in a ```json block, with repo-relative paths:",
+    `{"files":[{"path":"src/example.ts","issue":"${keys[1] ?? keys[0]}"}]}`,
+  ].join("\n");
+}
+
+export function toIssueMap(
+  issue: IssueDetail,
+  cwd: string,
+  result: z.infer<typeof ExploreResultSchema>,
+  now = new Date(),
+): IssueMap {
+  const keys = new Set([issue.identifier, ...issue.children.map((child) => child.identifier)]);
+  const seen = new Set<string>();
+  const files: IssueMap["files"] = [];
+  for (const entry of result.files) {
+    const filePath = relativePath(entry.path, cwd);
+    if (!filePath || seen.has(filePath)) continue;
+    seen.add(filePath);
+    const key = entry.issue.trim().toUpperCase();
+    files.push({ path: filePath, issue: keys.has(key) ? key : issue.identifier });
+  }
+  return { identifier: issue.identifier, source: "explore", files, createdAt: now.toISOString() };
+}
+
+export interface LiveDependencies {
+  access: LinearAccess;
+  maps: MapStore;
+  launches: LaunchQueue;
+  knowledge: KnowledgeService;
+  readSettings(): Promise<LinearSettings | null>;
+}
+
+type WorkspaceHandle = Awaited<ReturnType<Paseo["workspaces"]["open"]>>;
+
+/** Starts the implementing agent and attaches the issue card to its timeline. */
+export async function startLaunch(workspace: WorkspaceHandle, launch: LaunchInput) {
+  const agent = await workspace.agents.create(launch.agent);
+  await agent.timeline
+    .append({
+      type: "plugin",
+      id: `linear-issue-${launch.card.identifier}`,
+      kind: ISSUE_CARD_KIND,
+      version: 1,
+      data: launch.card,
+    })
+    .catch((error: unknown) => console.error("Linear issue card was not attached", error));
+  return agent.id;
+}
+
+export function registerLive(server: PluginServerContext, dependencies: LiveDependencies) {
+  const { access, maps, launches, knowledge, readSettings } = dependencies;
+  const jobs = createJobStore<IssueMap>();
+  const recovering = new Map<string, Promise<Job | null>>();
+  const recoveredAt = new Map<string, number>();
+
+  // Called whenever an explore run ends, by any path. Claiming first means a launch that two
+  // paths see still starts one agent.
+  async function startWaiting(paseo: Paseo, identifier: string) {
+    for (const launch of await launches.claim(identifier)) {
+      await startLaunch(paseo.workspaces.ref(launch.workspaceId), launch).catch((error: unknown) =>
+        console.error(`Linear agent for ${identifier} did not start after exploring`, error),
+      );
+    }
+  }
+
+  function track(paseo: Paseo, job: Job) {
+    void jobs.wait(job.id).then(() => startWaiting(paseo, job.id));
+    return job;
+  }
+
+  function saveMap(issue: IssueDetail, cwd: string) {
+    return async (value: z.infer<typeof ExploreResultSchema>) => {
+      const map = toIssueMap(issue, cwd, value);
+      await maps.set(map);
+      return map;
+    };
+  }
+
+  // A plugin reload or daemon restart drops the job but not the explore agent. Finds that
+  // agent by its label and finishes the run, or starts waiting launches when there is none.
+  async function adopt(paseo: Paseo, identifier: string): Promise<Job | null> {
+    const { entries } = await paseo.agents.list({
+      filter: { labels: { [AGENT_LABELS.explore]: identifier } },
+      page: { limit: 10 },
+    });
+    const orphan = entries.map((entry) => entry.agent).find((agent) => !agent.archivedAt);
+    if (!orphan) {
+      await startWaiting(paseo, identifier);
+      return null;
+    }
+    const job = await jobs.start(identifier, async () => {
+      const { linear } = await access.connect(orphan.labels?.[AGENT_LABELS.project] ?? null);
+      const issue = await linear.getIssue(identifier);
+      const handle = paseo.agents.ref(orphan.id);
+      const result = finishInternalRun(handle, orphan.cwd, ExploreResultSchema, EXPLORE_TIMEOUT_MS);
+      return { agentId: orphan.id, result: result.then(saveMap(issue, orphan.cwd)) };
+    });
+    return track(paseo, job);
+  }
+
+  function recover(paseo: Paseo, identifier: string): Promise<Job | null> {
+    const existing = jobs.get(identifier)?.job;
+    if (existing?.status === "running") return Promise.resolve(existing);
+    const inFlight = recovering.get(identifier);
+    if (inFlight) return inFlight;
+    recoveredAt.set(identifier, Date.now());
+    const run = adopt(paseo, identifier).finally(() => recovering.delete(identifier));
+    recovering.set(identifier, run);
+    return run;
+  }
+
+  server.handle(listFilesRpc, async ({ agentId, dirs }, { paseo }) => {
+    const agent = await agentInfo(paseo, agentId);
+    return { dirs: await listDirectories(agent.cwd, dirs) };
+  });
+
+  server.handle(liveProjectRpc, async ({ agentId, paths }, { paseo }) => {
+    const agent = await agentInfo(paseo, agentId);
+    const known = await knowledgeFor(paseo, knowledge, agent.projectId);
+    if (!known) return { areas: [], resolved: [] };
+    const resolved = [...resolvePaths(paths, known.files)].map(([from, to]) => ({ from, to }));
+    return { areas: known.areas.map(toAreaRef), resolved };
+  });
+
+  server.handle(clearMapRpc, async ({ agentId }, { paseo }) => {
+    const agent = await agentInfo(paseo, agentId);
+    const identifier = agent.labels[AGENT_LABELS.issue];
+    if (!identifier) throw new Error("This agent is not linked to a Linear issue");
+    if (jobs.get(identifier)?.job.status === "running") throw new Error("The explore agent is still mapping this issue");
+    await maps.delete(identifier);
+    jobs.forget(identifier);
+    return { cleared: true };
+  });
+  server.handle(subagentLogsRpc, async ({ agentId }, { paseo }) => {
+    const agent = await agentInfo(paseo, agentId);
+    // Only Claude keeps subagent transcripts this plugin can read.
+    if (agent.provider.split("/")[0] !== "claude" || !agent.sessionId) return { runs: [] };
+    return { runs: await subagentLogs(agent.sessionId, agent.cwd) };
+  });
+  server.handle(liveMapRpc, async ({ identifier }, { paseo }) => {
+    const map = await maps.get(identifier);
+    let job = jobs.get(identifier)?.job ?? null;
+    const checked = recoveredAt.get(identifier) ?? 0;
+    if (!map && !job && Date.now() - checked > RECOVER_INTERVAL_MS) {
+      job = await recover(paseo, identifier).catch(() => null);
+    }
+    return { map: map ?? (await maps.get(identifier)), job };
+  });
+
+  // Finishes runs whose job a reload dropped, as soon as the agent's turn ends.
+  server.on("agent.turn_ended", async (event, { paseo }) => {
+    const identifier = EXPLORE_TITLE.exec(event.agent.title ?? "")?.[1];
+    if (!identifier || jobs.get(identifier)?.job.status === "running") return;
+    await recover(paseo, identifier).catch((error: unknown) =>
+      console.error(`Linear explore run for ${identifier} was not recovered`, error),
+    );
+  });
+
+  interface ExploreTarget {
+    identifier: string;
+    keyScope: string | null;
+    /** Paseo project whose saved knowledge goes into the prompt. */
+    projectId: string | null;
+    cwd: string;
+    /** Opened only when a new run starts. */
+    workspace: () => Promise<WorkspaceHandle>;
+    provider: string;
+    effort: string;
+    force: boolean;
+  }
+
+  // One explore run per issue: a running job is shared, and a saved map is reused.
+  async function ensureExplore(paseo: Paseo, target: ExploreTarget): Promise<Job> {
+    const { identifier } = target;
+    const existing = jobs.get(identifier)?.job;
+    if (existing?.status === "running" || (existing?.status === "done" && !target.force)) {
+      return existing;
+    }
+    const stored = target.force ? null : await maps.get(identifier);
+    if (stored) {
+      return { id: identifier, status: "done", agentId: null, error: null, startedAt: stored.createdAt };
+    }
+    const adopted = target.force ? null : await recover(paseo, identifier).catch(() => null);
+    if (adopted?.status === "running") return adopted;
+    const job = await jobs.start(identifier, async () => {
+      const { linear } = await access.connect(target.keyScope);
+      const issue = await linear.getIssue(identifier);
+      const labels: Record<string, string> = { [AGENT_LABELS.explore]: identifier };
+      if (target.keyScope) labels[AGENT_LABELS.project] = target.keyScope;
+      const known = await knowledgeFor(paseo, knowledge, target.projectId);
+      const run = await startInternalRun({
+        paseo,
+        workspace: await target.workspace(),
+        cwd: target.cwd,
+        provider: target.provider,
+        effort: target.effort,
+        title: `Explore ${identifier}`,
+        prompt: explorePrompt(issue, known),
+        labels,
+        schema: ExploreResultSchema,
+        timeoutMs: EXPLORE_TIMEOUT_MS,
+      });
+      return { agentId: run.agentId, result: run.result.then(saveMap(issue, target.cwd)) };
+    });
+    return track(paseo, job);
+  }
+  async function requireEnabled(projectId: string | null) {
+    const settings = await readSettings();
+    if (settings && !projectEnabled(settings.access, projectId)) {
+      throw new Error("Linear is off for this project");
+    }
+    return settings;
+  }
+
+  server.handle(exploreRpc, async ({ agentId, force }, { paseo }) => {
+    const agent = await agentInfo(paseo, agentId);
+    const identifier = agent.labels[AGENT_LABELS.issue];
+    if (!identifier) throw new Error("This agent is not linked to a Linear issue");
+    const settings = await requireEnabled(agent.projectId);
+    const { workspaceId, cwd } = agent;
+    const job = await ensureExplore(paseo, {
+      identifier,
+      keyScope: agent.labels[AGENT_LABELS.project] ?? null,
+      projectId: agent.projectId,
+      cwd,
+      workspace: async () =>
+        workspaceId ? paseo.workspaces.ref(workspaceId) : paseo.workspaces.open(cwd),
+      provider: settings?.live.exploreProvider || agent.provider,
+      effort: settings?.live.exploreEffort ?? "",
+      force,
+    });
+    return { job };
+  });
+
+  server.handle(launchAfterExploreRpc, async (input, { paseo }) => {
+    const workspace = paseo.workspaces.ref(input.workspaceId);
+    const info = await workspace.refresh();
+    if (!info) throw new Error("The workspace was not found");
+    const settings = await requireEnabled(info.projectId);
+    const job = await ensureExplore(paseo, {
+      identifier: input.identifier,
+      keyScope: input.keyScope,
+      projectId: info.projectId,
+      cwd: info.workspaceDirectory ?? info.projectRootPath,
+      workspace: async () => workspace,
+      provider: settings?.live.exploreProvider || input.agent.config.provider,
+      effort: settings?.live.exploreEffort ?? "",
+      force: false,
+    });
+    // A failed or timed-out explore run still starts the agent; the map falls back to ticket text.
+    if (job.status !== "running") return { agentId: await startLaunch(workspace, input), job };
+    await launches.add(input);
+    // The run may have ended while the launch was saved; claiming makes a second start a no-op.
+    if (jobs.get(job.id)?.job.status !== "running") await startWaiting(paseo, input.identifier);
+    return { agentId: null, job };
+  });
+}

package/server/mcp-http.ts

@@ -0,0 +1,156 @@
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import { type ZodType, z } from "zod";
+
+// A small MCP server over HTTP for agents on this host. It sends plain JSON responses, which the
+// streamable HTTP transport allows, so it needs no sessions and no event streams.
+
+export interface McpTool<C> {
+  name: string;
+  description: string;
+  input: ZodType;
+  /** Callers that may list and call the tool; all callers when absent. */
+  allowed?(caller: C): boolean;
+  run(input: unknown, caller: C): Promise<string>;
+}
+
+/** A tool whose run gets its parsed input. */
+export function tool<S extends ZodType, C>(
+  definition: Omit<McpTool<C>, "input" | "run"> & { input: S; run(input: z.output<S>, caller: C): Promise<string> },
+): McpTool<C> {
+  return definition as unknown as McpTool<C>;
+}
+
+export interface McpOptions<C> {
+  name: string;
+  version: string;
+  tools: readonly McpTool<C>[];
+  /** The caller for a bearer token, or null to refuse the request. */
+  authorize(token: string): Promise<C | null>;
+  /** Why the caller gets no tools at all, or null. The tool list is then empty. */
+  closed?(caller: C): string | null;
+}
+
+const VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+const MAX_BODY = 1_000_000;
+
+type Message = { jsonrpc?: unknown; id?: unknown; method?: unknown; params?: unknown };
+
+const failure = (id: unknown, code: number, message: string) => ({ jsonrpc: "2.0", id: id ?? null, error: { code, message } });
+const success = (id: unknown, result: unknown) => ({ jsonrpc: "2.0", id, result });
+const text = (value: string, isError = false) => ({ content: [{ type: "text", text: value }], ...(isError ? { isError } : {}) });
+
+function errorText(error: unknown): string {
+  if (error instanceof z.ZodError) return error.issues.map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`).join("; ");
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** The answer to one JSON-RPC message, or null for a notification. */
+export async function answer<C>(options: McpOptions<C>, message: Message, caller: C): Promise<object | null> {
+  if (typeof message !== "object" || message === null || message.jsonrpc !== "2.0" || typeof message.method !== "string") {
+    return failure(message?.id, -32600, "Invalid request");
+  }
+  if (message.id === undefined || message.id === null) return null;
+  const params = (typeof message.params === "object" && message.params !== null ? message.params : {}) as Record<string, unknown>;
+  const closed = options.closed?.(caller) ?? null;
+  const tools = closed ? [] : options.tools.filter((tool) => tool.allowed?.(caller) ?? true);
+  switch (message.method) {
+    case "initialize": {
+      const asked = typeof params.protocolVersion === "string" ? params.protocolVersion : "";
+      return success(message.id, {
+        protocolVersion: VERSIONS.includes(asked) ? asked : VERSIONS[0],
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: options.name, version: options.version },
+      });
+    }
+    case "ping":
+      return success(message.id, {});
+    case "tools/list":
+      return success(message.id, {
+        tools: tools.map((tool) => ({
+          name: tool.name,
+          description: tool.description,
+          inputSchema: z.toJSONSchema(tool.input, { io: "input" }),
+        })),
+      });
+    case "tools/call": {
+      if (closed) return success(message.id, text(closed, true));
+      const tool = tools.find((entry) => entry.name === params.name);
+      if (!tool) return failure(message.id, -32602, `Unknown tool: ${String(params.name)}`);
+      try {
+        return success(message.id, text(await tool.run(tool.input.parse(params.arguments ?? {}), caller)));
+      } catch (error) {
+        return success(message.id, text(errorText(error), true));
+      }
+    }
+    default:
+      return failure(message.id, -32601, `Unknown method: ${message.method}`);
+  }
+}
+
+function readBody(request: IncomingMessage): Promise<string | null> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    request.on("data", (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > MAX_BODY) {
+        resolve(null);
+        request.destroy();
+      } else chunks.push(chunk);
+    });
+    request.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    request.on("error", reject);
+  });
+}
+
+function send(response: ServerResponse, status: number, body?: unknown) {
+  response.writeHead(status, body === undefined ? {} : { "content-type": "application/json" });
+  response.end(body === undefined ? undefined : JSON.stringify(body));
+}
+
+// Browsers send an Origin header and agents do not, so a web page can never reach the tools.
+export function createMcpServer<C>(options: McpOptions<C>): Server {
+  return createServer(async (request, response) => {
+    try {
+      if (new URL(request.url ?? "/", "http://localhost").pathname !== "/mcp") return send(response, 404);
+      if (request.headers.origin) return send(response, 403);
+      if (request.method !== "POST") {
+        response.setHeader("allow", "POST");
+        return send(response, 405);
+      }
+      const token = /^Bearer (\S+)$/.exec(request.headers.authorization ?? "")?.[1];
+      const caller = token ? await options.authorize(token) : null;
+      if (caller === null) return send(response, 401, failure(null, -32001, "Unknown token"));
+      const raw = await readBody(request);
+      if (raw === null) return send(response, 413);
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+        return send(response, 400, failure(null, -32700, "Parse error"));
+      }
+      const messages = (Array.isArray(parsed) ? parsed : [parsed]) as Message[];
+      const answers = (await Promise.all(messages.map((message) => answer(options, message, caller)))).filter(Boolean);
+      if (answers.length === 0) return send(response, 202);
+      send(response, 200, Array.isArray(parsed) ? answers : answers[0]);
+    } catch (error) {
+      console.error("Linear MCP request failed", error);
+      if (!response.headersSent) send(response, 500);
+    }
+  });
+}
+
+/** Listens on 127.0.0.1, on the preferred port when it is free. Returns the port. */
+export function listenLocal(server: Server, preferred: number | null): Promise<number> {
+  const attempt = (port: number) =>
+    new Promise<number>((resolve, reject) => {
+      const fail = (error: Error) => reject(error);
+      server.once("error", fail);
+      server.listen(port, "127.0.0.1", () => {
+        server.off("error", fail);
+        resolve((server.address() as AddressInfo).port);
+      });
+    });
+  return preferred ? attempt(preferred).catch(() => attempt(0)) : attempt(0);
+}

package/server/stores.ts

@@ -0,0 +1,126 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { type ZodType, z } from "zod";
+import { type IssueMap, IssueMapSchema, type LaunchInput, LaunchInputSchema } from "../shared/live";
+
+const MAX_MAPS = 200;
+/** A launch still waiting after this long is dropped, so a stale one never starts by surprise. */
+export const PENDING_LAUNCH_MAX_AGE_MS = 60 * 60_000;
+
+export interface JsonFile<T> {
+  read(): Promise<T>;
+  /** Changes run one at a time, so a read, change, and write never interleave. */
+  update<R>(change: (current: T) => { next: T; result: R }): Promise<R>;
+}
+
+export function createJsonFile<T>(file: string, schema: ZodType<T>, empty: () => T): JsonFile<T> {
+  let value: T | null = null;
+  let queue: Promise<unknown> = Promise.resolve();
+  async function load(): Promise<T> {
+    if (value !== null) return value;
+    try {
+      value = schema.parse(JSON.parse(await readFile(file, "utf8")));
+    } catch {
+      value = empty();
+    }
+    return value;
+  }
+  async function save(next: T) {
+    value = next;
+    await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${process.pid}.tmp`;
+    await writeFile(temporary, JSON.stringify(next), { mode: 0o600 });
+    await rename(temporary, file);
+  }
+  return {
+    read: load,
+    update(change) {
+      const run = queue
+        .catch(() => undefined)
+        .then(async () => {
+          const { next, result } = change(await load());
+          await save(next);
+          return result;
+        });
+      queue = run;
+      return run;
+    },
+  };
+}
+
+export interface MapStore {
+  get(identifier: string): Promise<IssueMap | null>;
+  set(map: IssueMap): Promise<void>;
+  delete(identifier: string): Promise<void>;
+}
+
+/** Explore maps survive daemon restarts, so a finished explore run is never paid for twice. */
+export function createMapStore(file: string): MapStore {
+  const store = createJsonFile<Record<string, IssueMap>>(
+    file,
+    z.record(z.string(), IssueMapSchema),
+    () => ({}),
+  );
+  return {
+    async get(identifier) {
+      return (await store.read())[identifier] ?? null;
+    },
+    set(map) {
+      return store.update((current) => {
+        const kept = Object.values({ ...current, [map.identifier]: map })
+          .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+          .slice(0, MAX_MAPS);
+        return { next: Object.fromEntries(kept.map((entry) => [entry.identifier, entry])), result: undefined };
+      });
+    },
+    delete(identifier) {
+      return store.update((current) => {
+        const { [identifier]: _removed, ...rest } = current;
+        return { next: rest, result: undefined };
+      });
+    },
+  };
+}
+
+const PendingLaunchSchema = LaunchInputSchema.extend({ queuedAt: z.number() });
+type PendingLaunch = z.infer<typeof PendingLaunchSchema>;
+
+export interface LaunchQueue {
+  add(launch: LaunchInput): Promise<void>;
+  /** Removes and returns the issue's waiting launches, so each one starts at most once. */
+  claim(identifier: string): Promise<LaunchInput[]>;
+}
+
+// Agents that wait for an explore run are saved to disk, so a plugin reload or daemon
+// restart while the run works still starts them once the map is ready.
+export function createLaunchQueue(file: string, now = () => Date.now()): LaunchQueue {
+  const store = createJsonFile<Record<string, PendingLaunch[]>>(
+    file,
+    z.record(z.string(), z.array(PendingLaunchSchema)),
+    () => ({}),
+  );
+  return {
+    add(launch) {
+      return store.update((current) => ({
+        next: {
+          ...current,
+          [launch.identifier]: [...(current[launch.identifier] ?? []), { ...launch, queuedAt: now() }],
+        },
+        result: undefined,
+      }));
+    },
+    claim(identifier) {
+      return store.update((current) => {
+        const { [identifier]: waiting = [], ...others } = current;
+        const fresh = waiting.filter((launch) => now() - launch.queuedAt < PENDING_LAUNCH_MAX_AGE_MS);
+        if (fresh.length < waiting.length) {
+          console.error(`Dropped ${waiting.length - fresh.length} stale Linear launch for ${identifier}`);
+        }
+        return {
+          next: others,
+          result: fresh.map(({ queuedAt: _queuedAt, ...launch }: PendingLaunch) => launch),
+        };
+      });
+    },
+  };
+}