openplanr 1.16.2 → 1.17.0

package/dist/services/operate/cadence.js

@@ -0,0 +1,56 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { recordOperatingLastRunAt } from './config.js';
+import { resolveOperatingPipelineRoot } from './protocol.js';
+import { OperateError } from './types.js';
+let cachedCadenceModule = null;
+async function loadCadenceModule() {
+    cachedCadenceModule ??= (async () => {
+        const root = resolveOperatingPipelineRoot();
+        if (!root) {
+            throw new OperateError('E_PIPELINE_NOT_INSTALLED', 'Operating cadence status requires the planr-pipeline cadence calculator.');
+        }
+        const module = (await import(pathToFileURL(path.join(root, 'lib', 'operate', 'cadence.mjs')).href));
+        if (typeof module.computeNextDueDate !== 'function' ||
+            typeof module.assertCadenceCannotMutate !== 'function') {
+            throw new OperateError('E_PIPELINE_NOT_INSTALLED', 'The installed pipeline does not expose the Protocol v1.3 cadence calculator.');
+        }
+        return module;
+    })();
+    return cachedCadenceModule;
+}
+/**
+ * Compute the surfaced next-due instant for a cadence via the pipeline's pure
+ * calculator (FR8 / E-008). `clock` is the injected `now` supplied by the CLI
+ * boundary — the computation reads no wall clock. `manual` yields `null`;
+ * `weekly` / `monthly` yield the calculator's RFC 3339 UTC instant (due
+ * immediately when `lastRunAt` is absent).
+ */
+export async function computeNextDueAt(cadence, lastRunAt, clock) {
+    const module = await loadCadenceModule();
+    return module.computeNextDueDate(cadence, lastRunAt, clock).nextDueAt;
+}
+/**
+ * Record the cadence `lastRunAt` marker when a cycle reaches a terminal
+ * reviewable/blocked/closed state (FR8 / E-008). Delegates the atomic
+ * machine-local preferences write to `config.ts`, keeping cadence policy in one
+ * module while persistence stays with the preferences owner. `runAt` is the
+ * injected cycle instant (RFC 3339 UTC), never a wall-clock read here.
+ */
+export async function recordOperatingCadenceRun(input) {
+    await recordOperatingLastRunAt({
+        projectRoot: input.projectRoot,
+        localRoot: input.localRoot,
+        lastRunAt: input.runAt,
+    });
+}
+/**
+ * FR8 never-acts anchor. Re-exposes the pipeline's structural guarantee that the
+ * cadence path cannot accept a finding, apply a route, or invoke PLAN/SHIP. The
+ * guarantee is the SHAPE of `computeNextDueAt` (no action parameter exists);
+ * this returns `true` purely as an explicit review anchor.
+ */
+export async function assertOperatingCadenceCannotMutate() {
+    return (await loadCadenceModule()).assertCadenceCannotMutate();
+}
+//# sourceMappingURL=cadence.js.map

package/dist/services/operate/cadence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cadence.js","sourceRoot":"","sources":["../../../src/services/operate/cadence.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAwB,MAAM,YAAY,CAAC;AAyChE,IAAI,mBAAmB,GAA0C,IAAI,CAAC;AAEtE,KAAK,UAAU,iBAAiB;IAC9B,mBAAmB,KAAK,CAAC,KAAK,IAAI,EAAE;QAClC,MAAM,IAAI,GAAG,4BAA4B,EAAE,CAAC;QAC5C,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,YAAY,CACpB,0BAA0B,EAC1B,0EAA0E,CAC3E,CAAC;QACJ,CAAC;QACD,MAAM,MAAM,GAAG,CAAC,MAAM,MAAM,CAC1B,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC,IAAI,CACrE,CAA8C,CAAC;QAChD,IACE,OAAO,MAAM,CAAC,kBAAkB,KAAK,UAAU;YAC/C,OAAO,MAAM,CAAC,yBAAyB,KAAK,UAAU,EACtD,CAAC;YACD,MAAM,IAAI,YAAY,CACpB,0BAA0B,EAC1B,8EAA8E,CAC/E,CAAC;QACJ,CAAC;QACD,OAAO,MAA+B,CAAC;IACzC,CAAC,CAAC,EAAE,CAAC;IACL,OAAO,mBAAmB,CAAC;AAC7B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAyB,EACzB,SAAwB,EACxB,KAAa;IAEb,MAAM,MAAM,GAAG,MAAM,iBAAiB,EAAE,CAAC;IACzC,OAAO,MAAM,CAAC,kBAAkB,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC,SAAS,CAAC;AACxE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,KAI/C;IACC,MAAM,wBAAwB,CAAC;QAC7B,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,SAAS,EAAE,KAAK,CAAC,KAAK;KACvB,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,kCAAkC;IACtD,OAAO,CAAC,MAAM,iBAAiB,EAAE,CAAC,CAAC,yBAAyB,EAAE,CAAC;AACjE,CAAC"}

package/dist/services/operate/citation-resolution.d.ts

@@ -0,0 +1,101 @@
+import type { OperatingEvidenceCache } from './evidence-cache.js';
+import { type OperatingSensitivity, type OperatingWorkspaceComponent } from './types.js';
+export type CitationRejectionReason = 'fabricated-path' | 'wrong-line-range' | 'stale-revision' | 'unresolvable' | 'dirty-working-tree';
+/** The canonical `operating-citation@1.3.0` anchor shape (exactly one locator). */
+export interface OperatingCitation {
+    citationKey?: string;
+    repositoryPath?: string;
+    lineRange?: {
+        start: number;
+        end: number;
+    };
+    gitRevision?: string;
+    planrArtifactId?: string;
+    pinnedRevision: string;
+}
+/** A Protocol v1.3 `operating-data-gap` (`category: 'unresolvable-citation'`). */
+export interface OperatingCitationGap {
+    kind: 'operating-data-gap';
+    schemaVersion: '1.0.0';
+    protocolVersion: '1.3.0';
+    id: string;
+    cycleId: string;
+    category: 'unresolvable-citation';
+    question: string;
+    reason: string;
+    unblocks: string[];
+    affectedRoles?: string[];
+    status: 'open';
+    owner: string;
+    evidenceRefs: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CitationResolutionContext {
+    projectRoot: string;
+    /** Must match `^CYCLE-[0-9]{3,}$` so an unresolvable-citation gap validates. */
+    cycleId: string;
+    /** The control repository descriptor: the frozen pinned revision and the dirty fingerprint. */
+    descriptor: OperatingWorkspaceComponent;
+    cache: OperatingEvidenceCache;
+    owner?: string;
+    affectedRoles?: string[];
+    snapshotTtlMs?: number;
+    now?: Date;
+    /** Sensitivity a snapshot inherits when the cited source declares none (defaults to `internal`). */
+    defaultSensitivity?: OperatingSensitivity;
+    /** Per-citation sensitivity inherited from the cited file (T-002's evidence-item sensitivity). */
+    sensitivityFor?(citation: OperatingCitation): OperatingSensitivity | undefined;
+}
+export interface ResolvedCitation {
+    citation: OperatingCitation;
+    citationKey: string;
+    outcome: 'resolved' | 'rejected';
+    reason?: CitationRejectionReason;
+    evidenceId?: string;
+    snapshotDigest?: `sha256:${string}`;
+    gap?: OperatingCitationGap;
+    sensitivity: OperatingSensitivity;
+}
+/**
+ * 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 declare function resolveOperatingCitationAtPin(citation: OperatingCitation, context: CitationResolutionContext): Promise<ResolvedCitation>;
+/** A proposal that carries the citations an advisor returned instead of pre-loaded evidence IDs. */
+export interface CitationBearingProposal {
+    proposalKey: string;
+    citations: OperatingCitation[];
+}
+export interface RejectedProposalCitation {
+    proposalKey: string;
+    /** The primary rejection reason (the single gap opened for this proposal). */
+    reason: CitationRejectionReason;
+    /** Every distinct rejection reason across the proposal's citations. */
+    reasons: CitationRejectionReason[];
+    gapId: string;
+}
+export interface ProposalCitationEnforcement<P extends CitationBearingProposal> {
+    /** Proposals whose every citation resolved, with the minted evidence IDs attached. */
+    accepted: Array<{
+        proposal: P;
+        evidenceRefs: string[];
+    }>;
+    /** Proposals dropped before consolidation because a citation could not be resolved. */
+    rejected: RejectedProposalCitation[];
+    /** Exactly one unresolvable-citation gap per rejected proposal. */
+    gaps: OperatingCitationGap[];
+    evidenceIds: string[];
+    resolutions: ResolvedCitation[];
+}
+/**
+ * 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 declare function enforceProposalCitations<P extends CitationBearingProposal>(proposals: readonly P[], context: CitationResolutionContext): Promise<ProposalCitationEnforcement<P>>;
+//# sourceMappingURL=citation-resolution.d.ts.map

package/dist/services/operate/citation-resolution.d.ts.map

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

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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"}