@dzhechkov/harness-core 0.4.5 → 0.5.1

package/src/guard.ts

@@ -73,6 +73,19 @@ export interface GuardFacts {
   readonly skillPacks?: readonly { readonly name: string; readonly nonRegistrable: readonly string[] }[];
   /** for readme-first: per publishable package, is a version bump staged without a README change? */
   readonly readmeFirst?: readonly { readonly name: string; readonly versionBumped: boolean; readonly readmeChanged: boolean }[];
+  /**
+   * for agents-md-policy-sync: result of the pure policy drift detector, gathered by the CLI.
+   * `applicable:false` is a repo whose canonical policy sources are unreadable; omission means the
+   * gatherer could not obtain evidence. `fenced` says whether the repo OPTED IN — i.e. its AGENTS.md
+   * already carries a `dz:policies` fence. The two combine to separate a repo that is out of scope
+   * (never opted in — silent) from one that opted in and then lost its sources (loud), so the shared
+   * `notes` channel does not carry a permanent "not applicable" line in every consumer repo.
+   */
+  readonly policyDrift?: {
+    readonly applicable: boolean;
+    readonly drifted: readonly string[];
+    readonly fenced?: boolean;
+  };
   /**
    * for lockfile-in-sync: what each workspace package DECLARES vs what pnpm-lock.yaml RECORDS for that
    * importer. `parsed:false` (or the fact absent) ⇒ the rule reports nothing — fail-open by construction,
@@ -227,6 +240,7 @@ export const DEFAULT_RULES: readonly GuardRule[] = [
   { id: 'readme-consistency', severity: 'soft', ops: ['publish'], description: 'README counts agree (CJM header vs All Commands, etc.)' },
   { id: 'skills-registrable', severity: 'soft', ops: ['publish'], description: 'every skill directory in a skill pack has a depth-1 SKILL.md (a buried or missing one ships un-registrable — the health-advisor 1.2.0 class)' },
   { id: 'readme-first', severity: 'soft', ops: ['publish'], description: 'a package with a staged version bump must update its own README.md in the same change (README-first)' },
+  { id: 'agents-md-policy-sync', severity: 'soft', ops: ['publish'], description: 'proves the AGENTS.md copy is in SYNC with its source — not that the runtime read or obeyed it; heal drift with dz agents-sync' },
   { id: 'lockfile-in-sync', severity: 'soft', ops: ['publish'], description: 'every workspace @dzhechkov/* dependency spec matches the specifier pnpm-lock.yaml records for that importer (a dep bump without a lockfile refresh breaks CI with ERR_PNPM_OUTDATED_LOCKFILE). SOFT-ONLY — a config cannot promote it to HARD' },
   { id: 'store-bloat-cap', severity: 'soft', ops: ['teach', 'consolidate'], description: 'the learned store is within its size cap' },
   // Description ASSEMBLED from STUB_MARKERS so guard.ts itself stays clean under the scan it defines
@@ -323,6 +337,16 @@ const CHECKERS: Record<string, (f: GuardFacts, sev: GuardSeverity) => Violation[
     }
     return out;
   },
+  'agents-md-policy-sync': (f, _sev) => {
+    const fact = f.policyDrift;
+    if (!fact || fact.applicable !== true || !Array.isArray(fact.drifted)) return [];
+    const drifted = fact.drifted.filter((item) => typeof item === 'string');
+    return drifted.length === 0 ? [] : [{
+      rule: 'agents-md-policy-sync',
+      severity: 'soft',
+      detail: `${drifted.length} AGENTS.md policy section(s) are out of sync: ${drifted.slice(0, 8).join(', ')}${drifted.length > 8 ? '…' : ''} — heal with: dz agents-sync`,
+    }];
+  },
   'lockfile-in-sync': (f, _sev) => {
     // The 2026-07-28 CI break, mechanized: an overnight dep bump edited package.json and left
     // pnpm-lock.yaml stale, so `pnpm install --frozen-lockfile` died with ERR_PNPM_OUTDATED_LOCKFILE.
@@ -417,7 +441,7 @@ const CHECKERS: Record<string, (f: GuardFacts, sev: GuardSeverity) => Violation[
  * may not understand a file, and "I might be wrong" plus "block the publish" is the wrong pair. Disabling
  * such a rule stays allowed — only the promotion is refused.
  */
-export const SOFT_ONLY_RULES: readonly string[] = ['lockfile-in-sync'];
+export const SOFT_ONLY_RULES: readonly string[] = ['lockfile-in-sync', 'agents-md-policy-sync'];
 
 /**
  * A well-formed PROMOTED rule: an id the engine does not know, made enforceable by a template +
@@ -533,6 +557,17 @@ export function evaluateGuard(facts: GuardFacts, rules: readonly GuardRule[] = D
       notes.push(`no-stubs: ${skipped} changed scannable file(s) not scanned (deleted/oversize/unreadable/beyond the file cap) — the stub scan is fail-open, so this is a coverage gap on the record, not a violation`);
     }
   }
+  if (checked.includes('agents-md-policy-sync')) {
+    // A repo that never opted in (no `dz:policies` fence in AGENTS.md) is OUT OF SCOPE, not
+    // inconclusive — noting it on every run would put a permanent line in a channel that exists to
+    // flag genuine coverage gaps, and a note that is always there is a note nobody reads.
+    // Opted in but sources unreadable IS a gap, and stays loud.
+    if (facts.policyDrift === undefined) {
+      notes.push('agents-md-policy-sync: policy drift evidence was unavailable; the advisory rule skipped with a recorded coverage gap, not a silent pass');
+    } else if (facts.policyDrift.applicable !== true && facts.policyDrift.fenced === true) {
+      notes.push('agents-md-policy-sync: this repository carries a dz:policies fence but its canonical policy sources are unreadable — the advisory rule could not compare, and that gap is on the record, not a silent pass');
+    }
+  }
   return { op, verdict, violations, checked, ...(notes.length > 0 ? { notes } : {}) };
 }
 

package/src/index.ts

@@ -24,8 +24,13 @@ export {
   GATE_FEATURE_IDS,
   computeParity,
   buildParityMatrix,
+  CAPABILITY_EVIDENCE,
+  findUnbackedCapabilities,
+  findStaleTranscriptEvidence,
+  newestRecordedRuntimeVersion,
+  downgradeForStaleEvidence,
 } from './parity.js';
-export type { RuntimeCapability, FeatureForm, ParityFeature, ParityCell, ParityMatrixRow } from './parity.js';
+export type { RuntimeCapability, FeatureForm, ParityFeature, ParityCell, ParityReportCell, ParityMatrixRow, CapabilityEvidence, UnbackedCapability, ProbedRuntimeVersions } from './parity.js';
 export * from './operations.js';
 // workflows.ts: the ADR-005 templates are RETIRED (feature loop-designer, AM-6) — the module is a
 // deprecation shim (empty WORKFLOW_NAMES). BREAKING for external harness-core consumers of
@@ -35,7 +40,13 @@ export * from './workflows.js';
 // loop-designer (feature loop-designer): loop-plan/1 schema + generator + lint + trace planes.
 export * from './loop-plan.js';
 export * from './loop-plan-graph.js';
+// loop-run-semantics: the ONE home of the enactment DECISIONS both enactors use — the generated
+// Claude-host script (via the always-on `loop-semantics` blob) and `dz workflow run` (by import).
+export * from './loop-run-semantics.js';
 export * from './loop-render.js';
+// dz workflow run (feature dz-workflow-run): the pure scheduler + the dispatcher seam.
+export * from './workflow-run.js';
+export * from './workflow-run-dispatch.js';
 // loop-lint: EXPLICIT export list (QE round-2 G14) — `dominators`, the deliberately-WEAKER
 // analysis kept in src/loop-lint.ts solely as AM-1's mutation seam, is NOT part of the published
 // API surface; the in-package tests reach it via the module path directly.
@@ -76,6 +87,30 @@ export { pretrain } from './pretrain.js';
 export { loadPatterns, loadSessions, computePatternBoost, readLearningConfig, readMemoryLearningConfig, BOOST_CAP, recordPattern, loadStorePatternsSync, loadStoreRecords, patternToRecord, recordToPattern, patternRecordId, patternIdentityOf, dreamRecordId, isMirrorableLearning, consolidateSessions, recallPatterns, pruneNoisePatterns, removePatternsByIds, snapshotStore, readReinforcementState, encodeReinforcementState, reinforcePattern, updateReinforcementState, storeStats, lessonDeltaReport, lessonDeltaMap, readQuarantineState, encodeQuarantineState, promotePatterns, quarantineExpiryCandidates, pruneQuarantinePatterns } from './patterns.js';
 export { withStoreLock, withStoreLockSync, storeLockPath, StoreLockTimeoutError, StoreLockCompromisedError, STALE_LOCK_MS, LOCK_TIMEOUT_MS } from './store-lock.js';
 export type { StoreLockOptions } from './store-lock.js';
+export { withNamedLockSync, namedLockPath, isSafeLockName, NamedLockNameError, NamedLockTimeoutError, NamedLockCompromisedError } from './named-lock.js';
+export {
+  QE_BRIDGE_SCHEMA,
+  QE_BRIDGE_FAILURE_SCHEMA,
+  CLAUDE_BRIDGE_PROMPT_CEILING_CHARS,
+  KNOWN_CLAUDE,
+  BRIDGE_MARKER,
+  BRIDGE_FENCE_LABEL,
+  BRIDGE_EXTRACT_END,
+  isSafeClaudeId,
+  CLAUDE_ISOLATION_ARGS,
+  BRIDGE_FAILURE_REASONS,
+  extractClaudeResult,
+  buildBridgeSignoffRecord,
+  claudeProbeArgs,
+  interpretClaudeProbe,
+  claudeReviewArgs,
+  defangSignoffEchoes,
+  buildBridgePrompt,
+  parseBridgeOutput,
+  buildBridgeFailureRecord,
+  renderBridgeReport,
+} from './qe-bridge.js';
+export type { BridgeFamily, BridgeFailureReason, BridgeFinding, BridgeSignoff, BridgeParse, BridgeParseOk, BridgeParseFail, BridgeChannels, BridgeAudit, ClaudeResultExtraction, NamedExtract, BridgePromptInput } from './qe-bridge.js';
 export type { PatternRecord, SessionRecord, LearningConfig, MemoryLearningConfig, LoadOptions, ConsolidateResult, ConsolidateOptions, SqliteBackendMode, RecallHit, SessionsSource, PruneNoiseResult, RemovePatternsResult, SnapshotStoreResult, ReinforcementState, ReinforcePatternResult, StoreStats, LessonDeltaReport, LessonDeltaRow, QuarantineState, PromoteResult, QuarantineExpiryCandidate } from './patterns.js';
 export { DEFAULT_REINFORCE_THRESHOLD, NoopLearningBackend, NativeReinforcementBackend, resolveLearningBackend, isLearningSignalBackend } from './learning-backend.js';
 export type { LearningSignalBackend, LearningSignalStats, LearningSample, SignalCandidate, EnhanceContext, TrainingResult, LearningBackendMode } from './learning-backend.js';
@@ -196,6 +231,9 @@ export {
   serializeTrainingPair,
   trainingPairPath,
   trainingPairAppendCmd,
+  // wave1-instrument-repair (ADR-003 Condition 3): the persist allowlist + composite shape check.
+  codeCheckpointPersistAllowed,
+  codeStageResultShapeValid,
 } from './feature-adr-checkpoints.js';
 export type { CheckpointStage, CheckpointEntry, ResumeMode, ResumeDecision, ParsedCheckpointRead, TrainingPairFamily, TrainingPair, TrainingPairEvaluation, TrainingPairProvenance, TrainingPairTruncation } from './feature-adr-checkpoints.js';
 export {
@@ -257,6 +295,9 @@ export {
   shouldCompactRecallUsageLogSize,
   compactRecallUsageLog,
   compactRecallUsageLogChecked,
+  appendRecallUsage,
+  runtimeOf,
+  RUNTIMES,
 } from './recall-usage.js';
 export type {
   RecallUsageReadRecord,
@@ -271,7 +312,74 @@ export type {
   CompactRecallUsageOptions,
   CompactRecallUsageResult,
   CompactRecallUsageStatus,
+  AppendRecallUsageInput,
+  AppendRecallUsageHit,
+  Runtime,
 } from './recall-usage.js';
+
+/* crossrt-2-codex-hooks (leg 2 of umbrella 98ed3967) */
+export { mergeManagedHookEntries, hookCommandsOf } from './managed-hooks.js';
+export type { HookMergePlan, MergeManagedHookOptions, ManagedHookEntry } from './managed-hooks.js';
+export {
+  CODEX_MANAGED_HOOKS,
+  DZ_HOOK_HELPER_VERSION,
+  DZ_HOOK_TIMEOUT_SECONDS,
+  DZ_VETO_MATCHER,
+  buildHookCommand,
+  buildManagedEntries,
+  buildCodexHookManifest,
+  codexHooksPaths,
+  diffCodexHooks,
+  emitterWriteSet,
+  expectedTrustKey,
+  isDzManagedEntry,
+  isSafeForSingleQuote,
+  looksLikeDzEntry,
+  managedByEvent,
+  parseCodexRegistry,
+  parseCodexHookManifest,
+  planCodexHooks,
+  removeCodexHooks,
+  renderTrustBlock,
+  runtimeWriteSet,
+  selectOwnHookMetadata,
+  serializeCodexRegistry,
+  codexHookSha256,
+  trustEventName,
+  upsertTrustBlock,
+} from './codex-hooks.js';
+export type {
+  CodexHookEvent,
+  CodexHookId,
+  CodexHookManifest,
+  CodexHookManifestEntry,
+  CodexHooksPaths,
+  CodexHooksPlan,
+  CodexRegistry,
+  DriftReport,
+  HooksListHookMetadata,
+  HookTrustRow,
+  ManagedEntry,
+} from './codex-hooks.js';
+export {
+  DZ_VETO_MARKER,
+  DZ_VETO_WARN_MARKER,
+  RUNTIME_BLOCK_PHRASE,
+  classifyTrust,
+  classifyVetoProbe,
+  isReadyVerdict,
+  verifyExitCode,
+} from './codex-hooks-verify.js';
+export type {
+  CodexHookTrustStatus,
+  VetoProbeEvidence,
+  VetoProbeResult,
+  VetoTrust,
+  VetoVerdict,
+} from './codex-hooks-verify.js';
+export { SHELL_VETO_RULE_ID, resolveVetoMode, vetoShellCommand } from './shell-veto-policy.js';
+export type { VetoHit, VetoMode } from './shell-veto-policy.js';
+export { generateCodexHelpers, generateCodexRecallHelper, generateCodexVetoHelper } from './codex-hooks-assets.js';
 export {
   EVENT_CHAIN_SCOPE,
   EVENT_CHAIN_GENESIS_HASH,
@@ -423,9 +531,58 @@ export {
   needsCodeLandedBarrier,
   codeLandedBarrierPlan,
   codeLandedBarrierHasLanded,
+  // decideCodeLanding was NEVER in this named list (a pre-existing omission found by the ADR-002
+  // Confirmation-1 sweep). Its `predicate` union NARROWS in this release, which is a breaking change
+  // to a published output type — so it has to actually BE published to be honest about it.
+  decideCodeLanding,
   CODE_LANDED_BARRIER_SLEEPS_SECONDS,
+  // wave1-instrument-repair (ADR-003): the landed-barrier honesty surface. This list is NAMED, so a
+  // missing entry silently drops the export from the published package — ADR-002 Confirmation 1 is
+  // the test that catches exactly that.
+  LANDING_PROTOCOL_VERSION,
+  LANDING_HASH_TOKEN,
+  addExpectedCodeTarget,
+  extractExpectedCodeTargetsFromText,
+  sourceExpectedCodeTargets,
+  validateExpectedTargetsBlock,
+  posixCksum,
+  verifyPreCodeBaseline,
+  preCodeBaselineCaptureCmd,
+  parseBaselineCapture,
+  CODE_LANDING_PREDICATES,
+  parseLandingSignal,
+  codeLandingProbeCmd,
+  // fa-plan-gate-wiring: the K2 plan-completeness gate halves. NAMED here on purpose — an omission
+  // silently drops them from the published package (the ADR-002 Confirmation-1 lesson).
+  PLAN_GATE_SCRIPT,
+  planCompletenessGateCmd,
+  parsePlanGateVerdict,
+  // qe-bridge-claude: the bridge's path/slug hygiene reuses these rather than minting a second
+  // definition of "safe" (ADR-001 D5-A).
+  isSafeSlug,
+  hasUnsafePathChars,
+  hasDotDotSegment,
+} from './feature-adr-routing.js';
+export type {
+  StageOpts,
+  RoutingEnv,
+  UsageSignal,
+  UsageAction,
+  CodeLandingStatus,
+  CodeStageLandingStatus,
+  LandingInconclusiveReason,
+  CodeLandedBarrierPlan,
+  CodeLandingSnapshot,
+  CodeLandingDecision,
+  SourcedCodeTargets,
+  ExpectedTargetRejectReason,
+  ExpectedTargetsValidation,
+  BaselineEntry,
+  BaselineVerification,
+  ParsedBaselineCapture,
+  ParsedLandingSignal,
+  PlanGateVerdict,
 } from './feature-adr-routing.js';
-export type { StageOpts, RoutingEnv, UsageSignal, UsageAction } from './feature-adr-routing.js';
 export {
   CLAUDE_USAGE_MODELS,
   computeUsage,
@@ -497,6 +654,9 @@ export * from './model-recommender.js';
 export * from './bto-optimize.js';
 export * from './discrimination-gate.js';
 export * from './guard.js';
+// Root AGENTS.md policy projection: pure anchor extraction/render/hash drift +
+// the shared-emitter I/O entry point exported from operations.
+export * from './agents-policy.js';
 // Lesson → guard-rule PROMOTION (feature guard-promotion, scout idea #1) — the cost-of-detection
 // ladder's elevator: moves a lesson from layer 5 (agent memory) to layer 1 (a deterministic rule),
 // but only after TWO consecutive shadow wins replayed over REAL commits. Never synthesises rule code.

package/src/loop-blobs.generated.ts

@@ -25,7 +25,7 @@ export interface LoopBlob {
   code: string;
 }
 
-export const LOOP_BLOB_NAMES = ["checkpoints","training-pairs","model-resolver","usage-probes","codex-dispatch","challenge-panel","trace","ha-consult-router"] as const;
+export const LOOP_BLOB_NAMES = ["checkpoints","training-pairs","model-resolver","usage-probes","codex-dispatch","challenge-panel","trace","loop-semantics","ha-consult-router"] as const;
 
 /** Workflow files the regen-diff gate covers TODAY (AM-5 honest scope): exactly the files
  * carrying BEGIN BLOB markers. Stage B (whole-file regeneration of feature-adr.js) is a
@@ -79,11 +79,11 @@ export const BLOBS: Record<string, LoopBlob> = {
   "codex-dispatch": {
     name: "codex-dispatch",
     version: "1.0.0",
-    contentHash: "e6a608d2856287aa4db2b2db769d2e7ea3ec76b6c7cf299d2e233b4d9d90d0cf",
+    contentHash: "140da3714d2507683b0a27fcb01fa449ea3cb1619f1a2e181aaf24291397642d",
     sourcePath: "packages/@dzhechkov/harness-core/src/feature-adr-routing.ts",
     requires: [],
     exports: ["codexDispatchMode","codexExecPlan","needsCodeLandedBarrier","decideCodeLanding"],
-    code: "const CODE_LANDING_PIPELINE_PREFIXES = ['features/', '.dz/', '.agentic-qe/', 'roam/'];\nfunction codeLandingEmptySignal(seconds) {\n    return 'changed=0 after ' + seconds + 's — genuinely not landed';\n}\nfunction needsCodeLandedBarrier(coderUsed) {\n    return coderUsed === 'codex' || coderUsed === 'codex-fallback';\n}\nfunction normalizeCodeLandingPath(path) {\n    let p = String(path || '').trim().replace(/\\\\/g, '/');\n    while (p.indexOf('./') === 0)\n        p = p.slice(2);\n    p = p.replace(/\\/+/g, '/');\n    if (!p)\n        return '';\n    if (p[0] === '/')\n        return '';\n    if (p === '..' || p.indexOf('../') === 0 || p.indexOf('/../') >= 0 || p.endsWith('/..'))\n        return '';\n    if (/[\\0\\r\\n\\t \"'\\x60$;&|<>*?()[\\]{}!]/.test(p))\n        return '';\n    if (p.endsWith('/'))\n        return '';\n    for (const prefix of CODE_LANDING_PIPELINE_PREFIXES) {\n        const bare = prefix.slice(0, -1);\n        if (p === bare || p.indexOf(prefix) === 0)\n            return '';\n    }\n    return p;\n}\nfunction filterPollableCodePaths(paths) {\n    const out = [];\n    const seen = new Set();\n    for (const path of paths) {\n        const normalized = normalizeCodeLandingPath(path);\n        if (!normalized || seen.has(normalized))\n            continue;\n        seen.add(normalized);\n        out.push(normalized);\n    }\n    return out;\n}\nfunction decideCodeLanding(snapshot) {\n    const maxWaitMs = Math.max(0, snapshot.maxWaitMs);\n    const elapsedMs = Math.max(0, snapshot.elapsedMs);\n    const elapsedSeconds = Math.floor(elapsedMs / 1000);\n    const expectedPaths = filterPollableCodePaths(snapshot.expectedPaths);\n    const changedPaths = filterPollableCodePaths(snapshot.changedEntries.map((entry) => entry.path));\n    const changed = new Set(changedPaths);\n    const matchedExpectedPaths = expectedPaths.filter((path) => changed.has(path));\n    if (expectedPaths.length > 0 && matchedExpectedPaths.length > 0) {\n        return {\n            status: 'landed',\n            changed: matchedExpectedPaths.length,\n            elapsedMs,\n            elapsedSeconds,\n            expectedPaths,\n            matchedExpectedPaths,\n            changedPaths,\n            predicate: 'expected-path',\n            qeSignalLine: 'CODEX-LANDING-SIGNAL status=landed changed=' +\n                matchedExpectedPaths.length +\n                ' after=' +\n                elapsedSeconds +\n                's predicate=expected-path matched=' +\n                matchedExpectedPaths.join(','),\n        };\n    }\n    if (expectedPaths.length === 0 && changedPaths.length > 0) {\n        return {\n            status: 'landed',\n            changed: changedPaths.length,\n            elapsedMs,\n            elapsedSeconds,\n            expectedPaths,\n            matchedExpectedPaths,\n            changedPaths,\n            predicate: 'any-code-change',\n            qeSignalLine: 'CODEX-LANDING-SIGNAL status=landed changed=' +\n                changedPaths.length +\n                ' after=' +\n                elapsedSeconds +\n                's predicate=any-code-change',\n        };\n    }\n    if (elapsedMs < maxWaitMs) {\n        return {\n            status: 'not-yet-flushed',\n            changed: 0,\n            elapsedMs,\n            elapsedSeconds,\n            expectedPaths,\n            matchedExpectedPaths: [],\n            changedPaths,\n            predicate: 'empty-before-timeout',\n            qeSignalLine: 'CODEX-LANDING-SIGNAL status=not-yet-flushed changed=0 after ' + elapsedSeconds + 's — not yet flushed',\n        };\n    }\n    const terminalSeconds = Math.ceil(maxWaitMs / 1000);\n    return {\n        status: 'genuinely-not-landed',\n        changed: 0,\n        elapsedMs,\n        elapsedSeconds: terminalSeconds,\n        expectedPaths,\n        matchedExpectedPaths: [],\n        changedPaths,\n        predicate: 'empty-after-timeout',\n        qeSignalLine: 'CODEX-LANDING-SIGNAL status=genuinely-not-landed ' + codeLandingEmptySignal(terminalSeconds),\n    };\n}\nconst WRAPPER_STAGES = { code: 1, plan: 1 };\nfunction codexDispatchMode(stage) {\n    return WRAPPER_STAGES[stage] ? 'wrapper' : 'exec';\n}\nconst CODEX_EXEC_PROMPT_CEILING_CHARS = 24000;\nfunction codexExecPlan(input) {\n    if (codexDispatchMode(input.stage) === 'wrapper') {\n        return { mode: 'wrapper', reason: 'deliverable is a file written out-of-band' };\n    }\n    if (!input.probedId) {\n        return { mode: 'claude', reason: 'no codex model id answered the probe' };\n    }\n    if (input.promptChars > CODEX_EXEC_PROMPT_CEILING_CHARS) {\n        return {\n            mode: 'claude',\n            reason: 'prompt is ' +\n                input.promptChars +\n                ' chars, over the ' +\n                CODEX_EXEC_PROMPT_CEILING_CHARS +\n                '-char codex exec ceiling (it would stall)',\n        };\n    }\n    return { mode: 'exec', reason: 'codex exec on ' + input.probedId };\n}",
+    code: "const CODE_LANDING_PIPELINE_PREFIXES = ['features/', '.dz/', '.agentic-qe/', 'roam/'];\nfunction codeLandingEmptySignal(seconds) {\n    return 'changed=0 after ' + seconds + 's — genuinely not landed';\n}\nfunction needsCodeLandedBarrier(coderUsed) {\n    return coderUsed === 'codex' || coderUsed === 'codex-fallback';\n}\nfunction stripCodeLandingPath(path) {\n    let p = String(path || '').trim().replace(/\\\\/g, '/');\n    while (p.indexOf('./') === 0)\n        p = p.slice(2);\n    return p.replace(/\\/+/g, '/');\n}\nfunction classifyCodeLandingPathReject(path) {\n    const p = stripCodeLandingPath(path);\n    if (!p)\n        return 'empty-after-strip';\n    if (p[0] === '/')\n        return 'absolute-path';\n    if (p === '..' || p.indexOf('../') === 0 || p.indexOf('/../') >= 0 || p.endsWith('/..'))\n        return 'traversal';\n    if (/[\\0\\r\\n\\t \"'\\x60$;&|<>*?()[\\]{}!]/.test(p))\n        return 'not-a-path';\n    if (p.endsWith('/'))\n        return 'not-a-path';\n    for (const prefix of CODE_LANDING_PIPELINE_PREFIXES) {\n        const bare = prefix.slice(0, -1);\n        if (p === bare || p.indexOf(prefix) === 0)\n            return 'pipeline-artifact-path';\n    }\n    return null;\n}\nfunction normalizeCodeLandingPath(path) {\n    return classifyCodeLandingPathReject(path) === null ? stripCodeLandingPath(path) : '';\n}\nfunction filterPollableCodePaths(paths) {\n    const out = [];\n    const seen = new Set();\n    for (const path of paths || []) {\n        const normalized = normalizeCodeLandingPath(path);\n        if (!normalized || seen.has(normalized))\n            continue;\n        seen.add(normalized);\n        out.push(normalized);\n    }\n    return out;\n}\nfunction isNewlyChanged(path, baseline, currentHashes) {\n    if (!baseline || !baseline.ok)\n        return false;\n    let recorded = null;\n    for (const entry of baseline.entries) {\n        if (entry.path === path) {\n            recorded = entry.hash;\n            break;\n        }\n    }\n    if (recorded === null)\n        return true;\n    const now = currentHashes ? currentHashes[path] : undefined;\n    if (now === undefined)\n        return false;\n    return now !== recorded;\n}\nfunction decideCodeLanding(snapshot) {\n    const maxWaitMs = Math.max(0, snapshot.maxWaitMs);\n    const elapsedMs = Math.max(0, snapshot.elapsedMs);\n    const elapsedSeconds = Math.floor(elapsedMs / 1000);\n    const expectedPaths = filterPollableCodePaths(snapshot.expectedPaths);\n    const changedPaths = filterPollableCodePaths(snapshot.changedEntries.map(function (entry) { return entry.path; }));\n    if (expectedPaths.length === 0) {\n        return {\n            status: 'inconclusive',\n            reason: 'empty-plan-block',\n            changed: 0,\n            elapsedMs: elapsedMs,\n            elapsedSeconds: elapsedSeconds,\n            expectedPaths: expectedPaths,\n            matchedExpectedPaths: [],\n            changedPaths: changedPaths,\n            predicate: 'no-expected-targets',\n            qeSignalLine: 'CODEX-LANDING-SIGNAL status=inconclusive predicate=no-expected-targets reason=empty-plan-block',\n        };\n    }\n    const baseline = snapshot.baseline;\n    if (!baseline || !baseline.ok) {\n        const reason = baseline && baseline.reason ? baseline.reason : 'no-baseline';\n        return {\n            status: 'inconclusive',\n            reason: reason,\n            changed: 0,\n            elapsedMs: elapsedMs,\n            elapsedSeconds: elapsedSeconds,\n            expectedPaths: expectedPaths,\n            matchedExpectedPaths: [],\n            changedPaths: changedPaths,\n            predicate: 'newly-changed',\n            qeSignalLine: 'CODEX-LANDING-SIGNAL status=inconclusive predicate=newly-changed reason=' + reason,\n        };\n    }\n    const changed = new Set(changedPaths);\n    const matchedExpectedPaths = expectedPaths.filter(function (path) {\n        return changed.has(path) && isNewlyChanged(path, baseline, snapshot.currentHashes);\n    });\n    if (matchedExpectedPaths.length > 0) {\n        return {\n            status: 'landed',\n            changed: matchedExpectedPaths.length,\n            elapsedMs: elapsedMs,\n            elapsedSeconds: elapsedSeconds,\n            expectedPaths: expectedPaths,\n            matchedExpectedPaths: matchedExpectedPaths,\n            changedPaths: changedPaths,\n            predicate: 'newly-changed',\n            qeSignalLine: 'CODEX-LANDING-SIGNAL status=landed changed=' +\n                matchedExpectedPaths.length +\n                ' after=' +\n                elapsedSeconds +\n                's predicate=newly-changed matched=' +\n                matchedExpectedPaths.join(','),\n        };\n    }\n    if (elapsedMs < maxWaitMs) {\n        return {\n            status: 'not-yet-flushed',\n            changed: 0,\n            elapsedMs: elapsedMs,\n            elapsedSeconds: elapsedSeconds,\n            expectedPaths: expectedPaths,\n            matchedExpectedPaths: [],\n            changedPaths: changedPaths,\n            predicate: 'empty-before-timeout',\n            qeSignalLine: 'CODEX-LANDING-SIGNAL status=not-yet-flushed changed=0 after ' + elapsedSeconds + 's — not yet flushed',\n        };\n    }\n    const terminalSeconds = Math.ceil(maxWaitMs / 1000);\n    return {\n        status: 'genuinely-not-landed',\n        changed: 0,\n        elapsedMs: elapsedMs,\n        elapsedSeconds: terminalSeconds,\n        expectedPaths: expectedPaths,\n        matchedExpectedPaths: [],\n        changedPaths: changedPaths,\n        predicate: 'empty-after-timeout',\n        qeSignalLine: 'CODEX-LANDING-SIGNAL status=genuinely-not-landed ' + codeLandingEmptySignal(terminalSeconds),\n    };\n}\nconst WRAPPER_STAGES = { code: 1, plan: 1 };\nfunction codexDispatchMode(stage) {\n    return WRAPPER_STAGES[stage] ? 'wrapper' : 'exec';\n}\nconst CODEX_EXEC_PROMPT_CEILING_CHARS = 24000;\nfunction codexExecPlan(input) {\n    if (codexDispatchMode(input.stage) === 'wrapper') {\n        return { mode: 'wrapper', reason: 'deliverable is a file written out-of-band' };\n    }\n    if (!input.probedId) {\n        return { mode: 'claude', reason: 'no codex model id answered the probe' };\n    }\n    if (input.promptChars > CODEX_EXEC_PROMPT_CEILING_CHARS) {\n        return {\n            mode: 'claude',\n            reason: 'prompt is ' +\n                input.promptChars +\n                ' chars, over the ' +\n                CODEX_EXEC_PROMPT_CEILING_CHARS +\n                '-char codex exec ceiling (it would stall)',\n        };\n    }\n    return { mode: 'exec', reason: 'codex exec on ' + input.probedId };\n}",
   },
   "challenge-panel": {
     name: "challenge-panel",
@@ -103,6 +103,15 @@ export const BLOBS: Record<string, LoopBlob> = {
     exports: ["LOOP_TRACE_SCHEMA_VERSION","TRACE_RUNID_RE","TRACE_KEY_RE","traceShellQuote","traceValidateEvent","traceInit","traceOnDispatch","traceOnSettle","traceClose","traceFlushCmd","traceFaRecordCmd","traceLedgerLine","traceLedgerAppendCmd"],
     code: "const LOOP_TRACE_SCHEMA_VERSION = 1;\nconst TRACE_RUNID_RE = /^[a-z0-9-]{1,40}$/;\nconst TRACE_KEY_RE = /^[a-z0-9_.:-]{1,64}$/i;\nfunction traceShellQuote(s) {\n    return \"'\" + String(s).replace(/'/g, \"'\\\\''\") + \"'\";\n}\nfunction traceValidateEvent(e) {\n    if (typeof e !== 'object' || e === null || Array.isArray(e))\n        return 'event must be an object';\n    const ev = e;\n    if (ev['v'] !== 1)\n        return 'v must be 1';\n    if (typeof ev['runId'] !== 'string' || !TRACE_RUNID_RE.test(ev['runId']))\n        return 'runId fails its VO regex';\n    if (typeof ev['seq'] !== 'number' || !Number.isInteger(ev['seq']) || ev['seq'] < 1)\n        return 'seq must be a positive integer';\n    const kind = ev['event'];\n    if (kind === 'dispatched') {\n        if (typeof ev['invocationId'] !== 'string' || ev['invocationId'] === '')\n            return 'invocationId required';\n        if (typeof ev['stepId'] !== 'string' || !TRACE_KEY_RE.test(ev['stepId']))\n            return 'stepId fails its VO regex';\n        if (ev['itemKey'] !== null && (typeof ev['itemKey'] !== 'string' || !TRACE_KEY_RE.test(ev['itemKey'])))\n            return 'itemKey fails its VO regex';\n        if (typeof ev['attempt'] !== 'number' || ev['attempt'] < 1)\n            return 'attempt must be >= 1';\n        if (typeof ev['phase'] !== 'string' || ev['phase'] === '')\n            return 'phase required';\n        if (!Array.isArray(ev['causedBy']) || ev['causedBy'].some((n) => typeof n !== 'number'))\n            return 'causedBy must be a number array';\n        return null;\n    }\n    if (kind === 'settled') {\n        if (typeof ev['invocationId'] !== 'string' || ev['invocationId'] === '')\n            return 'invocationId required';\n        if (ev['outcome'] !== 'ok' && ev['outcome'] !== 'null' && ev['outcome'] !== 'error')\n            return 'outcome must be ok|null|error';\n        return null;\n    }\n    if (kind === 'run.opened') {\n        if (typeof ev['planDigest'] !== 'string' || typeof ev['execFp'] !== 'string')\n            return 'run.opened needs planDigest + execFp';\n        return null;\n    }\n    if (kind === 'run.closed') {\n        const c = ev['counts'];\n        if (typeof c !== 'object' || c === null)\n            return 'run.closed needs counts';\n        return null;\n    }\n    return 'unknown event kind';\n}\nfunction traceInit(runId, planDigest, execFp) {\n    if (!TRACE_RUNID_RE.test(runId))\n        throw new Error('loop-trace: runId fails ' + String(TRACE_RUNID_RE));\n    const state = { runId, seq: 0, dispatched: 0, settled: 0, buffer: [] };\n    const opened = { v: 1, runId, seq: ++state.seq, event: 'run.opened', planDigest, execFp };\n    traceBuffer(state, opened);\n    return state;\n}\nfunction traceBuffer(state, e) {\n    const err = traceValidateEvent(e);\n    if (err !== null)\n        throw new Error('loop-trace: refusing non-conforming event (' + err + ') — the authoritative ordering source is never repaired later');\n    state.buffer.push(JSON.stringify(e));\n}\nfunction traceOnDispatch(state, e) {\n    const seq = ++state.seq;\n    state.dispatched++;\n    traceBuffer(state, {\n        v: 1,\n        runId: state.runId,\n        seq,\n        event: 'dispatched',\n        invocationId: e.invocationId,\n        stepId: e.stepId,\n        itemKey: e.itemKey,\n        attempt: e.attempt,\n        phase: e.phase,\n        model: e.model,\n        causedBy: e.causedBy,\n    });\n    return seq;\n}\nfunction traceOnSettle(state, e) {\n    const seq = ++state.seq;\n    state.settled++;\n    traceBuffer(state, { v: 1, runId: state.runId, seq, event: 'settled', invocationId: e.invocationId, outcome: e.outcome });\n    return seq;\n}\nfunction traceClose(state) {\n    const closed = {\n        v: 1,\n        runId: state.runId,\n        seq: ++state.seq,\n        event: 'run.closed',\n        counts: { dispatched: state.dispatched, settled: state.settled },\n    };\n    traceBuffer(state, closed);\n}\nfunction traceFlushCmd(state, traceFileAbs) {\n    if (state.buffer.length === 0)\n        return null;\n    const lines = state.buffer.splice(0, state.buffer.length);\n    const file = traceShellQuote(traceFileAbs);\n    const dir = traceShellQuote(traceFileAbs.replace(/\\/[^/]*$/, ''));\n    const printfs = lines\n        .map((l) => \"printf '%s\\\\n' \" + traceShellQuote(l) + ' | sed \"s/}$/,\\\\\"wallTime\\\\\":\\\\\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\\\\\"}/\" >> ' + file)\n        .join(' && ');\n    return 'mkdir -p ' + dir + ' && ' + printfs;\n}\nfunction traceFaRecordCmd(dzBin, slug, stepLabel, projectAbs) {\n    if (typeof slug !== 'string' || slug === ''\n        || typeof stepLabel !== 'string' || stepLabel === ''\n        || typeof projectAbs !== 'string' || projectAbs === '')\n        return null;\n    const bin = typeof dzBin === 'string' && dzBin !== '' ? dzBin : 'dz';\n    const cmd = traceShellQuote(bin) + ' statusline --fa-record --slug ' + traceShellQuote(slug)\n        + ' --step ' + traceShellQuote(stepLabel) + ' --kind loop --project ' + traceShellQuote(projectAbs);\n    return cmd + ' >/dev/null 2>&1';\n}\nfunction traceLedgerLine(opts) {\n    try {\n        if (typeof opts.slug !== 'string' || opts.slug === '')\n            return null;\n        const agents = typeof opts.agents === 'number'\n            && Number.isFinite(opts.agents)\n            && Number.isInteger(opts.agents)\n            && opts.agents >= 0\n            ? opts.agents\n            : 0;\n        const date = typeof opts.date === 'string' && /^\\d{4}-\\d{2}-\\d{2}$/.test(opts.date) ? opts.date : null;\n        const outcome = typeof opts.outcome === 'string' && opts.outcome !== '' ? opts.outcome : 'unknown';\n        const line = JSON.stringify({\n            slug: opts.slug,\n            stage: 'loop-run',\n            tier: null,\n            tokens: null,\n            minutes: null,\n            agents,\n            coder: null,\n            grade: null,\n            date,\n            auto: true,\n            outcome,\n            runId: typeof opts.runId === 'string' ? opts.runId : null,\n            planDigest: typeof opts.planDigest === 'string' ? opts.planDigest : null,\n        });\n        return line.length <= 4000 ? line : null;\n    }\n    catch {\n        return null;\n    }\n}\nfunction traceLedgerAppendCmd(repoAbs, line) {\n    if (typeof repoAbs !== 'string' || repoAbs === '' || typeof line !== 'string' || line === '')\n        return null;\n    const dir = traceShellQuote(repoAbs + '/.dz/feature-adr');\n    const file = traceShellQuote(repoAbs + '/.dz/feature-adr/run-cost-ledger.jsonl');\n    return 'mkdir -p ' + dir\n        + \" && printf '%s' \" + traceShellQuote(line)\n        + ' | sed \"s/\\\\\"date\\\\\":null/\\\\\"date\\\\\":\\\\\"$(date -u +%Y-%m-%d)\\\\\"/\" >> ' + file\n        + \" && printf '\\\\n' >> \" + file\n        + ' && echo LEDGER-OK';\n}\nfunction invocations(run) {\n    const out = new Map();\n    for (const e of run.events) {\n        if (e.event === 'dispatched') {\n            out.set(e.invocationId, {\n                invocationId: e.invocationId,\n                stepId: e.stepId,\n                itemKey: e.itemKey,\n                dispatchSeq: e.seq,\n                settleSeq: null,\n                causedBy: e.causedBy,\n            });\n        }\n        else if (e.event === 'settled') {\n            const inv = out.get(e.invocationId);\n            if (inv)\n                inv.settleSeq = e.seq;\n        }\n    }\n    return [...out.values()];\n}",
   },
+  "loop-semantics": {
+    name: "loop-semantics",
+    version: "1.0.0",
+    contentHash: "d918ba8d29d9dc20e2467ddb0ba126d537bc9e4560547e2ae52d28979ee6ea9c",
+    sourcePath: "packages/@dzhechkov/harness-core/src/loop-run-semantics.ts",
+    requires: [],
+    exports: ["errText","causeChain","errSnap","classifyFailure","gateVerdict","joinRegion"],
+    code: "function errText(err) {\n    try {\n        if (err !== null && typeof err === 'object') {\n            const m = err.message;\n            if (typeof m === 'string')\n                return m;\n        }\n        return String(err);\n    }\n    catch (_e) {\n        try {\n            return Object.prototype.toString.call(err);\n        }\n        catch (_e2) {\n            return '[unrenderable error]';\n        }\n    }\n}\nfunction causeChain(err) {\n    const chain = [];\n    let cur = err;\n    for (let d = 0; d < 5; d++) {\n        if (cur === null || cur === undefined)\n            break;\n        if (chain.indexOf(cur) !== -1)\n            break;\n        chain.push(cur);\n        try {\n            cur = typeof cur === 'object' ? cur.cause : undefined;\n        }\n        catch (_e) {\n            cur = undefined;\n        }\n    }\n    return chain.length > 0 ? chain : [err];\n}\nfunction errSnap(err) {\n    const chain = causeChain(err);\n    const snap = [];\n    for (let ci = 0; ci < chain.length; ci++) {\n        let code = null;\n        try {\n            const c = chain[ci] !== null && typeof chain[ci] === 'object' ? chain[ci].code : null;\n            code = typeof c === 'string' ? c.toUpperCase() : null;\n        }\n        catch (_e) {\n            code = null;\n        }\n        let name = null;\n        try {\n            const n = chain[ci] !== null && typeof chain[ci] === 'object' ? chain[ci].name : null;\n            name = typeof n === 'string' ? n : null;\n        }\n        catch (_e) {\n            name = null;\n        }\n        snap.push({ code: code, name: name, text: errText(chain[ci]) });\n    }\n    return snap;\n}\nfunction classifyFailure(outcome, snap) {\n    if (outcome === 'null')\n        return 'transport';\n    const links = Array.isArray(snap) ? snap : [];\n    for (let ci = 0; ci < links.length; ci++) {\n        const code = links[ci].code;\n        if (code === 'ETIMEDOUT' || code === 'ECONNRESET' || code === 'ECONNREFUSED' || code === 'ENOTFOUND' || code === 'EPIPE' || code === 'ECONNABORTED' || code === 'EAI_AGAIN')\n            return 'transport';\n    }\n    for (let ci = 0; ci < links.length; ci++) {\n        if (links[ci].name === 'SyntaxError')\n            return 'malformed-output';\n    }\n    let msg = '';\n    for (let ci = 0; ci < links.length; ci++)\n        msg += (ci > 0 ? '\\n' : '') + links[ci].text;\n    msg = msg.toLowerCase();\n    if (/\\btransport\\b|\\beconnreset\\b|\\beconnrefused\\b|\\benotfound\\b|\\bepipe\\b|\\betimedout\\b|\\bsocket hang up\\b|\\bnetwork error\\b|\\brate[ -]?limit(ed|ing|s)?\\b|\\boverloaded\\b|\\bhttp 5[0-9][0-9]\\b/.test(msg))\n        return 'transport';\n    if (/\\bpolicy\\b|\\brefus(e|ed|es|al|ing)\\b|\\bdeclin(e|ed|es|ing)\\b|\\bcontent filter\\b|\\bsafety block\\b/.test(msg))\n        return 'policy-refusal';\n    if (/\\bmalformed\\b|\\bunparseable\\b|\\bparse error\\b|\\binvalid json\\b|\\bunexpected token\\b|\\bunexpected end of json\\b|\\bschema mismatch\\b/.test(msg))\n        return 'malformed-output';\n    if (/\\btimeout\\b|\\btimed out\\b/.test(msg))\n        return 'timeout';\n    return null;\n}\nfunction gateVerdict(reply) {\n    if (typeof reply !== 'string')\n        return 'invalid';\n    const vLines = reply.split('\\n');\n    const vRe = /^\\s*GATE:\\s*(PASS|FAIL)\\s*$/;\n    let vCount = 0;\n    let vLast = '';\n    for (let i = 0; i < vLines.length; i++) {\n        if (vRe.test(vLines[i]))\n            vCount++;\n        if (vLines[i].trim() !== '')\n            vLast = vLines[i];\n    }\n    const vEnd = vRe.exec(vLast);\n    if (vCount !== 1 || vEnd === null)\n        return 'invalid';\n    return vEnd[1] === 'PASS' ? 'pass' : 'fail';\n}\nfunction joinRegion(results, o) {\n    const policy = o && o.policy ? o.policy : 'all-activated';\n    const failures = [];\n    for (let i = 0; i < results.length; i++) {\n        if (results[i] === null || results[i] === undefined)\n            failures.push(i);\n    }\n    if (policy === 'any') {\n        if (failures.length === results.length)\n            throw new Error('join ' + o.region + ': every branch failed (policy any)');\n        return { ok: true, values: results, failures: failures };\n    }\n    const quorum = /^quorum:([1-9][0-9]*)$/.exec(policy);\n    if (quorum) {\n        const okN = results.length - failures.length;\n        if (okN < Number(quorum[1]))\n            throw new Error('join ' + o.region + ': quorum ' + quorum[1] + ' not met (' + okN + ' ok)');\n        return { ok: true, values: results, failures: failures };\n    }\n    if (failures.length > 0)\n        throw new Error('join ' + o.region + ': ' + failures.length + ' dispatched branch(es) failed under policy ' + policy + ' — a dispatched branch is never skippable');\n    return { ok: true, values: results, failures: [] };\n}",
+  },
   "ha-consult-router": {
     name: "ha-consult-router",
     version: "1.0.0",

package/src/loop-plan.ts

@@ -27,6 +27,10 @@
 
 import { createHash } from 'node:crypto';
 import { TRACE_KEY_RE } from './loop-trace.js';
+// The ONE ceiling formula (ADR-004 Confirmation-2) — imported so the run projection's
+// `budgetTotal` and the rendered script's `__budget` constant cannot drift into two ceilings.
+// loop-run-semantics has no runtime import of its own, so this edge introduces no cycle.
+import { computeBudgetTotal } from './loop-run-semantics.js';
 
 export const LOOP_PLAN_SCHEMA = 'loop-plan/1';
 
@@ -1437,3 +1441,184 @@ export function toTraceProjection(plan: LoopPlan): TraceProjection {
     expectedSteps: norm.steps.filter((s) => s.kind === 'agent' || s.kind === 'gate').map((s) => s.stepId),
   };
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// The FOURTH projection (feature dz-workflow-run, ADR-001 O1 + AM-3 doctrine).
+//
+// `dz workflow run` is a SECOND enactor of the same plan, and the AM-3 rule that kept the first
+// one honest applies to it unchanged: a consumer reads a PROJECTION, never `plan.steps`. The three
+// existing projections cannot serve it — `TraceProjection` is the invariant-checking view and
+// carries no prompts, models or budgets by design. So the scheduler gets its own view, added next
+// to the other three, and joins the same layer-1 consumer grep.
+//
+// The addition is ANALYTICAL: the `loop-plan/1` SCHEMA SURFACE (the LoopPlan/LoopStep types,
+// FIELD_DOMAINS, KNOWN_KEYS, REQUIRED_FIELDS, STEP_FIELD_KINDS, CROSS_REFS, parsePlan,
+// validatePlan, normalizePlan, planDigest) is byte-unchanged — nothing below can make a plan that
+// used to parse stop parsing, or change a digest.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** One dispatching step as the scheduler needs it — everything it must know to build a prompt,
+ * pick a model, spend budget, retry, and verify a deliverable landed. */
+export interface RunStepSpec {
+  stepId: string;
+  kind: 'agent' | 'gate';
+  phase: string;
+  /** USER prompt seed (`plan.steps[].prompt`); null means the plan declared none. */
+  prompt: string | null;
+  model: string | null;
+  deliverable: Deliverable;
+  reads: string[];
+  writes: string[];
+  tools: string[];
+  /** INCLUDES the initial attempt (AM-4 semantics; 1 = no retry). */
+  retryMaxAttempts: number;
+  retryOn: FailureClass[];
+  /** `budget.maxAgents ?? 1` — the per-step worst case a boundary reservation is built from. */
+  maxAgents: number;
+  /** `step['x-role'] === 'qe'` — the designed `x-` seam, not a schema field (fence: zero surgery). */
+  qeRole: boolean;
+  gate: { kind: string; failRoute: string | null; maxRedos: number } | null;
+}
+
+/** One SCHEDULING BOUNDARY: the unit the runner reserves budget for, checkpoints, and may pause
+ * BEFORE. A parallel region is ONE boundary (its worst case is reserved as a whole), which is what
+ * makes "pause before the region, never mid-region" expressible. */
+export interface RunBoundary {
+  /** The stepId of the stage / fanout / gate / pause this boundary enacts. */
+  boundaryId: string;
+  kind: 'stage' | 'region' | 'gate' | 'pause';
+  /** Happens-before inputs, as BOUNDARY ids: a declared dep on a join stage or a fanout member is
+   * carried as its REGION, because the member and the join are not boundaries of their own. */
+  deps: string[];
+  /** Present for kind 'stage' | 'gate'. */
+  stage?: RunStepSpec;
+  /** Present for kind 'region'. */
+  region?: {
+    fanout: string;
+    join: string;
+    joinPolicy: string;
+    onInvalid: string;
+    maxFanout: number;
+    registry: string[];
+    dedup: boolean;
+    shape: ConcurrencyShape;
+    chain: RunStepSpec[];
+  };
+  /** Present for kind 'pause'. */
+  pause?: { state: string; resumeArg: string; payloadSchema: Record<string, unknown> | null };
+}
+
+export interface RunProjection {
+  kind: 'run-projection/1';
+  /** Plan order — the render's enactment order, so both enactors walk the same sequence. */
+  boundaries: RunBoundary[];
+  /** `computeBudgetTotal(plan)` — the SAME number the rendered script spends against. */
+  budgetTotal: number;
+  /** Plan-declared `pauses[].resumeArg` keys — the enumerated argsHash exclusions (AM-13). */
+  resumeArgKeys: string[];
+  /** `plan.trace.emit === true` — the AM-6 gate input (a run with no trace plane is refused). */
+  traceEmit: boolean;
+}
+
+/** The ONLY plan view `workflow-run.ts` consumes (AM-3, fourth consumer). */
+export function toRunProjection(plan: LoopPlan): RunProjection {
+  const norm = normalizePlan(plan);
+  const byId = new Map(norm.steps.map((s) => [s.stepId, s]));
+  const gatesById = new Map((norm.gates ?? []).map((g) => [g.stepId, g]));
+  const pausesByState = new Map((norm.pauses ?? []).map((p) => [p.state, p]));
+  const fanouts = norm.fanouts ?? [];
+  const joinsByForStage = new Map((norm.joins ?? []).map((j) => [j.forStage, j]));
+
+  /** member stepId → its owning fanout stage; join stepId → its owning fanout stage. */
+  const ownedByRegion = new Map<string, string>();
+  for (const f of fanouts) {
+    for (const c of f.chain ?? []) ownedByRegion.set(c, f.stage);
+    const j = joinsByForStage.get(f.stage);
+    if (j !== undefined) ownedByRegion.set(j.stage, f.stage);
+  }
+
+  const specOf = (s: LoopStep): RunStepSpec => {
+    const g = s.kind === 'gate' ? gatesById.get(s.stepId) : undefined;
+    return {
+      stepId: s.stepId,
+      kind: s.kind === 'gate' ? 'gate' : 'agent',
+      phase: s.phase,
+      prompt: typeof s.prompt === 'string' ? s.prompt : null,
+      model: typeof s.model === 'string' && s.model !== '' ? s.model : null,
+      deliverable: s.deliverable ?? 'return-value',
+      reads: [...(s.artifacts?.reads ?? [])],
+      writes: [...(s.artifacts?.writes ?? [])],
+      tools: [...(s.tools ?? [])],
+      retryMaxAttempts: typeof s.retry?.maxAttempts === 'number' && s.retry.maxAttempts >= 1 ? Math.floor(s.retry.maxAttempts) : 1,
+      retryOn: [...(s.retry?.retryableFailureClasses ?? [])],
+      maxAgents: typeof s.budget?.maxAgents === 'number' ? s.budget.maxAgents : 1,
+      qeRole: s['x-role'] === 'qe',
+      gate:
+        g === undefined
+          ? null
+          : {
+              kind: typeof g.kind === 'string' ? g.kind : 'gate',
+              failRoute: typeof g.failRoute === 'string' ? g.failRoute : null,
+              maxRedos: typeof g.maxRedos === 'number' && Number.isFinite(g.maxRedos) && g.maxRedos > 0 ? Math.floor(g.maxRedos) : 0,
+            },
+    };
+  };
+
+  /** A declared dep resolved to the BOUNDARY that must have settled before this one dispatches. */
+  const depBoundary = (dep: string): string => ownedByRegion.get(dep) ?? dep;
+
+  const boundaries: RunBoundary[] = [];
+  for (const s of norm.steps) {
+    if (ownedByRegion.has(s.stepId)) continue; // members and joins are rendered inside their region
+    const deps = [...new Set((s.deps ?? []).map(depBoundary).filter((d) => d !== s.stepId))];
+    if (s.kind === 'fanout') {
+      const f = fanouts.find((x) => x.stage === s.stepId);
+      const j = f === undefined ? undefined : joinsByForStage.get(f.stage);
+      boundaries.push({
+        boundaryId: s.stepId,
+        kind: 'region',
+        deps,
+        region: {
+          fanout: s.stepId,
+          join: j?.stage ?? '',
+          joinPolicy: j?.joinPolicy ?? '',
+          onInvalid: j?.onInvalid ?? 'named-failure',
+          maxFanout: typeof f?.maxFanout === 'number' ? f.maxFanout : 0,
+          registry: [...(f?.registry ?? [])],
+          dedup: f?.dedup === true,
+          shape: s.concurrency ?? 'barrier',
+          chain: (f?.chain ?? []).map((c) => byId.get(c)).filter((c): c is LoopStep => c !== undefined).map(specOf),
+        },
+      });
+      continue;
+    }
+    if (s.kind === 'pause') {
+      const state = typeof s.pauseState === 'string' ? s.pauseState : '';
+      const declared = pausesByState.get(state);
+      boundaries.push({
+        boundaryId: s.stepId,
+        kind: 'pause',
+        deps,
+        pause: {
+          state,
+          resumeArg: declared?.resumeArg ?? '',
+          payloadSchema: declared?.payloadSchema ?? null,
+        },
+      });
+      continue;
+    }
+    if (s.kind === 'gate') {
+      boundaries.push({ boundaryId: s.stepId, kind: 'gate', deps, stage: specOf(s) });
+      continue;
+    }
+    boundaries.push({ boundaryId: s.stepId, kind: 'stage', deps, stage: specOf(s) });
+  }
+
+  return {
+    kind: 'run-projection/1',
+    boundaries,
+    budgetTotal: computeBudgetTotal(norm),
+    resumeArgKeys: (norm.pauses ?? []).map((p) => p.resumeArg).filter((k): k is string => typeof k === 'string' && k !== ''),
+    traceEmit: norm.trace?.emit === true,
+  };
+}