fix(loop): unify durable resume head

Author: codeacme17

loops/issue-dev-loop/SKILL.md

@@ -7,7 +7,7 @@ Run exactly one bounded issue cycle. Treat [`LOOP.md`](./LOOP.md) as the constit
 ## Start safely
 
 1. Read `LOOP.md`, `state.md`, and `dependencies.md` completely.
-2. Require absolute `ECHO_UI_LOOP_CONTROL_PLANE` and `ECHO_UI_LOOP_TARGET_ROOT` values from the scheduler. Run activation through `"$ECHO_UI_LOOP_CONTROL_PLANE/scripts/with-github-identity" --loop-root "$ECHO_UI_LOOP_TARGET_ROOT" automation -- node "$ECHO_UI_LOOP_CONTROL_PLANE/scripts/loopctl.mjs" validate --activation --loop-root "$ECHO_UI_LOOP_TARGET_ROOT"`. The installed launcher verifies its hash manifest, probes both configured profiles, and attempts full validation first. It may fall back for an older target only after matching the local run to an automation-authored remote durable checkpoint, proving the clean exact branch and head without index concealment, and proving the issue diff did not modify the protected control or verification plane. A one-use in-memory router capability then checks stable target state, owner channel, JSON history, and a conservatively parsed low-privilege evidence workflow before rechecking the exact clean worktree. There is no standalone reduced validator, and callers and the public validation API cannot request this mode. `restore-checkpoint` still independently requires the durable exact branch, head, and clean worktree.
+2. Require absolute `ECHO_UI_LOOP_CONTROL_PLANE` and `ECHO_UI_LOOP_TARGET_ROOT` values from the scheduler. Run activation through `"$ECHO_UI_LOOP_CONTROL_PLANE/scripts/with-github-identity" --loop-root "$ECHO_UI_LOOP_TARGET_ROOT" automation -- node "$ECHO_UI_LOOP_CONTROL_PLANE/scripts/loopctl.mjs" validate --activation --loop-root "$ECHO_UI_LOOP_TARGET_ROOT"`. The installed launcher verifies its hash manifest, probes both configured profiles, and attempts full validation first. It may fall back for an older target only after excluding durably finalized runs, matching the worktree to an automation-authored remote active checkpoint, proving the clean event-derived branch and head without index concealment, and proving the issue diff did not modify the protected control or verification plane. A one-use in-memory router capability then checks stable target state, owner channel, JSON history, and a conservatively parsed low-privilege evidence workflow before rechecking the exact clean worktree. Activation, detection, and restore share the same event-derived head resolver. There is no standalone reduced validator, and callers and the public validation API cannot request this mode.
 3. Read [`references/github-operations.md`](./references/github-operations.md). Run every operational `loopctl`, executor GitHub command, remote Git command, trigger, and reviewer publication through the installed control plane with the explicit target root. Never use the credential-refusing repository launcher, invoke the `.mjs` router directly, install control code from an issue branch, or alter global `gh` or Git credential configuration.
 4. Run `loopctl.mjs reconcile` through the automation wrapper to rebuild verified terminal history, pending/completed evolve state, and active runs from the append-only GitHub state journal. It tombstones local terminal-cache rows with no durable counterpart before recomputing metrics. For returned `workType: resume`, fetch the recorded branch through the wrapper, create a clean isolated worktree at the returned exact head, and run `restore-checkpoint --run-id <id>` inside that worktree. The restore command rejects the wrong branch, a dirty checkout, or any head other than the durable head. Resume it before selecting a new issue.
 5. Run `loopctl.mjs evolve-status`. If `evolveDue` is true, start `echo_ui_loop_evolver` with fresh context; do not silently replace it with product work.

loops/issue-dev-loop/references/github-operations.md

@@ -10,7 +10,7 @@ Run every executor GitHub command through:
 
 `ECHO_UI_LOOP_CONTROL_PLANE` must name the versioned installation created from a clean owner-merged `dev`; `ECHO_UI_LOOP_TARGET_ROOT` names the active worktree's `loops/issue-dev-loop`. Operational `loopctl` and trigger commands must use the scripts inside the installed root and pass `--loop-root "$ECHO_UI_LOOP_TARGET_ROOT"`. The repository launcher intentionally refuses credentials.
 
-For a durable active run whose target predates newer trusted runtime files, the installed activation router attempts full validation first. Only if that fails may it select historical-target compatibility, and only after an automation-authored remote durable checkpoint exactly matches the local active run, the worktree is on its clean exact branch and head with no index concealment flags, and the issue diff is proven not to modify the protected control or verification plane. A one-use in-memory router capability then checks stable target state, owner channel, JSON history, and conservatively rejects unrecognized YAML, triggers, or job-level/write permissions before rechecking the worktree. No standalone reduced validator exists, and caller-supplied flags and the public validation API cannot select the reduced mode; the subsequent restore independently enforces the journal's exact branch and head on a clean worktree.
+For a durable active run whose target predates newer trusted runtime files, the installed activation router attempts full validation first. Only if that fails may it select historical-target compatibility, and only after excluding durably finalized runs, matching an automation-authored remote active checkpoint, proving its event-derived clean exact branch and head with no index concealment flags, and proving the issue diff does not modify the protected control or verification plane. A one-use in-memory router capability then checks stable target state, owner channel, JSON history, and conservatively rejects unrecognized YAML, triggers, or job-level/write permissions before rechecking the worktree. Activation, detection, and restore use the same checkpoint-head resolver. No standalone reduced validator exists, and caller-supplied flags and the public validation API cannot select the reduced mode.
 
 Run every reviewer publication command through the installed wrapper with role `reviewer`. Before reading either profile, it verifies every installed file, pins absolute Node/Git/`gh` executables, compares the target's security-critical owner-channel values to its trusted copy, removes token environment overrides, runs `gh api user`, and refuses an unexpected or owner identity. For Git, it clears global credential helpers and injects `gh auth git-credential` for the entire trusted child tree. Descendant `git` and `gh` processes pass through a role gate; arbitrary `sh`, `env`, Node scripts, caller PATH shims, and issue-worktree router changes are not authenticated. Never use owner credentials for executor or reviewer actions, never run raw remote `gh`/`git push` commands, and never call `gh auth setup-git`.
 

loops/issue-dev-loop/scripts/lib/active-journal.mjs

@@ -19,6 +19,7 @@ import {
   checkpointJournalConfiguration,
   checkpointPublicationBody,
   checkpointRecordDigest,
+  checkpointWorktreeHead,
   parseCheckpointRecord,
   validateCheckpointRecord,
   verifyPublishedCheckpoint,
@@ -227,7 +228,7 @@ async function defaultWorkspaceValidator({ loopRoot, record }) {
   if (branch.stdout.trim() !== record.run.branch) {
     throw new Error(`restore requires isolated worktree branch ${record.run.branch}`)
   }
-  const expectedHead = record.run.headSha ?? record.run.implementationCommit ?? record.run.baseSha
+  const expectedHead = checkpointWorktreeHead(record)
   if (head.stdout.trim() !== expectedHead) {
     throw new Error(`restore requires exact durable head ${expectedHead}`)
   }

loops/issue-dev-loop/scripts/lib/checkpoint-proof.mjs

@@ -13,6 +13,20 @@ import {
 
 const ACTIVE_STATUSES = new Set(['running', 'waiting_for_owner', 'awaiting_owner_review'])
 
+export function checkpointWorktreeHead(record) {
+  let expectedHead = record?.run?.baseSha
+  for (const event of record?.events ?? []) {
+    if (event.type === 'implementation_completed' && event.status === 'passed') {
+      expectedHead = event.payload?.commitSha
+    }
+    if (event.type === 'pr_published') expectedHead = event.payload?.headSha
+  }
+  if (!/^[0-9a-f]{40}$/i.test(expectedHead ?? '')) {
+    throw new Error('durable active checkpoint has no valid working head')
+  }
+  return expectedHead
+}
+
 export async function checkpointJournalConfiguration(loopRoot) {
   const channel = await readJson(
     path.resolve(loopRoot, '..', '_shared', 'owner-channel', 'channel.json'),

loops/issue-dev-loop/scripts/lib/finalization-journal.mjs

@@ -320,9 +320,8 @@ export async function recordFinalizationPublication({
   return { record, digest, commentUrl }
 }
 
-export async function reconcileFinalizationJournal({
+export async function loadDurableFinalizationRecords({
   loopRoot = DEFAULT_LOOP_ROOT,
-  now = new Date(),
   githubPaginatedApi = defaultGitHubPaginatedApi,
   githubApi = defaultGitHubApi,
   latestActiveCheckpoints = null,
@@ -380,6 +379,22 @@ export async function reconcileFinalizationJournal({
   effectiveRecords.sort(
     (left, right) => Date.parse(left.finishedAt) - Date.parse(right.finishedAt),
   )
+  return effectiveRecords
+}
+
+export async function reconcileFinalizationJournal({
+  loopRoot = DEFAULT_LOOP_ROOT,
+  now = new Date(),
+  githubPaginatedApi = defaultGitHubPaginatedApi,
+  githubApi = defaultGitHubApi,
+  latestActiveCheckpoints = null,
+} = {}) {
+  const effectiveRecords = await loadDurableFinalizationRecords({
+    loopRoot,
+    githubPaginatedApi,
+    githubApi,
+    latestActiveCheckpoints,
+  })
 
   const indexPath = path.join(loopRoot, 'logs', 'index.jsonl')
   const existing = (await readFile(indexPath, 'utf8'))

loops/issue-dev-loop/scripts/lib/github-identity.mjs

@@ -17,11 +17,13 @@ import {
 import { reconcileActiveJournal } from './active-journal.mjs'
 import {
   checkpointRecordDigest,
+  checkpointWorktreeHead,
   parseCheckpointRecord,
   validateCheckpointRecord,
   verifyLatestDurableCheckpoint,
 } from './checkpoint-proof.mjs'
 import { verifyPublishedEvolveRequest } from './evolve.mjs'
+import { loadDurableFinalizationRecords } from './finalization-journal.mjs'
 import {
   parseReviewPublisherArguments,
   reviewPublisherSyntheticGitHubArguments,
@@ -1355,20 +1357,6 @@ export function consumeHistoricalValidationCapability(capability) {
   }
 }
 
-export function durableCheckpointWorktreeHead(record) {
-  let expectedHead = record?.run?.baseSha
-  for (const event of record?.events ?? []) {
-    if (event.type === 'implementation_completed' && event.status === 'passed') {
-      expectedHead = event.payload?.commitSha
-    }
-    if (event.type === 'pr_published') expectedHead = event.payload?.headSha
-  }
-  if (!/^[0-9a-f]{40}$/i.test(expectedHead ?? '')) {
-    throw new Error('durable active checkpoint has no valid working head')
-  }
-  return expectedHead
-}
-
 async function assertCleanExactDurableWorktree({
   realGit,
   repositoryRoot,
@@ -1471,19 +1459,30 @@ async function authorizeHistoricalTargetValidation({
     })
     return JSON.parse(stdout)
   }
-  const { activeCheckpoints } = await reconcileActiveJournal({
+  const paginatedApi = (endpoint) =>
+    paginateGitHubApi(githubApi, endpoint.replace(/[?&]per_page=100$/, ''))
+  const { activeCheckpoints: allActiveCheckpoints } = await reconcileActiveJournal({
     loopRoot,
-    githubPaginatedApi: (endpoint) =>
-      paginateGitHubApi(githubApi, endpoint.replace(/[?&]per_page=100$/, '')),
+    githubPaginatedApi: paginatedApi,
   })
+  const finalizations = await loadDurableFinalizationRecords({
+    loopRoot,
+    githubPaginatedApi: paginatedApi,
+    githubApi,
+    latestActiveCheckpoints: allActiveCheckpoints,
+  })
+  const terminalRunIds = new Set(finalizations.map((record) => record.runId))
+  const activeCheckpoints = allActiveCheckpoints.filter(
+    (checkpoint) => !terminalRunIds.has(checkpoint.record.run.runId),
+  )
   const durableMatches = activeCheckpoints.filter(
     (checkpoint) =>
       checkpoint.record.run.branch === checkedOutBranch.stdout.trim() &&
-      durableCheckpointWorktreeHead(checkpoint.record) === checkedOutHead.stdout.trim(),
+      checkpointWorktreeHead(checkpoint.record) === checkedOutHead.stdout.trim(),
   )
   const durable = durableMatches.length === 1 ? durableMatches[0] : null
   const run = durable?.record.run
-  const expectedHead = durable ? durableCheckpointWorktreeHead(durable.record) : null
+  const expectedHead = durable ? checkpointWorktreeHead(durable.record) : null
   if (
     !run ||
     run.finishedAt !== null ||

loops/issue-dev-loop/scripts/lib/github.mjs

@@ -26,7 +26,7 @@ import { reconcileActiveJournal } from './active-journal.mjs'
 import { reconcileEvolveJournal } from './evolve.mjs'
 import { defaultReleaseIssueClaim } from './issue-claim.mjs'
 import { appendValidatedEvent, finalizeRun, readEvents, readRun } from './run-store.mjs'
-import { verifyLatestDurableCheckpoint } from './checkpoint-proof.mjs'
+import { checkpointWorktreeHead, verifyLatestDurableCheckpoint } from './checkpoint-proof.mjs'
 import { validateFinalizationHistory } from './validation.mjs'
 
 const PRIORITY = new Map([
@@ -168,10 +168,7 @@ export async function detectWork({
       workType: 'resume',
       runId: resumable.record.run.runId,
       branch: resumable.record.run.branch,
-      expectedHeadSha:
-        resumable.record.run.headSha ??
-        resumable.record.run.implementationCommit ??
-        resumable.record.run.baseSha,
+      expectedHeadSha: checkpointWorktreeHead(resumable.record),
       issue: {
         number: resumable.record.run.issueNumber,
         title: resumable.record.run.issueTitle,

loops/issue-dev-loop/tests/github-identity-routing.test.mjs

@@ -28,6 +28,10 @@ import {
   prepareEvolveRequestPublication,
   recordEvolveRequestPublication,
 } from '../scripts/lib/evolve.mjs'
+import {
+  canonicalFinalizationRecord,
+  finalizationRecordDigest,
+} from '../scripts/lib/finalization-proof.mjs'
 import { resolveExecutable } from '../scripts/lib/github-identity.mjs'
 
 const execFileAsync = promisify(execFile)
@@ -67,6 +71,7 @@ async function createFixture({
   historicalActivation = false,
   remoteCheckpoint = true,
   removeLocalRun = false,
+  terminalFinalization = false,
 } = {}) {
   const parent = await mkdtemp(path.join(os.tmpdir(), 'echo-ui-identity-routing-'))
   const loopRoot = path.join(parent, 'issue-dev-loop')
@@ -305,10 +310,60 @@ async function createFixture({
         'utf8',
       )
     }
+    if (terminalFinalization) {
+      const finalization = {
+        schemaVersion: 1,
+        runId: run.runId,
+        issueNumber: run.issueNumber,
+        status: 'cancelled',
+        startedAt: run.startedAt,
+        finishedAt: '2026-07-23T00:06:00.000Z',
+        prUrl: run.prUrl,
+        headSha,
+        mergeSha: null,
+        failureFingerprint: null,
+        notificationUrl: null,
+        readyNotificationUrl: null,
+        readyNotifiedAt: null,
+        completionNotifiedAt: null,
+        notificationWebhookStatus: null,
+        predecessorCheckpointUrl: null,
+        predecessorCheckpointDigest: null,
+        pauseStartedAt: null,
+        notificationNotifiedAt: null,
+      }
+      const finalizationBody = [
+        `<!-- issue-dev-loop:finalization:${run.runId}:sha256:${finalizationRecordDigest(finalization)} -->`,
+        '```json',
+        canonicalFinalizationRecord(finalization),
+        '```',
+      ].join('\n')
+      const finalizationComment = {
+        id: 3,
+        user: { login: 'executor-user' },
+        body: finalizationBody,
+        html_url: 'https://github.com/example/repo/issues/999#issuecomment-3',
+        created_at: finalization.finishedAt,
+      }
+      const journal = JSON.parse(
+        await readFile(path.join(parent, 'checkpoint-journal.json'), 'utf8'),
+      )
+      await writeFile(
+        path.join(parent, 'checkpoint-journal.json'),
+        `${JSON.stringify([...journal, finalizationComment])}\n`,
+        'utf8',
+      )
+      await writeFile(
+        path.join(parent, 'finalization-comment.json'),
+        `${JSON.stringify(finalizationComment)}\n`,
+        'utf8',
+      )
+    }
     await writeFile(
       path.join(parent, 'live-pr.json'),
       `${JSON.stringify({
-        state: 'open',
+        state: terminalFinalization ? 'closed' : 'open',
+        merged: false,
         draft: liveDraft,
         user: { login: 'executor-user' },
         base: { ref: 'dev', repo: { full_name: 'example/repo' } },
@@ -454,6 +509,7 @@ if (commandArguments[0] === 'validate' && ${JSON.stringify(historicalActivation)
     `export async function validateLoop() {
   return { valid: true, historicalTargetCompatibility: true }
 }
+export function validateFinalizationHistory() {}
 `,
     'utf8',
   )
@@ -507,6 +563,10 @@ if [ "$1 $2 $3 $4" != "api user --jq .login" ]; then
     first_line "$parent_dir/evolve-comment.json"
     exit 0
   fi
+  if [ "$1" = "api" ] && [ "$2" = "repos/example/repo/issues/comments/3" ]; then
+    first_line "$parent_dir/finalization-comment.json"
+    exit 0
+  fi
   if [ "$1 $2" = "pr review" ]; then
     echo "comment review published"
     exit 0
@@ -917,6 +977,33 @@ test('wrapped activation can select an exact durable checkpoint without local ru
   })
 })
 
+test('wrapped activation excludes checkpoints superseded by durable finalization', async () => {
+  const fixture = await createFixture({
+    historicalActivation: true,
+    removeLocalRun: true,
+    terminalFinalization: true,
+  })
+  await assert.rejects(
+    execFileAsync(
+      routerLauncherPath,
+      [
+        '--loop-root',
+        fixture.loopRoot,
+        'automation',
+        '--',
+        process.execPath,
+        fixture.loopctlPath,
+        'validate',
+        '--activation',
+        '--loop-root',
+        fixture.loopRoot,
+      ],
+      { env: fixture.env },
+    ),
+    /historical target validation requires the exact remote durable active checkpoint/,
+  )
+})
+
 test('wrapped activation rejects local active state that differs from its durable checkpoint', async () => {
   const fixture = await createFixture({ historicalActivation: true })
   const runPath = path.join(fixture.loopRoot, 'logs', 'runs', 'fixture-run', 'run.json')