fix(loop): capability-gate historical activation

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, 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.
+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.
 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, 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.
+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.
 
 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

@@ -42,6 +42,7 @@ const roleFields = {
     environmentVariable: 'reviewerGitHubConfigEnvironmentVariable',
   },
 }
+const historicalValidationCapabilities = new WeakSet()
 
 const inheritedEnvironmentNames = new Set([
   'CI',
@@ -1344,6 +1345,104 @@ function activationValidationRequested({ role, tool, args, loopRoot, trustedLoop
   )
 }
 
+export function consumeHistoricalValidationCapability(capability) {
+  if (
+    (typeof capability !== 'object' && typeof capability !== 'function') ||
+    capability === null ||
+    !historicalValidationCapabilities.delete(capability)
+  ) {
+    throw new Error('historical target validation requires an authorized router 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,
+  environment,
+  run,
+  expectedHead,
+}) {
+  const [branch, head, status, indexState] = 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,
+    }),
+    execFileAsync(realGit, ['ls-files', '-v', '-z'], {
+      cwd: repositoryRoot,
+      env: environment,
+      maxBuffer: 8 * 1024 * 1024,
+    }),
+  ])
+  const concealedIndexEntries = indexState.stdout
+    .split('\0')
+    .filter(Boolean)
+    .filter((entry) => !entry.startsWith('H '))
+  if (concealedIndexEntries.length > 0) {
+    throw new Error(
+      'historical target validation rejects index concealment and nonstandard tracked state',
+    )
+  }
+  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',
+    )
+  }
+  try {
+    await execFileAsync(
+      realGit,
+      [
+        '-c',
+        'core.fileMode=true',
+        'diff',
+        '--quiet',
+        '--no-ext-diff',
+        '--no-textconv',
+        'HEAD',
+        '--',
+      ],
+      {
+        cwd: repositoryRoot,
+        env: environment,
+        maxBuffer: 1024 * 1024,
+      },
+    )
+  } catch (error) {
+    if (error?.code === 1) {
+      throw new Error(
+        'historical target validation requires tracked filesystem contents to match HEAD',
+      )
+    }
+    throw error
+  }
+}
+
 async function authorizeHistoricalTargetValidation({
   authorization,
   loopRoot,
@@ -1354,9 +1453,17 @@ async function authorizeHistoricalTargetValidation({
   environment,
 }) {
   const localIssue = authorization.issue
-  if (!localIssue?.runId) {
-    throw new Error('historical target validation requires a local active run')
-  }
+  const repositoryRoot = repositoryRootForLoop(loopRoot)
+  const [checkedOutBranch, checkedOutHead] = await Promise.all([
+    execFileAsync(realGit, ['branch', '--show-current'], {
+      cwd: repositoryRoot,
+      env: environment,
+    }),
+    execFileAsync(realGit, ['rev-parse', 'HEAD'], {
+      cwd: repositoryRoot,
+      env: environment,
+    }),
+  ])
   const githubApi = async (endpoint) => {
     const { stdout } = await execFileAsync(realGh, ['api', endpoint], {
       env: environment,
@@ -1369,49 +1476,34 @@ async function authorizeHistoricalTargetValidation({
     githubPaginatedApi: (endpoint) =>
       paginateGitHubApi(githubApi, endpoint.replace(/[?&]per_page=100$/, '')),
   })
-  const durable = activeCheckpoints.find(
-    (checkpoint) => checkpoint.record.run.runId === localIssue.runId,
+  const durableMatches = activeCheckpoints.filter(
+    (checkpoint) =>
+      checkpoint.record.run.branch === checkedOutBranch.stdout.trim() &&
+      durableCheckpointWorktreeHead(checkpoint.record) === checkedOutHead.stdout.trim(),
   )
+  const durable = durableMatches.length === 1 ? durableMatches[0] : null
   const run = durable?.record.run
-  const expectedHead = run?.headSha ?? run?.implementationCommit ?? run?.baseSha
+  const expectedHead = durable ? durableCheckpointWorktreeHead(durable.record) : null
   if (
     !run ||
     run.finishedAt !== null ||
-    run.issueNumber !== localIssue.issueNumber ||
-    run.branch !== localIssue.branch ||
-    run.status !== localIssue.status ||
-    run.implementationCommit !== localIssue.implementationCommit
+    (localIssue &&
+      (run.runId !== localIssue.runId ||
+        run.issueNumber !== localIssue.issueNumber ||
+        run.branch !== localIssue.branch))
   ) {
     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 assertCleanExactDurableWorktree({
+    realGit,
+    repositoryRoot,
+    environment,
+    run,
+    expectedHead,
+  })
 
   await execFileAsync(
     realNode,
@@ -1425,14 +1517,22 @@ async function authorizeHistoricalTargetValidation({
       run.baseSha,
       '--head-sha',
       expectedHead,
+      '--durable-issue-number',
+      String(run.issueNumber),
+      '--durable-implementation-commit',
+      run.implementationCommit ?? 'none',
+      '--durable-pr-head',
+      run.headSha ?? 'none',
     ],
     {
       cwd: repositoryRoot,
       env: environment,
       maxBuffer: 4 * 1024 * 1024,
     },
   )
-  return durable
+  const capability = Object.freeze({})
+  historicalValidationCapabilities.add(capability)
+  return { capability, durable, expectedHead, repositoryRoot, run }
 }
 
 function pullRequestWriteIntent(role, args, authorization) {
@@ -2026,8 +2126,7 @@ export async function runWithGitHubRole({
       process.stdout.write(stdout)
       return 0
     } catch (fullValidationError) {
-      if (!authorization.issue?.runId) throw fullValidationError
-      await authorizeHistoricalTargetValidation({
+      const historicalAuthorization = await authorizeHistoricalTargetValidation({
         authorization,
         loopRoot,
         trustedLoopRoot: trustedControlPlane.loopRoot,
@@ -2037,23 +2136,19 @@ export async function runWithGitHubRole({
         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)
+        const { validateLoop } = await import('./validation.mjs')
+        const result = await validateLoop({
+          loopRoot,
+          historicalCapability: historicalAuthorization.capability,
+        })
+        await assertCleanExactDurableWorktree({
+          realGit,
+          repositoryRoot: historicalAuthorization.repositoryRoot,
+          environment: childEnvironment,
+          run: historicalAuthorization.run,
+          expectedHead: historicalAuthorization.expectedHead,
+        })
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
         return 0
       } catch (historicalValidationError) {
         historicalValidationError.cause = fullValidationError

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

@@ -2,7 +2,10 @@ import { readFile, readdir } from 'node:fs/promises'
 import path from 'node:path'
 
 import { DEFAULT_LOOP_ROOT, pathExists, readJson, sameGitHubLogin } from './common.mjs'
-import { assertGitHubRoleIdentity } from './github-identity.mjs'
+import {
+  assertGitHubRoleIdentity,
+  consumeHistoricalValidationCapability,
+} from './github-identity.mjs'
 
 async function collectFiles(root, output = []) {
   const entries = await readdir(root, { withFileTypes: true })
@@ -79,7 +82,10 @@ function yamlSequenceMapping(line) {
   }
 }
 
-function conservativeYamlBlock(lines) {
+function conservativeYamlBlock(
+  lines,
+  { rejectFlowValues = true, rejectPermissionKeys = true } = {},
+) {
   let scalarParentIndent = null
   for (const line of lines) {
     const lineIndent = line.match(/^\s*/)?.[0].length ?? 0
@@ -90,8 +96,8 @@ function conservativeYamlBlock(lines) {
     if (
       !mapping ||
       mapping.quoted ||
-      mapping.key === 'permissions' ||
-      /^[{[]/.test(mapping.value) ||
+      (rejectPermissionKeys && mapping.key === 'permissions') ||
+      (rejectFlowValues && /^[{[]/.test(mapping.value)) ||
       /^[!&*]/.test(mapping.value)
     ) {
       return false
@@ -103,7 +109,7 @@ function conservativeYamlBlock(lines) {
   return true
 }
 
-function historicalWorkflowIsLowPrivilege(source) {
+export function historicalWorkflowIsLowPrivilege(source) {
   const lines = activeYamlLines(source)
   if (
     lines.some(
@@ -116,6 +122,14 @@ function historicalWorkflowIsLowPrivilege(source) {
   ) {
     return false
   }
+  if (
+    !conservativeYamlBlock(lines, {
+      rejectFlowValues: false,
+      rejectPermissionKeys: false,
+    })
+  ) {
+    return false
+  }
   const mappings = lines.map((line, index) => ({
     index,
     mapping: yamlMapping(line),
@@ -249,7 +263,6 @@ async function validateLoopMode({
     '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',
@@ -478,13 +491,14 @@ async function validateLoopMode({
 }
 
 export function validateLoop(options = {}) {
-  return validateLoopMode({ ...options, targetCompatibility: false })
-}
-
-export function validateHistoricalTarget(options = {}) {
-  return validateLoopMode({
-    ...options,
-    activation: false,
-    targetCompatibility: true,
-  })
+  const { historicalCapability, ...validatedOptions } = options
+  if (historicalCapability) {
+    consumeHistoricalValidationCapability(historicalCapability)
+    return validateLoopMode({
+      ...validatedOptions,
+      activation: false,
+      targetCompatibility: true,
+    })
+  }
+  return validateLoopMode({ ...validatedOptions, targetCompatibility: false })
 }