@justjoshn/pi-pstack 0.15.36-pi.12 → 0.15.36-pi.13

package/src/plan.ts

@@ -1,17 +1,28 @@
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { join, resolve, sep } from 'node:path';
 
-import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext, stripFrontmatter } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
+import type * as YAML from 'yaml';
 import { canAsk } from './modes.ts';
 import { plansDir } from './paths.ts';
 import { createReadonlyBashTool, releaseReadonlySandbox } from './readonly-shell.ts';
+import type { TodoItem } from './todo.ts';
 
 export const PLAN_ENTRY = 'pstack/plan';
 const STATUS_KEY = 'pstack-plan';
 
+// Pi's local package installer does not install dependencies, so missing YAML must not block unrelated tools.
+let yaml: typeof YAML | undefined;
+try {
+  yaml = createRequire(import.meta.url)('yaml') as typeof YAML;
+} catch (error) {
+  if ((error as NodeJS.ErrnoException).code !== 'MODULE_NOT_FOUND') throw error;
+}
+
 /**
  * Pi's `bash` cannot be swapped for the sandboxed shell by name without replacing it for the whole session, so plan
  * mode offers the sandboxed shell under its own name and makes it the only shell while plan mode is on.
@@ -120,6 +131,12 @@ export function planSection(planFile: string | undefined): string {
 export interface PlanTodo {
   id: string;
   content: string;
+  dependencies?: string[];
+}
+
+export interface PlanProject {
+  is_project?: boolean;
+  phases?: { name: string; todos?: PlanTodo[] }[];
 }
 
 /** The plan's title as Cursor finds it: the first level-1 heading, else the first line of text. */
@@ -141,13 +158,24 @@ export function planFileName(name: string, chatKey: string): string {
 
 const yamlString = (value: string) => `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t')}"`;
 
+function planTodoLines(todo: PlanTodo): string[] {
+  const lines = [`  - id: ${yamlString(todo.id)}`, `    content: ${yamlString(todo.content)}`, '    status: pending'];
+  if (todo.dependencies !== undefined && todo.dependencies.length > 0) lines.push('    dependencies:', ...todo.dependencies.map((id) => `      - ${yamlString(id)}`));
+  return lines;
+}
+
 /** The plan file as Cursor writes it: the chat id in a comment, the todos as front matter, then the plan. */
-export function planFileContent(sessionId: string, plan: string, todos: readonly PlanTodo[]): string {
+export function planFileContent(sessionId: string, plan: string, todos: readonly PlanTodo[], project: PlanProject = {}): string {
   const lines = [`<!-- ${sessionId} -->`];
-  if (todos.length > 0) {
-    lines.push('---', 'todos:');
-    for (const todo of todos) lines.push(`  - id: ${yamlString(todo.id)}`, `    content: ${yamlString(todo.content)}`, '    status: pending');
-    lines.push('isProject: false', '---');
+  if (todos.length > 0 || project.is_project === true) {
+    lines.push('---');
+    if (todos.length > 0) lines.push('todos:', ...todos.flatMap(planTodoLines));
+    lines.push(`isProject: ${project.is_project === true}`);
+    if (project.is_project === true && project.phases !== undefined && project.phases.length > 0) {
+      lines.push('phases:');
+      for (const phase of project.phases) lines.push(`  - name: ${yamlString(phase.name)}`, '    todos:', ...(phase.todos ?? []).flatMap((todo) => planTodoLines(todo).map((line) => `    ${line}`)));
+    }
+    lines.push('---');
   }
   lines.push(plan);
   return lines.join('\n');
@@ -157,29 +185,94 @@ export function planFileContent(sessionId: string, plan: string, todos: readonly
  * Writes the plan under the plans folder and returns its path. A chat keeps one file per plan name, as Cursor keys the
  * name by its conversation; Pi's session ids start with a timestamp, so the 8 characters come from a hash of the id.
  */
-export function savePlan(sessionId: string, plan: string, name: string | undefined, todos: readonly PlanTodo[], dir = plansDir()): string {
+export function savePlan(sessionId: string, plan: string, name: string | undefined, todos: readonly PlanTodo[], dir = plansDir(), project: PlanProject = {}): string {
   mkdirSync(dir, { recursive: true, mode: 0o700 });
   const chatKey = createHash('sha256').update(sessionId).digest('hex');
   const path = join(dir, planFileName(name === undefined || name.trim() === '' ? planTitle(plan) : name, chatKey));
-  writeFileSync(path, planFileContent(sessionId, plan, todos), { mode: 0o600 });
+  writeFileSync(path, planFileContent(sessionId, plan, todos, project), { mode: 0o600 });
   return path;
 }
 
 /** The plan text the build turn carries: the file without Cursor's chat comment and todo front matter. */
 export function planBody(file: string): string {
-  return readFileSync(file, 'utf8')
-    .replace(/^<!-- [^\n]*-->\n/, '')
-    .replace(/^---\n[\s\S]*?\n---\n/, '')
-    .trim();
+  return stripFrontmatter(readFileSync(file, 'utf8').replace(/^<!-- [^\n]*-->\r?\n/, '')).trim();
+}
+
+function planMetadata(file: string) {
+  const source = readFileSync(file, 'utf8');
+  const comment = /^<!-- [^\n]*-->\r?\n/.exec(source)?.[0] ?? '';
+  const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(source.slice(comment.length));
+  if (frontmatter === null) return undefined;
+  if (yaml === undefined) throw new Error('Plan metadata needs the yaml dependency. Run bun install in the pi-pstack package directory, then reload Pi.');
+  const document = yaml.parseDocument(frontmatter[1] ?? '');
+  if (document.errors.length > 0) throw new Error(`Invalid plan metadata in ${file}: ${document.errors[0]?.message}`);
+  return { source, offset: comment.length + frontmatter[0].indexOf('\n') + 1, document, yaml };
+}
+
+export function planTodos(file: string): TodoItem[] {
+  const metadata = planMetadata(file);
+  if (metadata === undefined) return [];
+  const { isSeq, isMap, isScalar } = metadata.yaml;
+  const field = metadata.document.get('todos');
+  if (field === undefined || field === null) return [];
+  if (!isSeq(field)) throw new Error(`Plan todos in ${file} must be a list.`);
+  return field.items.map((todo) => {
+    if (!isMap(todo)) throw new Error(`Each plan todo in ${file} must have an id, content, and status.`);
+    const id = todo.get('id');
+    const content = todo.get('content');
+    const status = todo.get('status') ?? 'pending';
+    const dependencies = todo.get('dependencies');
+    if (typeof id !== 'string' || typeof content !== 'string' || !(status === 'pending' || status === 'in_progress' || status === 'completed' || status === 'cancelled')) throw new Error(`Invalid plan todo in ${file}.`);
+    if (dependencies !== undefined && (!isSeq(dependencies) || dependencies.items.some((dependency) => !isScalar(dependency) || typeof dependency.value !== 'string'))) throw new Error(`Invalid todo dependencies in ${file}.`);
+    return { id, content, status, ...(isSeq(dependencies) ? { dependencies: dependencies.toJSON() as string[] } : {}) };
+  });
 }
 
+export function syncPlanTodoStatuses(file: string, todos: readonly TodoItem[]): void {
+  const metadata = planMetadata(file);
+  if (metadata === undefined) return;
+  const { source, offset, document, yaml: parser } = metadata;
+  const { isSeq, isMap, isScalar } = parser;
+  const field = document.get('todos');
+  if (!isSeq(field)) return;
+  const statuses = new Map(todos.map((todo) => [todo.id, todo.status]));
+  const edits: { start: number; end: number; text: string }[] = [];
+  for (const todo of field.items) {
+    if (!isMap(todo)) continue;
+    const status = statuses.get(String(todo.get('id')));
+    const node = todo.get('status', true);
+    if (status === undefined || (node === undefined && status === 'pending')) continue;
+    if (node === undefined && todo.range != null) {
+      const start = offset + todo.range[0] + (todo.flow ? 1 : 0);
+      const indent = start - source.lastIndexOf('\n', start) - 1;
+      const newline = source.includes('\r\n') ? '\r\n' : '\n';
+      const text = todo.flow ? `status: ${status}, ` : `status: ${status}${newline}${' '.repeat(indent)}`;
+      edits.push({ start, end: start, text });
+      continue;
+    }
+    if (!isScalar(node) || node.range == null || node.value === status) continue;
+    const value = node.type === 'QUOTE_DOUBLE' ? JSON.stringify(status) : node.type === 'QUOTE_SINGLE' ? `'${status}'` : status;
+    edits.push({ start: offset + node.range[0], end: offset + node.range[1], text: value });
+  }
+  if (edits.length === 0) return;
+  let updated = source;
+  for (const edit of edits.sort((a, b) => b.start - a.start)) updated = updated.slice(0, edit.start) + edit.text + updated.slice(edit.end);
+  writeFileSync(file, updated);
+}
+
+const PlanTodoParams = Type.Object({
+  id: Type.String({ description: 'Unique identifier for the todo' }),
+  content: Type.String({ description: 'Description of the todo task' }),
+  dependencies: Type.Optional(Type.Array(Type.String(), { description: 'IDs of todos that must finish before this todo' })),
+});
+
 const CreatePlanParams = Type.Object({
   plan: Type.String({ description: "A detailed, concrete plan for accomplishing the user's request" }),
   name: Type.Optional(Type.String({ description: 'A short 3-4 word name for the plan. Give it only on the first CreatePlan call, so the plan file name stays stable.' })),
   overview: Type.Optional(Type.String({ description: 'A 1-2 sentence high-level description of what the plan accomplishes' })),
-  todos: Type.Optional(
-    Type.Array(Type.Object({ id: Type.String({ description: 'Unique identifier for the todo' }), content: Type.String({ description: 'Description of the todo task' }) }), { description: 'Array of implementation todos' }),
-  ),
+  todos: Type.Optional(Type.Array(PlanTodoParams, { description: 'Array of implementation todos' })),
+  is_project: Type.Optional(Type.Boolean({ description: 'Whether the plan is a project organized into phases' })),
+  phases: Type.Optional(Type.Array(Type.Object({ name: Type.String(), todos: Type.Optional(Type.Array(PlanTodoParams)) }), { description: 'Named project phases and their todos, saved when is_project is true' })),
 });
 
 // Cursor's CreatePlan rules: a glanceable markdown plan with a title, todos, no tables, and edits in the file afterwards.
@@ -236,12 +329,15 @@ const isGitRepository = (cwd: string): boolean => {
 };
 
 export interface PlanModeOptions {
+  buildPlan?: string;
+  setTodos?: (todos: TodoItem[], ctx: ExtensionContext) => void;
   /** Starts the build in an isolated worktree worker, Pi's counterpart to Cursor's "build in cloud". Returns the agent ID. */
   buildInWorker?: (planFile: string, request: string) => Promise<string>;
 }
 
-export function registerPlanMode(pi: ExtensionAPI, options: PlanModeOptions = {}): { section: () => string | undefined; enabled: () => boolean } {
+export function registerPlanMode(pi: ExtensionAPI, options: PlanModeOptions = {}) {
   let state: PlanState = { enabled: false };
+  let buildPlan = options.buildPlan;
   // A plan saved during the current run, which the user reviews once the run settles.
   let review: string | undefined;
 
@@ -259,7 +355,7 @@ export function registerPlanMode(pi: ExtensionAPI, options: PlanModeOptions = {}
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     async execute(_id, params, _signal, _onUpdate, ctx) {
       if (!state.enabled) throw new Error(`${PLAN_SAVE} is available only in plan mode. Enter it with /plan.`);
-      const planFile = savePlan(ctx.sessionManager.getSessionId(), params.plan, params.name, params.todos ?? []);
+      const planFile = savePlan(ctx.sessionManager.getSessionId(), params.plan, params.name, params.todos ?? [], undefined, params);
       state = { ...state, planFile };
       review = planFile;
       pi.appendEntry(PLAN_ENTRY, state);
@@ -284,7 +380,10 @@ export function registerPlanMode(pi: ExtensionAPI, options: PlanModeOptions = {}
   };
 
   const restore = (ctx: ExtensionContext) => {
-    const stored = planFromBranch(ctx.sessionManager.getBranch());
+    const branch = ctx.sessionManager.getBranch();
+    const stored = planFromBranch(branch);
+    // Pi replays tools from system messages before session_tree. A branch without one has no loadout to restore.
+    if (!stored.enabled && state.enabled && !branch.some((entry) => entry.type === 'message' && entry.message.role === 'system')) disable();
     state = { ...stored };
     review = undefined;
     if (stored.enabled) enable(stored.toolsBefore ?? state.toolsBefore ?? pi.getActiveTools());
@@ -293,7 +392,17 @@ export function registerPlanMode(pi: ExtensionAPI, options: PlanModeOptions = {}
     if (!canAsk(ctx) && pi.getActiveTools().includes(SWITCH_MODE)) pi.setActiveTools(pi.getActiveTools().filter((name) => name !== SWITCH_MODE));
     show(ctx);
   };
-  pi.on('session_start', (_event, ctx) => restore(ctx));
+  pi.on('session_start', (_event, ctx) => {
+    restore(ctx);
+    const initialPlan = buildPlan;
+    buildPlan = undefined;
+    if (initialPlan === undefined) return;
+    const planFile = storedPlanFile(initialPlan, plansDir());
+    if (planFile === undefined) throw new Error('The plan build must use a file inside the pi-pstack plans directory.');
+    prepareBuild(ctx, planFile);
+    state = { enabled: false, planFile };
+    pi.appendEntry(PLAN_ENTRY, state);
+  });
   pi.on('session_tree', (_event, ctx) => restore(ctx));
 
   // Active tools decide what the model is offered; this decides what may run, including names the model
@@ -305,7 +414,13 @@ export function registerPlanMode(pi: ExtensionAPI, options: PlanModeOptions = {}
     return reason === undefined ? undefined : { block: true, reason };
   });
 
+  const prepareBuild = (ctx: ExtensionContext, planFile: string) => {
+    const todos = planTodos(planFile).filter((todo) => todo.status !== 'completed' && todo.status !== 'cancelled');
+    options.setTodos?.(todos, ctx);
+  };
+
   const build = (ctx: ExtensionContext, planFile: string) => {
+    prepareBuild(ctx, planFile);
     if (state.enabled) disable();
     pi.appendEntry(PLAN_ENTRY, state);
     show(ctx);
@@ -319,6 +434,7 @@ export function registerPlanMode(pi: ExtensionAPI, options: PlanModeOptions = {}
     if (!state.enabled || state.planFile !== planFile) return;
     if (choice === BUILD_LOCALLY) build(ctx, planFile);
     else if (choice === BUILD_IN_WORKER && options.buildInWorker !== undefined) {
+      prepareBuild(ctx, planFile);
       disable();
       pi.appendEntry(PLAN_ENTRY, state);
       show(ctx);
@@ -392,5 +508,11 @@ export function registerPlanMode(pi: ExtensionAPI, options: PlanModeOptions = {}
     },
   });
 
-  return { section: () => (state.enabled ? planSection(state.planFile) : undefined), enabled: () => state.enabled };
+  return {
+    section: () => (state.enabled ? planSection(state.planFile) : undefined),
+    enabled: () => state.enabled,
+    syncTodos: (todos: readonly TodoItem[]) => {
+      if (state.planFile !== undefined && existsSync(state.planFile)) syncPlanTodoStatuses(state.planFile, todos);
+    },
+  };
 }

package/src/process-lock.ts

@@ -0,0 +1,76 @@
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+function zombie(pid: number): boolean {
+  if (process.platform !== 'linux') return false;
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+    const close = stat.lastIndexOf(')');
+    return close !== -1 && stat.slice(close + 2, close + 3) === 'Z';
+  } catch {
+    return false;
+  }
+}
+
+export function alive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return !zombie(pid);
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+export type Lease = { token: string; release: () => void };
+
+/** A holder token keeps a stale reaper from unlinking a replacement owner's lease. */
+export function acquireLease(path: string): Lease | undefined {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const token = `${process.pid}-${randomUUID()}`;
+  const temporary = `${path}.${token}.tmp`;
+  mkdirSync(temporary, { mode: 0o700 });
+  try {
+    writeFileSync(join(temporary, token), '', { mode: 0o600 });
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+      try {
+        renameSync(temporary, path);
+        return {
+          token,
+          release: () => {
+            rmSync(join(path, token), { force: true });
+            try {
+              rmdirSync(path);
+            } catch (error) {
+              if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
+            }
+          },
+        };
+      } catch (error) {
+        if (!['ENOTEMPTY', 'EEXIST'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
+      }
+      let holders: string[];
+      try {
+        holders = readdirSync(path);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+        throw error;
+      }
+      for (const holder of holders) {
+        const pid = Number(/^(\d+)-[a-f0-9-]+$/.exec(holder)?.[1]);
+        if (!Number.isInteger(pid)) throw new Error(`Invalid process lock ${path}. Retain it for diagnosis.`);
+        if (alive(pid)) return undefined;
+        rmSync(join(path, holder), { force: true });
+      }
+      try {
+        rmdirSync(path);
+      } catch (error) {
+        if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
+      }
+    }
+    return undefined;
+  } finally {
+    rmSync(temporary, { recursive: true, force: true });
+  }
+}

package/src/readonly-shell.ts

@@ -8,11 +8,9 @@ import { type BashSpawnContext, createBashTool, type ExtensionAPI, type Extensio
 // denyWrite names the paths the sandbox makes writable for itself (/tmp/claude is a dependency default), and
 // denyRead drops the dependency's writable home defaults (~/.npm/_logs, ~/.claude/debug). Seatbelt is
 // last-match-wins with deny emitted after allow; on Linux bubblewrap binds deny last the same way.
-// allowAllUnixSockets skips apply-seccomp: on GitHub-hosted runners (and other nested-userns hosts) that
-// helper fails writing /proc/self/setgroups even with setuid bwrap. Write and network denial still come
-// from bubblewrap / sandbox-exec; only AF_UNIX blocking is dropped.
+// Unix sockets must stay blocked too: a host service can mutate files on a command's behalf.
 const READ_ONLY_POLICY: SandboxRuntimeConfig = {
-  network: { allowedDomains: [], deniedDomains: [], allowAllUnixSockets: true },
+  network: { allowedDomains: [], deniedDomains: [], allowAllUnixSockets: false },
   filesystem: {
     denyRead: ['~/.npm/_logs', '~/.claude/debug'],
     allowWrite: [],
@@ -40,10 +38,10 @@ function sandboxReady(): Promise<Sandbox> {
     try {
       const { SandboxManager } = await import('@anthropic-ai/sandbox-runtime');
       if (!SandboxManager.isSupportedPlatform()) throw new Error(`${process.platform} is not supported`);
-      // initialize verifies the sandbox dependencies (bubblewrap, socat, sandbox-exec) before it starts.
-      // A second initialize is a no-op once another consumer has started the manager, and several
-      // Linux flags (notably allowAllUnixSockets) are read from the manager config, not the per-call
-      // wrap override — so updateConfig installs our policy even when we lost the initialize race.
+      const socketWarning = SandboxManager.checkDependencies().warnings.find((warning) => warning.includes('unix socket access not restricted'));
+      if (socketWarning !== undefined) throw new Error(socketWarning);
+      // initialize is a no-op if another consumer started the manager. Linux socket isolation also
+      // reads the shared config, so both it and the per-command override must carry this policy.
       await SandboxManager.initialize(READ_ONLY_POLICY);
       SandboxManager.updateConfig(READ_ONLY_POLICY);
       return SandboxManager;

package/src/subscriptions/durable-store.ts

@@ -1,9 +1,10 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmdirSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { performance } from 'node:perf_hooks';
 
 import { durableRegistryPath, durableRuntimeDir } from '../paths.ts';
+import { acquireLease, alive } from '../process-lock.ts';
 import { parseCron } from './cron.ts';
 import type { ArmStatus, DurableRegistry, DurableSubscription, EventAdmission, PendingEvent, StoredSubscription, SupervisorLock } from './durable-types.ts';
 import { routineSlug } from './webhook.ts';
@@ -18,28 +19,6 @@ export function canonicalPath(path: string): string {
   }
 }
 
-function zombie(pid: number): boolean {
-  if (process.platform !== 'linux') return false;
-  try {
-    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
-    const close = stat.lastIndexOf(')');
-    return close !== -1 && stat.slice(close + 2, close + 3) === 'Z';
-  } catch {
-    return false;
-  }
-}
-
-export function alive(pid: number): boolean {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    process.kill(pid, 0);
-    // A zombie still answers kill(pid, 0) until its parent reaps it, but it holds no lock and runs nothing.
-    return !zombie(pid);
-  } catch (error) {
-    return (error as NodeJS.ErrnoException).code === 'EPERM';
-  }
-}
-
 function writeAtomic(path: string, value: unknown): void {
   mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
   const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
@@ -77,58 +56,6 @@ export function writeRoutinesPort(cwd: string, port: number): void {
   }
 }
 
-export type Lease = { token: string; release: () => void };
-
-/** Publish a nonempty directory atomically. Recovery removes only the dead holder's token. */
-export function acquireLease(path: string): Lease | undefined {
-  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-  const token = `${process.pid}-${randomUUID()}`;
-  const temporary = `${path}.${token}.tmp`;
-  mkdirSync(temporary, { mode: 0o700 });
-  try {
-    writeFileSync(join(temporary, token), '', { mode: 0o600 });
-    for (let attempt = 0; attempt < 4; attempt += 1) {
-      try {
-        renameSync(temporary, path);
-        return {
-          token,
-          release: () => {
-            rmSync(join(path, token), { force: true });
-            try {
-              rmdirSync(path);
-            } catch (error) {
-              if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
-            }
-          },
-        };
-      } catch (error) {
-        if (!['ENOTEMPTY', 'EEXIST'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
-      }
-      let holders: string[];
-      try {
-        holders = readdirSync(path);
-      } catch (error) {
-        if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
-        throw error;
-      }
-      for (const holder of holders) {
-        const pid = Number(/^(\d+)-[a-f0-9-]+$/.exec(holder)?.[1]);
-        if (!Number.isInteger(pid)) throw new Error(`Invalid subscription lock ${path}. Retain it for diagnosis.`);
-        if (alive(pid)) return undefined;
-        rmSync(join(path, holder), { force: true });
-      }
-      try {
-        rmdirSync(path);
-      } catch (error) {
-        if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
-      }
-    }
-    return undefined;
-  } finally {
-    rmSync(temporary, { recursive: true, force: true });
-  }
-}
-
 export function ownerIsLive(cwd: string, sessionId: string): boolean {
   const path = ownerLockPath(cwd, sessionId);
   try {

package/src/subscriptions/index.ts

@@ -6,24 +6,9 @@ import { type Static, Type } from 'typebox';
 import { Value } from 'typebox/value';
 import { isOneShot } from '../modes.ts';
 import { routinesDir } from '../paths.ts';
+import { acquireLease, type Lease } from '../process-lock.ts';
 import { parseCron } from './cron.ts';
-import {
-  acquireLease,
-  cancelDesired,
-  canonicalPath,
-  createDesired,
-  deliverOwner,
-  finishFresh,
-  isDesired,
-  isSupervisorLive,
-  type Lease,
-  ownerLockPath,
-  readArm,
-  readRegistry,
-  runsDetached,
-  startFresh,
-  visibleSubscriptions,
-} from './durable-store.ts';
+import { cancelDesired, canonicalPath, createDesired, deliverOwner, finishFresh, isDesired, isSupervisorLive, ownerLockPath, readArm, readRegistry, runsDetached, startFresh, visibleSubscriptions } from './durable-store.ts';
 import type { StoredSubscription } from './durable-types.ts';
 import { defaultEnsureSupervisor, waitForArm, waitForSupervisor } from './ensure-supervisor.ts';
 import { type GhRunner, targetText } from './github.ts';

package/src/subscriptions/supervisor.ts

@@ -1,11 +1,11 @@
 import { randomUUID } from 'node:crypto';
 
 import { routinesDir } from '../paths.ts';
+import { alive } from '../process-lock.ts';
 import { cronMatches, parseCron } from './cron.ts';
 import {
   acceptEvent,
   acquireSupervisorLock,
-  alive,
   canonicalPath,
   clearError,
   expireDesired,

package/src/task/records.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, w
 import { join } from 'node:path';
 
 import { parseSessionEntries, SessionManager } from '@earendil-works/pi-coding-agent';
+import { acquireLease, alive } from '../process-lock.ts';
 import type { ModelSpec } from './models.ts';
 import type { Worktree } from './worktree.ts';
 
@@ -142,15 +143,6 @@ export function recordIds(dir: string): string[] {
     .map((name) => name.slice(0, -'.json'.length));
 }
 
-function alive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    return (error as NodeJS.ErrnoException).code === 'EPERM';
-  }
-}
-
 const isPid = (value: number) => Number.isInteger(value) && value > 0;
 
 /** The live pid the agent's run lock names, or undefined when no live process holds it. */
@@ -198,33 +190,46 @@ export interface RunLock {
 /**
  * Pi appends to a session file without a lock, so two processes on one agent ID would interleave its transcript.
  * The lock file holds the pid of the process writing the transcript. A lock without a readable pid counts as held.
- * A dead holder's lock is removed only if it still names that holder, then created again exclusively; two
- * processes taking over the same stale lock in the narrow window between that re-read and the removal can both succeed.
+ * A token-directory lease serializes acquisition and stale recovery without changing the PID file read by stop/status.
  */
 export function acquireRunLock(dir: string, agentId: string): RunLock {
   mkdirSync(dir, { recursive: true, mode: 0o700 });
   const path = join(dir, `${agentId}.lock`);
-  for (let attempt = 0; attempt < 2; attempt += 1) {
-    if (createExclusive(path)) {
-      let owner = process.pid;
-      return {
-        holdFor: (pid) => {
-          writeAtomically(path, String(pid));
-          owner = pid;
-        },
-        // Best effort: a lock left behind names a pid that will be dead, so the next acquire takes it over.
-        release: () => {
-          try {
-            if (holderOf(path) === owner) rmSync(path, { force: true });
-          } catch (error) {
-            if (!['EACCES', 'EPERM', 'EROFS', 'EBUSY', 'EIO'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
-          }
-        },
-      };
+  const lease = acquireLease(`${path}.owner`);
+  if (lease === undefined) throw stillRunning(agentId, runningPid(dir, agentId), path);
+  let acquired = false;
+  try {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      if (createExclusive(path)) {
+        acquired = true;
+        let owner = process.pid;
+        return {
+          holdFor: (pid) => {
+            writeAtomically(path, String(pid));
+            owner = pid;
+          },
+          release: () => {
+            for (const release of [
+              () => {
+                if (holderOf(path) === owner) rmSync(path, { force: true });
+              },
+              lease.release,
+            ]) {
+              try {
+                release();
+              } catch (error) {
+                if (!['EACCES', 'EPERM', 'EROFS', 'EBUSY', 'EIO'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
+              }
+            }
+          },
+        };
+      }
+      const holder = holderOf(path);
+      if (holder !== undefined && (!isPid(holder) || alive(holder))) throw stillRunning(agentId, holder, path);
+      if (holder !== undefined && holderOf(path) === holder) rmSync(path, { force: true });
     }
-    const holder = holderOf(path);
-    if (holder !== undefined && (!isPid(holder) || alive(holder))) throw stillRunning(agentId, holder, path);
-    if (holder !== undefined && holderOf(path) === holder) rmSync(path, { force: true });
+    throw stillRunning(agentId, holderOf(path), path);
+  } finally {
+    if (!acquired) lease.release();
   }
-  throw stillRunning(agentId, holderOf(path), path);
 }

package/src/task/tool.ts

@@ -5,7 +5,7 @@ import { isAbsolute, join, relative } from 'node:path';
 import { getSupportedThinkingLevels } from '@earendil-works/pi-ai';
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 import { type Static, Type } from 'typebox';
-import { childIdentity, childVariables } from '../child-env.ts';
+import { BUILD_PLAN_ENV, childIdentity, childVariables } from '../child-env.ts';
 import { rootStoreDir, subagentDir, workspaceStateDir, worktreesDir } from '../paths.ts';
 import { piCommand } from '../pi-command.ts';
 import { type AgentDefinition, findAgent } from './agents.ts';
@@ -111,6 +111,7 @@ export interface Launch {
   attachments: string[];
   notes: string[];
   description: string;
+  buildPlan?: string;
 }
 
 const runsReadonly = (plan: Launch) => plan.readonly || plan.planMode;
@@ -269,7 +270,11 @@ export function planFork(params: TaskInput, ctx: ExtensionContext, agents: reado
 
 function launchChild(plan: Launch, input: ChildInput, signal: AbortSignal | undefined, onEvent?: (event: { type: string } & Record<string, unknown>) => void) {
   const readonly = runsReadonly(plan);
-  const env = { ...process.env, ...childVariables(plan.agent.type, plan.depth, readonly, plan.rootStore, workspaceStateDir(plan.workspace), plan.rootWorkspace) };
+  const env = {
+    ...process.env,
+    ...childVariables(plan.agent.type, plan.depth, readonly, plan.rootStore, workspaceStateDir(plan.workspace), plan.rootWorkspace),
+    ...(plan.buildPlan === undefined ? {} : { [BUILD_PLAN_ENV]: plan.buildPlan }),
+  };
   const transcript = plan.kind === 'fresh' || readonly ? undefined : transcriptFor(subagentDir(plan.workspace), plan.agentId);
   const restoreTools = transcript === undefined ? [] : readonlyLaunchRestores(transcript);
   const args = childArgs({
@@ -501,6 +506,8 @@ export interface StartBackgroundOptions {
   environment?: 'cloud';
   /** The owner's project-trust decision, used when this subscription fire starts away from its chat. */
   trusted?: boolean;
+  /** Imports the reviewed plan's todos into the worker before its first model request. */
+  buildPlan?: string;
 }
 
 export interface TaskHandle {
@@ -582,6 +589,7 @@ export function registerTask(pi: ExtensionAPI, options: TaskToolOptions): TaskHa
     taskPreflight(params, options.depth);
     const { plan, lock } = prepare(params, ctx, options, registry.isRunning);
     if (startOptions?.trusted !== undefined) plan.trusted = startOptions.trusted;
+    if (startOptions?.buildPlan !== undefined) plan.buildPlan = startOptions.buildPlan;
     await createWorktree(plan, lock, undefined);
     const handle = start(plan, { text: prompt.trim(), images: [] }, undefined, lock);
     registry.track(plan.agentId, handle, lock.release, runsReadonly(plan), backgroundNotice(plan, prompt, description, ctx, `pstack-${plan.agentId}`));