@dzhechkov/harness-core 0.8.38 → 0.8.40

package/dist/doctor-instrument.js

@@ -0,0 +1,91 @@
+import { isAbsolute, relative, sep } from 'node:path';
+/** Strip semver build metadata: `0.8.32+a1b2c3` and `0.8.32` are the same release. */
+function withoutBuildMetadata(version) {
+    const plus = version.indexOf('+');
+    return plus < 0 ? version : version.slice(0, plus);
+}
+function isInsideRoot(candidate, root) {
+    const fromRoot = relative(root, candidate);
+    return fromRoot === '' || (!isAbsolute(fromRoot) && fromRoot !== '..' && !fromRoot.startsWith(`..${sep}`));
+}
+/**
+ * Decide whether the executable answering `dz doctor` is the workspace's current instrument.
+ *
+ * LIMITS NAMED BY INDEPENDENT REVIEW (Claude Sonnet, 2026-09-20), none of them hidden behind a
+ * passing test:
+ *  - Containment is a case-SENSITIVE path comparison. On a case-insensitive filesystem, or where the
+ *    same location is reachable under two path forms, an in-tree binary can read as external. This
+ *    repo runs on Linux; the cost of being wrong is one extra `warn` line and never an exit code.
+ *  - The caller attributes a version by walking up from the binary to the NEAREST `package.json`.
+ *    A shim in package A that loads package B's code is attributed to A, and a broken install with
+ *    no own manifest is attributed to whatever ancestor has one. The detail always prints the
+ *    resolved binary path so a reader can see which file was actually measured.
+ */
+export function checkInstrumentFreshness(input) {
+    const binary = input.binPath ?? '(unresolved)';
+    const binaryVersion = input.binVersion ?? 'unknown';
+    const treeVersion = input.treeVersion ?? 'unknown';
+    if (!input.isMonorepo) {
+        return {
+            freshness: 'unknown',
+            level: 'ok',
+            detail: `not applicable in a consumer project: no packages/@dzhechkov tree version to compare; resolved binary ${binary}; binary version ${binaryVersion}; tree version ${treeVersion}`,
+        };
+    }
+    if (input.binPath !== null && input.projectRootRealpathed && isInsideRoot(input.binPath, input.projectRoot)) {
+        return {
+            freshness: 'same',
+            level: 'ok',
+            detail: `resolved binary ${input.binPath} is inside project root ${input.projectRoot}; binary version ${binaryVersion}; tree version ${treeVersion}; this binary is the tree instrument`,
+        };
+    }
+    if (!input.projectRootRealpathed) {
+        return {
+            freshness: 'unknown',
+            level: 'unknown',
+            detail: `project root ${input.projectRoot} could not be resolved through its symlinks, so it cannot be told whether the answering binary is the tree's own; version could not be determined safely; resolved binary ${binary}; binary version ${binaryVersion}; tree version ${treeVersion}`,
+        };
+    }
+    if (input.binPath === null || input.binVersion === null || input.treeVersion === null) {
+        return {
+            freshness: 'unknown',
+            level: 'unknown',
+            detail: `instrument version could not be determined; resolved binary ${binary}; binary version ${binaryVersion}; tree version ${treeVersion}`,
+        };
+    }
+    // Semver says build metadata after `+` does not participate in equality, so a pipeline that
+    // stamps a commit hash onto the version must not read as a stale instrument.
+    if (withoutBuildMetadata(input.binVersion) === withoutBuildMetadata(input.treeVersion)) {
+        return {
+            freshness: 'same',
+            level: 'ok',
+            detail: `resolved binary ${input.binPath}; binary version ${input.binVersion}; tree version ${input.treeVersion}; versions match`,
+        };
+    }
+    return {
+        freshness: 'stale',
+        level: 'warn',
+        detail: `resolved binary ${input.binPath}; binary version ${input.binVersion}; tree version ${input.treeVersion}; the answering instrument is stale`,
+    };
+}
+/** Decide whether enabled bandit re-ranking has the on-disk state needed to operate. */
+export function checkRankingState(input) {
+    const binary = input.binPath ?? '(unresolved)';
+    if (!input.flagOn) {
+        return {
+            level: 'ok',
+            detail: `bandit re-ranking feature is off; no state is expected at ${input.statePath}; answering binary ${binary}`,
+        };
+    }
+    if (input.stateExists) {
+        return {
+            level: 'ok',
+            detail: `bandit re-ranking is on and state is present at ${input.statePath}; answering binary ${binary}`,
+        };
+    }
+    return {
+        level: 'warn',
+        detail: `bandit re-ranking is on but state is absent at ${input.statePath}; answering binary ${binary}`,
+    };
+}
+//# sourceMappingURL=doctor-instrument.js.map

package/dist/doctor-instrument.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-instrument.js","sourceRoot":"","sources":["../src/doctor-instrument.ts"],"names":[],"mappings":"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"}

package/dist/experiment-assign.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Deterministic, blocked arm assignment for a prospective ablation (ADR-001, ablation-c-start).
+ *
+ * WHY. The owner's question — does the Step-8 QE mode change task speed — is only answerable
+ * causally if the variant a task receives is decided by chance, BEFORE the work starts, and tied to
+ * the task's own identity so a repeated query for the same task never reassigns it. This module is
+ * that decision: a PURE function of `(experiment, stratum, seed, index)`. No filesystem, no clock,
+ * no network — the caller (the cli) owns the journal, the lock, and the "did work already start?"
+ * check; this module only computes.
+ *
+ * ALGORITHM — block randomization, one pair per arm-combination per block. `mulberry32` is the
+ * repo's ONLY pseudo-random generator (`compounding.ts` — "no second RNG in this repo"); reused
+ * here rather than adding a second stream. Block size is `arms.length * 2` — two occurrences of
+ * every arm per block, so a completed block is always perfectly balanced and `propensity` (the
+ * arm's actual share of its block) is a fixed `1 / arms.length` — never guessed, never assumed
+ * 0.5 by default (NFR-4). The block's own permutation is seeded from
+ * `fnv1a(JSON.stringify([experiment, stratum, seed, block]))` (a JSON-tuple, not a delimiter join —
+ * the same reason `workOrderDigestInput` in epoch-replay.ts uses tuples: a delimiter in `experiment`
+ * or `stratum` could otherwise make two different keys hash identically) — so different strata (and
+ * different experiments) never share a stream, and the SAME `(experiment, stratum, seed, index)`
+ * always rederives the SAME arm (A1 idempotency, A2 block balance, A3 propensity).
+ */
+export interface AssignArmInput {
+    readonly experiment: string;
+    readonly stratum: string;
+    /** Pre-registered seed — fixed once, before any assignment is made. */
+    readonly seed: number;
+    /** 0-based ordinal of this task within its `(experiment, stratum)` sequence. */
+    readonly index: number;
+    /** The arms on offer, e.g. `['direct', 'reference']`. At least 2, all non-empty, all unique. */
+    readonly arms: readonly string[];
+}
+export type AssignArmResult = {
+    readonly ok: true;
+    readonly arm: string;
+    readonly propensity: number;
+    readonly block: number;
+    readonly position: number;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Deterministically assign one arm to task ordinal `index` within `(experiment, stratum)`. Refuses
+ * (never throws, never guesses) on any malformed input — empty strings, a non-integer seed/index, a
+ * negative index, fewer than two arms, duplicate or blank arm names.
+ */
+export declare function assignArm(input: AssignArmInput): AssignArmResult;
+export interface AssignmentRecord {
+    readonly ts: string;
+    readonly experiment: string;
+    readonly taskId: string;
+    readonly stratum: string;
+    readonly seed: number;
+    readonly index: number;
+    readonly block: number;
+    readonly position: number;
+    readonly arm: string;
+    readonly propensity: number;
+    readonly assignedAt: string;
+}
+export interface ReadAssignmentsResult {
+    readonly records: readonly AssignmentRecord[];
+    /** Non-blank lines that did not parse as a valid assignment record. Never silently dropped: a
+     * caller checking "is this task assigned?" must be able to tell "no" from "the journal is
+     * unreadable here" (A5). */
+    readonly malformedLines: number;
+}
+export type VerifyAssignmentResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+    /** Lead delta after Codex r2: `null` when the record failed on its SEED — there is nothing to
+     *  expect, because the tuple it would be derived from is itself the thing under suspicion. */
+    readonly expected: {
+        readonly arm: string;
+        readonly block: number;
+        readonly position: number;
+        readonly propensity: number;
+    } | null;
+    readonly actual: {
+        readonly arm: string;
+        readonly block: number;
+        readonly position: number;
+        readonly propensity: number;
+    };
+};
+/**
+ * fix-round-1 (Codex r1 HIGH #7) — "syntactically valid journal corruption is accepted and returned
+ * as the task's assignment". A record that passes `isValidAssignmentRecord`'s SHAPE checks can still
+ * have been hand-edited to a different arm/block/position/propensity while keeping every field the
+ * right TYPE (e.g. flipping `arm:"direct"` to `arm:"reference"`, or `position:99`). The only way to
+ * catch that is to REDERIVE the assignment from the record's own tuple
+ * `(experiment, stratum, seed, index)` via the SAME pure `assignArm` that produced it, and compare —
+ * never trust the stored arm/block/position/propensity on their own. `arms` is the experiment's own
+ * registered arm set (from its `dz experiment init` config), passed in by the caller — this module
+ * stays pure and fs-free.
+ */
+export declare function verifyAssignmentRecord(record: AssignmentRecord, arms: readonly string[], pinnedSeed?: number): VerifyAssignmentResult;
+/**
+ * Parse a JSONL assignments journal (one record per line) into records, WITHOUT touching the
+ * filesystem — the caller reads the file, this only parses its text (NFR-1: the core stays
+ * `node:fs`-free). A line that is blank is skipped silently (append-only files end in a trailing
+ * newline); a line that is non-blank but does not parse as JSON, or parses to something missing a
+ * required field, counts toward `malformedLines` and is otherwise ignored — corruption is named, not
+ * folded into "not assigned" (A5).
+ */
+export declare function readAssignments(text: string): ReadAssignmentsResult;
+//# sourceMappingURL=experiment-assign.d.ts.map

package/dist/experiment-assign.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiment-assign.d.ts","sourceRoot":"","sources":["../src/experiment-assign.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gGAAgG;IAChG,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC3H;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAkBpD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,eAAe,CA+BhE;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C;;gCAE4B;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AA6CD,MAAM,MAAM,sBAAsB,GAC9B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GACrB;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;kGAC8F;IAC9F,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACnI,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3H,CAAC;AAEN;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,sBAAsB,CAkErI;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,qBAAqB,CAiBnE"}

package/dist/experiment-assign.js

@@ -0,0 +1,229 @@
+/**
+ * Deterministic, blocked arm assignment for a prospective ablation (ADR-001, ablation-c-start).
+ *
+ * WHY. The owner's question — does the Step-8 QE mode change task speed — is only answerable
+ * causally if the variant a task receives is decided by chance, BEFORE the work starts, and tied to
+ * the task's own identity so a repeated query for the same task never reassigns it. This module is
+ * that decision: a PURE function of `(experiment, stratum, seed, index)`. No filesystem, no clock,
+ * no network — the caller (the cli) owns the journal, the lock, and the "did work already start?"
+ * check; this module only computes.
+ *
+ * ALGORITHM — block randomization, one pair per arm-combination per block. `mulberry32` is the
+ * repo's ONLY pseudo-random generator (`compounding.ts` — "no second RNG in this repo"); reused
+ * here rather than adding a second stream. Block size is `arms.length * 2` — two occurrences of
+ * every arm per block, so a completed block is always perfectly balanced and `propensity` (the
+ * arm's actual share of its block) is a fixed `1 / arms.length` — never guessed, never assumed
+ * 0.5 by default (NFR-4). The block's own permutation is seeded from
+ * `fnv1a(JSON.stringify([experiment, stratum, seed, block]))` (a JSON-tuple, not a delimiter join —
+ * the same reason `workOrderDigestInput` in epoch-replay.ts uses tuples: a delimiter in `experiment`
+ * or `stratum` could otherwise make two different keys hash identically) — so different strata (and
+ * different experiments) never share a stream, and the SAME `(experiment, stratum, seed, index)`
+ * always rederives the SAME arm (A1 idempotency, A2 block balance, A3 propensity).
+ */
+import { fnv1a } from './feature-adr-checkpoints.js';
+import { mulberry32 } from './compounding.js';
+function isNonEmptyString(v) {
+    return typeof v === 'string' && v.trim() !== '';
+}
+/** Fisher-Yates, driven by the given deterministic RNG. Does not mutate its input. */
+function shuffle(items, rand) {
+    const out = items.slice();
+    for (let i = out.length - 1; i > 0; i--) {
+        const j = Math.floor(rand() * (i + 1));
+        const tmp = out[i];
+        out[i] = out[j];
+        out[j] = tmp;
+    }
+    return out;
+}
+/**
+ * Deterministically assign one arm to task ordinal `index` within `(experiment, stratum)`. Refuses
+ * (never throws, never guesses) on any malformed input — empty strings, a non-integer seed/index, a
+ * negative index, fewer than two arms, duplicate or blank arm names.
+ */
+export function assignArm(input) {
+    if (!isNonEmptyString(input?.experiment))
+        return { ok: false, reason: 'experiment: expected a non-empty string' };
+    if (!isNonEmptyString(input?.stratum))
+        return { ok: false, reason: 'stratum: expected a non-empty string' };
+    if (!Number.isInteger(input?.seed) || input.seed < 0)
+        return { ok: false, reason: 'seed: expected a non-negative integer' };
+    if (!Number.isInteger(input?.index) || input.index < 0)
+        return { ok: false, reason: 'index: expected a non-negative integer' };
+    if (!Array.isArray(input?.arms) || input.arms.length < 2) {
+        return { ok: false, reason: 'arms: expected an array of at least 2 arm names' };
+    }
+    if (!input.arms.every(isNonEmptyString))
+        return { ok: false, reason: 'arms: every arm name must be a non-empty string' };
+    const seen = new Set();
+    for (const a of input.arms) {
+        if (seen.has(a))
+            return { ok: false, reason: `arms: duplicate arm name ${JSON.stringify(a)}` };
+        seen.add(a);
+    }
+    const blockSize = input.arms.length * 2; // two copies of every arm — always a perfect block
+    const block = Math.floor(input.index / input.arms.length / 2); // == Math.floor(index / blockSize)
+    const position = input.index % blockSize;
+    const key = JSON.stringify({ experiment: input.experiment, stratum: input.stratum, seed: input.seed, block });
+    const rand = mulberry32(parseInt(fnv1a(key), 16) >>> 0);
+    // Base card set for this block: every arm twice, in the input's own order — then permuted by the
+    // block-seeded stream, so the CONTENT of every block is fixed by construction (perfect balance)
+    // and only the ORDER is randomized.
+    const cards = [];
+    for (const a of input.arms) {
+        cards.push(a);
+        cards.push(a);
+    }
+    const permuted = shuffle(cards, rand);
+    const arm = permuted[position];
+    const propensity = 2 / blockSize; // == 1 / arms.length — the arm's fixed, actual share of its block
+    return { ok: true, arm, propensity, block, position };
+}
+/** fix-round-1 (Codex r1 HIGH #7): `new Date().toISOString()` is the ONLY producer of `ts`/
+ * `assignedAt` (see the cli's `experimentJournalPath` writer) — a record whose timestamp does not
+ * match that exact shape did not come from this code path, so it is corruption, not merely an
+ * unusual value. */
+const ISO_TIMESTAMP_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+function isValidIsoTimestamp(v) {
+    // Lead delta after Codex r2 (MEDIUM): shape + `Date.parse` accepts impossible calendar dates —
+    // `2026-02-30T00:00:00.000Z` parses (it rolls into March) and passed. Round-tripping through
+    // `toISOString()` is the exact check: only a real instant re-serializes to the same string.
+    if (typeof v !== 'string' || !ISO_TIMESTAMP_RE.test(v))
+        return false;
+    const ms = Date.parse(v);
+    return Number.isFinite(ms) && new Date(ms).toISOString() === v;
+}
+/**
+ * PURELY STRUCTURAL: every field is present and the right TYPE. This is `readAssignments`'s gate —
+ * it decides whether a journal LINE parses at all (A5's `malformedLines`). It deliberately does NOT
+ * validate timestamp FORMAT, propensity RANGE, or arm MEMBERSHIP: a line that is well-typed but
+ * semantically wrong (a hand-edited `position:99`, `propensity:2`, a flipped `arm`) is exactly the
+ * "syntactically valid corruption" `verifyAssignmentRecord` below exists to catch — folding those
+ * checks in here would make a single semantically-tampered record poison `readAssignments` for
+ * every caller, including ones (like `status`'s per-task duration math) that need to name WHICH
+ * task is bad rather than refuse the whole read (fix-round-1 HIGH #7/#8 — see `verifyAssignmentRecord`).
+ */
+function isValidAssignmentRecord(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const r = v;
+    return (isNonEmptyString(r['ts']) &&
+        isNonEmptyString(r['experiment']) &&
+        isNonEmptyString(r['taskId']) &&
+        isNonEmptyString(r['stratum']) &&
+        Number.isInteger(r['seed']) && r['seed'] >= 0 &&
+        Number.isInteger(r['index']) && r['index'] >= 0 &&
+        Number.isInteger(r['block']) && r['block'] >= 0 &&
+        Number.isInteger(r['position']) && r['position'] >= 0 &&
+        isNonEmptyString(r['arm']) &&
+        typeof r['propensity'] === 'number' && Number.isFinite(r['propensity']) &&
+        isNonEmptyString(r['assignedAt']));
+}
+/**
+ * fix-round-1 (Codex r1 HIGH #7) — "syntactically valid journal corruption is accepted and returned
+ * as the task's assignment". A record that passes `isValidAssignmentRecord`'s SHAPE checks can still
+ * have been hand-edited to a different arm/block/position/propensity while keeping every field the
+ * right TYPE (e.g. flipping `arm:"direct"` to `arm:"reference"`, or `position:99`). The only way to
+ * catch that is to REDERIVE the assignment from the record's own tuple
+ * `(experiment, stratum, seed, index)` via the SAME pure `assignArm` that produced it, and compare —
+ * never trust the stored arm/block/position/propensity on their own. `arms` is the experiment's own
+ * registered arm set (from its `dz experiment init` config), passed in by the caller — this module
+ * stays pure and fs-free.
+ */
+export function verifyAssignmentRecord(record, arms, pinnedSeed) {
+    // Lead delta after Codex r2 (BLOCKER): rederiving from `record.seed` proves the record is
+    // internally CONSISTENT, never that it is AUTHENTIC — a row carrying any seed at all passes,
+    // because the check compares the row with itself. The experiment's pinned seed (from its
+    // `dz experiment init` config, the one value fixed before the first assignment) is the trusted
+    // side of the comparison; a row that disagrees with it is tampered, however well-formed.
+    if (pinnedSeed !== undefined && record.seed !== pinnedSeed) {
+        return {
+            ok: false,
+            reason: `assignment-tampered: task ${JSON.stringify(record.taskId)} carries seed ${record.seed}, but experiment ${JSON.stringify(record.experiment)} is pinned to seed ${pinnedSeed} — a record's own seed can never authenticate it`,
+            expected: null,
+            actual: { arm: record.arm, block: record.block, position: record.position, propensity: record.propensity },
+        };
+    }
+    const recomputed = assignArm({ experiment: record.experiment, stratum: record.stratum, seed: record.seed, index: record.index, arms });
+    const actual = { arm: record.arm, block: record.block, position: record.position, propensity: record.propensity };
+    const expected = recomputed.ok
+        ? { arm: recomputed.arm, block: recomputed.block, position: recomputed.position, propensity: recomputed.propensity }
+        : { arm: '(tuple refused)', block: -1, position: -1, propensity: -1 };
+    if (!recomputed.ok) {
+        return {
+            ok: false,
+            reason: `assignment-tampered: task ${JSON.stringify(record.taskId)}'s stored tuple (experiment=${JSON.stringify(record.experiment)}, stratum=${JSON.stringify(record.stratum)}, seed=${record.seed}, index=${record.index}) no longer rederives a valid assignment (${recomputed.reason}) — the stored record does not match what assignArm would produce from its own tuple`,
+            expected,
+            actual,
+        };
+    }
+    if (expected.arm !== actual.arm || expected.block !== actual.block || expected.position !== actual.position || expected.propensity !== actual.propensity) {
+        return {
+            ok: false,
+            reason: `assignment-tampered: task ${JSON.stringify(record.taskId)}'s stored assignment does not match what assignArm rederives from its own tuple (experiment=${JSON.stringify(record.experiment)}, stratum=${JSON.stringify(record.stratum)}, seed=${record.seed}, index=${record.index}) — the journal line was modified after it was written`,
+            expected,
+            actual,
+        };
+    }
+    // fix-round-1 HIGH #7 (named explicitly in the brief, beyond what recompute-and-compare already
+    // implies): timestamp FORMAT, propensity RANGE, and arm MEMBERSHIP. Recompute already makes a
+    // WRONG arm/propensity/block/position fail above; these three checks catch what recompute cannot
+    // — `assignArm` never produces a `ts`/`assignedAt` at all (they are wall-clock, not derived from
+    // the tuple), so a hand-edited "not-a-date" needs its own check.
+    if (!isValidIsoTimestamp(record.ts) || !isValidIsoTimestamp(record.assignedAt)) {
+        return {
+            ok: false,
+            reason: `assignment-tampered: task ${JSON.stringify(record.taskId)}'s ts/assignedAt is not a valid ISO-8601 UTC timestamp (ts=${JSON.stringify(record.ts)}, assignedAt=${JSON.stringify(record.assignedAt)})`,
+            expected,
+            actual,
+        };
+    }
+    if (!(record.propensity >= 0 && record.propensity <= 1)) {
+        return {
+            ok: false,
+            reason: `assignment-tampered: task ${JSON.stringify(record.taskId)}'s propensity ${record.propensity} is outside the valid [0,1] range`,
+            expected,
+            actual,
+        };
+    }
+    if (!arms.includes(record.arm)) {
+        return {
+            ok: false,
+            reason: `assignment-tampered: task ${JSON.stringify(record.taskId)}'s arm ${JSON.stringify(record.arm)} is not one of this experiment's registered arms (${arms.join(', ')})`,
+            expected,
+            actual,
+        };
+    }
+    return { ok: true };
+}
+/**
+ * Parse a JSONL assignments journal (one record per line) into records, WITHOUT touching the
+ * filesystem — the caller reads the file, this only parses its text (NFR-1: the core stays
+ * `node:fs`-free). A line that is blank is skipped silently (append-only files end in a trailing
+ * newline); a line that is non-blank but does not parse as JSON, or parses to something missing a
+ * required field, counts toward `malformedLines` and is otherwise ignored — corruption is named, not
+ * folded into "not assigned" (A5).
+ */
+export function readAssignments(text) {
+    const records = [];
+    let malformedLines = 0;
+    for (const raw of String(text ?? '').split('\n')) {
+        const line = raw.trim();
+        if (line === '')
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            malformedLines++;
+            continue;
+        }
+        if (isValidAssignmentRecord(parsed))
+            records.push(parsed);
+        else
+            malformedLines++;
+    }
+    return { records, malformedLines };
+}
+//# sourceMappingURL=experiment-assign.js.map

package/dist/experiment-assign.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiment-assign.js","sourceRoot":"","sources":["../src/experiment-assign.ts"],"names":[],"mappings":"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"}

package/dist/feature-adr-checkpoints.d.ts

@@ -185,7 +185,7 @@ export declare function decideCheckpointResume(opts: {
 /** Serialize one checkpoint line, or null when the result is null/oversize/unserializable —
  * the caller logs the skip loudly; a missing checkpoint only costs a re-run, never corrupts.
  * A null result is never persisted (Codex QE #8: it would later parse as a resumable entry). */
-export declare function serializeCheckpoint(stage: string, inputHash: string, result: unknown): string | null;
+export declare function serializeCheckpoint(stage: string, inputHash: string, result: unknown, ts?: string): string | null;
 export interface ParsedCheckpointRead {
     entries: Record<string, CheckpointEntry>;
     listing: Set<string>;
@@ -209,7 +209,12 @@ export declare function shellQuote(s: string): string;
 export declare function checkpointReadCmd(fdirAbs: string): string;
 /** The one Bash command the write agent runs: mkdir the state dir, then append ONE line. The line
  * is single-quote-escaped as a whole — JSON.stringify output never contains literal newlines, so
- * printf '%s\n' emits exactly one record. */
+ * printf '%s\n' emits exactly one record.
+ *
+ * The record's `ts` is stamped SHELL-SIDE (`date -u`), the same idiom the decision-recall ledger
+ * uses, because the workflow sandbox forbids `Date` and this function must stay pure. A line that
+ * is not a JSON object falls back to the plain append: an unstamped record beats a lost one, and
+ * the return type stays `string` so no caller grows a new failure path. */
 export declare function checkpointAppendCmd(fdirAbs: string, line: string): string;
 export type CaptureMode = 'capture' | 'backfill' | 'skip-disabled' | 'skip-empty';
 /** Decide whether this completion is captured. A resumed stage is backfilled rather than

package/dist/feature-adr-checkpoints.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"feature-adr-checkpoints.d.ts","sourceRoot":"","sources":["../src/feature-adr-checkpoints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;qGACqG;AACrG,eAAO,MAAM,YAAY,UAAU,CAAC;AAEpC;;0DAE0D;AAC1D,eAAO,MAAM,iBAAiB,8DAA+D,CAAC;AAC9F,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE;;;;8EAI8E;AAC9E,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAUlE,CAAC;AAEF,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB;;;;;;;;;;;;;;;;;;OAkBG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;yFACyF;AACzF,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAElD;;qGAEqG;AACrG;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,qBAAqB,wBAAwB,CAAC;AAE3D,wGAAwG;AACxG,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOzC;AAED;;kFAEkF;AAClF,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED;;;;;;;0DAO0D;AAC1D,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAEpF;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAEpD,6FAA6F;AAC7F,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CAEnD;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EACF,SAAS,GACT,eAAe,GACf,YAAY,GACZ,eAAe,GACf,aAAa,GACb,kBAAkB,CAAC;CACxB;AAED;;;;gFAIgF;AAChF;qGACqG;AACrG,eAAO,MAAM,gBAAgB,0DAA2D,CAAC;AACzF,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/D,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,GAAG,MAAM,CAEnE;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,CAAC;IAClB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B;uGACmG;IACnG,MAAM,EAAE,IAAI,GAAG,kBAAkB,GAAG,kBAAkB,GAAG,uBAAuB,CAAC;CAClF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C;;;;;;;;;;;;OAYG;IACH,OAAO,EAAE,SAAS,OAAO,EAAE,CAAC;IAC5B,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,gGAAgG;IAChG,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B;;;;;;;;;;OAUG;IACH,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;CAC5C,GAAG,gBAAgB,CAoBnB;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,eAAe,GAAG,SAAS,CAAC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IAC/C,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC9B,GAAG,cAAc,CAYjB;AAED;;gGAEgG;AAChG,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAUpG;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACzC,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;uBACuB;AACvB,eAAO,MAAM,sBAAsB,qBAAqB,CAAC;AAEzD;;;;;6FAK6F;AAC7F,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,CA6BtE;AAED,6DAA6D;AAC7D,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED;;qEAEqE;AACrE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAOzD;AAED;;6CAE6C;AAC7C,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIzE;AAwBD,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,eAAe,GAAG,YAAY,CAAC;AAElF;;;;gDAIgD;AAChD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,CAIhH;AAED,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,gBAAgB,GAAG,YAAY,GAAG,qBAAqB,GAAG,cAAc,CAAC;AAEtH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,oBAAoB,CAAC;IAC7B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;gGACgG;AAChG,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,oBAAoB,CAoB1H;AAED,2EAA2E;AAC3E,eAAO,MAAM,wBAAwB,mBAAmB,CAAC;AAEzD;;;;6DAI6D;AAC7D,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEpD;;;qFAGqF;AACrF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,kBAAkB,CAEpE;AAED,MAAM,WAAW,sBAAsB;IACrC,qFAAqF;IACrF,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,2EAA2E;IAC3E,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,MAAM,EAAE,kBAAkB,CAAC;IAC3B,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,wFAAwF;AACxF,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC5B,MAAM,EAAE,QAAQ,GAAG,KAAK,CAAC;IACzB,KAAK,EAAE,QAAQ,GAAG,KAAK,CAAC;IACxB,MAAM,EAAE,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;CAC1D;AAED,MAAM,WAAW,sBAAsB;IACrC,wFAAwF;IACxF,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wFAAwF;AACxF,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,iNAAiN;IACjN,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,sBAAsB,CAAC;IACnC,UAAU,EAAE,sBAAsB,CAAC;IACnC,UAAU,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACtC,SAAS,EAAE,sBAAsB,GAAG,IAAI,CAAC;IACzC,WAAW,EAAE,SAAS,GAAG,UAAU,CAAC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB;;;sDAGkD;IAClD,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;CAC1B;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED;kFACkF;AAClF,eAAO,MAAM,sBAAsB,kpBACymB,CAAC;AAE7oB;;mCAEmC;AACnC;;kGAEkG;AAClG,eAAO,MAAM,uBAAuB,8BAA8B,CAAC;AACnE,eAAO,MAAM,qBAAqB,4BAA4B,CAAC;AAE/D;+CAC+C;AAC/C,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAE3D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAiCzD;AA4DD;;;;;;sFAMsF;AACtF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,GAAG,IAAI,CAAC;IACpD,UAAU,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,GAAG,IAAI,CAAC;IACpD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,YAAY,CA4Cf;AAED;qGACqG;AACrG,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAOvE;AAED;;oCAEoC;AACpC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CASxG;AAED,oGAAoG;AACpG,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAC/C,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AACnD,eAAO,MAAM,eAAe,oBAAoB,CAAC;AAEjD;;;;;;;;;;;;;0CAa0C;AAC1C,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAyB/I;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,4BAA4B,CAAC,aAAa,EAAE,OAAO,EAAE,eAAe,EAAE,OAAO,GAAG,OAAO,CAItG;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAQ7D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAoBrB;AAED,uEAAuE;AACvE,MAAM,MAAM,sBAAsB,GAC9B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACnF;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,GAAG,sBAAsB,CAqBzB"}
+{"version":3,"file":"feature-adr-checkpoints.d.ts","sourceRoot":"","sources":["../src/feature-adr-checkpoints.ts"],"names":[],"mappings":"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"}

package/dist/feature-adr-checkpoints.js

@@ -173,12 +173,12 @@ export function decideCheckpointResume(opts) {
 /** Serialize one checkpoint line, or null when the result is null/oversize/unserializable —
  * the caller logs the skip loudly; a missing checkpoint only costs a re-run, never corrupts.
  * A null result is never persisted (Codex QE #8: it would later parse as a resumable entry). */
-export function serializeCheckpoint(stage, inputHash, result) {
+export function serializeCheckpoint(stage, inputHash, result, ts) {
     if (result === null || result === undefined)
         return null;
     let line;
     try {
-        line = JSON.stringify({ stage, inputHash, result });
+        line = JSON.stringify({ stage, inputHash, result, ...(ts === undefined ? {} : { ts }) });
     }
     catch {
         return null;
@@ -190,6 +190,8 @@ export function serializeCheckpoint(stage, inputHash, result) {
 /** Sentinel separating the checkpoint file body from the artifact listing in the single read-back
  * command's stdout. */
 export const CHECKPOINT_LS_SENTINEL = '---FA-CKPT-LS---';
+/** A writer-produced UTC instant. A malformed supplied value is unmeasured, not a bad record. */
+const CHECKPOINT_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
 /** Parse the read-back agent's stdout: JSONL entries (LAST occurrence of a stage wins — a re-run
  * overwrites by append), then the sentinel ON ITS OWN LINE, then one artifact path per line
  * (relative to the feature dir). The sentinel match is LINE-ANCHORED: JSON.stringify never emits
@@ -210,7 +212,11 @@ export function parseCheckpointRead(text) {
         try {
             const e = JSON.parse(t);
             if (e && typeof e === 'object' && typeof e.stage === 'string' && typeof e.inputHash === 'string' && 'result' in e && e.result !== null && e.result !== undefined) {
-                out.entries[e.stage] = e;
+                const { ts, ...entry } = e;
+                // Narrow to `string` before the spread: under exactOptionalPropertyTypes an optional
+                // `ts?: string` refuses `string | undefined`, and an unmeasured record must carry NO key
+                // rather than an explicit undefined.
+                out.entries[e.stage] = typeof ts === 'string' && CHECKPOINT_TIMESTAMP.test(ts) ? { ...entry, ts } : entry;
             }
             else {
                 // last-wins holds for BAD records too: a stage-identifiable null/invalid record ERASES the
@@ -246,11 +252,20 @@ export function checkpointReadCmd(fdirAbs) {
 }
 /** The one Bash command the write agent runs: mkdir the state dir, then append ONE line. The line
  * is single-quote-escaped as a whole — JSON.stringify output never contains literal newlines, so
- * printf '%s\n' emits exactly one record. */
+ * printf '%s\n' emits exactly one record.
+ *
+ * The record's `ts` is stamped SHELL-SIDE (`date -u`), the same idiom the decision-recall ledger
+ * uses, because the workflow sandbox forbids `Date` and this function must stay pure. A line that
+ * is not a JSON object falls back to the plain append: an unstamped record beats a lost one, and
+ * the return type stays `string` so no caller grows a new failure path. */
 export function checkpointAppendCmd(fdirAbs, line) {
     const dir = shellQuote(fdirAbs + '/.fa-state');
     const file = shellQuote(fdirAbs + '/.fa-state/checkpoints.jsonl');
-    return 'mkdir -p ' + dir + " && printf '%s\\n' " + shellQuote(line) + ' >> ' + file;
+    const plain = 'mkdir -p ' + dir + " && printf '%s\\n' " + shellQuote(line) + ' >> ' + file;
+    if (typeof line !== 'string' || !line.startsWith('{'))
+        return plain;
+    return 'ts=$(date -u +%Y-%m-%dT%H:%M:%SZ); mkdir -p ' + dir
+        + ' && { printf \'{"ts":"%s",\' "$ts"; printf \'%s\\n\' ' + shellQuote(line.slice(1)) + '; } >> ' + file;
 }
 /** Decide whether this completion is captured. A resumed stage is backfilled rather than
  * skipped: its input (stage template + args) and checkpointed output are both in scope at the