openplanr 1.16.1 → 1.17.0

package/dist/services/operate/citation-resolution.js

@@ -0,0 +1,308 @@
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { resolvePipelinePackage } from '../pipeline-package-service.js';
+import { resolvePlanrArtifactCitation } from './artifacts.js';
+import { canonicalDigest } from './canonical.js';
+import { assertOperatingArtifact } from './protocol.js';
+import { gitRevisionResolves, readGitCommitSummary, readGitPathAtRevision, } from './read-only-providers.js';
+import { redactSensitiveText } from './redaction.js';
+import { OperateError, } from './types.js';
+import { isPathInside } from './workspace.js';
+/**
+ * FR3 (E-003) — resolve every citation an advisor returns against the cycle's
+ * pinned revision and snapshot the cited content into machine-local evidence.
+ *
+ * This module owns NO precedence and NO citation/gap shape. Every fact/reason
+ * mapping (path → line → revision → artifact) and the canonical resolution and
+ * unresolvable-citation gap records come from the installed pipeline's
+ * `lib/operate/citation.mjs` (`operating-citation@1.3.0`). This module supplies
+ * the facts — computed honestly against live git/`.planr/` state at the pinned
+ * revision — and, on a resolved outcome, snapshots the cited bytes through the
+ * standard redaction + secret-scan path before attaching the resulting evidence
+ * ID to the proposal. A citation with any unresolvable component NEVER produces
+ * an evidence ID: it fails closed into a gap, and its proposal never reaches
+ * consolidation.
+ *
+ * The one classification this module adds beyond the library — which by design
+ * has no repo access and cannot make it — is the DISTINCT dirty-working-tree
+ * rejection. The pin is frozen at cycle start; a citation into content that is
+ * present in the working tree but not committed at the pin would otherwise be
+ * indistinguishable from a fabricated path. Naming it distinctly keeps a
+ * legitimate finding that points at in-flight work from being silently
+ * discarded as a fabrication.
+ */
+const DEFAULT_SNAPSHOT_TTL_MS = 24 * 60 * 60 * 1_000;
+let cachedModule = null;
+async function loadCitationModule() {
+    cachedModule ??= (async () => {
+        const pkg = resolvePipelinePackage(false);
+        if (!pkg) {
+            throw new OperateError('E_PIPELINE_NOT_INSTALLED', 'Citation resolution requires the pipeline package with Protocol v1.3 (operating-citation@1.3.0).');
+        }
+        const modulePath = path.join(pkg.root, 'lib', 'operate', 'citation.mjs');
+        const loaded = (await import(pathToFileURL(modulePath).href));
+        if (typeof loaded.resolveOperatingCitation !== 'function' ||
+            typeof loaded.validateOperatingCitation !== 'function' ||
+            typeof loaded.buildUnresolvableCitationGap !== 'function') {
+            throw new OperateError('E_PIPELINE_VERSION_INCOMPATIBLE', `Installed planr-pipeline ${pkg.version} does not export the Protocol v1.3 citation resolver.`);
+        }
+        return loaded;
+    })();
+    return cachedModule;
+}
+function citationKind(citation) {
+    if (typeof citation.repositoryPath === 'string')
+        return 'repo-path';
+    if (typeof citation.gitRevision === 'string')
+        return 'git-revision';
+    if (typeof citation.planrArtifactId === 'string')
+        return 'planr-artifact';
+    return null;
+}
+function stableCitationKey(citation) {
+    if (typeof citation.citationKey === 'string' && /^[A-Za-z0-9._-]+$/.test(citation.citationKey)) {
+        return citation.citationKey;
+    }
+    return `cite-${canonicalDigest(citation).slice('sha256:'.length, 34)}`;
+}
+function lineRangeWithin(range, lineCount) {
+    return (Number.isInteger(range.start) &&
+        Number.isInteger(range.end) &&
+        range.start >= 1 &&
+        range.end >= range.start &&
+        range.end <= lineCount);
+}
+async function workingTreeHasFile(projectRoot, relativePath) {
+    const root = path.resolve(projectRoot);
+    const target = path.resolve(root, relativePath);
+    if (!isPathInside(root, target))
+        return false;
+    try {
+        return (await stat(target)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function dirtyWorkingTreeGap(citation, context, now) {
+    const range = citation.lineRange
+        ? ` lines ${citation.lineRange.start}-${citation.lineRange.end}`
+        : '';
+    const createdAt = now.toISOString();
+    const gap = {
+        kind: 'operating-data-gap',
+        schemaVersion: '1.0.0',
+        protocolVersion: '1.3.0',
+        id: `GAP-${canonicalDigest({ citation, reason: 'dirty-working-tree' }).slice('sha256:'.length)}`,
+        cycleId: context.cycleId,
+        category: 'unresolvable-citation',
+        question: `The repository path "${citation.repositoryPath}"${range} cites uncommitted working-tree ` +
+            `content that is not present at pinned revision ${citation.pinnedRevision}; commit the change ` +
+            'or cite the pinned revision before this proposal can be accepted.',
+        reason: 'dirty-working-tree',
+        unblocks: [],
+        status: 'open',
+        owner: context.owner && context.owner.length > 0 ? context.owner : 'chair',
+        evidenceRefs: [],
+        createdAt,
+        updatedAt: createdAt,
+    };
+    return gap;
+}
+async function observeCitation(citation, context, sensitivity) {
+    const kind = citationKind(citation);
+    if (kind === 'repo-path' && citation.repositoryPath) {
+        const blob = await readGitPathAtRevision(context.projectRoot, citation.pinnedRevision, citation.repositoryPath);
+        const inWorkingTree = blob.exists
+            ? true
+            : await workingTreeHasFile(context.projectRoot, citation.repositoryPath);
+        return {
+            kind,
+            pathExistsAtRevision: blob.exists,
+            inWorkingTree,
+            content: blob.content,
+            lineCount: blob.lineCount,
+            location: citation.repositoryPath,
+        };
+    }
+    if (kind === 'git-revision' && citation.gitRevision) {
+        const resolves = await gitRevisionResolves(context.projectRoot, citation.gitRevision);
+        const summary = resolves
+            ? await readGitCommitSummary(context.projectRoot, citation.gitRevision)
+            : null;
+        return {
+            kind,
+            revisionResolves: resolves,
+            content: summary ?? `commit ${citation.gitRevision}`,
+            location: `git:${citation.gitRevision}`,
+        };
+    }
+    // planr-artifact
+    const resolution = await resolvePlanrArtifactCitation({
+        projectRoot: context.projectRoot,
+        pinnedRevision: citation.pinnedRevision,
+        artifactId: citation.planrArtifactId,
+        sensitivity,
+    });
+    return {
+        kind: 'planr-artifact',
+        artifactExists: resolution.artifactExists,
+        content: resolution.content,
+        location: resolution.location,
+        preRedacted: true,
+    };
+}
+function factsFor(citation, observation, cyclePinnedRevision, sensitivity) {
+    const facts = { sensitivity };
+    if (observation.kind === 'repo-path') {
+        facts.pathExistsAtRevision = observation.pathExistsAtRevision === true;
+        if (citation.lineRange) {
+            facts.lineRangeInBounds =
+                observation.pathExistsAtRevision === true &&
+                    lineRangeWithin(citation.lineRange, observation.lineCount ?? 0);
+        }
+        facts.revisionIsCurrent = citation.pinnedRevision === cyclePinnedRevision;
+    }
+    else if (observation.kind === 'git-revision') {
+        facts.revisionIsCurrent =
+            citation.pinnedRevision === cyclePinnedRevision && observation.revisionResolves === true;
+    }
+    else {
+        facts.artifactExists = observation.artifactExists === true;
+    }
+    return facts;
+}
+/**
+ * Resolve one citation against the cycle's pinned revision. Never throws for a
+ * resolvable/unresolvable outcome: a resolved citation carries an `evidenceId`
+ * whose snapshot has been persisted to machine-local evidence; a rejected one
+ * carries a distinct `reason` and a single unresolvable-citation `gap`.
+ */
+export async function resolveOperatingCitationAtPin(citation, context) {
+    const module = await loadCitationModule();
+    try {
+        module.validateOperatingCitation(citation);
+    }
+    catch (error) {
+        throw new OperateError('E_OPERATE_STATE_INVALID', `Citation is not a valid operating-citation@1.3.0 anchor: ${error instanceof Error ? error.message : String(error)}.`);
+    }
+    const now = context.now ?? new Date();
+    const citationKey = stableCitationKey(citation);
+    const keyed = { ...citation, citationKey };
+    const sensitivity = context.sensitivityFor?.(citation) ?? context.defaultSensitivity ?? 'internal';
+    const observation = await observeCitation(keyed, context, sensitivity);
+    // Distinct dirty-working-tree classification, ahead of the library's
+    // path-existence precedence: a cited path absent at the pin but present and
+    // uncommitted in a dirty working tree is named separately from a fabrication.
+    if (observation.kind === 'repo-path' &&
+        observation.pathExistsAtRevision === false &&
+        observation.inWorkingTree === true &&
+        context.descriptor.dirtyFingerprint !== null) {
+        const gap = await assertOperatingArtifact('operating-data-gap', dirtyWorkingTreeGap(keyed, context, now));
+        return {
+            citation: keyed,
+            citationKey,
+            outcome: 'rejected',
+            reason: 'dirty-working-tree',
+            gap,
+            sensitivity,
+        };
+    }
+    const facts = factsFor(keyed, observation, context.descriptor.pinnedRevision, sensitivity);
+    const resolution = module.resolveOperatingCitation(keyed, facts);
+    if (resolution.outcome === 'rejected') {
+        const gap = module.buildUnresolvableCitationGap(keyed, resolution, {
+            cycleId: context.cycleId,
+            createdAt: now.toISOString(),
+            owner: context.owner,
+            affectedRoles: context.affectedRoles,
+        });
+        return {
+            citation: keyed,
+            citationKey,
+            outcome: 'rejected',
+            reason: resolution.reason,
+            gap,
+            sensitivity,
+        };
+    }
+    // Resolved: snapshot the cited bytes through the standard redaction path and
+    // persist them as machine-local evidence under the resolver-minted id.
+    const rawContent = observation.content ?? '';
+    const content = observation.preRedacted ? rawContent : redactSensitiveText(rawContent).value;
+    await context.cache.putCitationSnapshot({
+        evidenceId: resolution.evidenceId,
+        citationKey,
+        snapshotDigest: resolution.snapshotDigest,
+        sourceLocation: observation.location ?? citationKey,
+        sensitivity,
+        content,
+    }, context.snapshotTtlMs ?? DEFAULT_SNAPSHOT_TTL_MS, now);
+    return {
+        citation: keyed,
+        citationKey,
+        outcome: 'resolved',
+        evidenceId: resolution.evidenceId,
+        snapshotDigest: resolution.snapshotDigest,
+        sensitivity,
+    };
+}
+/**
+ * Resolve and enforce every proposal's citations before consolidation. A
+ * proposal whose citations all resolve is accepted with its minted evidence IDs
+ * attached; a proposal with ANY unresolvable citation is dropped and a single
+ * unresolvable-citation gap is opened in its place. Nothing with an unresolved
+ * citation is ever returned in `accepted`, so it can never reach consolidation.
+ */
+export async function enforceProposalCitations(proposals, context) {
+    const accepted = [];
+    const rejected = [];
+    const gapsById = new Map();
+    const evidenceIds = new Set();
+    const resolutions = [];
+    for (const proposal of proposals) {
+        const citations = Array.isArray(proposal.citations) ? proposal.citations : [];
+        const proposalResolutions = [];
+        for (const citation of citations) {
+            const resolved = await resolveOperatingCitationAtPin(citation, context);
+            proposalResolutions.push(resolved);
+            resolutions.push(resolved);
+        }
+        const rejectedCitations = proposalResolutions.filter((resolution) => resolution.outcome === 'rejected');
+        if (rejectedCitations.length > 0) {
+            // Exactly one gap per rejected proposal: the first rejected citation is the
+            // representative cause and owns the opened gap.
+            const primary = rejectedCitations[0];
+            if (primary.gap)
+                gapsById.set(primary.gap.id, primary.gap);
+            rejected.push({
+                proposalKey: proposal.proposalKey,
+                reason: primary.reason,
+                reasons: [
+                    ...new Set(rejectedCitations
+                        .map((resolution) => resolution.reason)
+                        .filter((reason) => Boolean(reason))),
+                ].sort(),
+                gapId: primary.gap?.id ?? '',
+            });
+            continue;
+        }
+        const evidenceRefs = [
+            ...new Set(proposalResolutions
+                .map((resolution) => resolution.evidenceId)
+                .filter((id) => Boolean(id))),
+        ].sort();
+        for (const id of evidenceRefs)
+            evidenceIds.add(id);
+        accepted.push({ proposal, evidenceRefs });
+    }
+    return {
+        accepted,
+        rejected,
+        gaps: [...gapsById.values()].sort((left, right) => left.id.localeCompare(right.id)),
+        evidenceIds: [...evidenceIds].sort(),
+        resolutions,
+    };
+}
+//# sourceMappingURL=citation-resolution.js.map

package/dist/services/operate/citation-resolution.js.map

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

package/dist/services/operate/config.d.ts

@@ -1,5 +1,6 @@
 import { type JournalWrite } from './journal.js';
-import { type OperatingCharter, type OperatingConfig, type OperatingEventHead, type OperatingInitAnswers, type OperatingLocalPreferences, type OperatingProfile, type OperatingWorkspaceManifest } from './types.js';
+import type { OperatingDispatchMode } from './mission-dispatch.js';
+import { type OperatingCharter, type OperatingConfig, type OperatingEventHead, type OperatingInitAnswers, type OperatingLocalPreferences, type OperatingProfile, type OperatingRoleId, type OperatingWorkspaceManifest } from './types.js';
 export declare const OPERATING_PROFILES: readonly OperatingProfile[];
 export declare function listOperatingProfiles(): OperatingProfile[];
 export declare function getOperatingProfile(id: OperatingProfile['id']): OperatingProfile;
@@ -9,6 +10,70 @@ export declare function getOperatingProfile(id: OperatingProfile['id']): Operati
  * (including accidental secrets) never reach command results.
  */
 export declare function normalizeCustomOperatingProfile(value: unknown): Partial<OperatingProfile>;
+/**
+ * Per-project dispatch-mode overrides (FR4 / E-004). A map of role IDs to a
+ * `pack | mission` selection that overrides the derived v1.3 registry default.
+ *
+ * These live in the machine-local `preferences.json`, NOT the schema-frozen
+ * `operating-config` artifact: the v1.2 on-disk config surface is frozen
+ * (`additionalProperties: false`), so v1.3 dispatch policy is carried in the
+ * local operating preferences alongside `sensitivityCeiling` and `runtime`.
+ */
+export type OperatingDispatchModeOverrides = Record<OperatingRoleId, OperatingDispatchMode>;
+/**
+ * Strictly allowlist per-project dispatch-mode overrides before they are echoed,
+ * persisted, or consumed by dispatch — mirroring the `normalizeCustomOperatingProfile`
+ * pattern. Keys must be known registry role IDs; values must be exactly `pack`
+ * or `mission`. Unknown roles or values fail closed with `E_OPERATE_CONFIG_INVALID`.
+ */
+export declare function normalizeOperatingDispatchModeOverrides(value: unknown): OperatingDispatchModeOverrides;
+/**
+ * Parse repeatable `--dispatch-mode-override <roleId>=<pack|mission>` CLI tokens
+ * into a validated override map. Each token must be exactly `roleId=mode`.
+ */
+export declare function parseOperatingDispatchModeOverrideFlags(flags?: readonly string[]): OperatingDispatchModeOverrides;
+/** Read the validated per-project dispatch-mode overrides, or `{}` when none set. */
+export declare function readOperatingDispatchModeOverrides(projectRoot: string, options?: {
+    localRoot?: string;
+}): Promise<OperatingDispatchModeOverrides>;
+/**
+ * Merge validated dispatch-mode overrides into the machine-local preferences and
+ * persist atomically (temp + rename, mode 0o600), matching how initialization
+ * writes preferences.json. An override set to the registry default can be
+ * cleared by omitting it. Requires the project to have been initialized.
+ */
+export declare function applyOperatingDispatchModeOverrides(input: {
+    projectRoot: string;
+    localRoot?: string;
+    overrides: OperatingDispatchModeOverrides;
+}): Promise<{
+    dispatchModeOverrides: OperatingDispatchModeOverrides;
+    changed: boolean;
+}>;
+/**
+ * Read the persisted per-project cadence `lastRunAt` marker (FR8 / E-008), or
+ * `null` when no cycle has completed yet. Machine-local, alongside
+ * `dispatchModeOverrides`.
+ */
+export declare function readOperatingLastRunAt(projectRoot: string, options?: {
+    localRoot?: string;
+}): Promise<string | null>;
+/**
+ * Persist the per-project cadence `lastRunAt` marker into the machine-local
+ * preferences atomically (temp + rename, mode 0o600), matching how dispatch-mode
+ * overrides are written. FR8 / E-008: recorded whenever a cycle reaches
+ * reviewable/blocked/closed so `operate status` can surface the pipeline's
+ * `nextDueAt` under an injected clock. `lastRunAt` is the injected cycle instant,
+ * never a wall-clock read here. Requires an initialized project.
+ */
+export declare function recordOperatingLastRunAt(input: {
+    projectRoot: string;
+    localRoot?: string;
+    lastRunAt: string;
+}): Promise<{
+    lastRunAt: string;
+    changed: boolean;
+}>;
 export declare function normalizeCharter(input?: Partial<OperatingCharter>): OperatingCharter;
 /** Normalize already-validated questionnaire or explicit CLI answers once. */
 export declare function normalizeOperatingInitializationAnswers(input: OperatingInitAnswers): OperatingInitAnswers;
@@ -41,6 +106,7 @@ export declare function prepareOperatingInitialization(input: {
     charter?: Partial<OperatingCharter>;
     customProfile?: Partial<OperatingProfile>;
     componentRoots?: string[];
+    dispatchModeOverrides?: OperatingDispatchModeOverrides;
     localRoot?: string;
     now?: string;
 }): Promise<OperatingInitializationPreview>;

package/dist/services/operate/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/services/operate/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/services/operate/config.ts"],"names":[],"mappings":"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"}

package/dist/services/operate/config.js

@@ -3,7 +3,7 @@ import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { spliceManagedBlock } from '../../utils/splice-managed-block.js';
 import { canonicalDigest, canonicalize, sha256Digest } from './canonical.js';
-import { OperatingEventStore } from './event-store.js';
+import { OperatingEventStore, operatingRecordsLogLine } from './event-store.js';
 import { resolveEvidenceImportPath } from './evidence-import.js';
 import { applyJournalTransaction, prepareJournalTransaction, rollbackJournalTransaction, } from './journal.js';
 import { withOperatingLock } from './lock-service.js';
@@ -179,6 +179,145 @@ export function normalizeCustomOperatingProfile(value) {
     }
     return normalized;
 }
+const DISPATCH_MODES = new Set(['pack', 'mission']);
+/**
+ * Strictly allowlist per-project dispatch-mode overrides before they are echoed,
+ * persisted, or consumed by dispatch — mirroring the `normalizeCustomOperatingProfile`
+ * pattern. Keys must be known registry role IDs; values must be exactly `pack`
+ * or `mission`. Unknown roles or values fail closed with `E_OPERATE_CONFIG_INVALID`.
+ */
+export function normalizeOperatingDispatchModeOverrides(value) {
+    const record = plainRecord(value, 'dispatchModeOverrides');
+    const entries = Object.entries(record);
+    if (entries.length > ALL_ROLES.length) {
+        throw new OperateError('E_OPERATE_CONFIG_INVALID', 'dispatchModeOverrides contains more entries than there are operating roles.');
+    }
+    const normalized = {};
+    for (const [roleId, mode] of entries) {
+        if (!ALL_ROLES.includes(roleId)) {
+            throw new OperateError('E_OPERATE_CONFIG_INVALID', `dispatchModeOverrides references an unknown role: ${roleId}.`);
+        }
+        if (typeof mode !== 'string' || !DISPATCH_MODES.has(mode)) {
+            throw new OperateError('E_OPERATE_CONFIG_INVALID', `dispatchModeOverrides value for ${roleId} must be "pack" or "mission".`);
+        }
+        normalized[roleId] = mode;
+    }
+    return normalized;
+}
+/**
+ * Parse repeatable `--dispatch-mode-override <roleId>=<pack|mission>` CLI tokens
+ * into a validated override map. Each token must be exactly `roleId=mode`.
+ */
+export function parseOperatingDispatchModeOverrideFlags(flags = []) {
+    const raw = {};
+    for (const flag of flags) {
+        const separator = flag.indexOf('=');
+        if (separator <= 0) {
+            throw new OperateError('E_OPERATE_CONFIG_INVALID', `--dispatch-mode-override must be "<roleId>=<pack|mission>", received "${flag}".`);
+        }
+        const roleId = flag.slice(0, separator).trim();
+        const mode = flag.slice(separator + 1).trim();
+        if (raw[roleId] && raw[roleId] !== mode) {
+            throw new OperateError('E_OPERATE_CONFIG_INVALID', `--dispatch-mode-override sets conflicting modes for role ${roleId}.`);
+        }
+        raw[roleId] = mode;
+    }
+    return normalizeOperatingDispatchModeOverrides(raw);
+}
+async function readOperatingPreferencesRecord(projectRoot, options = {}) {
+    const paths = resolveOperatingPaths(projectRoot, { localRoot: options.localRoot });
+    const raw = await readFile(path.join(paths.localRoot, 'preferences.json'), 'utf8').catch(() => null);
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new OperateError('E_OPERATE_CONFIG_INVALID', 'Operating preferences.json is not valid JSON.');
+    }
+}
+/** Read the validated per-project dispatch-mode overrides, or `{}` when none set. */
+export async function readOperatingDispatchModeOverrides(projectRoot, options = {}) {
+    const preferences = await readOperatingPreferencesRecord(projectRoot, options);
+    if (!preferences?.dispatchModeOverrides)
+        return {};
+    return normalizeOperatingDispatchModeOverrides(preferences.dispatchModeOverrides);
+}
+/**
+ * Merge validated dispatch-mode overrides into the machine-local preferences and
+ * persist atomically (temp + rename, mode 0o600), matching how initialization
+ * writes preferences.json. An override set to the registry default can be
+ * cleared by omitting it. Requires the project to have been initialized.
+ */
+export async function applyOperatingDispatchModeOverrides(input) {
+    const preferences = await readOperatingPreferencesRecord(input.projectRoot, {
+        localRoot: input.localRoot,
+    });
+    if (!preferences) {
+        throw new OperateError('E_OPERATE_NOT_INITIALIZED', 'Operating Board is not initialized in this project; run `planr operate init` first.');
+    }
+    const validated = normalizeOperatingDispatchModeOverrides(input.overrides);
+    const merged = {
+        ...(preferences.dispatchModeOverrides ?? {}),
+        ...validated,
+    };
+    const next = { ...preferences };
+    if (Object.keys(merged).length > 0)
+        next.dispatchModeOverrides = merged;
+    else
+        delete next.dispatchModeOverrides;
+    const paths = resolveOperatingPaths(input.projectRoot, { localRoot: input.localRoot });
+    const preferencePath = path.join(paths.localRoot, 'preferences.json');
+    const before = await readFile(preferencePath, 'utf8').catch(() => null);
+    const serialized = `${canonicalize(next)}\n`;
+    const changed = before !== serialized;
+    if (changed) {
+        await mkdir(paths.localRoot, { recursive: true, mode: 0o700 });
+        const temporary = `${preferencePath}.${process.pid}.${randomUUID()}.tmp`;
+        await writeFile(temporary, serialized, { mode: 0o600 });
+        await rename(temporary, preferencePath);
+    }
+    return { dispatchModeOverrides: merged, changed };
+}
+/**
+ * Read the persisted per-project cadence `lastRunAt` marker (FR8 / E-008), or
+ * `null` when no cycle has completed yet. Machine-local, alongside
+ * `dispatchModeOverrides`.
+ */
+export async function readOperatingLastRunAt(projectRoot, options = {}) {
+    const preferences = await readOperatingPreferencesRecord(projectRoot, options);
+    const value = preferences?.lastRunAt;
+    return typeof value === 'string' && value.trim() ? value : null;
+}
+/**
+ * Persist the per-project cadence `lastRunAt` marker into the machine-local
+ * preferences atomically (temp + rename, mode 0o600), matching how dispatch-mode
+ * overrides are written. FR8 / E-008: recorded whenever a cycle reaches
+ * reviewable/blocked/closed so `operate status` can surface the pipeline's
+ * `nextDueAt` under an injected clock. `lastRunAt` is the injected cycle instant,
+ * never a wall-clock read here. Requires an initialized project.
+ */
+export async function recordOperatingLastRunAt(input) {
+    const preferences = await readOperatingPreferencesRecord(input.projectRoot, {
+        localRoot: input.localRoot,
+    });
+    if (!preferences) {
+        throw new OperateError('E_OPERATE_NOT_INITIALIZED', 'Operating Board is not initialized in this project; run `planr operate init` first.');
+    }
+    const next = { ...preferences, lastRunAt: input.lastRunAt };
+    const paths = resolveOperatingPaths(input.projectRoot, { localRoot: input.localRoot });
+    const preferencePath = path.join(paths.localRoot, 'preferences.json');
+    const before = await readFile(preferencePath, 'utf8').catch(() => null);
+    const serialized = `${canonicalize(next)}\n`;
+    const changed = before !== serialized;
+    if (changed) {
+        await mkdir(paths.localRoot, { recursive: true, mode: 0o700 });
+        const temporary = `${preferencePath}.${process.pid}.${randomUUID()}.tmp`;
+        await writeFile(temporary, serialized, { mode: 0o600 });
+        await rename(temporary, preferencePath);
+    }
+    return { lastRunAt: input.lastRunAt, changed };
+}
 export function normalizeCharter(input = {}) {
     const list = (values) => [
         ...new Set((values ?? []).map((value) => value.trim()).filter(Boolean)),
@@ -263,10 +402,12 @@ export function renderOperatingCharter(config, input = {}) {
 }
 const INITIALIZATION_RECOVERY_ID = 'RCV-operating-board-initialized';
 const INITIALIZATION_CORRELATION_ID = 'operate-initialization-v1';
-function operatingRecordPath(digest) {
-    const hex = digest.slice('sha256:'.length);
-    return `.planr/operate/records/sha256/${hex.slice(0, 2)}/${hex.slice(2)}.json`;
-}
+// Protocol v1.3 (FR5/E-005) init layout: internals collapse under `.state/`
+// (events.jsonl, records.jsonl, checkpoint.json). Fresh `operate init` writes
+// this layout directly — there is no SPEC-002 tree to migrate for a new project.
+const OPERATE_STATE_EVENTS = '.planr/operate/.state/events.jsonl';
+const OPERATE_STATE_RECORDS = '.planr/operate/.state/records.jsonl';
+const OPERATE_STATE_CHECKPOINT = '.planr/operate/.state/checkpoint.json';
 async function buildInitialOperatingState(input) {
     const protocol = await loadOperatingProtocol();
     const genesis = { sequence: 0, hash: null };
@@ -340,12 +481,12 @@ async function buildInitialOperatingState(input) {
     const projectionByPath = new Map(projection.files.map((file) => [file.relativePath, file]));
     const writes = [
         {
-            relativePath: operatingRecordPath(record.digest),
-            content: canonicalize(record),
+            relativePath: OPERATE_STATE_RECORDS,
+            content: `${operatingRecordsLogLine(record)}\n`,
             operation: 'create',
         },
         {
-            relativePath: '.planr/operate/checkpoints/current.json',
+            relativePath: OPERATE_STATE_CHECKPOINT,
             content: `${canonicalize(checkpoint)}\n`,
         },
         ...renderOperatingProjectionFiles(state).map((file) => ({
@@ -355,7 +496,7 @@ async function buildInitialOperatingState(input) {
         // Keep the canonical event last: journal head revalidation remains at
         // genesis for every preceding write, then changes exactly once.
         {
-            relativePath: '.planr/operate/events.jsonl',
+            relativePath: OPERATE_STATE_EVENTS,
             content: `${canonicalize(event)}\n`,
             operation: 'create',
         },
@@ -461,6 +602,13 @@ export async function prepareOperatingInitialization(input) {
         ]);
         resolvedImportPaths.push(resolved.absolutePath);
     }
+    // Dispatch-mode overrides are validated once here and carried in the
+    // machine-local preferences (the v1.2 config artifact surface is frozen).
+    // Omitted entirely when empty so a project with no overrides keeps a
+    // byte-identical preferences payload and preview digest.
+    const dispatchModeOverrides = input.dispatchModeOverrides
+        ? normalizeOperatingDispatchModeOverrides(input.dispatchModeOverrides)
+        : {};
     const preferences = {
         runtime: input.runtime ?? 'auto',
         timezone,
@@ -470,6 +618,7 @@ export async function prepareOperatingInitialization(input) {
         ...(resolvedImportPaths.length > 0
             ? { importPaths: [...new Set(resolvedImportPaths)].sort() }
             : {}),
+        ...(Object.keys(dispatchModeOverrides).length > 0 ? { dispatchModeOverrides } : {}),
     };
     const paths = resolveOperatingPaths(input.projectRoot, { localRoot: input.localRoot });
     const existingWorkspace = await readFile(paths.workspace, 'utf8')