@aiwg/cli 2026.10.11 → 2026.10.12

package/dist/src/mission-protocol/health-trace-codecs.js

@@ -0,0 +1,281 @@
+import { stableJson } from './worker-contract-json.js';
+// Pure Mission supervision trace and lease mapping codecs.
+import { createHash } from 'node:crypto';
+import { assertValidWorkerPayload, validateWorkerPayload } from './codecs.js';
+import { WorkerContractError, HEALTH_ACTIVITY_SUMMARY_MAX_UTF8_BYTES, HEALTH_KNOWN_REASON_CODES } from './types.js';
+// S1 health-to-lease and Mission reconciliation mapping (B-OG-54 / #2916,
+// 05 §8, ADR-OG-10/13). Pure functions over validated shapes: no scheduler,
+// store, Mission runtime or managed import. S2 owners (B-OG-12/16) wire these
+// verdicts into actual renew/fence/stop/settle/release runtime.
+const HEALTH_TERMINAL_LIKE = new Set(['completed', 'failed', 'cancelled', 'crashed', 'failed-to-start']);
+/**
+ * Classify supervision evidence into a distinct shared-trace kind. Quiet,
+ * stalled and uncertain map distinctly. Heartbeat/lease-only observation
+ * yields activity-only, never productive work. A crashed or failed-to-start
+ * worker without confirmed termination is terminal-unconfirmed: fail-stop is
+ * claimed but a live descendant may survive, so it is never stop proof
+ * (ADR-OG-10). Precondition: schema-valid workerHealthSummary.
+ */
+export function classifyHealthTrace(health) {
+    if (health.termination === 'confirmed' && HEALTH_TERMINAL_LIKE.has(health.state))
+        return 'terminal-proof';
+    if (HEALTH_TERMINAL_LIKE.has(health.state))
+        return 'terminal-unconfirmed';
+    // Confirmed termination with a non-terminal state is contradictory owner
+    // evidence (finish() never produces it): downgrade, never productive.
+    if (health.termination === 'confirmed')
+        return 'uncertain';
+    if (health.termination === 'uncertain')
+        return 'uncertain';
+    switch (health.state) {
+        case 'launching':
+        case 'started':
+            return 'setup';
+        case 'active':
+            return health.lastProgressAt === null ? 'activity-only' : 'productive';
+        case 'quiet':
+            return 'quiet';
+        case 'stalled':
+        case 'hung':
+            return 'stalled';
+        default:
+            return 'uncertain';
+    }
+}
+const TRACE_TRUNCATION_MARKER = '…[truncated]';
+/** Strip control/format characters and cap at maxUtf8Bytes (marker included). */
+export function boundTraceText(text, maxUtf8Bytes) {
+    const clean = String(text).replace(/[\u0000-\u001F\u007F-\u009F\u2028\u2029]/g, '');
+    if (maxUtf8Bytes <= 0)
+        return '';
+    if (Buffer.byteLength(clean, 'utf8') <= maxUtf8Bytes)
+        return clean;
+    const markerBytes = Buffer.byteLength(TRACE_TRUNCATION_MARKER, 'utf8');
+    if (maxUtf8Bytes < markerBytes) {
+        // The budget cannot hold even the marker: return the longest
+        // character-boundary prefix of the marker that fits, so the output
+        // never exceeds the budget.
+        let bytes = 0;
+        let end = 0;
+        for (const char of TRACE_TRUNCATION_MARKER) {
+            const size = Buffer.byteLength(char, 'utf8');
+            if (bytes + size > maxUtf8Bytes)
+                break;
+            bytes += size;
+            end += char.length;
+        }
+        return TRACE_TRUNCATION_MARKER.slice(0, end);
+    }
+    let bytes = 0;
+    let end = 0;
+    for (const char of clean) {
+        const size = Buffer.byteLength(char, 'utf8');
+        if (bytes + size > maxUtf8Bytes - markerBytes)
+            break;
+        bytes += size;
+        end += char.length;
+    }
+    return clean.slice(0, end) + TRACE_TRUNCATION_MARKER;
+}
+/**
+ * Allowlisted reason label for the shared trace. Unlisted codes (including
+ * any free text carrying secret material) project as UNCLASSIFIED#digest:
+ * stable and bounded, never verbatim.
+ */
+export function healthReasonLabel(reasonCode) {
+    if (HEALTH_KNOWN_REASON_CODES.includes(reasonCode))
+        return reasonCode;
+    const digest = createHash('sha256').update(reasonCode, 'utf8').digest('hex').slice(0, 12);
+    return `UNCLASSIFIED#${digest}`;
+}
+/**
+ * Digest-only lifecycle reference for the effect ledger. Only enum, counter,
+ * digest and timestamp fields enter the digest; no payload content crosses.
+ */
+export function healthLifecycleDigest(health) {
+    assertValidWorkerPayload('workerHealthSummary', health);
+    const lifecycle = {
+        version: health.version,
+        state: health.state,
+        coverage: health.coverage,
+        handshake: health.handshake,
+        termination: health.termination,
+        confidence: health.confidence,
+        observerGeneration: health.observerGeneration,
+        transitionCount: health.transitionCount,
+        restartCount: health.restartCount,
+        lastObservedAt: health.lastObservedAt,
+        lastActivityAt: health.lastActivityAt,
+        lastProgressAt: health.lastProgressAt,
+    };
+    const digest = `sha256:${createHash('sha256').update(stableJson(lifecycle), 'utf8').digest('hex')}`;
+    return { ref: `artifact:${digest}`, digest };
+}
+/**
+ * Closed observed-state vocabulary for the previous-state channel. Free
+ * text (including leaked bearer material) never interpolates into the
+ * shared trace.
+ */
+const HEALTH_OBSERVED_STATES = new Set([
+    'launching', 'started', 'active', 'quiet', 'stalled', 'hung',
+    'crashed', 'failed-to-start', 'completed', 'failed', 'cancelled',
+]);
+/**
+ * Parse an ISO timestamp into epoch milliseconds for chronological
+ * comparison. Comparison must never fall back to string ordering: distinct
+ * representations of the same instant (e.g. '.000Z' vs 'Z') must compare
+ * equal, not greater/lesser. Unparseable values reject as having no
+ * timestamp evidence (null), never throw.
+ */
+function parseProgressTimestampMs(value) {
+    if (value === null)
+        return null;
+    const ms = Date.parse(value);
+    return Number.isFinite(ms) ? ms : null;
+}
+/**
+ * Fresh-progress gate: credit requires genuinely new progress evidence.
+ * The health shape carries no progress sequence/key, so freshness is a
+ * NONDECREASING credit watermark: `previousWatermark` is not merely "the
+ * last observation" but the highest-ever CREDITED lastProgressAt, compared
+ * by parsed epoch milliseconds (never raw strings). Out-of-order or
+ * replayed snapshots (older than, or equal to, the watermark) earn no
+ * credit and never move the watermark backward; heartbeats (which advance
+ * activity/observed timestamps while the watermark is frozen) never
+ * re-credit historical progress. Unparseable timestamps earn no credit.
+ * Callers thread the watermark forward with `advanceProgressWatermark`.
+ */
+function isFreshProgressEvidence(health, previousWatermark) {
+    const currentMs = parseProgressTimestampMs(health.lastProgressAt);
+    if (currentMs === null)
+        return false;
+    if (previousWatermark === null || previousWatermark.lastProgressAt === null)
+        return true;
+    const watermarkMs = parseProgressTimestampMs(previousWatermark.lastProgressAt);
+    if (watermarkMs === null)
+        return false;
+    return currentMs > watermarkMs;
+}
+/**
+ * Pure watermark reducer (no store): callers thread the returned value into
+ * the next observation's `previousHealth`/watermark argument instead of
+ * re-passing the raw last observation. The watermark advances ONLY when the
+ * current observation was actually credited; a non-credited observation
+ * (replay, heartbeat, or an out-of-order/older snapshot) leaves the
+ * watermark exactly where it was. This is what makes real A -> B -> A -> B
+ * delivery sequences credit true,true,false,false instead of re-crediting
+ * B the second time it arrives: a naive caller that re-threads "the last
+ * observation" (rather than this reducer's output) regresses to that bug.
+ */
+export function advanceProgressWatermark(previousWatermark, credited, health) {
+    if (credited)
+        return { lastProgressAt: health.lastProgressAt };
+    return previousWatermark ?? { lastProgressAt: null };
+}
+/**
+ * Project one health observation into the shared trace. The activity summary
+ * is built only from enum/counter/generation fields plus the allowlisted
+ * reason label; completionCredit is always false because Mission/Flow
+ * completion gates stay authoritative. previousState must be a closed
+ * observed state (or null); anything else is rejected, never interpolated.
+ * progressCredit requires fresh progress evidence relative to
+ * previousHealth, which callers must maintain as the nondecreasing credit
+ * watermark (see advanceProgressWatermark) rather than the raw last
+ * observation (null for a first observation / no watermark yet).
+ */
+export function projectHealthTrace(health, previousState = null, previousHealth = null) {
+    assertValidWorkerPayload('workerHealthSummary', health);
+    if (previousState !== null && !HEALTH_OBSERVED_STATES.has(previousState)) {
+        throw new WorkerContractError('OG_CONTRACT_INVALID', 'Invalid previous health state.');
+    }
+    const kind = classifyHealthTrace(health);
+    const summary = `health.${health.state}:${health.termination}`
+        + ` gen=${health.observerGeneration ?? 'none'} transitions=${health.transitionCount}`
+        + ` prev=${previousState ?? 'none'} reason=${healthReasonLabel(health.reasonCode)}`;
+    return {
+        kind,
+        progressCredit: kind === 'productive' && isFreshProgressEvidence(health, previousHealth),
+        completionCredit: false,
+        activitySummary: boundTraceText(summary, HEALTH_ACTIVITY_SUMMARY_MAX_UTF8_BYTES),
+        effectRef: healthLifecycleDigest(health),
+    };
+}
+/**
+ * Derive stop proof from owner-observed supervision evidence (ADR-OG-10).
+ * Only a terminal state with owner-confirmed termination is stop proof;
+ * terminal-unconfirmed and uncertain observations stay uncertain, and the
+ * absence of evidence is none. There is no free-form proof parameter:
+ * callers pass the health summary (or null) and the proof is derived.
+ * A late final after cancel-disconnect therefore never releases while
+ * termination is uncertain (ADR-OG-13: late results stay unaccepted
+ * evidence).
+ */
+export function stopProofFromHealth(health) {
+    if (health === null)
+        return 'none';
+    assertValidWorkerPayload('workerHealthSummary', health);
+    if (health.termination === 'confirmed') {
+        return HEALTH_TERMINAL_LIKE.has(health.state) ? 'confirmed' : 'uncertain';
+    }
+    if (HEALTH_TERMINAL_LIKE.has(health.state) || health.termination === 'uncertain')
+        return 'uncertain';
+    return 'none';
+}
+/**
+ * The generation the stop-proof evidence actually belongs to, bridging a
+ * missing observerGeneration to 0 (the bootstrap generation) for fencing —
+ * mirroring the same bridge decideLeaseMapping already applies to the
+ * caller-supplied leaseGeneration/observedGeneration fields. This is bound
+ * to the health summary's OWN observerGeneration field, which the caller
+ * cannot set independently of the evidence: a caller cannot claim generation
+ * 3 while attaching generation-2 evidence and have it treated as current.
+ */
+function stopProofGeneration(health) {
+    if (health === null)
+        return null;
+    return health.observerGeneration ?? 0;
+}
+/**
+ * Pure renewal/reconcile/release verdict over a mocked scheduler boundary.
+ * Fencing binds every action to the current generation: a stale observation
+ * denies renew, cancel, settle and accept alike. Expiry or cancel-disconnect
+ * without derived confirmed stop proof retains the uncertain reservation
+ * and releases nothing. Confirmed stop proof settles exactly once — and only
+ * when that proof's OWN generation (not merely the caller-asserted
+ * observedGeneration) matches the current leaseGeneration; a confirmed
+ * proof carried over from a stale generation never releases.
+ */
+export function decideLeaseMapping(input) {
+    let record;
+    try {
+        if (!input || typeof input !== 'object' || Array.isArray(input))
+            throw new Error('Expected object');
+        record = input;
+    }
+    catch {
+        throw new WorkerContractError('OG_CONTRACT_INVALID', 'Invalid lease mapping input.');
+    }
+    const leaseStates = ['admitted', 'expired', 'cancelled-disconnected'];
+    if (typeof record.leaseState !== 'string' || !leaseStates.includes(record.leaseState)
+        || !Number.isSafeInteger(record.leaseGeneration) || record.leaseGeneration < 0
+        || !Number.isSafeInteger(record.observedGeneration) || record.observedGeneration < 0
+        || typeof record.settled !== 'boolean'
+        || !('health' in record)
+        || (record.health !== null && !validateWorkerPayload('workerHealthSummary', record.health).valid)) {
+        throw new WorkerContractError('OG_CONTRACT_INVALID', 'Invalid lease mapping input.');
+    }
+    const mapping = input;
+    if (mapping.observedGeneration !== mapping.leaseGeneration)
+        return 'deny-stale';
+    if (mapping.settled)
+        return 'deny-already-settled';
+    const stopProof = stopProofFromHealth(mapping.health);
+    const proofIsCurrent = stopProofGeneration(mapping.health) === mapping.leaseGeneration;
+    if (stopProof === 'confirmed' && proofIsCurrent)
+        return 'release-once';
+    if (stopProof === 'uncertain' || (stopProof === 'confirmed' && !proofIsCurrent) || mapping.leaseState !== 'admitted') {
+        return 'retain-uncertain';
+    }
+    return 'renew';
+}
+//# sourceMappingURL=health-trace-codecs.js.map

package/dist/src/mission-protocol/health-trace-types.js

@@ -0,0 +1,43 @@
+/** Bounded activity-log transition summary budget (UTF-8 bytes, marker included). */
+export const HEALTH_ACTIVITY_SUMMARY_MAX_UTF8_BYTES = 1024;
+/**
+ * Closed observer reason-code allowlist for activity summaries. Mirrors the
+ * `reasons` set in tools/ralph-external/lib/worker-health.mjs: B-OG-50 owns
+ * the observer set, B-OG-54 owns this mapping allowlist; extend them together.
+ * Unlisted codes project as UNCLASSIFIED#digest so free text (and any secret
+ * material it carries) never crosses into the shared trace.
+ */
+export const HEALTH_KNOWN_REASON_CODES = [
+    'OK',
+    'AWAITING_HANDSHAKE',
+    'PROCESS_ONLY',
+    'ACCEPTED',
+    'PROGRESS',
+    'QUIET',
+    'NO_PROGRESS',
+    'STARTUP_DEADLINE',
+    'HARD_DEADLINE',
+    'STEP_LIMIT',
+    'AUTH',
+    'RATE_LIMIT',
+    'NETWORK',
+    'MODEL',
+    'TRUST',
+    'STDIN_WAIT',
+    'SANDBOX',
+    'NOT_FOUND',
+    'RESOURCE',
+    'PROVIDER_ERROR',
+    'CRASH',
+    'EXIT_ERROR',
+    'FINAL_INVALID',
+    'CANCELLED',
+    'DISCONNECTED',
+    'OBSERVER_GAP',
+    'CAPTURE_WRITE',
+    'OUTPUT_LIMIT',
+    'MALFORMED_FRAME',
+    'SOURCE_GAP',
+    'IDENTITY_CHANGED',
+];
+//# sourceMappingURL=health-trace-types.js.map

package/dist/src/mission-protocol/types.js

@@ -1,3 +1,4 @@
+export * from './worker-review-types.js';
 export const MISSION_API_VERSION = 'mission.aiwg.io/v1';
 // Worker dispatch payloads merged from 05 §5.1 into schemas/mission-v1.schema.json.
 // The schema file is the executable contract; these types mirror its shapes.
@@ -59,48 +60,7 @@ export const WORKER_DEFINITION_PRODUCERS = {
     workerHealthSummary: 'shared-component',
     workerEffectiveHealth: 'shared-component',
 };
-/** Bounded activity-log transition summary budget (UTF-8 bytes, marker included). */
-export const HEALTH_ACTIVITY_SUMMARY_MAX_UTF8_BYTES = 1024;
-/**
- * Closed observer reason-code allowlist for activity summaries. Mirrors the
- * `reasons` set in tools/ralph-external/lib/worker-health.mjs: B-OG-50 owns
- * the observer set, B-OG-54 owns this mapping allowlist; extend them together.
- * Unlisted codes project as UNCLASSIFIED#digest so free text (and any secret
- * material it carries) never crosses into the shared trace.
- */
-export const HEALTH_KNOWN_REASON_CODES = [
-    'OK',
-    'AWAITING_HANDSHAKE',
-    'PROCESS_ONLY',
-    'ACCEPTED',
-    'PROGRESS',
-    'QUIET',
-    'NO_PROGRESS',
-    'STARTUP_DEADLINE',
-    'HARD_DEADLINE',
-    'STEP_LIMIT',
-    'AUTH',
-    'RATE_LIMIT',
-    'NETWORK',
-    'MODEL',
-    'TRUST',
-    'STDIN_WAIT',
-    'SANDBOX',
-    'NOT_FOUND',
-    'RESOURCE',
-    'PROVIDER_ERROR',
-    'CRASH',
-    'EXIT_ERROR',
-    'FINAL_INVALID',
-    'CANCELLED',
-    'DISCONNECTED',
-    'OBSERVER_GAP',
-    'CAPTURE_WRITE',
-    'OUTPUT_LIMIT',
-    'MALFORMED_FRAME',
-    'SOURCE_GAP',
-    'IDENTITY_CHANGED',
-];
+export * from './health-trace-types.js';
 export class WorkerContractError extends Error {
     code;
     constructor(code, message) {

package/dist/src/mission-protocol/worker-contract-json.js

@@ -0,0 +1,10 @@
+// Stable JSON representation shared by Mission artifact and health digests.
+export function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+//# sourceMappingURL=worker-contract-json.js.map

package/dist/src/mission-protocol/worker-review-gate.js

@@ -0,0 +1,100 @@
+// Acceptance checks over conductor briefs, trusted head/lineage and verifier records.
+import { workerReviewLineageDiagnostics } from '../models/worker-review-lineage.js';
+import { WorkerContractError, } from './types.js';
+function fail(message) { throw new WorkerContractError('OG_CONTRACT_INVALID', message); }
+/** Additional relational checks after JSON Schema shape validation. */
+export function workerReviewEvidenceErrors(verification) {
+    const errors = [];
+    const rounds = verification.reviewRounds;
+    if (rounds?.some((review, index) => review.round !== index + 1)) {
+        errors.push('Review rounds must be contiguous and start at one');
+    }
+    const ledger = verification.findingsLedger ?? [];
+    if (new Set(ledger.map(finding => finding.id)).size !== ledger.length)
+        errors.push('Finding IDs must be unique');
+    if (rounds && ledger.some(finding => finding.round > rounds.length))
+        errors.push('Finding round has no review record');
+    if (verification.roundsToClean !== undefined && (verification.status !== 'accepted'
+        || verification.roundsToClean !== rounds?.length))
+        errors.push('roundsToClean must count all review rounds on acceptance');
+    if (verification.status === 'accepted') {
+        if (ledger.some(finding => finding.class === 'A' && finding.status === 'open'
+            && ['blocker', 'major'].includes(finding.severity)))
+            errors.push('Open class A blocker or major findings prevent acceptance');
+        if (rounds?.length && (verification.headSha !== rounds.at(-1).headSha
+            || verification.roundsToClean !== rounds.length || !verification.findingsLedger)) {
+            errors.push('Accepted review needs the final headSha, findingsLedger and roundsToClean');
+        }
+    }
+    const commands = verification.oracleResults?.map(result => result.command) ?? [];
+    if (new Set(commands).size !== commands.length)
+        errors.push('Oracle result commands must be unique');
+    return errors;
+}
+/** Derive telemetry, then validate it through the normal verifier payload codec. */
+export function prepareWorkerAcceptance(brief, execution, supplied, context) {
+    const verification = structuredClone(supplied);
+    if (verification.status !== 'accepted')
+        return verification;
+    if (brief.designReviewRequired && !brief.designReviewArtifact) {
+        fail('Acceptance requires a design-review artifact in the implementation brief');
+    }
+    const oracle = brief.verificationOracle;
+    if (oracle) {
+        const results = verification.oracleResults ?? [];
+        if (new Set(oracle.map(check => check.command)).size !== oracle.length
+            || results.length !== oracle.length || oracle.some(check => {
+            const matches = results.filter(result => result.command === check.command);
+            return matches.length !== 1 || matches[0].exitCode !== check.expectedExitCode;
+        }))
+            fail('Acceptance requires exact verificationOracle command outcomes');
+    }
+    const required = brief.intent.verification.independentReview === 'required'
+        || brief.intent.verification.differentFamily === 'require';
+    const rounds = verification.reviewRounds ?? [];
+    if (!required && !rounds.length)
+        return verification;
+    const final = rounds.at(-1);
+    if (!final)
+        fail('Acceptance requires a final cross-model review record');
+    if (!context.headSha || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(context.headSha)
+        || final.headSha !== context.headSha || verification.headSha !== undefined && verification.headSha !== context.headSha) {
+        fail('Final review is missing the current PR head SHA or is bound to a stale head');
+    }
+    const writer = context.reviewLineage?.writer;
+    const observations = context.reviewLineage?.reviewers;
+    const reviewers = Array.isArray(observations)
+        ? observations.filter(observation => observation?.recordId === final.reviewerObservationRef) : [];
+    if (reviewers.length !== 1)
+        fail('Final review is missing unambiguous reviewer lineage');
+    const diagnostics = workerReviewLineageDiagnostics({ reviewOf: writer, reviewer: reviewers[0], requireDifferentFamily: true });
+    if (diagnostics.length)
+        fail(diagnostics.map(diagnostic => `${diagnostic.pointer}: ${diagnostic.message}`).join('; '));
+    if (writer.cliId !== brief.selected.cli || writer.family !== execution.observedFamily) {
+        fail('Review source lineage differs from the observed writer');
+    }
+    if (verification.roundsToClean !== undefined && verification.roundsToClean !== rounds.length) {
+        fail('roundsToClean differs from the retained review rounds');
+    }
+    verification.headSha = context.headSha;
+    verification.roundsToClean = rounds.length;
+    return verification;
+}
+/** Successors keep earlier rounds and findings; resolving a finding retains its ID. */
+export function assertWorkerReviewSuccessor(prior, next) {
+    for (const [index, round] of (prior.reviewRounds ?? []).entries()) {
+        const successor = next.reviewRounds?.[index];
+        if (!successor || successor.round !== round.round || successor.headSha !== round.headSha
+            || successor.reviewerObservationRef !== round.reviewerObservationRef
+            || successor.artifact.ref !== round.artifact.ref || successor.artifact.digest !== round.artifact.digest) {
+            fail('Worker successor drops or rewrites a review round');
+        }
+    }
+    for (const finding of prior.findingsLedger ?? []) {
+        const successor = next.findingsLedger?.find(candidate => candidate.id === finding.id);
+        if (!successor || successor.class !== finding.class || successor.severity !== finding.severity || successor.round !== finding.round) {
+            fail('Worker successor drops or reclassifies a retained finding');
+        }
+    }
+}
+//# sourceMappingURL=worker-review-gate.js.map

package/dist/src/mission-protocol/worker-review-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=worker-review-types.js.map