@1aboveio/skills 1.0.18 → 1.0.20

package/skills/engineering/resolve-issues/scripts/next-actions.mjs

@@ -5,7 +5,7 @@
 //   next-actions.mjs --run <run dir> [--capacity-json '<snapshot>' | --slots N] [--quiet-minutes 45] [--resume] [--sync] [--json] [--peek] [--mode full|narrow|off] [--rules] [--exit-due]
 //
 // Reads <run>/task-plan.json (units with status, stage, worker, workerSince, workspace,
-// dependsOn, pr, headSha, reviewedHead) and <run>/reviews/<unit>-r<N>.json (+ .fix.json; its head, complete, and
+// implementationOwner, dependsOn, pr, headSha, reviewedHead) and <run>/reviews/<unit>-r<N>.json (+ .fix.json; its head, complete, and
 // external.awaiting, and whether it holds a P0/P1). A unit with `worker`
 // set is busy. Actions, in priority order:
 //
@@ -75,6 +75,28 @@
 //                   fetch failed, it prints `sync` instead. A run never finishes on a tree it
 //                   could not read
 //
+// A unit's optional `implementationOwner` is the retained implement-or-fix conversation that outlives
+// the worker slot, recorded from the harness as { runId, sessionId?, cwd?, kind }: `runId` is the
+// attempt to resume, `kind` ("implement" or "fix", default "implement") says which worker owned it,
+// and `sessionId` and `cwd` (the unit's workspace) identify that conversation and its tree. It is
+// independent of `worker`, which records whichever worker is active now, so the owner survives the
+// review phase and a later fix continues the same conversation instead of starting over.
+//
+// Every action that spawns a worker therefore carries the structured continuation the coordinator
+// launches, beside its name: `continuation: "fresh"` for a first start or a new worker, launched
+// normally, with no retention argument (a saved conversation stays continuable by its id;
+// `retain_session: true` is optional protection a caller adds only for a long wait before cleanup).
+// Implement and fix sessions become the unit's owner; `continuation: "owner-resume"` with
+// `owner: { runId, kind, sessionId?, cwd? }` for a fix, a restack, or an unfinished implementation
+// whose owner is still usable (subagent_resume({ id: owner.runId, ... }) returns a new attempt on
+// the same conversation). `workerKind` names the slot the action launches. A review round is
+// always a fresh reviewer: a finished review
+// is never resumed, and a review recorded as an owner is not usable. An owner without a `runId`,
+// with a `kind` outside implement and fix, or whose `cwd` is not the unit's workspace is not usable,
+// so a fresh action reports ownerUnavailable rather than claiming continuity. A `retentionReleased`
+// marker records that optional protection lapsed, so it never makes an owner unusable. A completed
+// worker holds no slot: the owner is a reference, never an occupancy.
+//
 // Text output ends with one short line pointing to the skill path. With --resume or --rules it
 // ends with RULES instead, the rules a compaction summary most often drops (in narrow and off
 // modes, a one-line rules reminder for that mode).
@@ -120,6 +142,13 @@ import { BLOCKING } from './review-verdict.mjs'
 // No skill-owned concurrency default: the caller supplies fresh host capacity.
 // The only workers a unit runs (SKILL.md, Your role). A watcher is not a worker.
 export const WORKER_KINDS = Object.freeze(['implement', 'fix', 'review'])
+// The worker each worker-spawning action launches, in the plan's `workerKind` vocabulary. These are
+// the actions that carry a structured continuation (`continuation`, `workerKind`, `owner`) for the
+// coordinator.
+export const WORKER_ACTION_KINDS = Object.freeze({ 'fill-slot': 'implement', resume: 'implement', 'start-fix': 'fix', restack: 'fix', 'start-review': 'review' })
+// The kinds that may own a unit's implementation. A review is never resumed for the next round, so
+// it is not one.
+export const IMPLEMENTATION_OWNER_KINDS = Object.freeze(['implement', 'fix'])
 export const SKILL_PATH = join(dirname(dirname(fileURLToPath(import.meta.url))), 'SKILL.md')
 // Printed after every text call, and by rehydrate.mjs after a compaction.
 export const RULES = 'Per unit, run only implement, fix, and review workers, recorded as workerKind: no planning, architecture, product, or setup workers. You own preflight findings; use an optional explorer on the fleet explore row only for concrete planning unknowns (exploration.md). You coordinate: never edit product code. In full mode take every step from next-actions.mjs; in every mode the run ends only when it reports done. A HEAD after a passing review is carried; any other new HEAD takes the tier rereview-scope.mjs picks, never yours. Decide before you defer: a question a worker or review raises is answered and recorded, then the unit continues; retrying or deferring never answers it. Never block on the human: take the automatic answer and keep going. Fix the root cause, never only its symptom. Before each scheduling pass, refresh subagent_settings and pass its snapshot with --capacity-json; do not reuse a run-start budget or subtract workflow workers again.'
@@ -176,6 +205,25 @@ export function normalizeCapacity(input) {
 const hasWorker = (u) => u.worker !== undefined && u.worker !== null && u.worker !== ''
 const codeDone = (u) => u.stage === 'done'
 
+// A unit's usable implementation owner, normalized to { runId, kind, sessionId?, cwd? }, or null.
+// Usable means it names the attempt to resume (`runId`), its `kind` is an implement or fix worker
+// (never a reviewer: a finished review is never resumed for the next round), and, when both are
+// recorded, its `cwd` is the unit's workspace (a conversation cannot be resumed in another tree).
+// A plan that records nothing here keeps today's behavior: a fresh worker.
+export function implementationOwnerOf(unit) {
+  const saved = unit?.implementationOwner
+  if (!saved || typeof saved !== 'object' || Array.isArray(saved)) return null
+  if (saved.cwd !== undefined && saved.cwd !== null && typeof saved.cwd !== 'string') return null
+  const runId = typeof saved.runId === 'string' ? saved.runId.trim() : ''
+  const kind = saved.kind === undefined ? 'implement' : saved.kind
+  if (!runId || !IMPLEMENTATION_OWNER_KINDS.includes(kind)) return null
+  const cwd = typeof saved.cwd === 'string' ? saved.cwd.trim() : ''
+  const workspace = typeof unit.workspace === 'string' ? unit.workspace.trim() : ''
+  if (cwd && workspace && cwd !== workspace) return null
+  const sessionId = typeof saved.sessionId === 'string' ? saved.sessionId.trim() : ''
+  return { runId, kind, ...(sessionId ? { sessionId } : {}), ...(cwd ? { cwd } : {}) }
+}
+
 export function workspaceCleanupSettled(unit) {
   const result = unit.lifecycle?.cleanup
   return typeof unit.headSha === 'string' && unit.headSha.length > 0 && result?.headSha === unit.headSha &&
@@ -338,6 +386,18 @@ export function nextActions(plan, reviews = {}, capacity, { resume = false, now,
   }
   const actions = []
   const add = (action, u, detail) => actions.push({ action, unit: String(u.id), detail })
+  // Keep owners through delivery and their saved conversations through later repair.
+  // A new review round starts fresh even when the preceding session remains available.
+  const continuationFor = (u, workerKind) => {
+    const owner = workerKind === 'review' ? null : implementationOwnerOf(u)
+    if (owner) return { continuation: 'owner-resume', workerKind, owner }
+    const ownerUnavailable = workerKind !== 'review' && u.implementationOwner != null
+      ? 'Saved implementationOwner is malformed, names another role, or does not match the unit workspace; record replacement and retain its evidence.' : undefined
+    return { continuation: 'fresh', workerKind, ...(ownerUnavailable ? { ownerUnavailable } : {}) }
+  }
+  // Appended to an owner-resumed action: the work is the same, so the action keeps its name; only
+  // the launch changes, and it is a resume rather than a second worker for the unit.
+  const ownerNote = (id, owner) => `; launch it as a resume of unit ${id}'s implementation owner: subagent_resume({ id: ${JSON.stringify(owner.runId)}, prompt: <that brief or task> }) returns a new attempt on the same conversation${owner.sessionId ? ` (session ${owner.sessionId})` : ''}${owner.cwd ? ` in ${owner.cwd}` : ''}; record the returned id as implementationOwner.runId and keep the owner through review`
   const managed = (u) => plan.workspaceLifecycle === 1 || u.lifecycle?.version === 1
   for (const u of units) {
     if (TERMINAL.has(u.status) && hasWorker(u) && (u.status !== 'blocked' || reasonOk(u))) {
@@ -346,7 +406,7 @@ export function nextActions(plan, reviews = {}, capacity, { resume = false, now,
     }
     if (!managed(u) || u.status !== 'succeeded' || !u.workspace) continue
     if (!hasWorker(u) && !workspaceCleanupSettled(u)) {
-      add('cleanup-workspace', u, `unit ${u.id} landed: record lifecycle.cleanup with state applying and headSha ${u.headSha ?? '(record the delivered HEAD first)'}, then run cleanup-runs.mjs cleanup --run <run> --unit ${u.id} --revision <saved planRevision> --apply --json; inspect and persist the returned lifecycle. A refusal is retained with its reason, never complete; do this before finish and alongside independent units`)
+      add('cleanup-workspace', u, `unit ${u.id} landed: release any retain_session protection it still holds and record that acknowledgement (implementation.md#settle-session-retention), then record lifecycle.cleanup with state applying and headSha ${u.headSha ?? '(record the delivered HEAD first)'}, then run cleanup-runs.mjs cleanup --run <run> --unit ${u.id} --revision <saved planRevision> --apply --json; inspect and persist the returned lifecycle. A refusal is retained with its reason, never complete; do this before finish and alongside independent units`)
     }
   }
   const chainReady = []
@@ -637,6 +697,16 @@ export function nextActions(plan, reviews = {}, capacity, { resume = false, now,
   // One restack per unit per pass: the first reason found; the next pass sees the new HEAD.
   const restacked = new Set()
   for (let i = 0; i < actions.length; i++) if (actions[i].action === 'restack') { if (restacked.has(actions[i].unit)) actions.splice(i--, 1); else restacked.add(actions[i].unit) }
+  // One place attaches each worker action's continuation, so no site can spawn a worker without
+  // saying whether it starts fresh or resumes the unit's owner.
+  for (const a of actions) {
+    const workerKind = WORKER_ACTION_KINDS[a.action]
+    if (!workerKind) continue
+    const continuation = continuationFor(byId.get(a.unit), workerKind)
+    Object.assign(a, continuation)
+    if (continuation.owner) a.detail += ownerNote(a.unit, continuation.owner)
+    if (continuation.ownerUnavailable) a.detail += `; ${continuation.ownerUnavailable}`
+  }
   const busy = units.filter(hasWorker).length
   // The Harness already counted our workers along with other work and reservations.
   // Without a capacity source every worker-needing action is due: the harness spawn limit governs.
@@ -652,9 +722,14 @@ export function nextActions(plan, reviews = {}, capacity, { resume = false, now,
       const reviewReady = a.action !== 'start-review' || u.lifecycle?.resources?.some((r) => r.role === 'review' && r.state === 'ready')
       const needsPreparation = managed(u) && (u.lifecycle?.workspace?.state !== 'ready' || !reviewReady)
       const removalPending = managed(u) && u.lifecycle?.cleanup?.state === 'applying'
-      const admitted = removalPending ? { action: 'recover-workspace', unit: a.unit,
+      // A gating action keeps the worker action's continuation, so the launch stays explicit after
+      // the workspace is prepared or its cleanup is resolved.
+      const launch = { unit: a.unit, continuation: a.continuation, workerKind: a.workerKind,
+        ...(a.owner ? { owner: a.owner } : {}),
+        ...(a.ownerUnavailable ? { ownerUnavailable: a.ownerUnavailable } : {}) }
+      const admitted = removalPending ? { action: 'recover-workspace', ...launch,
         detail: `before ${a.action} for unit ${a.unit}, resolve its applying cleanup: inspect cleanup-runs.mjs recover --repo <repo-root> --json, collect any running cleanup operation's terminal result, and verify its receipt and every owned resource before updating lifecycle. Never admit a worker while removal of its environment is unresolved` }
-        : needsPreparation ? { action: 'prepare-workspace', unit: a.unit,
+        : needsPreparation ? { action: 'prepare-workspace', ...launch,
         detail: `before ${a.action} for unit ${a.unit}, record its exact workspace, branch, base SHA and lifecycle preparation intent${reviewReady ? '' : ', including its one review clone'}; run cleanup-runs.mjs prepare --run <run> --unit ${a.unit} --revision <saved planRevision> --apply --json and persist its returned ready identity. Reuse an existing matching workspace; never reset, replace or create another one on retry` } : a
       due.push(unlimited ? { ...admitted, detail: `${admitted.detail} [needs a free worker slot]` } : admitted)
       free--