@yaawn/workflow 0.3.1 → 0.5.0

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);