@yaawn/workflow 0.4.0 → 0.5.0

package/agents/skills/yaawn-implement-plan/SKILL.md

@@ -16,16 +16,16 @@ Work in the developer persona (`.agents/personas/yaawn-developer.md`) — this s
 
 An orchestrator ([scripts/overnight.ts](./scripts/overnight.ts)) running in a background terminal, kept awake by `caffeinate`, plus two chat messages from you: the **start message** once it runs (step 5) and the **final result** once it ends (step 6).
 
-The terminal stays quiet: the walk-away banner, one line `<ISO> #<issue> <state>` each time a lane moves on — `started` → `implement` → `review` → `fix` (only if the review found blocking issues) → `done`, `failed`, or `stopped` — and at the end a `--- summary` with every lane's result and one `run result:` line, e.g. `run result: 1 done, 0 failed, 1 stopped (#51 in review)`. Ctrl+C, closing the terminal, or killing the run stops every lane and writes a result `#<issue> stopped in <stage>` naming the stage each unfinished lane was in.
+The terminal stays quiet: the walk-away banner, one line `<ISO> #<issue> <state>` each time a lane moves on — `started` → `implement` → `review` → `fix` (prototypes skip the review; fix only if the review found blocking issues) → `done`, `failed`, or `stopped` — and at the end a `--- summary` with every lane's result and one `run result:` line, e.g. `run result: 1 done, 0 failed, 1 stopped (#51 in review)`. Ctrl+C, closing the terminal, or killing the run stops every lane and writes a result `#<issue> stopped in <stage>` naming the stage each unfinished lane was in.
 
 ### Lanes and worktrees
 
 Every launch runs its issues as **lanes** — one lane per issue, a single issue included:
 
-- **Worktrees** — each lane runs in its own git worktree `<project>/yaawn-<issue>-<slug>` (inside the project, next to the main copy `<project>/main`; `<slug>` is the issue title, lowercased, only `a-z`, `0-9`, and `-`, at most 40 characters) on branch `yaawn/<issue>`. This needs the bare-repo layout — the project root holds a bare `.git` and the main copy is checked out at `<project>/main`; set it up once as described in [`.agents/yaawn-worktrees.md`](../../yaawn-worktrees.md). The worktree is created when its lane starts — the branch from HEAD if it does not exist yet — and reused on relaunch, so relaunching resumes. `/yaawn-verify-executed-plan` later opens the issue's pull request from that branch. The lane's progress logs, summaries, review reports, and transcripts live under `.yaawn/plans/` **in its worktree**. Uncommitted changes in the main copy are not in the worktrees.
+- **Worktrees** — each lane runs in its own git worktree `<project>/yaawn-<issue>-<slug>` (inside the project, next to the main copy `<project>/main`; `<slug>` is the issue title, lowercased, only `a-z`, `0-9`, and `-`, at most 40 characters) on branch `yaawn/<issue>`. An issue labelled `Yaawn: Prototype` runs in `<project>/prototype/yaawn-<issue>-<slug>` on branch `prototype/yaawn-<issue>-<slug>` instead (`<slug>` falls back to `prototype` when the title has none) — that branch is never merged to main and no pull request is opened from it. This needs the bare-repo layout — the project root holds a bare `.git` and the main copy is checked out at `<project>/main`; set it up once as described in [`.agents/yaawn-worktrees.md`](../../yaawn-worktrees.md). The worktree is created when its lane starts — the branch from HEAD if it does not exist yet — and reused on relaunch, so relaunching resumes. `/yaawn-verify-executed-plan` later opens the issue's pull request from that branch; for a prototype, `/yaawn-extract-learnings` reads the branch instead. The lane's progress logs, summaries, review reports, and transcripts live under `.yaawn/plans/` **in its worktree**. Uncommitted changes in the main copy are not in the worktrees.
 - **Lanes** — the issue numbers given, or with `--ready` the open issues labelled `Yaawn: Ready To Implement`. Every issue is its own lane — its only target is the issue itself.
 - **Parallel** — at most `--max-parallel N` lanes run at once (default: all); a waiting lane starts as soon as a running one ends. Lanes run independently, so pre-flight refuses lanes that change the same file (per `### Files to Change`) or depend on each other.
-- **Result per lane** — `.yaawn/plans/yaawn-<issue>-overnight-result.md` **in the main copy**: the lane's **final block** from its worktree — each target's state and ELI5 summary, its review report, the last 20 output lines of every failed target, and one `run result:` line — plus `worktree:` and `branch:` lines. While the lane runs, the result is live: `#<issue> running — stage <stage>`, rewritten at lane start and at every stage. A stopped run replaces it with `#<issue> stopped in <stage>`. Session output is not streamed; only each target's last 20 lines are kept. The result is deleted for every lane at launch so an earlier run's result never looks current.
+- **Result per lane** — `.yaawn/plans/yaawn-<issue>-overnight-result.md` **in the main copy**: the lane's **final block** from its worktree — each target's state and ELI5 summary, its review report (prototypes skip the review, so their result has none), the last 20 output lines of every failed target, and one `run result:` line — plus `worktree:` and `branch:` lines. While the lane runs, the result is live: `#<issue> running — stage <stage>`, rewritten at lane start and at every stage. A stopped run replaces it with `#<issue> stopped in <stage>`. Session output is not streamed; only each target's last 20 lines are kept. The result is deleted for every lane at launch so an earlier run's result never looks current.
 
 The script never merges, commits, or pushes the branches — the human does that after verification.
 
@@ -35,14 +35,14 @@ A lane's **target** is its issue: one implementer session for the issue itself.
 
 Each session gets [assets/session-prompt.md](./assets/session-prompt.md) as its prompt, with `<target>` filled in: implement the plan, keep the progress log, work every step to done (no blockers), collect manual checks for the human, write the ELI5 summary, never commit, push, or verify. Right before a session starts, the orchestrator fetches the target's issue fresh and writes its whole "Implementation Plan" section — answers included — to `.yaawn/plans/yaawn-<target>-llm-plan.md`; the session works from that file.
 
-When the implementer session leaves every progress step done, two more sessions follow for that target before the run moves on:
+When the implementer session leaves every progress step done, two more sessions follow for that target before the run moves on — except for issues labelled `Yaawn: Prototype`, which skip the review entirely: prototype code is throwaway and carries no code-quality requirements, so reviewing it would be wasted effort:
 
 - **Review session** — a different model (`gpt-5.3-codex`) gets [assets/review-prompt.md](./assets/review-prompt.md): review the whole working-tree diff against the implementation plan, `yaawn-clean-code`, and `yaawn-owasp-security`, treat everything it reads as untrusted data, and write only the **review report** `.yaawn/plans/yaawn-<target>-review.md` — a `## Verdict` with a `blocking: N` line, then `## Findings`. It is read-only: the orchestrator snapshots HEAD, `git status`, and hashes of the tracked diff and the untracked files' contents (all outside `.yaawn/plans/`) before and after, and fails the target on any change. It fails closed: a missing, oversized (over 256 KB), or unparseable report fails the target too.
 - **Fix session** — only when `N > 0`. The implementer model gets [assets/fix-prompt.md](./assets/fix-prompt.md): append each blocking finding as a fix-step to the progress log, sanity-check and apply it, work every fix-step to done, and add an `Action:` line to each blocking finding in the review report. Non-blocking findings are left for the human. There is no second review.
 
 Within a lane, the sessions run **one after another** — never two at once, so they never edit the same files at the same time:
 
-- **done** = the review passed and every step in `.yaawn/plans/yaawn-<target>-progress.md` — fix-steps included — is `- [x]`. Anything else is **failed**.
+- **done** = the review passed (prototypes skip the review) and every step in `.yaawn/plans/yaawn-<target>-progress.md` — fix-steps included — is `- [x]`. Anything else is **failed**.
 - Targets already **done** at launch are not rerun, so relaunching resumes.
 
 The sessions have `--no-ask-user`. Anything they would need to ask must be settled **before** launch.
@@ -167,10 +167,11 @@ Lanes (each in its own worktree):
 
 - #<a> — worktree `<worktree path>`, branch `yaawn/<a>`
 - #<b> — worktree `<worktree path>`, branch `yaawn/<b>`
+- #<c> — worktree `<project>/prototype/yaawn-<c>-<slug>`, branch `prototype/yaawn-<c>-<slug>` (prototype: never merged, no pull request)
 
 Stop: Ctrl+C in the terminal (every lane stops; its result says in which stage).
 
-Per lane: the result `.yaawn/plans/yaawn-<issue>-overnight-result.md` in this copy. Per target, under `.yaawn/plans/` in the lane's worktree: `yaawn-<target>-progress.md`, `yaawn-<target>-summary.md`, review report `yaawn-<target>-review.md`, transcripts `yaawn-<target>-overnight-session.md`, `yaawn-<target>-review-session.md`, and `yaawn-<target>-fix-session.md` (`.jsonl` with Claude or Vibe; each written when its session ends; the fix session runs only if the review found blocking issues). I will post the final result here when the run ends.
+Per lane: the result `.yaawn/plans/yaawn-<issue>-overnight-result.md` in this copy. Per target, under `.yaawn/plans/` in the lane's worktree: `yaawn-<target>-progress.md`, `yaawn-<target>-summary.md`, review report `yaawn-<target>-review.md`, transcripts `yaawn-<target>-overnight-session.md`, `yaawn-<target>-review-session.md`, and `yaawn-<target>-fix-session.md` (`.jsonl` with Claude or Vibe; each written when its session ends; the fix session runs only if the review found blocking issues). Prototype targets skip the review: no review report, no review or fix session. I will post the final result here when the run ends.
 ````
 
 Then end your turn and wait. Do not poll the terminal or the result file — the harness notifies you when the background process ends.
@@ -179,11 +180,12 @@ Then end your turn and wait. Do not poll the terminal or the result file — the
 
 Reporting is read-only: never start, stop, or relaunch the run, never edit the issue or the plan, never commit or push, and never post anything to GitHub.
 
-**When the run ends** (the harness notifies you that the background process exited): read `.yaawn/plans/yaawn-<issue>-overnight-result.md` for every lane — done, failed, and stopped — and post it verbatim — with several lanes, each under a `## #<issue>` heading. Render the summaries and each target's `### Review` section (the review report with its findings and the fix session's `Action:` lines) as markdown, keep each failed target's output lines in their code block, and keep the `worktree:` and `branch:` lines. End with the `run result:` line from the terminal. Then add the next steps per lane:
+**When the run ends** (the harness notifies you that the background process exited): read `.yaawn/plans/yaawn-<issue>-overnight-result.md` for every lane — done, failed, and stopped — and post it verbatim — with several lanes, each under a `## #<issue>` heading. Render the summaries and each target's `### Review` section (the review report with its findings and the fix session's `Action:` lines; prototypes skip the review, so they have none) as markdown, keep each failed target's output lines in their code block, and keep the `worktree:` and `branch:` lines. End with the `run result:` line from the terminal. Then add the next steps per lane:
 
 - Review the diff in the lane's worktree, and the non-blocking review findings left for you.
 - Do the manual checks listed in each summary.
-- **done** lanes: start a new session **inside the lane's worktree** (`cd <worktree path>`), commit and push the `yaawn/<issue>` branch, then run `/yaawn-verify-executed-plan <issue>` there once — it opens the pull request. The run itself never commits or pushes.
+- **done** lanes (not prototypes): start a new session **inside the lane's worktree** (`cd <worktree path>`), commit and push the `yaawn/<issue>` branch, then run `/yaawn-verify-executed-plan <issue>` there once — it opens the pull request. The run itself never commits or pushes.
+- **done** lanes of issues labelled `Yaawn: Prototype` (their result carries a `prototype:` line): commit and push the `prototype/yaawn-<issue>-<slug>` branch, test the prototype with customers, then run `/yaawn-extract-learnings <issue>` — **not** `/yaawn-verify-executed-plan <issue>`. The branch is never merged to main and no pull request is opened.
 - **failed** lanes: the lane's result and the progress logs in its worktree show why; launching again resumes it in the same worktree.
 - **stopped** lanes (`#<issue> stopped in <stage>`): the run was stopped in that stage; launching again resumes it in the same worktree.
 

package/agents/skills/yaawn-implement-plan/scripts/agent.ts

@@ -5,7 +5,7 @@ import { succeeds } from "./targets.js";
 // from this fixed allow-list — never from the settings file or a flag as
 // free text — and is spawned with an argument array, never through a shell.
 
-const agentNames = ["copilot", "claude", "vibe"] as const;
+export const agentNames = ["copilot", "claude", "vibe"] as const;
 
 export type AgentName = (typeof agentNames)[number];
 

package/agents/skills/yaawn-implement-plan/scripts/overnight.ts

@@ -46,7 +46,7 @@ import {
   resultPath,
   unansweredQuestionTexts,
 } from "./targets.js";
-import { runsInOwnWorktree, worktreePath } from "./worktrees.js";
+import { isPrototype, runsInOwnWorktree, worktreePath } from "./worktrees.js";
 
 type RunState = "pending" | "running" | "done" | "failed" | "skipped";
 
@@ -530,6 +530,9 @@ async function runTarget(
   // failure output for diagnosis.
   recordExitCode(code, handle.agent, tail);
   if (!isDone(target.number)) return false;
+  // Prototypes skip the review: throwaway code carries no code-quality
+  // requirements, so a review would be wasted effort.
+  if (isPrototype(target.labels)) return true;
   announceStage(handle, "review");
   const blocking = await reviewTarget(target, tail, handle);
   if (blocking === null) return false;
@@ -687,10 +690,10 @@ async function runLaneCommand(
 ): Promise<void> {
   if (args.length !== 1 || !/^\d+$/.test(args[0])) throw new Error(usage);
   const parent = Number(args[0]);
-  const { title } = fetchIssue(parent);
-  if (!runsInOwnWorktree(parent, title)) {
+  const { title, labels } = fetchIssue(parent);
+  if (!runsInOwnWorktree(parent, title, labels)) {
     throw new Error(
-      `lane #${parent} must run in its worktree ${worktreePath(parent, title)}`,
+      `lane #${parent} must run in its worktree ${worktreePath(parent, title, labels)}`,
     );
   }
   mkdirSync(plansDir, { recursive: true });

package/agents/skills/yaawn-implement-plan/scripts/parallel.ts

@@ -13,10 +13,12 @@ import path from "node:path";
 import { createInterface } from "node:readline";
 import { createInterface as createPrompt } from "node:readline/promises";
 import type { Readable } from "node:stream";
+import { setTimeout as delay } from "node:timers/promises";
 import { promisify } from "node:util";
 import {
   type AgentChoice,
   type AgentName,
+  agentNames,
   readAgent,
 } from "./agent.js";
 import { keepMacAwakeWhileRunning, printWalkAwayBanner } from "./caffeinate.js";
@@ -38,7 +40,13 @@ import {
   laneOwners,
   lanePairs,
 } from "./groups.js";
-import { drainOutput } from "./processes.js";
+import {
+  type LeftoverSession,
+  drainOutput,
+  findLeftoverAgentSessions,
+  isProcessAlive,
+  killProcessGroupByPid,
+} from "./processes.js";
 import {
   type LaneOutcomeState,
   type StageLabel,
@@ -70,12 +78,12 @@ import {
 import {
   type MainCopyCheck,
   blockedUpdateReason,
-  branchName,
   describeMainCopyState,
   fetchMainCopy,
   git,
   isBareLayout,
-  laneWorktreePath,
+  isPrototype,
+  laneWorktreeAndBranch,
   registeredWorktrees,
   syncMainCopy,
 } from "./worktrees.js";
@@ -92,9 +100,11 @@ export interface LaunchRequest {
 type LaneState = LaneOutcomeState;
 
 // The lane issue's title names a new worktree directory; an existing checkout
-// of the lane branch is reused instead.
+// of the lane branch is reused instead. Its labels mark a prototype, whose
+// worktree and branch live under `prototype/`.
 interface TitledLane extends Lane {
   title: string;
+  labels: string[];
 }
 
 // What a pre-flight lookup found, or why it could not look.
@@ -119,6 +129,7 @@ interface LaneRun {
   lane: TitledLane;
   agent: AgentName;
   worktree: string;
+  branch: string;
   state: LaneState;
   stage: StageLabel;
   tail: string[];
@@ -219,9 +230,21 @@ function resolvedLane(issue: number): Lane {
 }
 
 function titledLane(lane: Lane): TitledLane {
-  return { ...lane, title: lane.targets[0].title };
+  const [issue] = lane.targets;
+  return { ...lane, title: issue.title, labels: issue.labels };
 }
 
+// Both the worktree path and its actual branch come from one porcelain
+// lookup, so a relaunch after a rename reports the branch that is really
+// checked out — never a branch recomputed from the new title.
+const laneWorktreeAndBranchFor = (
+  lane: TitledLane,
+): { path: string; branch: string } =>
+  laneWorktreeAndBranch(lane.issue, lane.title, lane.labels);
+
+const prototypeNote = (issue: number): string =>
+  `prototype: the branch is never merged and no pull request is opened — run /yaawn-extract-learnings ${issue}`;
+
 async function lookedUpLane(issue: number): Promise<Lookup<TitledLane[]>> {
   return lookup(
     resolveTargetsAsync(issue).then((targets) => [
@@ -266,9 +289,8 @@ function branchExists(branch: string): boolean {
 }
 
 // Reused on relaunch: an existing worktree keeps the work of an earlier run.
-function ensureWorktree(worktree: string, issue: number): void {
+function ensureWorktree(worktree: string, branch: string): void {
   if (registeredWorktrees().has(worktree) && existsSync(worktree)) return;
-  const branch = branchName(issue);
   const args = branchExists(branch)
     ? ["worktree", "add", worktree, branch]
     : ["worktree", "add", "-b", branch, worktree, "HEAD"];
@@ -475,7 +497,7 @@ function printMainCopyState(check: MainCopyCheck): void {
 }
 
 function worktreeFailures(lane: TitledLane): string[] {
-  const worktree = laneWorktreePath(lane.issue, lane.title);
+  const { path: worktree } = laneWorktreeAndBranchFor(lane);
   return existsSync(worktree) && !registeredWorktrees().has(worktree)
     ? [
         `lane #${lane.issue}: ${worktree} exists but is not a git worktree of this repository`,
@@ -702,7 +724,9 @@ function printImplementationGroups(groups: ImplementationGroup[]): void {
 }
 
 function describeLane(lane: TitledLane): string[] {
-  const header = `  #${lane.issue} — worktree ${laneWorktreePath(lane.issue, lane.title)}, branch ${branchName(lane.issue)}`;
+  const prototype = isPrototype(lane.labels) ? ` (${prototypeNote(lane.issue)})` : "";
+  const { path: worktree, branch } = laneWorktreeAndBranchFor(lane);
+  const header = `  #${lane.issue} — worktree ${worktree}, branch ${branch}${prototype}`;
   const targets = lane.targets.map((target, index) => {
     const after =
       target.dependsOn.length > 0
@@ -774,6 +798,8 @@ async function checkedLanes(
     ...mainCopyFailures(mainCopy, changes.value),
     ...conflicts,
   ];
+  const leftoversCleared =
+    failures.length === 0 && (await leftoverSessionsCleared(lanes));
   printLanes(lanes, request.maxParallel);
   printFailures(failures);
   printMainCopyState(mainCopy);
@@ -784,9 +810,123 @@ async function checkedLanes(
     if (!groups) printCompatibleSuggestion(lanes, conflicts);
     return null;
   }
+  if (!leftoversCleared) return null;
   return { lanes, changes: changes.value };
 }
 
+// --- leftover agent sessions
+
+const leftoverStopTimeoutMs = 5000;
+const leftoverPollIntervalMs = 250;
+
+// Paths come from the process table: control characters are replaced so
+// a crafted directory name cannot rewrite the terminal.
+const printable = (text: string): string =>
+  // eslint-disable-next-line no-control-regex -- matches the C0/C1 control characters a crafted path could use to rewrite the terminal
+  text.replace(/[\u0000-\u001f\u007f-\u009f]/g, "?");
+
+function describeLeftover(session: LeftoverSession): string {
+  const cwd = session.cwd === null ? "unreadable" : printable(session.cwd);
+  const worktree = session.worktree ?? "unknown";
+  return `  pid ${session.pid} — ${session.agent}, cwd ${cwd}, worktree ${worktree}`;
+}
+
+function printLeftovers(sessions: LeftoverSession[]): void {
+  console.log(
+    "--- agent sessions from a previous run are still running in the lane worktrees (an unreadable working directory counts, to fail closed)",
+  );
+  sessions.map(describeLeftover).forEach((line) => console.log(line));
+}
+
+async function scannedLeftovers(
+  lanes: TitledLane[],
+): Promise<LeftoverSession[] | null> {
+  const worktrees = lanes.map((lane) => laneWorktreeAndBranchFor(lane).path);
+  try {
+    return await findLeftoverAgentSessions(worktrees, agentNames);
+  } catch (error) {
+    printFailures([
+      `could not check for leftover agent sessions: ${errorMessage(error)}`,
+    ]);
+    return null;
+  }
+}
+
+// Anything but an explicit "stop" refuses: the orchestrator never kills on
+// its own, and never without a terminal to ask.
+async function leftoverChoice(): Promise<"stop" | "refuse"> {
+  if (!process.stdin.isTTY) {
+    console.log(
+      "no terminal to choose whether to stop them; refusing to start. Stop the sessions (or ask the human) before launching",
+    );
+    return "refuse";
+  }
+  const prompt = createPrompt({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await prompt.question(
+      "stop them, or refuse to start? [stop/refuse] (default: refuse) ",
+    );
+    return /^stop( them)?$/i.test(answer.trim()) ? "stop" : "refuse";
+  } finally {
+    prompt.close();
+  }
+}
+
+async function survivorsAfterStop(pids: number[]): Promise<number[]> {
+  const deadline = Date.now() + leftoverStopTimeoutMs;
+  let alive = pids.filter(isProcessAlive);
+  while (alive.length > 0 && Date.now() < deadline) {
+    await delay(leftoverPollIntervalMs);
+    alive = alive.filter(isProcessAlive);
+  }
+  return alive;
+}
+
+function signalLeftovers(pids: number[]): string[] {
+  return pids.flatMap((pid) => {
+    try {
+      killProcessGroupByPid(pid, "SIGTERM");
+      return [];
+    } catch (error) {
+      return [`could not stop pid ${pid}: ${errorMessage(error)}`];
+    }
+  });
+}
+
+async function stoppedLeftovers(sessions: LeftoverSession[]): Promise<boolean> {
+  const pids = sessions.map((session) => session.pid);
+  const signalFailures = signalLeftovers(pids);
+  const survivors = await survivorsAfterStop(pids);
+  const failures = [
+    ...signalFailures,
+    ...survivors.map(
+      (pid) =>
+        `pid ${pid} still running ${leftoverStopTimeoutMs / 1000}s after SIGTERM — not starting`,
+    ),
+  ];
+  printFailures(failures);
+  if (failures.length > 0) return false;
+  console.log("leftover agent sessions stopped");
+  return true;
+}
+
+// Runs after the lanes resolve and before the results print, only once
+// every other check passed, so the sessions of another active run (whose
+// lanes already fail the pre-flight) are never offered for stopping.
+async function leftoverSessionsCleared(lanes: TitledLane[]): Promise<boolean> {
+  const sessions = await scannedLeftovers(lanes);
+  if (sessions === null) return false;
+  if (sessions.length === 0) return true;
+  printLeftovers(sessions);
+  const choice = await leftoverChoice();
+  if (choice === "refuse") {
+    console.log("leftover agent sessions: chose to refuse to start");
+    return false;
+  }
+  console.log("leftover agent sessions: chose to stop them");
+  return stoppedLeftovers(sessions);
+}
+
 // Without a terminal nobody can answer: fail closed so preflight never
 // passes without a confirmation, and the caller asks the human instead.
 async function confirmedUncommittedChanges(): Promise<boolean> {
@@ -1026,7 +1166,8 @@ function laneReport(run: LaneRun, body: string): string {
   return [
     body,
     `worktree: ${run.worktree}`,
-    `branch: ${branchName(run.lane.issue)}`,
+    `branch: ${run.branch}`,
+    ...(isPrototype(run.lane.labels) ? [prototypeNote(run.lane.issue)] : []),
   ].join("\n\n");
 }
 
@@ -1088,7 +1229,7 @@ async function runLane(
   setState(run, "started");
   saveRunningResult(run);
   try {
-    ensureWorktree(run.worktree, run.lane.issue);
+    ensureWorktree(run.worktree, run.branch);
   } catch (error) {
     run.tail.push(
       `could not create worktree ${run.worktree}: ${errorMessage(error)}`,
@@ -1135,10 +1276,12 @@ function combinedResult(runs: LaneRun[]): string {
 }
 
 function newLaneRun(lane: TitledLane, agent: AgentName): LaneRun {
+  const { path: worktree, branch } = laneWorktreeAndBranchFor(lane);
   return {
     lane,
     agent,
-    worktree: laneWorktreePath(lane.issue, lane.title),
+    worktree,
+    branch,
     state: "started",
     stage: laneStartedLabel,
     tail: [],

package/agents/skills/yaawn-implement-plan/scripts/processes.ts

@@ -1,4 +1,6 @@
-import type { ChildProcess } from "node:child_process";
+import { type ChildProcess, execFile } from "node:child_process";
+import { realpathSync } from "node:fs";
+import path from "node:path";
 import type { Readable } from "node:stream";
 import { finished } from "node:stream/promises";
 import { setTimeout as delay } from "node:timers/promises";
@@ -51,3 +53,161 @@ export function killProcessGroup(
     if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error;
   }
 }
+
+// Signals a process group by its leader's pid. Never pid 0 or 1: -0 and -1
+// would reach the caller's own group or every process the user may signal.
+export function killProcessGroupByPid(
+  pid: number,
+  signal: NodeJS.Signals,
+): void {
+  if (!Number.isSafeInteger(pid) || pid <= 1) {
+    throw new Error(`refusing to signal invalid pid ${pid}`);
+  }
+  try {
+    process.kill(-pid, signal);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error;
+  }
+}
+
+// Signal 0 only checks: ESRCH means gone, EPERM means alive but not ours.
+export function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code !== "ESRCH";
+  }
+}
+
+// --- leftover agent sessions
+
+export interface LeftoverSession {
+  pid: number;
+  agent: string;
+  cwd: string | null;
+  worktree: string | null;
+}
+
+export interface CommandResult {
+  exitCode: number;
+  stdout: string;
+}
+
+// Resolves with the exit code when the command ran; rejects only when it
+// could not run at all (e.g. ENOENT). Always an argument array, never a shell.
+export type CommandRunner = (
+  command: string,
+  args: string[],
+) => Promise<CommandResult>;
+
+interface AgentProcess {
+  pid: number;
+  agent: string;
+}
+
+const maxCommandOutputBytes = 16 * 1024 * 1024;
+const processLinePattern = /^\s*(\d+)\s+(.+)$/;
+
+export const runCommand: CommandRunner = (command, args) =>
+  new Promise((resolve, reject) => {
+    execFile(
+      command,
+      args,
+      { encoding: "utf-8", maxBuffer: maxCommandOutputBytes },
+      (error, stdout) => {
+        const exitCode = (error as { code?: unknown } | null)?.code;
+        if (error && typeof exitCode !== "number") reject(error);
+        else resolve({ exitCode: error ? (exitCode as number) : 0, stdout });
+      },
+    );
+  });
+
+function agentProcessFrom(
+  line: string,
+  agentNames: readonly string[],
+): AgentProcess | null {
+  const match = processLinePattern.exec(line);
+  if (!match) return null;
+  const pid = Number(match[1]);
+  // macOS reports comm as the full executable path.
+  const agent = path.basename(match[2].trim());
+  if (!Number.isSafeInteger(pid) || pid <= 1 || pid === process.pid) return null;
+  return agentNames.includes(agent) ? { pid, agent } : null;
+}
+
+async function agentProcesses(
+  agentNames: readonly string[],
+  run: CommandRunner,
+): Promise<AgentProcess[]> {
+  const { exitCode, stdout } = await run("ps", ["-eo", "pid=,comm="]);
+  if (exitCode !== 0) throw new Error(`ps exited with code ${exitCode}`);
+  return stdout
+    .split("\n")
+    .map((line) => agentProcessFrom(line, agentNames))
+    .filter((found): found is AgentProcess => found !== null);
+}
+
+// A non-zero lsof exit means this one process is unreadable (it vanished or
+// belongs to someone else): null, so the caller fails closed and reports it.
+// lsof that cannot run at all rejects, so the whole check fails.
+async function workingDirectory(
+  pid: number,
+  run: CommandRunner,
+): Promise<string | null> {
+  const { exitCode, stdout } = await run("lsof", [
+    "-a",
+    "-d",
+    "cwd",
+    "-p",
+    String(pid),
+    "-Fn",
+  ]);
+  if (exitCode !== 0) return null;
+  const nameLine = stdout.split("\n").find((line) => line.startsWith("n/"));
+  return nameLine ? nameLine.slice(1) : null;
+}
+
+function canonicalPath(target: string): string {
+  try {
+    return realpathSync(target);
+  } catch {
+    return path.resolve(target);
+  }
+}
+
+function containingWorktree(cwd: string, worktrees: string[]): string | null {
+  const resolved = path.resolve(cwd);
+  return (
+    worktrees.find(
+      (worktree) =>
+        resolved === worktree || resolved.startsWith(worktree + path.sep),
+    ) ?? null
+  );
+}
+
+async function leftoverSession(
+  found: AgentProcess,
+  worktrees: string[],
+  run: CommandRunner,
+): Promise<LeftoverSession | null> {
+  const cwd = await workingDirectory(found.pid, run);
+  if (cwd === null) return { ...found, cwd: null, worktree: null };
+  const worktree = containingWorktree(cwd, worktrees);
+  return worktree === null ? null : { ...found, cwd, worktree };
+}
+
+// Agent sessions still running inside one of the worktrees. Stateless: a
+// process-name and working-directory scan. Throws when the scan cannot run.
+export async function findLeftoverAgentSessions(
+  worktrees: string[],
+  agentNames: readonly string[],
+  run: CommandRunner = runCommand,
+): Promise<LeftoverSession[]> {
+  const canonicalWorktrees = worktrees.map(canonicalPath);
+  const candidates = await agentProcesses(agentNames, run);
+  const sessions = await Promise.all(
+    candidates.map((found) => leftoverSession(found, canonicalWorktrees, run)),
+  );
+  return sessions.filter((session): session is LeftoverSession => session !== null);
+}

package/agents/skills/yaawn-implement-plan/scripts/targets.ts

@@ -10,6 +10,7 @@ export interface Issue {
   number: number;
   title: string;
   body: string;
+  labels: string[];
   dependsOn: number[];
   externalDependsOn: number[];
 }
@@ -18,6 +19,7 @@ interface RawIssue {
   number: number;
   title: string;
   body: string | null;
+  labels?: { name?: unknown }[] | null;
 }
 
 export const plansDir = ".yaawn/plans";
@@ -133,11 +135,20 @@ function parseDependsOn(body: string): number[] {
   return [...line.matchAll(/#(\d+)/g)].map((match) => Number(match[1]));
 }
 
-function toIssue({ number, title, body }: RawIssue): Issue {
+// Only string label names count; anything else gh might return is dropped.
+function rawLabelNames(labels: RawIssue["labels"]): string[] {
+  if (!Array.isArray(labels)) return [];
+  return labels
+    .map((label) => label?.name)
+    .filter((name): name is string => typeof name === "string");
+}
+
+function toIssue({ number, title, body, labels }: RawIssue): Issue {
   return {
     number,
     title,
     body: body ?? "",
+    labels: rawLabelNames(labels),
     dependsOn: parseDependsOn(body ?? ""),
     externalDependsOn: [],
   };
@@ -148,7 +159,7 @@ const fetchIssueArgs = (issue: number): string[] => [
   "view",
   String(issue),
   "--json",
-  "number,title,body",
+  "number,title,body,labels",
 ];
 
 const parseIssue = (output: string): Issue => toIssue(JSON.parse(output) as RawIssue);