fix(loop): bind historical validation to durable state

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 and probes both configured profiles before starting validation. When the target contains a durable active run created by an older owner-merged control plane, the launcher alone selects historical-target compatibility validation: installed runtime files remain hash-verified in the trusted bundle, while the target is checked for its stable state files, owner channel, JSON history, and evidence workflow. Callers cannot request this reduced target-only mode directly, and `restore-checkpoint` still 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 matching the local run to an automation-authored remote durable checkpoint, proving the clean exact branch and head, and proving the issue diff did not modify the protected control or verification plane. The installed internal validator then checks stable target state, owner channel, JSON history, and a conservatively parsed low-privilege evidence workflow. Callers and the public validation API cannot request this reduced mode, and `restore-checkpoint` still requires the durable exact branch, head, and clean worktree.
 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, only the installed activation router may select historical-target compatibility validation. It continues to hash-verify the complete installed control plane and both identities, then validates the target's stable state files, owner channel, JSON history, and evidence workflow. A caller-supplied compatibility flag is rejected; the subsequent restore still 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 an automation-authored remote durable checkpoint exactly matches the local active run, the worktree is on its clean exact branch and head, and the issue diff is proven not to modify the protected control or verification plane. The installed internal validator then checks stable target state, owner channel, JSON history, and conservatively rejects evidence workflows with unrecognized triggers or any job-level/write permission. 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.
 
 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/github-identity.mjs

@@ -14,6 +14,7 @@ import {
   readJson,
   sameGitHubLogin,
 } from './common.mjs'
+import { reconcileActiveJournal } from './active-journal.mjs'
 import {
   checkpointRecordDigest,
   parseCheckpointRecord,
@@ -1343,6 +1344,97 @@ function activationValidationRequested({ role, tool, args, loopRoot, trustedLoop
   )
 }
 
+async function authorizeHistoricalTargetValidation({
+  authorization,
+  loopRoot,
+  trustedLoopRoot,
+  realGit,
+  realGh,
+  realNode,
+  environment,
+}) {
+  const localIssue = authorization.issue
+  if (!localIssue?.runId) {
+    throw new Error('historical target validation requires a local active run')
+  }
+  const githubApi = async (endpoint) => {
+    const { stdout } = await execFileAsync(realGh, ['api', endpoint], {
+      env: environment,
+      maxBuffer: 1024 * 1024,
+    })
+    return JSON.parse(stdout)
+  }
+  const { activeCheckpoints } = await reconcileActiveJournal({
+    loopRoot,
+    githubPaginatedApi: (endpoint) =>
+      paginateGitHubApi(githubApi, endpoint.replace(/[?&]per_page=100$/, '')),
+  })
+  const durable = activeCheckpoints.find(
+    (checkpoint) => checkpoint.record.run.runId === localIssue.runId,
+  )
+  const run = durable?.record.run
+  const expectedHead = run?.headSha ?? run?.implementationCommit ?? run?.baseSha
+  if (
+    !run ||
+    run.finishedAt !== null ||
+    run.issueNumber !== localIssue.issueNumber ||
+    run.branch !== localIssue.branch ||
+    run.status !== localIssue.status ||
+    run.implementationCommit !== localIssue.implementationCommit
+  ) {
+    throw new Error(
+      'historical target validation requires the exact remote durable active checkpoint',
+    )
+  }
+
+  const repositoryRoot = repositoryRootForLoop(loopRoot)
+  const [branch, head, status] = await Promise.all([
+    execFileAsync(realGit, ['branch', '--show-current'], {
+      cwd: repositoryRoot,
+      env: environment,
+    }),
+    execFileAsync(realGit, ['rev-parse', 'HEAD'], {
+      cwd: repositoryRoot,
+      env: environment,
+    }),
+    execFileAsync(realGit, ['status', '--porcelain'], {
+      cwd: repositoryRoot,
+      env: environment,
+      maxBuffer: 1024 * 1024,
+    }),
+  ])
+  if (
+    branch.stdout.trim() !== run.branch ||
+    head.stdout.trim() !== expectedHead ||
+    status.stdout.trim()
+  ) {
+    throw new Error(
+      'historical target validation requires the clean exact durable branch and head',
+    )
+  }
+
+  await execFileAsync(
+    realNode,
+    [
+      path.resolve(trustedLoopRoot, 'scripts', 'validate-candidate-control-plane.mjs'),
+      '--loop-root',
+      path.resolve(loopRoot),
+      '--run-id',
+      run.runId,
+      '--base-sha',
+      run.baseSha,
+      '--head-sha',
+      expectedHead,
+    ],
+    {
+      cwd: repositoryRoot,
+      env: environment,
+      maxBuffer: 4 * 1024 * 1024,
+    },
+  )
+  return durable
+}
+
 function pullRequestWriteIntent(role, args, authorization) {
   const group = githubGroup(args)
   if (role === 'reviewer' && group.name === 'api') {
@@ -1920,13 +2012,54 @@ export async function runWithGitHubRole({
       ? hardenedGitArguments(args, { expectedRepository: channel.repository })
       : [...args]
   if (activationValidation) {
-    executionArgs = [
+    const fullValidationArguments = [
       args[0],
       'validate',
-      ...(authorization.issue ? ['--target-compatibility'] : []),
       '--loop-root',
       path.resolve(loopRoot),
     ]
+    try {
+      const { stdout } = await execFileAsync(executable, fullValidationArguments, {
+        env: childEnvironment,
+        maxBuffer: 4 * 1024 * 1024,
+      })
+      process.stdout.write(stdout)
+      return 0
+    } catch (fullValidationError) {
+      if (!authorization.issue?.runId) throw fullValidationError
+      await authorizeHistoricalTargetValidation({
+        authorization,
+        loopRoot,
+        trustedLoopRoot: trustedControlPlane.loopRoot,
+        realGit,
+        realGh,
+        realNode,
+        environment: childEnvironment,
+      })
+      try {
+        const { stdout } = await execFileAsync(
+          realNode,
+          [
+            path.resolve(
+              trustedControlPlane.loopRoot,
+              'scripts',
+              'validate-historical-target.mjs',
+            ),
+            '--loop-root',
+            path.resolve(loopRoot),
+          ],
+          {
+            env: childEnvironment,
+            maxBuffer: 4 * 1024 * 1024,
+          },
+        )
+        process.stdout.write(stdout)
+        return 0
+      } catch (historicalValidationError) {
+        historicalValidationError.cause = fullValidationError
+        throw historicalValidationError
+      }
+    }
   }
   const child = spawnCommand(executable, executionArgs, {
     env: childEnvironment,

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

@@ -44,7 +44,55 @@ export function validateFinalizationHistory(historyLines) {
   }
 }
 
-export async function validateLoop({
+function activeYamlLines(source) {
+  return source
+    .split(/\r?\n/)
+    .map((line) => line.replace(/\s+$/, ''))
+    .filter((line) => line.trim() && !line.trimStart().startsWith('#'))
+}
+
+function historicalWorkflowIsLowPrivilege(source) {
+  const lines = activeYamlLines(source)
+  const onIndex = lines.findIndex((line) => /^on:\s*(?:#.*)?$/.test(line))
+  if (onIndex === -1) return false
+  const onBlock = lines.slice(onIndex + 1).findIndex((line) => /^\S/.test(line))
+  const triggerLines =
+    onBlock === -1 ? lines.slice(onIndex + 1) : lines.slice(onIndex + 1, onIndex + 1 + onBlock)
+  if (
+    !triggerLines.some((line) => /^  pull_request:\s*(?:#.*)?$/.test(line)) ||
+    lines.some((line) => /^\s*pull_request_target\s*:/.test(line))
+  ) {
+    return false
+  }
+
+  const permissionIndexes = lines.flatMap((line, index) =>
+    /^permissions\s*:/.test(line) ? [index] : [],
+  )
+  if (
+    permissionIndexes.length !== 1 ||
+    !/^permissions:\s*(?:#.*)?$/.test(lines[permissionIndexes[0]]) ||
+    lines.some((line) => /^\s+permissions\s*:/.test(line))
+  ) {
+    return false
+  }
+  const permissionIndex = permissionIndexes[0]
+  const permissionBlockEnd = lines
+    .slice(permissionIndex + 1)
+    .findIndex((line) => /^\S/.test(line))
+  const permissionLines =
+    permissionBlockEnd === -1
+      ? lines.slice(permissionIndex + 1)
+      : lines.slice(permissionIndex + 1, permissionIndex + 1 + permissionBlockEnd)
+  const permissions = new Map()
+  for (const line of permissionLines) {
+    const match = line.match(/^  ([a-z-]+):\s*(read|none)\s*(?:#.*)?$/)
+    if (!match || permissions.has(match[1])) return false
+    permissions.set(match[1], match[2])
+  }
+  return permissions.get('contents') === 'read'
+}
+
+async function validateLoopMode({
   loopRoot = DEFAULT_LOOP_ROOT,
   activation = false,
   targetCompatibility = false,
@@ -97,6 +145,7 @@ export async function validateLoop({
     'scripts/lib/trusted-control-plane.mjs',
     'scripts/github-command-gate.mjs',
     'scripts/publish-review.mjs',
+    'scripts/validate-historical-target.mjs',
     'scripts/identity-bin/gh',
     'scripts/identity-bin/git',
     'scripts/lib/issue-claim.mjs',
@@ -199,11 +248,7 @@ export async function validateLoop({
     throw new Error('missing .github/workflows/issue-dev-loop-evidence.yml')
   }
   const evidenceWorkflowSource = await readFile(evidenceWorkflow, 'utf8')
-  if (
-    !evidenceWorkflowSource.includes('pull_request:') ||
-    evidenceWorkflowSource.includes('pull_request_target:') ||
-    !evidenceWorkflowSource.includes('permissions:\n  contents: read')
-  ) {
+  if (!historicalWorkflowIsLowPrivilege(evidenceWorkflowSource)) {
     throw new Error(
       'historical target evidence workflow must remain a low-privilege pull_request workflow',
     )
@@ -327,3 +372,15 @@ export async function validateLoop({
   }
   return { valid: true, checkedFiles: required.length + jsonFiles.length }
 }
+
+export function validateLoop(options = {}) {
+  return validateLoopMode({ ...options, targetCompatibility: false })
+}
+
+export function validateHistoricalTarget(options = {}) {
+  return validateLoopMode({
+    ...options,
+    activation: false,
+    targetCompatibility: true,
+  })
+}

loops/issue-dev-loop/scripts/loopctl.mjs

@@ -236,11 +236,13 @@ async function main() {
       )
       break
     case 'validate':
+      if (args['target-compatibility']) {
+        throw new Error('target compatibility validation is reserved to wrapped activation')
+      }
       output(
         await validateLoop({
           loopRoot,
           activation: Boolean(args.activation),
-          targetCompatibility: Boolean(args['target-compatibility']),
         }),
       )
       break

loops/issue-dev-loop/scripts/validate-historical-target.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+import path from 'node:path'
+
+import { parseArguments } from './lib/common.mjs'
+import { validateHistoricalTarget } from './lib/validation.mjs'
+
+const args = parseArguments(process.argv.slice(2))
+const loopRoot = args['loop-root'] ? path.resolve(args['loop-root']) : undefined
+const result = await validateHistoricalTarget({ loopRoot })
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)