fix: avoid stale skill route stop loops

Author: rockyshi1993

hooks/_runtime/host-skill-route-capabilities.v1.json

@@ -13,10 +13,10 @@
       "status": "PASS",
       "testedVersion": "codex-cli 0.145.0",
       "protocol": "MCP 2024-11-05",
-      "runtimeContractDigest": "e1f1f244e0fc7cb6bb789abc18f11fe4e0e762ff611488de341277866b2142bb",
-      "hostAdapterDigest": "b2693a7aad1643fd7d21be90b7f73ba42b6c79f1eac405d3919bbb28a316ad20",
-      "evidenceDigest": "203c109eb4b9208035bc67c08ca632896428de795752c150773daa4f959b2b86",
-      "evidenceRef": "E:/Worker/.devcodex/devcodex/.audit-state/skill-route-s15-codex-20260729-full-closure-production.json",
+      "runtimeContractDigest": "4c225c1110a7a24d483c80870aca8b58c7a1d0f8864bf1b9d3a5937277e73065",
+      "hostAdapterDigest": "10710bef81d425e6df9c09a5c059c301aff85dfb701599337698ed105fca6172",
+      "evidenceDigest": "77a911f991b53769cdd4fb527292c74c9e7076694106e51534847abafc4e3a9f",
+      "evidenceRef": "E:/Worker/.devcodex/devcodex/.audit-state/skill-route-s15-codex-20260729-stale-stop-fix-production-r3.json",
       "entrySurface": "codex exec --ephemeral",
       "bootstrapDelivery": "user-global hooks.json UserPromptSubmit",
       "defaultEligible": true

hooks/_runtime/lifecycle.cjs

@@ -1722,7 +1722,8 @@ async function main() {
     if (eventName === 'Stop' && state.contextAcquisition?.contextEpoch) {
       try {
         const {
-          evaluateProgressiveSkillRouteStop
+          evaluateProgressiveSkillRouteStop,
+          shouldEnforceProgressiveSkillRouteStop
         } = require('./skill-route-tool.cjs')
         const routeStop = evaluateProgressiveSkillRouteStop({
           project: state.contextAcquisition.project,
@@ -1736,9 +1737,10 @@ async function main() {
         const explicitRoutePending =
           state.progressiveSkillRoute?.bootstrap?.explicitStatus === 'ready'
         if (
-          routeStop.present &&
-          !routeStop.complete &&
-          (routeStop.errorCode !== 'PLAN_NOT_COMMITTED' || explicitRoutePending)
+          shouldEnforceProgressiveSkillRouteStop(
+            routeStop,
+            explicitRoutePending
+          )
         ) {
           const enforceCount = Number(state.progressiveSkillRouteStopCount || 0)
           if (enforceCount < 2) {

hooks/_runtime/skill-route-tool.cjs

@@ -1172,6 +1172,25 @@ function evaluateProgressiveSkillRouteStop (input, options = {}) {
   }
 }
 
+const NON_RECOVERABLE_ROUTE_IDENTITY_ERRORS = new Set([
+  'MODE_CAPABILITY_STALE',
+  'RUNTIME_CONTRACT_STALE'
+])
+
+function shouldEnforceProgressiveSkillRouteStop (routeStop, explicitRoutePending) {
+  if (!routeStop?.present || routeStop.complete) return false
+  if (routeStop.errorCode === 'PLAN_NOT_COMMITTED') {
+    return explicitRoutePending === true
+  }
+  if (NON_RECOVERABLE_ROUTE_IDENTITY_ERRORS.has(routeStop.errorCode)) {
+    // A runtime/capability refresh invalidates the frozen turn identity. A
+    // non-explicit route has no body obligation, so fail closed without
+    // trapping Stop in a continuation that cannot repair the old envelope.
+    return explicitRoutePending === true
+  }
+  return true
+}
+
 function handleSkillRoute (input, options = {}) {
   const shapeError = validateRequestShape(input)
   if (shapeError) return makeToolError(input?.op || 'unknown', shapeError)
@@ -1266,6 +1285,7 @@ module.exports = {
   finalizeResponse,
   handleSkillRoute,
   evaluateProgressiveSkillRouteStop,
+  shouldEnforceProgressiveSkillRouteStop,
   formatSkillRouteBootstrapInjection,
   bootstrapSkillRouteForTurn,
   summarizePlan,

scripts/fixtures/skill-route-closure-trace.v1.json

@@ -34,7 +34,7 @@
     "S10": ["C06"],
     "S11": ["P02"],
     "S12": ["C07", "P10", "M05"],
-    "S13": ["M02", "M05"],
+    "S13": ["M02", "M05", "M08a"],
     "S14": ["M01", "M03"],
     "S15": ["M05"],
     "S16": ["C01", "C03"],
@@ -90,6 +90,7 @@
     "M06": {"owner": "scripts/test-global-install-smoke.js", "anchor": "real global install"},
     "M07": {"owner": "README.md", "anchor": "global-adapters apply"},
     "M08": {"owner": "scripts/test-skill-route-state.js", "anchor": "MODE_CAPABILITY_STALE"},
+    "M08a": {"owner": "scripts/test-skill-route-lifecycle.js", "anchor": "MODE_CAPABILITY_STALE"},
     "M09": {"owner": "scripts/test-global-install-smoke.js", "anchor": "host-native .agents/skills root"},
     "M10": {"owner": "scripts/test-skill-route-state.js", "anchor": "Acceptance T01a / T07 / M10"}
   }

scripts/test-skill-route-closure.js

@@ -57,6 +57,7 @@ const expectedTests = [
   'M02',
   'M02a',
   ...range('M0', 3, 9),
+  'M08a',
   'M10'
 ]
 

scripts/test-skill-route-lifecycle.js

@@ -9,6 +9,9 @@ const { spawnSync } = require('child_process')
 const {
   createSkillRouteFixture
 } = require('./lib/skill-route-test-fixture')
+const {
+  shouldEnforceProgressiveSkillRouteStop
+} = require('../hooks/_runtime/skill-route-tool.cjs')
 
 const RUNTIME = path.resolve(__dirname, '..', 'hooks', '_runtime', 'lifecycle.cjs')
 
@@ -106,6 +109,64 @@ function runLifecycle (fixture, payload = {}, env = {}) {
       childBefore.contextAcquisition.contextEpoch
     )
     assert.strictEqual(childAfter.progressiveSkillRouteStopCount || 0, 0)
+
+    assert.strictEqual(
+      shouldEnforceProgressiveSkillRouteStop({
+        present: true,
+        complete: false,
+        errorCode: 'MODE_CAPABILITY_STALE'
+      }, false),
+      false
+    )
+    assert.strictEqual(
+      shouldEnforceProgressiveSkillRouteStop({
+        present: true,
+        complete: false,
+        errorCode: 'MODE_CAPABILITY_STALE'
+      }, true),
+      true
+    )
+
+    const staleSession = 'non-explicit-runtime-refresh'
+    runLifecycle(fixture, {
+      session_id: staleSession,
+      prompt: 'Summarize the current implementation status'
+    })
+    const alternateSkillsRoot = path.join(fixture.root, 'alternate-skills')
+    fs.mkdirSync(path.join(alternateSkillsRoot, '_schemas'), { recursive: true })
+    fs.copyFileSync(
+      path.join(fixture.packageRoot, 'skills', 'portfolio.json'),
+      path.join(alternateSkillsRoot, 'portfolio.json')
+    )
+    for (const schema of [
+      'skill-intent.v1.schema.json',
+      'workflow-root-registry.v1.schema.json',
+      'progressive-skill-route.v1.schema.json'
+    ]) {
+      fs.copyFileSync(
+        path.join(fixture.packageRoot, 'skills', '_schemas', schema),
+        path.join(alternateSkillsRoot, '_schemas', schema)
+      )
+    }
+    fs.appendFileSync(
+      path.join(alternateSkillsRoot, '_schemas', 'skill-intent.v1.schema.json'),
+      '\n',
+      'utf8'
+    )
+    const staleStop = runLifecycle(fixture, {
+      hookEventName: 'Stop',
+      session_id: staleSession,
+      lastAssistantMessage: 'Implementation status summarized.'
+    }, {
+      DEVCODEX_GLOBAL_SKILLS_RUNTIME: alternateSkillsRoot
+    })
+    assert.doesNotMatch(staleStop.text, /Progressive Skill route is incomplete/)
+    const staleState = JSON.parse(fs.readFileSync(sessionFile(staleSession), 'utf8'))
+    assert.strictEqual(
+      staleState.progressiveSkillRouteStop.errorCode,
+      'RUNTIME_CONTRACT_STALE'
+    )
+    assert.strictEqual(staleState.progressiveSkillRouteStopCount || 0, 0)
   } finally {
     fixture.cleanup()
   }

skills/portfolio.json

@@ -11,10 +11,10 @@
     "pluginDigest": "705fe7c86c7225b67756749be5bb3b14a1ee3bffa386483a9ab61dc971f419ae",
     "portfolioEvidence": "skills/portfolio-evidence.json",
     "portfolioEvidenceDigest": "8364a73c66ed2ec9787cdb9300223278d128a45b689a2b8deda0d1f03189f42b",
-    "consumerInventoryFileCount": 482,
-    "consumerInventoryDigest": "4e64bbe16c22c73b0b4510c7ca628e0a3b32dad24b45f74ee6864990c3fc3ddd",
-    "consumerProjectionDigest": "2cf58088304bebaf95c778266bb663dda2b6dc934f08810e70247a9665604065",
-    "portfolioInputDigest": "02e808b3092e5f8e37a8f4168e5581e2918429cb839c97930718af3eef813cf6"
+    "consumerInventoryFileCount": 484,
+    "consumerInventoryDigest": "b41848c7674010854bda6ef9503b8a0ad3d725b7beabe021c9b7cc618bdcb727",
+    "consumerProjectionDigest": "536f496032116a06bc8598c46deb39d8d06b7794de0589c39ed2e23b13b90ea0",
+    "portfolioInputDigest": "388dfc88d475e57d9274319ee838caa8fab7b7ba66b0c1f83d54eafb5eb1689f"
   },
   "ordering": "skills.id asc; graph edges from/to asc",
   "summary": {
@@ -10760,6 +10760,10 @@
           "path": "scripts/fixtures/host-parity/unaligned-ledger.v1.json",
           "role": "current"
         },
+        {
+          "path": "scripts/fixtures/skill-route-closure-trace.v1.json",
+          "role": "current"
+        },
         {
           "path": "scripts/generate-skill-intents.js",
           "role": "current"
@@ -10940,10 +10944,18 @@
           "path": "scripts/test-skill-resolve.js",
           "role": "current"
         },
+        {
+          "path": "scripts/test-skill-route-closure.js",
+          "role": "current"
+        },
         {
           "path": "scripts/test-skill-route-contracts.js",
           "role": "current"
         },
+        {
+          "path": "scripts/test-skill-route-lifecycle.js",
+          "role": "current"
+        },
         {
           "path": "scripts/test-skill-route-state.js",
           "role": "current"
@@ -10987,7 +10999,9 @@
         "scripts/test-skill-intents.js",
         "scripts/test-skill-portfolio.js",
         "scripts/test-skill-resolve.js",
+        "scripts/test-skill-route-closure.js",
         "scripts/test-skill-route-contracts.js",
+        "scripts/test-skill-route-lifecycle.js",
         "scripts/test-skill-route-state.js",
         "scripts/test-visible-output-contract.js",
         "scripts/test-workflow-completion-contract.js",
@@ -11077,7 +11091,9 @@
           "scripts/test-skill-intents.js",
           "scripts/test-skill-portfolio.js",
           "scripts/test-skill-resolve.js",
+          "scripts/test-skill-route-closure.js",
           "scripts/test-skill-route-contracts.js",
+          "scripts/test-skill-route-lifecycle.js",
           "scripts/test-skill-route-state.js",
           "scripts/test-visible-output-contract.js",
           "scripts/test-workflow-completion-contract.js",