chati-dev 4.5.28 → 4.5.29

package/src/orchestrator/planning-contract-revision.js

@@ -0,0 +1,711 @@
+/**
+ * A Planning contract revision reopens genuine upstream ownership after the
+ * bounded QA recovery history is exhausted. It is pipeline authority only.
+ */
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, relative } from 'node:path';
+import { canonicalize, canonicalSerialize, sha256 } from '@chati/core';
+import { pinPlanningCouncilRework, pinPlanningQaSubject } from './council-gate-runtime.js';
+import { assertPlanningContractRevisionBoundary, loadSession } from './session-manager.js';
+import { readAttestedPlanningReconciliationDecision } from './planning-reconciliation.js';
+import { loadRuntimeInstallationV2, resolveRuntimeInvocationV2 } from './runtime-installation-v2.js';
+import { findAgentHandoffPath } from '../utils/handoff-paths.js';
+import { MAX_CORRECTION_CYCLES } from './pipeline-manager.js';
+import { persistImmutableInstallationFile, readSafeInstallationStorageFile } from '../installer-v2/catalog-client.js';
+import { signHostAuthorityPayload, verifyHostAuthorityPayload } from '../installer-v2/installation-authority.js';
+
+export const PLANNING_CONTRACT_REVISION_DOMAIN = 'chati.planning-contract-revision.v1';
+const CONTINUATION_DOMAIN = 'chati.planning-contract-revision.v2';
+const CORRECTION_CONTINUATION_DOMAIN = 'chati.planning-contract-revision.v3';
+export const PLANNING_CONTRACT_REVISION_TARGET = 'detail';
+export const PLANNING_CONTRACT_REVISION_OWNERS = Object.freeze(['detail', 'architect', 'ux', 'qa-planning']);
+const INSTRUCTION_MAX_BYTES = 8192;
+const BRIEF_PATH = 'artifacts/1-Brief/brief-report.md';
+const OWNER_ARTIFACTS = Object.freeze({
+  detail: Object.freeze(['artifacts/2-PRD/prd.md']),
+  architect: Object.freeze([
+    'artifacts/3-Architecture/architecture.md',
+    'artifacts/3-Architecture/system-architecture.md',
+    'artifacts/3-Architecture/data-architecture.md',
+  ]),
+  ux: Object.freeze([
+    'artifacts/4-UX/ux-specification.md',
+    'artifacts/4-UX/visual-surface-assessment.md',
+  ]),
+  'qa-planning': Object.freeze(['artifacts/7-QA-Planning/qa-planning-report.md']),
+});
+
+function fail(code, message) {
+  throw Object.assign(new Error(message), { code });
+}
+
+function equal(left, right) {
+  return canonicalSerialize(left) === canonicalSerialize(right);
+}
+
+function revisionDomain(request) {
+  return request.schema_version === 3 ? CORRECTION_CONTINUATION_DOMAIN
+    : request.schema_version === 2 ? CONTINUATION_DOMAIN : PLANNING_CONTRACT_REVISION_DOMAIN;
+}
+
+function rawDigest(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function closed(value, keys, label) {
+  if (!value || Array.isArray(value) || typeof value !== 'object'
+    || Object.keys(value).sort().join(',') !== [...keys].sort().join(',')) {
+    fail('PLANNING_CONTRACT_REVISION_INPUT_INVALID', `${label} must use the closed Planning contract revision schema.`);
+  }
+}
+
+export function normalizePlanningContractDirection(value) {
+  closed(value, ['accepted_blocker_ids', 'instruction', 'target_agent'], 'Direction');
+  if (value.target_agent !== PLANNING_CONTRACT_REVISION_TARGET
+    || typeof value.instruction !== 'string' || !value.instruction.trim()
+    || Buffer.byteLength(value.instruction.trim(), 'utf8') > INSTRUCTION_MAX_BYTES
+    || !Array.isArray(value.accepted_blocker_ids) || value.accepted_blocker_ids.length === 0
+    || value.accepted_blocker_ids.some(id => typeof id !== 'string' || !id.trim() || Buffer.byteLength(id, 'utf8') > 512)
+    || new Set(value.accepted_blocker_ids).size !== value.accepted_blocker_ids.length) {
+    fail('PLANNING_CONTRACT_REVISION_INPUT_INVALID', 'Direction requires target detail, a bounded instruction and unique accepted blocker ids.');
+  }
+  return canonicalize({ target_agent: value.target_agent,
+    accepted_blocker_ids: [...value.accepted_blocker_ids].sort(), instruction: value.instruction.trim() });
+}
+
+function handoffRef(projectDir, agent, { allowMissing = false } = {}) {
+  const root = realpathSync(projectDir);
+  const path = findAgentHandoffPath(root, agent);
+  if (!path) {
+    if (allowMissing) return null;
+    fail('PLANNING_CONTRACT_REVISION_HANDOFF_MISSING', `Planning contract revision requires the existing ${agent} handoff.`);
+  }
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.isSymbolicLink()) fail('PLANNING_CONTRACT_REVISION_HANDOFF_INVALID', `${agent} handoff must be a regular file.`);
+  const resolved = realpathSync(path), rel = relative(root, resolved);
+  if (!rel || rel.startsWith('..') || isAbsolute(rel)) fail('PLANNING_CONTRACT_REVISION_HANDOFF_INVALID', `${agent} handoff must remain inside the project.`);
+  return canonicalize({ path: rel.split('\\').join('/'), sha256: rawDigest(readFileSync(resolved)) });
+}
+
+function qaBinding(artifact) {
+  const invocation = resolveRuntimeInvocationV2({ artifact, agent: 'qa-planning' });
+  return canonicalize({ provider: invocation.harness_id, provider_id: invocation.provider_id,
+    model: invocation.model_pin.model_id, reasoning_configuration: invocation.model_pin.reasoning_configuration,
+    catalog_snapshot_ref: invocation.model_pin.catalog_snapshot_ref });
+}
+
+function blockerIds(blockers) {
+  return blockers.map(finding => `${finding.member_id}/${finding.finding_id}`).sort();
+}
+
+/** Historical outputs are bound, not replaced when a later direction is consumed. */
+export function planningRevisionResultDigest(session, entry) {
+  const subjects = session.planning_contract_revision_subjects?.filter(item => item.revision_id === entry.request.revision_id);
+  if (subjects?.length !== 1 || !entry.result || !entry.owner_results
+    || !equal(Object.keys(entry.owner_results).sort(), ['architect', 'detail', 'ux'])
+    || subjects[0].execution_claim_id !== entry.result.execution_claim_id
+    || subjects[0].execution_finished_at !== entry.result.execution_finished_at
+    || !equal(subjects[0].artifacts, entry.result.artifacts)) {
+    fail('PLANNING_CONTRACT_REVISION_PREDECESSOR_INVALID', 'Continuation requires the predecessor\'s single genuine held QA subject and three completed owners.');
+  }
+  return sha256({ owner_results: entry.owner_results, result: entry.result, subject: subjects[0] });
+}
+
+/** Terminal negative QA has been consumed and is a fourth preserved owner. */
+export function planningRevisionTerminalDigest(session, entry) {
+  const subjects = session.planning_contract_revision_subjects?.filter(item => item.revision_id === entry.request.revision_id);
+  const result = entry.result, qa = entry.owner_results?.['qa-planning'];
+  if (!['completed', 'superseded'].includes(entry.status) || subjects?.length !== 1
+    || !equal(Object.keys(entry.owner_results || {}).sort(), [...PLANNING_CONTRACT_REVISION_OWNERS].sort())
+    || result?.qa_result?.gate_result !== 'needs_correction'
+    || !Number.isFinite(result.qa_result.score) || result.qa_result.score < 0 || result.qa_result.score > 100
+    || !Number.isSafeInteger(result.qa_result.blocking_count) || result.qa_result.blocking_count < 1
+    || !Number.isFinite(Date.parse(entry.completed_at)) || qa?.completed_at !== entry.completed_at
+    || qa.execution_claim_id !== result.execution_claim_id || qa.execution_finished_at !== result.execution_finished_at
+    || Date.parse(result.execution_finished_at) > Date.parse(entry.completed_at)
+    || subjects[0].execution_claim_id !== result.execution_claim_id
+    || subjects[0].execution_finished_at !== result.execution_finished_at
+    || !equal(subjects[0].artifacts, result.artifacts)
+    || !equal(qa.subject, { gate_id: subjects[0].gate_id, artifacts: result.artifacts })) {
+    fail('PLANNING_CONTRACT_REVISION_PREDECESSOR_INVALID', 'Post-correction continuation requires the complete terminal negative QA and all four preserved owner results.');
+  }
+  return sha256({ kind: 'completed-negative', completed_at: entry.completed_at,
+    owner_results: entry.owner_results, result, subject: subjects[0] });
+}
+
+function ownerCompletion(session, agent) {
+  const state = session.agents?.[agent], result = session.agent_results?.[agent];
+  if (!state || state.status !== 'completed' || !session.completed_agents?.includes(agent)
+    || state.execution_claim_id || state.execution_claim_state || state.planning_contract_revision_id
+    || result?.status !== 'completed' || result.score !== state.score || result.completed_at !== state.completed_at
+    || !Array.isArray(result.outputs) || !Number.isFinite(Date.parse(state.completed_at))) {
+    fail('PLANNING_CONTRACT_REVISION_CORRECTION_INVALID', 'Normal correction requires each canonical completed owner and its unchanged result.');
+  }
+  const binding = canonicalize(Object.fromEntries(['provider', 'provider_id', 'model', 'reasoning_configuration', 'catalog_snapshot_ref']
+    .map(key => [key, state.execution_binding?.[key] ?? null])));
+  return canonicalize({ agent, binding, result });
+}
+
+// Public exit/activate-harness/init-resume append lifecycle observations, not
+// owner transitions. Keep their closed producer shapes in the signed snapshot
+// without treating them as evidence that an owner completed or a QA ran.
+function isCorrectionLifecycle(event) {
+  if (!['session_ended', 'session_started', 'harness_activated'].includes(event.type)) return false;
+  const invalid = () => fail('PLANNING_CONTRACT_REVISION_CORRECTION_INVALID', 'Correction lifecycle must match the public Planning pause/resume contract.');
+  const text = value => typeof value === 'string' && Boolean(value.trim());
+  const harness = value => value === null || text(value);
+  if (event.agent !== 'orchestrator' && !PLANNING_CONTRACT_REVISION_OWNERS.includes(event.agent)) invalid();
+  if (event.type === 'session_ended') {
+    closed(event.data, ['mode', 'harness'], 'Correction exit');
+    if (event.data.mode !== 'plan' || !harness(event.data.harness)) invalid();
+  } else if (event.type === 'harness_activated') {
+    closed(event.data, ['harness', 'previous_harness'], 'Correction harness activation');
+    if (event.agent !== 'orchestrator' || !text(event.data.harness) || !harness(event.data.previous_harness)
+      || event.data.harness === event.data.previous_harness) invalid();
+  } else if (Object.hasOwn(event.data || {}, 'resume')) {
+    closed(event.data, ['resume', 'workflow',
+      ...(Object.hasOwn(event.data, 'concurrent_init_preserved') ? ['concurrent_init_preserved'] : [])], 'Correction init resume');
+    if (event.agent !== 'orchestrator' || event.data.resume !== true || !text(event.data.workflow)
+      || (Object.hasOwn(event.data, 'concurrent_init_preserved') && event.data.concurrent_init_preserved !== true)) invalid();
+  } else {
+    closed(event.data, ['harness', 'resumed'], 'Correction session start');
+    if (!text(event.data.harness) || typeof event.data.resumed !== 'boolean') invalid();
+  }
+  return true;
+}
+
+function validateCorrectionSource(source, request, previous) {
+  closed(source, ['kind', 'events', 'owners', 'correction_cycles', 'qa_claim_started_at'], 'Correction source');
+  const invalid = () => fail('PLANNING_CONTRACT_REVISION_CORRECTION_INVALID', 'Continuation requires one unambiguous normal correction descent to this later approved QA.');
+  if (source.kind !== 'post-negative-correction' || !Array.isArray(source.events) || !source.events.length
+    || !Array.isArray(source.owners) || !equal(source.owners.map(item => item.agent), ['detail', 'architect', 'ux'])
+    || !source.correction_cycles || typeof source.correction_cycles !== 'object') invalid();
+  let last = -Infinity;
+  const ids = new Set();
+  const events = [];
+  for (const event of source.events) {
+    closed(event, ['id', 'type', 'agent', 'data', 'timestamp'], 'Correction event');
+    const at = Date.parse(event.timestamp);
+    if (typeof event.id !== 'string' || !event.id || ids.has(event.id) || !Number.isFinite(at) || at < last) invalid();
+    ids.add(event.id); last = at;
+    if (isCorrectionLifecycle(event)) continue;
+    if (at > Date.parse(request.source_held_qa.finished_at)
+      || !PLANNING_CONTRACT_REVISION_OWNERS.includes(event.agent)
+      || !['agent_completed', 'agent_activated', 'correction_triggered', 'agent_waiting_for_input'].includes(event.type)) invalid();
+    events.push(event);
+  }
+  if (!events.length) invalid();
+  const negative = events[0];
+  if (request.source_held_qa.qa_result?.gate_result !== 'approved'
+    || request.source_held_qa.qa_result.blocking_count !== 0
+    || !Number.isFinite(source.qa_claim_started_at && Date.parse(source.qa_claim_started_at))
+    || Date.parse(source.qa_claim_started_at) > Date.parse(request.source_held_qa.finished_at)
+    || !Number.isFinite(Date.parse(request.source_held_qa.finished_at))) invalid();
+  if (previous && (Date.parse(negative.timestamp) < Date.parse(previous.completed_at)
+    || negative.data?.score !== previous.result.qa_result.score
+    || request.source_held_qa.claim_id === previous.result.execution_claim_id
+    || Date.parse(request.source_held_qa.finished_at) <= Date.parse(previous.completed_at))) invalid();
+  // Each public correction must complete its affected suffix before another QA.
+  // Intermediate normal QA has timeline facts only, never invented claim pins.
+  const upstream = ['detail', 'architect', 'ux'], cycles = new Map(), completions = new Map();
+  const assertWaiting = (event, agent) => {
+    closed(event.data, ['task_id'], 'Correction waiting event');
+    // The runner preserves caller-selected task ids. Completion events do not
+    // carry task pins, so only the available owner/phase linkage is asserted.
+    if (event.agent !== agent || typeof event.data.task_id !== 'string' || !event.data.task_id.trim()) invalid();
+  };
+  let cursor = 0;
+  while (cursor < events.length) {
+    const rejected = events[cursor++], correctionEvent = events[cursor++];
+    const correction = correctionEvent?.data?.correction, target = upstream.indexOf(correction?.target);
+    const key = `qa-planning->${correction?.target}`;
+    if (rejected.type !== 'agent_completed' || rejected.agent !== 'qa-planning' || rejected.data?.status !== 'completed'
+      || !Number.isFinite(rejected.data.score) || rejected.data.score < 0 || rejected.data.score > 100
+      || correctionEvent?.type !== 'correction_triggered' || target < 0 || correctionEvent.agent !== correction.target
+      || correction.source !== 'qa-planning' || correction.score !== rejected.data.score || correction.exceeded !== false
+      || !Number.isSafeInteger(correction.cycle) || correction.cycle < 1 || correction.cycle > MAX_CORRECTION_CYCLES
+      || (cycles.has(key) && correction.cycle !== cycles.get(key) + 1)
+      || !Array.isArray(correction.findings) || !correction.findings.length
+      || correction.findings.some(item => !item.id || item.resolved !== false)) invalid();
+    cycles.set(key, correction.cycle);
+    const affected = upstream.slice(target), completed = new Set(), active = new Set([correction.target]);
+    const ownerWaits = new Map();
+    let waitingOwner = null;
+    while (cursor < events.length && events[cursor].agent !== 'qa-planning') {
+      const event = events[cursor++];
+      if (!affected.includes(event.agent) || !['agent_completed', 'agent_activated', 'agent_waiting_for_input'].includes(event.type)) invalid();
+      if (event.type === 'agent_waiting_for_input') {
+        assertWaiting(event, event.agent);
+        if (!active.has(event.agent) || completed.has(event.agent) || (waitingOwner && waitingOwner !== event.agent)) invalid();
+        waitingOwner = event.agent;
+        ownerWaits.set(event.agent, event);
+      }
+      if (event.type === 'agent_activated') {
+        if (!active.has(event.agent) || completed.has(event.agent) || event.data?.phase !== 'plan') invalid();
+        if (event.agent === 'architect' && event.data?.action === 'spawn_parallel' && affected.includes('ux')) active.add('ux');
+      }
+      if (event.type === 'agent_completed') {
+        if (completed.has(event.agent) || event.data?.status !== 'completed' || !Number.isFinite(event.data.score)) invalid();
+        completed.add(event.agent);
+        active.delete(event.agent);
+        if (waitingOwner === event.agent) waitingOwner = null;
+        const next = affected.find(owner => !completed.has(owner));
+        if (next) active.add(next);
+        completions.set(event.agent, { event, correctionEvent, lastWait: ownerWaits.get(event.agent) });
+      }
+    }
+    const activation = events[cursor++];
+    if (completed.size !== affected.length || activation?.type !== 'agent_activated' || activation.agent !== 'qa-planning'
+      || activation.data?.phase !== 'plan'
+      || !['spawn_autonomous', 'spawn_routed_interactive', 'spawn_parallel', 'spawn_team'].includes(activation.data.action)) invalid();
+    // The runner also supports QA questions. Its final relay claim is the held
+    // QA identity; pending_interaction must already be consumed at admission.
+    let qaWait;
+    while (events[cursor]?.type === 'agent_waiting_for_input') {
+      qaWait = events[cursor++];
+      assertWaiting(qaWait, 'qa-planning');
+    }
+    if (cursor === events.length && qaWait
+      && Date.parse(source.qa_claim_started_at) < Date.parse(qaWait.timestamp)) invalid();
+  }
+  if (!cycles.size || [...cycles].some(([key, cycle]) => source.correction_cycles[key] !== cycle)) invalid();
+  for (const owner of source.owners) {
+    closed(owner, ['agent', 'binding', 'result'], 'Corrected owner');
+    closed(owner.binding, ['provider', 'provider_id', 'model', 'reasoning_configuration', 'catalog_snapshot_ref'], 'Corrected owner binding');
+    closed(owner.result, ['status', 'score', 'outputs', 'completed_at',
+      ...(Object.hasOwn(owner.result || {}, 'started_at') ? ['started_at'] : [])], 'Corrected owner result');
+    const completed = completions.get(owner.agent);
+    const completedAt = Date.parse(owner.result.completed_at);
+    if (owner.result.status !== 'completed' || !Number.isFinite(owner.result.score) || !Array.isArray(owner.result.outputs)
+      || !Number.isFinite(completedAt)
+      || completedAt >= Date.parse(source.qa_claim_started_at)
+      || Object.values(owner.binding).some(value => typeof value !== 'string' || !value)) invalid();
+    if (completed) {
+      if (completed.event.data.score !== owner.result.score || completedAt <= Date.parse(completed.correctionEvent.timestamp)
+        || (completed.lastWait && completedAt < Date.parse(completed.lastWait.timestamp))
+        || completedAt > Date.parse(completed.event.timestamp)) invalid();
+    } else if (completedAt > Date.parse(negative.timestamp)
+      || (previous && owner.result.completed_at !== previous.owner_results[owner.agent]?.completed_at)) invalid();
+  }
+  return source;
+}
+
+function correctedOwners(source) {
+  return new Set(source.events.filter(event => event.type === 'agent_completed' && event.agent !== 'qa-planning').map(event => event.agent));
+}
+
+/** Canonical chronology is evidence of descent, never retroactive artifact pins. */
+export function derivePlanningCorrectionSource(projectDir, session, previous, held) {
+  planningRevisionTerminalDigest(session, previous);
+  const file = readSafeInstallationStorageFile(join(projectDir, '.chati/timeline.json'), { label: 'Planning correction timeline' });
+  let timeline;
+  try { timeline = JSON.parse(file.content); } catch { fail('PLANNING_CONTRACT_REVISION_CORRECTION_INVALID', 'Correction timeline is not JSON.'); }
+  if (!Array.isArray(timeline) || timeline.some(event => !Number.isFinite(Date.parse(event?.timestamp)))
+    || new Set(timeline.map(event => event.id)).size !== timeline.length) {
+    fail('PLANNING_CONTRACT_REVISION_CORRECTION_INVALID', 'Correction timeline is malformed or ambiguous.');
+  }
+  const events = timeline.filter(event => Date.parse(event.timestamp) >= Date.parse(previous.completed_at));
+  const source = canonicalize({ kind: 'post-negative-correction', events,
+    owners: ['detail', 'architect', 'ux'].map(agent => ownerCompletion(session, agent)),
+    qa_claim_started_at: session.agents?.['qa-planning']?.execution_claim_started_at || null,
+    correction_cycles: session.correction_cycles || {} });
+  validateCorrectionSource(source, { source_held_qa: held }, previous);
+  const pending = session.planning_contract_revisions?.at(-1);
+  if (pending?.status === 'reserved' && pending.request.schema_version === 3
+    && pending.request.previous_revision.revision_id === previous.request.revision_id
+    && equal(pending.request.source_held_qa, held)) {
+    // Reservation freezes its source. Subsequent public lifecycle may append
+    // observations, never rewrite the prefix or extend the work descent. The
+    // full current source above is still checked; canonical history is untouched.
+    const captured = pending.request.correction_source.events;
+    if (!equal(events.slice(0, captured.length), captured)
+      || events.slice(captured.length).some(event => !isCorrectionLifecycle(event))) {
+      fail('PLANNING_CONTRACT_REVISION_CORRECTION_INVALID', 'Reserved correction chronology changed beyond public lifecycle append.');
+    }
+    source.events = captured;
+  }
+  return source;
+}
+
+/** Pure topology guard shared by routing and every canonical writer. */
+export function planningContractRevisionHistory(session) {
+  const history = session.planning_contract_revisions || [];
+  const invalid = () => fail('PLANNING_CONTRACT_REVISION_HISTORY_INVALID', 'Planning directions require one non-branching authenticated lineage and one current tip.');
+  if (!Array.isArray(history)) invalid();
+  const ids = new Set(), sources = new Set(), claims = new Set();
+  for (const [index, entry] of history.entries()) {
+    const request = validateStoredRequest(entry?.request);
+    if (ids.has(request.revision_id) || sources.has(request.source_gate_id)
+      || claims.has(request.source_held_qa?.claim_id)) invalid();
+    ids.add(request.revision_id); sources.add(request.source_gate_id); claims.add(request.source_held_qa?.claim_id);
+    if (index === 0) {
+      if (request.schema_version !== 1) invalid();
+    } else {
+      const prior = history[index - 1], ref = request.previous_revision;
+      if (![2, 3].includes(request.schema_version) || ref.revision_id !== prior.request.revision_id
+        || ref.launch_nonce !== prior.launch_nonce || ref.decision_sha256 !== prior.decision_sha256
+        || ref.result_sha256 !== (request.schema_version === 3 ? planningRevisionTerminalDigest(session, prior) : planningRevisionResultDigest(session, prior))
+        || !equal(request.source_reconciliation, prior.request.source_reconciliation)
+        || request.language !== prior.request.language || request.project_id !== prior.request.project_id
+        || request.installation_digest !== prior.request.installation_digest
+        || request.direction.instruction === prior.request.direction.instruction) invalid();
+      if (request.schema_version === 3) {
+        validateCorrectionSource(request.correction_source, request, prior);
+        if (!equal(request.source_held_qa.binding, prior.request.source_held_qa.binding)
+          || !equal(request.old_subject.artifacts.find(item => item.path === BRIEF_PATH),
+            prior.request.old_subject.artifacts.find(item => item.path === BRIEF_PATH))) invalid();
+        if (entry.status !== 'reserved') {
+          const archived = entry.archived;
+          const owners = ['detail', 'architect', 'ux'].map(agent => ownerCompletion({
+            agents: archived?.previous_agents, agent_results: archived?.previous_agent_results,
+            completed_agents: archived?.completed_agents }, agent));
+          if (!equal(owners, request.correction_source.owners)) invalid();
+        }
+      } else if (request.source_held_qa.claim_id !== prior.result.execution_claim_id
+        || request.source_held_qa.finished_at !== prior.result.execution_finished_at
+        || !equal(request.source_held_qa.qa_result, prior.result.qa_result)
+        || !equal(request.old_subject.artifacts, prior.result.artifacts)
+        || session.planning_contract_revision_subjects.find(item => item.revision_id === prior.request.revision_id)?.gate_id !== request.source_gate_id) invalid();
+    }
+    const pendingSuccessor = index === history.length - 2 && history.at(-1).status === 'reserved';
+    const pendingStatus = history[index + 1]?.request.schema_version === 3 ? 'completed' : 'active';
+    if (index < history.length - 1 ? entry.status !== (pendingSuccessor ? pendingStatus : 'superseded')
+      : !['reserved', 'active', 'completed'].includes(entry.status)) invalid();
+    if (entry.status !== 'reserved' && !/^[a-f0-9]{64}$/.test(entry.decision_sha256 || '')) invalid();
+    if (entry.status === 'superseded' && entry.superseded_by !== history[index + 1].request.revision_id) invalid();
+  }
+  const subjects = session.planning_contract_revision_subjects || [];
+  if (!Array.isArray(subjects) || new Set(subjects.map(item => item.revision_id)).size !== subjects.length
+    || subjects.some(item => !ids.has(item.revision_id))) invalid();
+  const tip = history.at(-1) || null;
+  return { history, tip, active: history.find(entry => entry.status === 'active') || null,
+    pending: tip?.status === 'reserved' ? tip : null };
+}
+
+export function authenticatePlanningContractRevisionHistory(projectDir, session) {
+  const lineage = planningContractRevisionHistory(session);
+  const entry = lineage.history.findLast(item => item.status !== 'reserved');
+  // Reading the tip authenticates all immutable ancestors, without quadratic reads.
+  if (entry) readAttestedPlanningContractRevision(projectDir, entry.request, entry.launch_nonce, entry.decision_sha256);
+  return lineage;
+}
+
+function authenticatePositiveReconciliation(projectDir, current, provenance) {
+  closed(provenance, ['decision_sha256', 'launch_nonce', 'request'], 'Source reconciliation');
+  if (typeof provenance.launch_nonce !== 'string' || !provenance.launch_nonce
+    || !/^[a-f0-9]{64}$/.test(provenance.decision_sha256 || '')) {
+    fail('PLANNING_CONTRACT_REVISION_RECONCILIATION_UNTRUSTED', 'Source reconciliation provenance is malformed.');
+  }
+  const decision = readAttestedPlanningReconciliationDecision(projectDir, current,
+    provenance.request, provenance.decision_sha256);
+  if (decision.record.decision.decision !== 'authorize-qa-revalidation'
+    || decision.record.decision.launch_nonce !== provenance.launch_nonce) {
+    fail('PLANNING_CONTRACT_REVISION_RECONCILIATION_UNTRUSTED',
+      'Source reconciliation must be the exact immutable positive decision and nonce.');
+  }
+  return decision;
+}
+
+/** Pin the exact rejected hold and derive one closed controller direction. */
+export function pinPlanningContractRevision(projectDir, match, session) {
+  const direction = normalizePlanningContractDirection(match.direction);
+  const subject = pinPlanningCouncilRework(projectDir, match.gateId);
+  let oldHandoffs;
+  try {
+    const binding = qaBinding(subject.artifact);
+    const boundary = assertPlanningContractRevisionBoundary(projectDir, session, match, binding, subject);
+    const accepted = blockerIds(subject.evidence.blockers);
+    if (!equal(direction.accepted_blocker_ids, accepted)) {
+      fail('PLANNING_CONTRACT_REVISION_BLOCKERS_MISMATCH', 'Direction must name every exact accepted blocker from the authenticated REWORK.');
+    }
+    oldHandoffs = PLANNING_CONTRACT_REVISION_OWNERS.map(agent => ({ agent, ...handoffRef(projectDir, agent) }));
+    if (boundary.previous) {
+      const previous = session.planning_contract_revisions.find(item => item.request.revision_id === boundary.previous.revision_id);
+      const current = new Map(subject.plan.artifacts.map(item => [item.path, item.sha256]));
+      const brief = previous.request.old_subject.artifacts.find(item => item.path === BRIEF_PATH);
+      if (!brief || current.get(BRIEF_PATH) !== brief.sha256) fail('PLANNING_CONTRACT_REVISION_BRIEF_CHANGED', 'Continuation cannot change the original frozen Brief.');
+      const corrected = boundary.correction ? correctedOwners(boundary.correction) : null;
+      for (const item of oldHandoffs) {
+        if (corrected && (item.agent === 'qa-planning' || corrected.has(item.agent))) continue;
+        const produced = item.agent === 'qa-planning' ? session.agents[item.agent].execution_planning_revision_result
+          : previous.owner_results[item.agent];
+        if (!produced?.handoff || !equal(produced.handoff, { path: item.path, sha256: item.sha256 })
+          || !produced.owned_artifacts?.length
+          || produced.owned_artifacts.some(ref => current.get(ref.path) !== ref.sha256)) {
+          fail('PLANNING_CONTRACT_REVISION_HELD_OUTPUT_CHANGED', 'Continuation must preserve the preceding genuine owner outputs and handoffs.');
+        }
+      }
+    }
+    const material = canonicalize({ schema_version: boundary.correction ? 3 : boundary.previous ? 2 : 1, project_id: subject.artifact.project_id,
+      installation_digest: sha256(subject.artifact), language: session.language,
+      target_agent: PLANNING_CONTRACT_REVISION_TARGET, source_gate_id: subject.evidence.source_gate_id,
+      source_decision_sha256: subject.evidence.decision_sha256,
+      source_reconciliation: boundary.reconciliation,
+      source_held_qa: boundary.held, old_subject: { gate_id: subject.plan.gate_id,
+        artifacts: subject.plan.artifacts }, old_handoffs: oldHandoffs,
+      accepted_blocker_ids: accepted, direction, new_subject: null,
+      ...(boundary.previous ? { previous_revision: boundary.previous } : {}),
+      ...(boundary.correction ? { correction_source: boundary.correction } : {}) });
+    const request = canonicalize({ ...material, revision_id: `planning-contract-revision-${sha256(material)}` });
+    const correctionState = boundary.correction ? structuredClone(session) : null;
+    const assertCurrent = () => {
+      subject.assertCurrent();
+      authenticatePositiveReconciliation(projectDir, subject, boundary.reconciliation);
+      if (boundary.previous) authenticatePlanningContractRevisionHistory(projectDir, session);
+      if (correctionState) {
+        const previous = correctionState.planning_contract_revisions.find(item => item.request.revision_id === boundary.previous.revision_id);
+        if (!equal(derivePlanningCorrectionSource(projectDir, correctionState, previous, boundary.held), boundary.correction)) {
+          fail('PLANNING_CONTRACT_REVISION_SUBJECT_CHANGED', 'The normal correction evidence changed while reopening was reserved.');
+        }
+      }
+      for (const item of oldHandoffs) {
+        if (!equal(handoffRef(projectDir, item.agent), { path: item.path, sha256: item.sha256 })) {
+          fail('PLANNING_CONTRACT_REVISION_SUBJECT_CHANGED', 'A Planning handoff changed while contract revision was being reserved.');
+        }
+      }
+    };
+    assertCurrent();
+    return Object.freeze({ ...subject, request, binding, assertCurrent,
+      close() { subject.close(); } });
+  } catch (error) { subject.close(); throw error; }
+}
+
+/** Public recovery guidance uses the same admission checks as reservation. */
+export function planningContractRevisionCapability(projectDir, session, gateId) {
+  let council, pinned;
+  try {
+    const { tip, pending } = authenticatePlanningContractRevisionHistory(projectDir, session);
+    if (pending) return { available: false, code: 'PLANNING_CONTRACT_REVISION_PENDING' };
+    council = pinPlanningCouncilRework(projectDir, gateId);
+    const qa = session.agents?.['qa-planning'];
+    const previousRevisionId = tip?.request.revision_id;
+    pinned = pinPlanningContractRevision(projectDir, { agent: 'qa-planning', gateId,
+      claimId: qa?.execution_claim_id, finishedAt: qa?.execution_finished_at,
+      ...(previousRevisionId ? { previousRevisionId } : {}),
+      direction: { target_agent: 'detail', accepted_blocker_ids: blockerIds(council.evidence.blockers),
+        instruction: `Inspect reopening capability for ${gateId}.` } }, session);
+    return { available: true, ...(previousRevisionId ? { previousRevisionId } : {}) };
+  } catch (error) { return { available: false, code: error.code || 'PLANNING_CONTRACT_REVISION_UNAVAILABLE' }; }
+  finally { pinned?.close(); council?.close(); }
+}
+
+function decisionPath(projectDir, revisionId) {
+  return join(realpathSync(projectDir), '.chati/v2/planning-contract-revisions', `${revisionId}.json`);
+}
+
+function validateStoredRequest(request) {
+  closed(request, ['accepted_blocker_ids', 'direction', 'installation_digest', 'language', 'new_subject',
+    'old_handoffs', 'old_subject', 'project_id', 'revision_id', 'schema_version', 'source_decision_sha256',
+    'source_gate_id', 'source_held_qa', 'source_reconciliation', 'target_agent',
+    ...([2, 3].includes(request?.schema_version) ? ['previous_revision'] : []),
+    ...(request?.schema_version === 3 ? ['correction_source'] : [])], 'Request');
+  const { revision_id: id, ...material } = request;
+  normalizePlanningContractDirection(request.direction);
+  if (![1, 2, 3].includes(request.schema_version) || request.target_agent !== PLANNING_CONTRACT_REVISION_TARGET
+    || request.new_subject !== null || !/^planning-contract-revision-[a-f0-9]{64}$/.test(id || '')
+    || id !== `planning-contract-revision-${sha256(material)}`
+    || !/^council-planning-[a-f0-9]{64}$/.test(request.source_gate_id || '')
+    || !/^[a-f0-9]{64}$/.test(request.source_decision_sha256 || '')
+    || request.old_subject?.gate_id !== request.source_gate_id
+    || !equal(request.accepted_blocker_ids, request.direction.accepted_blocker_ids)
+    || !Array.isArray(request.old_subject?.artifacts) || !Array.isArray(request.old_handoffs)
+    || request.old_handoffs.length !== PLANNING_CONTRACT_REVISION_OWNERS.length) {
+    fail('PLANNING_CONTRACT_REVISION_REQUEST_INVALID', 'Planning contract revision request is malformed or not content-addressed.');
+  }
+  if ([2, 3].includes(request.schema_version)) {
+    closed(request.previous_revision, ['revision_id', 'decision_sha256', 'launch_nonce', 'result_sha256'], 'Previous revision');
+    const previous = request.previous_revision;
+    if (!/^planning-contract-revision-[a-f0-9]{64}$/.test(previous.revision_id || '')
+      || previous.revision_id === id || !/^[a-f0-9]{64}$/.test(previous.decision_sha256 || '')
+      || !/^[a-f0-9]{64}$/.test(previous.result_sha256 || '')
+      || typeof previous.launch_nonce !== 'string' || !previous.launch_nonce) {
+      fail('PLANNING_CONTRACT_REVISION_REQUEST_INVALID', 'Continuation requires an exact predecessor reference.');
+    }
+  }
+  if (request.schema_version === 3) validateCorrectionSource(request.correction_source, request);
+  closed(request.source_reconciliation, ['decision_sha256', 'launch_nonce', 'request'], 'Source reconciliation');
+  if (typeof request.source_reconciliation.launch_nonce !== 'string' || !request.source_reconciliation.launch_nonce
+    || !/^[a-f0-9]{64}$/.test(request.source_reconciliation.decision_sha256 || '')
+    || typeof request.source_reconciliation.request !== 'object' || !request.source_reconciliation.request) {
+    fail('PLANNING_CONTRACT_REVISION_REQUEST_INVALID', 'Planning contract revision source reconciliation is malformed.');
+  }
+  return request;
+}
+
+/** Persist the reserved controller decision. No Planning quality is approved. */
+export function persistPlanningContractRevision({ projectDir, reservation } = {}) {
+  const request = validateStoredRequest(reservation?.request);
+  if (typeof reservation.launch_nonce !== 'string' || !reservation.launch_nonce
+    || typeof reservation.reserved_at !== 'string' || !Number.isFinite(Date.parse(reservation.reserved_at))) {
+    fail('PLANNING_CONTRACT_REVISION_RESERVATION_INVALID', 'An exact reserved nonce and timestamp are required.');
+  }
+  const current = pinPlanningCouncilRework(projectDir, request.source_gate_id);
+  try {
+    if (request.installation_digest !== sha256(current.artifact)
+      || request.project_id !== current.artifact.project_id
+      || !equal(request.old_subject, { gate_id: current.plan.gate_id, artifacts: current.plan.artifacts })
+      || request.source_decision_sha256 !== current.evidence.decision_sha256) {
+      fail('PLANNING_CONTRACT_REVISION_REQUEST_MISMATCH', 'Reserved direction no longer matches its installation, project, council or old subject.');
+    }
+    authenticatePositiveReconciliation(projectDir, current, request.source_reconciliation);
+    if ([2, 3].includes(request.schema_version)) {
+      const session = loadSession(projectDir).session;
+      const lineage = authenticatePlanningContractRevisionHistory(projectDir, session);
+      if (!lineage.pending || !equal(lineage.pending.request, request)
+        || lineage.pending.launch_nonce !== reservation.launch_nonce) {
+        fail('PLANNING_CONTRACT_REVISION_RESERVATION_INVALID', 'Only the exact reserved continuation may be signed.');
+      }
+      if (request.schema_version === 3) {
+        const pinned = pinPlanningContractRevision(projectDir, { agent: 'qa-planning', gateId: request.source_gate_id,
+          claimId: request.source_held_qa.claim_id, finishedAt: request.source_held_qa.finished_at,
+          previousRevisionId: request.previous_revision.revision_id, direction: request.direction }, session);
+        try {
+          if (!equal(pinned.request, request)) fail('PLANNING_CONTRACT_REVISION_SUBJECT_CHANGED', 'The reserved correction source changed before signing.');
+          pinned.assertCurrent();
+        } finally { pinned.close(); }
+      }
+    }
+    const material = canonicalize({ record_type: 'chati-planning-contract-revision', request,
+      decision: { decision: 'reopen-planning-contract', authority_scope: 'pipeline-reopening-only',
+        launch_nonce: reservation.launch_nonce, recorded_at: reservation.reserved_at } });
+    const signed = signHostAuthorityPayload(material, { domain: revisionDomain(request) });
+    const record = canonicalize({ ...material, authority_receipt: {
+      schema_version: 1, authority_id: signed.authority_id, signature: signed.signature } });
+    const content = `${canonicalSerialize(record)}\n`;
+    const path = decisionPath(projectDir, request.revision_id);
+    current.assertCurrent();
+    persistImmutableInstallationFile(path, content, {
+      conflictCode: 'PLANNING_CONTRACT_REVISION_DECISION_CONFLICT', label: 'Planning contract revision decision' });
+    return Object.freeze({ path, record, sha256: rawDigest(content) });
+  } finally { current.close(); }
+}
+
+/** Read a previously created host record after its old subject has been reopened. */
+function readRevisionRecord(projectDir, request, launchNonce, expectedDigest) {
+  validateStoredRequest(request);
+  const artifact = loadRuntimeInstallationV2(projectDir);
+  if (request.installation_digest !== sha256(artifact) || request.project_id !== artifact.project_id) {
+    fail('PLANNING_CONTRACT_REVISION_INSTALLATION_CHANGED', 'Planning contract revision belongs to another installation or project.');
+  }
+  const path = decisionPath(projectDir, request.revision_id);
+  const source = readSafeInstallationStorageFile(path, { label: 'Planning contract revision decision' });
+  let record;
+  try { record = JSON.parse(source.content); }
+  catch { fail('PLANNING_CONTRACT_REVISION_DECISION_INVALID', 'Planning contract revision record is not JSON.'); }
+  closed(record, ['authority_receipt', 'decision', 'record_type', 'request'], 'Decision record');
+  closed(record.decision, ['authority_scope', 'decision', 'launch_nonce', 'recorded_at'], 'Decision');
+  closed(record.authority_receipt, ['authority_id', 'schema_version', 'signature'], 'Authority receipt');
+  const { authority_receipt, ...material } = record;
+  const digest = rawDigest(source.content);
+  if (record.record_type !== 'chati-planning-contract-revision' || !equal(record.request, request)
+    || record.decision.decision !== 'reopen-planning-contract'
+    || record.decision.authority_scope !== 'pipeline-reopening-only'
+    || record.decision.launch_nonce !== launchNonce || authority_receipt.schema_version !== 1
+    || (expectedDigest && digest !== expectedDigest)
+    || !verifyHostAuthorityPayload(material, { domain: revisionDomain(request),
+      authorityId: authority_receipt.authority_id, signature: authority_receipt.signature })) {
+    fail('PLANNING_CONTRACT_REVISION_DECISION_UNTRUSTED', 'Planning contract revision is not authoritative for this exact reserved direction.');
+  }
+  return Object.freeze({ path, record, sha256: digest });
+}
+
+/** Verify every immutable predecessor, iteratively and without trusting session pointers. */
+export function readAttestedPlanningContractRevision(projectDir, request, launchNonce, expectedDigest) {
+  const result = readRevisionRecord(projectDir, request, launchNonce, expectedDigest);
+  const visited = new Set([request.revision_id]);
+  let current = request;
+  while ([2, 3].includes(current.schema_version)) {
+    const previous = current.previous_revision;
+    if (visited.has(previous.revision_id)) fail('PLANNING_CONTRACT_REVISION_HISTORY_INVALID', 'Cyclic Planning revision provenance.');
+    visited.add(previous.revision_id);
+    const source = readSafeInstallationStorageFile(decisionPath(projectDir, previous.revision_id), { label: 'Previous Planning direction' });
+    let record;
+    try { record = JSON.parse(source.content); }
+    catch { fail('PLANNING_CONTRACT_REVISION_DECISION_INVALID', 'Previous direction is not JSON.'); }
+    const authenticated = readRevisionRecord(projectDir, record.request, previous.launch_nonce, previous.decision_sha256);
+    if (authenticated.record.request.revision_id !== previous.revision_id
+      || current.installation_digest !== record.request.installation_digest
+      || current.project_id !== record.request.project_id || current.language !== record.request.language
+      || !equal(current.source_reconciliation, record.request.source_reconciliation)) {
+      fail('PLANNING_CONTRACT_REVISION_DECISION_UNTRUSTED', 'Continuation does not bind its exact predecessor installation and source authority.');
+    }
+    current = record.request;
+  }
+  return result;
+}
+
+function pinOwnerSnapshot(projectDir, revision, agent) {
+  if (!PLANNING_CONTRACT_REVISION_OWNERS.includes(agent)) {
+    fail('PLANNING_CONTRACT_REVISION_OWNER_INVALID', 'Output provenance is limited to reopened Planning owners.');
+  }
+  const request = validateStoredRequest(revision.request);
+  readAttestedPlanningContractRevision(projectDir, request, revision.launch_nonce, revision.decision_sha256);
+  const subject = pinPlanningQaSubject(projectDir);
+  let handoff;
+  try {
+    const current = new Map(subject.plan.artifacts.map(item => [item.path, item.sha256]));
+    const owned = OWNER_ARTIFACTS[agent].filter(path => current.has(path));
+    handoff = handoffRef(projectDir, agent);
+    if (!owned.length) fail('PLANNING_CONTRACT_REVISION_OUTPUT_MISSING', `${agent} has no owned Planning artifact in the current subject.`);
+    const original = new Map(request.old_subject.artifacts.map(item => [item.path, item.sha256]));
+    if (!original.has(BRIEF_PATH) || current.get(BRIEF_PATH) !== original.get(BRIEF_PATH)) {
+      fail('PLANNING_CONTRACT_REVISION_BRIEF_CHANGED', 'Planning contract revision cannot change the frozen Brief.');
+    }
+    for (const [priorAgent, result] of Object.entries(revision.owner_results || {})) {
+      if (!PLANNING_CONTRACT_REVISION_OWNERS.includes(priorAgent) || priorAgent === agent) continue;
+      const prior = new Map(result.subject?.artifacts?.map(item => [item.path, item.sha256]) || []);
+      if (OWNER_ARTIFACTS[priorAgent].some(path => current.get(path) !== prior.get(path))) {
+        fail('PLANNING_CONTRACT_REVISION_OWNER_OUTPUT_CHANGED', `${priorAgent} owned output changed after its recorded completion.`);
+      }
+    }
+    const assertCurrent = () => {
+      subject.assertCurrent();
+      if (!equal(handoffRef(projectDir, agent), handoff)) {
+        fail('PLANNING_CONTRACT_REVISION_OUTPUT_CHANGED', `${agent} handoff changed during completion.`);
+      }
+    };
+    assertCurrent();
+    return Object.freeze({ ...subject, request, handoff, subject_artifacts: subject.plan.artifacts,
+      owned_artifacts: subject.plan.artifacts.filter(item => owned.includes(item.path)),
+      assertCurrent, close() { subject.close(); } });
+  } catch (error) { subject.close(); throw error; }
+}
+
+/** Capture the exact owned bytes immediately before one genuine execution starts. */
+export function pinPlanningContractRevisionOwnerBaseline(projectDir, revision, agent) {
+  return pinOwnerSnapshot(projectDir, revision, agent);
+}
+
+/** Require replacement relative to both the original direction and this execution attempt. */
+export function pinPlanningContractRevisionOwnerOutput(projectDir, revision, agent, attemptBaseline) {
+  const snapshot = pinOwnerSnapshot(projectDir, revision, agent);
+  try {
+    const oldArtifacts = new Map(snapshot.request.old_subject.artifacts.map(item => [item.path, item.sha256]));
+    const current = new Map(snapshot.owned_artifacts.map(item => [item.path, item.sha256]));
+    const attempt = new Map(attemptBaseline?.owned_artifacts?.map(item => [item.path, item.sha256]) || []);
+    const attemptSubject = new Map(attemptBaseline?.subject_artifacts?.map(item => [item.path, item.sha256]) || []);
+    const ownedPaths = [...current.keys()];
+    if (!ownedPaths.some(path => current.get(path) !== oldArtifacts.get(path))) {
+      fail('PLANNING_CONTRACT_REVISION_OUTPUT_NOT_REGENERATED', `${agent} must materially regenerate an owned Planning artifact.`);
+    }
+    if (attempt.size !== current.size || ownedPaths.some(path => !attempt.has(path))
+      || !ownedPaths.some(path => current.get(path) !== attempt.get(path))) {
+      fail('PLANNING_CONTRACT_REVISION_ATTEMPT_OUTPUT_NOT_REGENERATED', `${agent} must materially regenerate an owned artifact during this execution attempt.`);
+    }
+    const currentSubject = new Map(snapshot.subject_artifacts.map(item => [item.path, item.sha256]));
+    if (attemptSubject.size !== currentSubject.size
+      || [...currentSubject].some(([path, digest]) => !current.has(path) && attemptSubject.get(path) !== digest)) {
+      fail('PLANNING_CONTRACT_REVISION_NON_OWNER_INPUT_CHANGED', `${agent} execution changed a Planning input it does not own.`);
+    }
+    const originalHandoff = snapshot.request.old_handoffs.find(item => item.agent === agent);
+    if (!originalHandoff || snapshot.handoff.sha256 === originalHandoff.sha256) {
+      fail('PLANNING_CONTRACT_REVISION_HANDOFF_NOT_REGENERATED', `${agent} must produce a fresh handoff for this revision.`);
+    }
+    if (!attemptBaseline?.handoff || snapshot.handoff.path !== attemptBaseline.handoff.path
+      || snapshot.handoff.sha256 === attemptBaseline.handoff.sha256) {
+      fail('PLANNING_CONTRACT_REVISION_ATTEMPT_HANDOFF_NOT_REGENERATED', `${agent} must produce a fresh handoff during this execution attempt.`);
+    }
+    return snapshot;
+  } catch (error) { snapshot.close(); throw error; }
+}