cclaw-cli 6.6.0 → 6.8.0

package/dist/delegation.d.ts

@@ -60,6 +60,15 @@ export type DelegationEntry = {
     taskId?: string;
     waiverReason?: string;
     acceptedBy?: DelegationWaiverAcceptedBy;
+    /**
+     * Waiver approval token captured from `cclaw-cli internal waiver-grant`.
+     * Present on waiver rows written after v6.7.0. Legacy waiver rows omit
+     * these fields and are surfaced as the advisory linter finding
+     * `waiver_legacy_provenance`.
+     */
+    approvalToken?: string;
+    approvalReason?: string;
+    approvalIssuedAt?: string;
     ts?: string;
     /**
      * Run id the entry belongs to. Older ledgers written before 0.5.17 may omit this;
@@ -107,6 +116,19 @@ export type DelegationEntry = {
      *   `dispatchSurface`, `agentDefinitionPath`, and ACK timestamp
      */
     schemaVersion?: 1 | 2 | 3;
+    /**
+     * v6.8.0 — when set, the operator explicitly opted into running this
+     * scheduled span concurrently with another active span on the same
+     * `(stage, agent)` pair. Bypasses the dispatch-dedup check.
+     */
+    allowParallel?: boolean;
+    /**
+     * v6.8.0 — set on synthetic terminal `stale` rows written via
+     * `--supersede=<prevSpanId>`. References the new spanId that
+     * superseded this span. Helps `/cc tree` and the linter report a
+     * coherent successor chain.
+     */
+    supersededBy?: string;
 };
 export declare const DELEGATION_LEDGER_SCHEMA_VERSION: 3;
 export type DelegationLedger = {
@@ -135,6 +157,91 @@ export declare function readDelegationEvents(projectRoot: string): Promise<{
     events: DelegationEvent[];
     corruptLines: number[];
 }>;
+/**
+ * Fold ledger entries to the latest row per `spanId` and keep only spans
+ * whose latest status is still active (`scheduled | launched |
+ * acknowledged`). Used by the `state/subagents.json` writer so the
+ * tracker never reports a span that already has a terminal row.
+ *
+ * Output is ordered by ascending `startTs ?? ts` so existing UI
+ * consumers see a stable presentation order.
+ *
+ * Rows without a `spanId` are skipped — they are not addressable by
+ * the tracker contract and would collide on the empty key.
+ *
+ * Callers are expected to pass entries already filtered to the active
+ * `runId`; cross-run rows are therefore not re-filtered here.
+ *
+ * keep in sync with the inline copy in
+ * `src/content/hooks.ts::delegationRecordScript`.
+ */
+export declare function computeActiveSubagents(entries: DelegationEntry[]): DelegationEntry[];
+/**
+ * v6.8.0 — thrown by `validateMonotonicTimestamps` when an incoming row
+ * would push a span's timeline backwards. Carries enough context that
+ * the CLI / hook surface can format a `delegation_timestamp_non_monotonic`
+ * JSON payload without re-deriving the offending field.
+ *
+ * keep in sync with the inline copy in
+ * `src/content/hooks.ts::delegationRecordScript`.
+ */
+export declare class DelegationTimestampError extends Error {
+    readonly field: string;
+    readonly actual: string;
+    readonly priorBound: string;
+    constructor(field: string, actual: string, priorBound: string);
+}
+/**
+ * v6.8.0 — enforce that lifecycle timestamps on a delegation span move
+ * forward (or stay equal). Validates both per-row invariants
+ * (`startTs ≤ launchedTs ≤ ackTs ≤ completedTs`) and a cross-row
+ * invariant: the union of prior rows for this `spanId` plus the
+ * incoming row must have non-decreasing `ts`.
+ *
+ * Equality is allowed because fast-completing dispatches legitimately
+ * collapse multiple lifecycle markers onto the same instant.
+ *
+ * keep in sync with the inline copy in
+ * `src/content/hooks.ts::delegationRecordScript`.
+ */
+export declare function validateMonotonicTimestamps(stamped: DelegationEntry, prior: DelegationEntry[]): void;
+/**
+ * v6.8.0 — thrown by `appendDelegation` when the operator opens a
+ * second `scheduled` span on the same `(stage, agent)` pair while an
+ * earlier span on the same pair is still active. Callers can catch and
+ * either pass the existing span id via `--supersede=<id>` (which
+ * pre-writes a synthetic `stale` row) or `--allow-parallel` to record
+ * concurrent spans intentionally.
+ */
+export declare class DispatchDuplicateError extends Error {
+    readonly existingSpanId: string;
+    readonly existingStatus: DelegationStatus;
+    readonly newSpanId: string;
+    readonly pair: {
+        stage: string;
+        agent: string;
+    };
+    constructor(params: {
+        existingSpanId: string;
+        existingStatus: DelegationStatus;
+        newSpanId: string;
+        pair: {
+            stage: string;
+            agent: string;
+        };
+    });
+}
+/**
+ * v6.8.0 — find the latest active span for a given `(stage, agent)`
+ * pair in the supplied ledger entries. Returns the row whose latest
+ * status (after the latest-by-spanId fold) is still in the active set
+ * (`scheduled | launched | acknowledged`). Caller is responsible for
+ * filtering to the current run.
+ *
+ * keep in sync with the inline copy in
+ * `src/content/hooks.ts::delegationRecordScript`.
+ */
+export declare function findActiveSpanForPair(stage: string, agent: string, runId: string, ledger: DelegationLedger): DelegationEntry | null;
 export declare function appendDelegation(projectRoot: string, entry: DelegationEntry): Promise<void>;
 /**
  * Aggregate the fulfillment mode cclaw expects for the active harness set.

package/dist/delegation.js

@@ -199,6 +199,9 @@ function isDelegationEntry(value) {
         (o.taskId === undefined || typeof o.taskId === "string") &&
         (o.waiverReason === undefined || typeof o.waiverReason === "string") &&
         (o.acceptedBy === undefined || o.acceptedBy === "user-flag") &&
+        (o.approvalToken === undefined || typeof o.approvalToken === "string") &&
+        (o.approvalReason === undefined || typeof o.approvalReason === "string") &&
+        (o.approvalIssuedAt === undefined || typeof o.approvalIssuedAt === "string") &&
         waiverOk &&
         (o.runId === undefined || typeof o.runId === "string") &&
         (o.fulfillmentMode === undefined ||
@@ -219,7 +222,9 @@ function isDelegationEntry(value) {
         retryOk &&
         (o.evidenceRefs === undefined || (Array.isArray(o.evidenceRefs) && o.evidenceRefs.every((item) => typeof item === "string"))) &&
         (o.skill === undefined || typeof o.skill === "string") &&
-        (o.schemaVersion === undefined || o.schemaVersion === 1 || o.schemaVersion === 2 || o.schemaVersion === 3));
+        (o.schemaVersion === undefined || o.schemaVersion === 1 || o.schemaVersion === 2 || o.schemaVersion === 3) &&
+        (o.allowParallel === undefined || typeof o.allowParallel === "boolean") &&
+        (o.supersededBy === undefined || typeof o.supersededBy === "string"));
 }
 function isDelegationDispatchSurface(value) {
     return typeof value === "string" && DELEGATION_DISPATCH_SURFACES.includes(value);
@@ -375,10 +380,196 @@ async function appendDelegationEvent(projectRoot, event) {
     await fs.mkdir(path.dirname(filePath), { recursive: true });
     await fs.appendFile(filePath, `${JSON.stringify(event)}\n`, { encoding: "utf8", mode: 0o600 });
 }
+/**
+ * Effective timestamp used to order rows that share a `spanId`. Newest
+ * lifecycle column wins. Returns the empty string when nothing is set
+ * so the caller still has a stable lexicographic compare key.
+ *
+ * keep in sync with the inline copy in
+ * `src/content/hooks.ts::delegationRecordScript`.
+ */
+function effectiveSpanTs(entry) {
+    return entry.completedTs ?? entry.ackTs ?? entry.launchedTs ?? entry.endTs ?? entry.startTs ?? entry.ts ?? "";
+}
+const ACTIVE_DELEGATION_STATUSES = new Set([
+    "scheduled",
+    "launched",
+    "acknowledged"
+]);
+/**
+ * Fold ledger entries to the latest row per `spanId` and keep only spans
+ * whose latest status is still active (`scheduled | launched |
+ * acknowledged`). Used by the `state/subagents.json` writer so the
+ * tracker never reports a span that already has a terminal row.
+ *
+ * Output is ordered by ascending `startTs ?? ts` so existing UI
+ * consumers see a stable presentation order.
+ *
+ * Rows without a `spanId` are skipped — they are not addressable by
+ * the tracker contract and would collide on the empty key.
+ *
+ * Callers are expected to pass entries already filtered to the active
+ * `runId`; cross-run rows are therefore not re-filtered here.
+ *
+ * keep in sync with the inline copy in
+ * `src/content/hooks.ts::delegationRecordScript`.
+ */
+export function computeActiveSubagents(entries) {
+    const latestBySpan = new Map();
+    for (const entry of entries) {
+        if (!entry.spanId)
+            continue;
+        const existing = latestBySpan.get(entry.spanId);
+        if (!existing) {
+            latestBySpan.set(entry.spanId, entry);
+            continue;
+        }
+        const existingTs = effectiveSpanTs(existing);
+        const incomingTs = effectiveSpanTs(entry);
+        if (incomingTs >= existingTs) {
+            latestBySpan.set(entry.spanId, entry);
+        }
+    }
+    const folded = [];
+    for (const entry of latestBySpan.values()) {
+        if (ACTIVE_DELEGATION_STATUSES.has(entry.status)) {
+            folded.push(entry);
+        }
+    }
+    folded.sort((a, b) => {
+        const aKey = a.startTs ?? a.ts ?? "";
+        const bKey = b.startTs ?? b.ts ?? "";
+        if (aKey === bKey)
+            return 0;
+        return aKey < bKey ? -1 : 1;
+    });
+    return folded;
+}
+/**
+ * v6.8.0 — thrown by `validateMonotonicTimestamps` when an incoming row
+ * would push a span's timeline backwards. Carries enough context that
+ * the CLI / hook surface can format a `delegation_timestamp_non_monotonic`
+ * JSON payload without re-deriving the offending field.
+ *
+ * keep in sync with the inline copy in
+ * `src/content/hooks.ts::delegationRecordScript`.
+ */
+export class DelegationTimestampError extends Error {
+    field;
+    actual;
+    priorBound;
+    constructor(field, actual, priorBound) {
+        super(`delegation_timestamp_non_monotonic — ${field}: ${actual} < ${priorBound}`);
+        this.name = "DelegationTimestampError";
+        this.field = field;
+        this.actual = actual;
+        this.priorBound = priorBound;
+    }
+}
+/**
+ * v6.8.0 — enforce that lifecycle timestamps on a delegation span move
+ * forward (or stay equal). Validates both per-row invariants
+ * (`startTs ≤ launchedTs ≤ ackTs ≤ completedTs`) and a cross-row
+ * invariant: the union of prior rows for this `spanId` plus the
+ * incoming row must have non-decreasing `ts`.
+ *
+ * Equality is allowed because fast-completing dispatches legitimately
+ * collapse multiple lifecycle markers onto the same instant.
+ *
+ * keep in sync with the inline copy in
+ * `src/content/hooks.ts::delegationRecordScript`.
+ */
+export function validateMonotonicTimestamps(stamped, prior) {
+    const startTs = stamped.startTs;
+    if (stamped.launchedTs && startTs && stamped.launchedTs < startTs) {
+        throw new DelegationTimestampError("launchedTs", stamped.launchedTs, startTs);
+    }
+    if (stamped.ackTs) {
+        const ackBound = stamped.launchedTs ?? startTs;
+        if (ackBound && stamped.ackTs < ackBound) {
+            throw new DelegationTimestampError("ackTs", stamped.ackTs, ackBound);
+        }
+    }
+    if (stamped.completedTs) {
+        const completedBound = stamped.ackTs ?? stamped.launchedTs ?? startTs;
+        if (completedBound && stamped.completedTs < completedBound) {
+            throw new DelegationTimestampError("completedTs", stamped.completedTs, completedBound);
+        }
+    }
+    if (!stamped.spanId)
+        return;
+    const priorForSpan = prior.filter((entry) => entry.spanId === stamped.spanId);
+    if (priorForSpan.length === 0)
+        return;
+    const timeline = [...priorForSpan, stamped]
+        .map((entry) => ({ entry, ts: entry.ts ?? entry.startTs ?? "" }))
+        .filter((row) => row.ts.length > 0)
+        .sort((a, b) => (a.ts === b.ts ? 0 : a.ts < b.ts ? -1 : 1));
+    for (let i = 1; i < timeline.length; i += 1) {
+        const previous = timeline[i - 1];
+        const current = timeline[i];
+        if (current.ts < previous.ts) {
+            throw new DelegationTimestampError("ts", current.ts, previous.ts);
+        }
+    }
+    // Find the latest existing row by `ts` for the same spanId; if the
+    // new row's `ts` is older than that latest, the timeline regressed.
+    const latestPrior = priorForSpan
+        .map((entry) => entry.ts ?? entry.startTs ?? "")
+        .filter((ts) => ts.length > 0)
+        .sort()
+        .at(-1);
+    const stampedTs = stamped.ts ?? stamped.startTs ?? "";
+    if (latestPrior && stampedTs && stampedTs < latestPrior) {
+        throw new DelegationTimestampError("ts", stampedTs, latestPrior);
+    }
+}
+/**
+ * v6.8.0 — thrown by `appendDelegation` when the operator opens a
+ * second `scheduled` span on the same `(stage, agent)` pair while an
+ * earlier span on the same pair is still active. Callers can catch and
+ * either pass the existing span id via `--supersede=<id>` (which
+ * pre-writes a synthetic `stale` row) or `--allow-parallel` to record
+ * concurrent spans intentionally.
+ */
+export class DispatchDuplicateError extends Error {
+    existingSpanId;
+    existingStatus;
+    newSpanId;
+    pair;
+    constructor(params) {
+        super(`dispatch_duplicate — already-active spanId=${params.existingSpanId} (status=${params.existingStatus}) on stage=${params.pair.stage}, agent=${params.pair.agent}. ` +
+            `pass --supersede=${params.existingSpanId} to close the previous span as stale, or --allow-parallel to record both as concurrent.`);
+        this.name = "DispatchDuplicateError";
+        this.existingSpanId = params.existingSpanId;
+        this.existingStatus = params.existingStatus;
+        this.newSpanId = params.newSpanId;
+        this.pair = params.pair;
+    }
+}
+/**
+ * v6.8.0 — find the latest active span for a given `(stage, agent)`
+ * pair in the supplied ledger entries. Returns the row whose latest
+ * status (after the latest-by-spanId fold) is still in the active set
+ * (`scheduled | launched | acknowledged`). Caller is responsible for
+ * filtering to the current run.
+ *
+ * keep in sync with the inline copy in
+ * `src/content/hooks.ts::delegationRecordScript`.
+ */
+export function findActiveSpanForPair(stage, agent, runId, ledger) {
+    const sameRun = ledger.entries.filter((entry) => {
+        if (entry.runId && entry.runId !== runId)
+            return false;
+        return entry.stage === stage && entry.agent === agent;
+    });
+    for (const entry of computeActiveSubagents(sameRun)) {
+        return entry;
+    }
+    return null;
+}
 async function writeSubagentTracker(projectRoot, entries) {
-    const active = entries
-        .filter((entry) => entry.status === "scheduled" || entry.status === "launched" || entry.status === "acknowledged")
-        .map((entry) => ({
+    const active = computeActiveSubagents(entries).map((entry) => ({
         spanId: entry.spanId,
         dispatchId: entry.dispatchId,
         workerRunId: entry.workerRunId,
@@ -389,7 +580,8 @@ async function writeSubagentTracker(projectRoot, entries) {
         agentDefinitionPath: entry.agentDefinitionPath,
         startedAt: entry.startTs,
         launchedAt: entry.launchedTs,
-        acknowledgedAt: entry.ackTs
+        acknowledgedAt: entry.ackTs,
+        allowParallel: entry.allowParallel
     }));
     await writeFileSafe(subagentsStatePath(projectRoot), `${JSON.stringify({ active, updatedAt: new Date().toISOString() }, null, 2)}\n`, { mode: 0o600 });
 }
@@ -398,7 +590,20 @@ export async function appendDelegation(projectRoot, entry) {
     await withDirectoryLock(delegationLockPath(projectRoot), async () => {
         const filePath = delegationLogPath(projectRoot);
         const prior = await readDelegationLedger(projectRoot);
-        const startTs = entry.startTs ?? entry.ts ?? new Date().toISOString();
+        // Span start anchor: prefer explicit `startTs`; otherwise fall back to
+        // the earliest provided lifecycle marker so the monotonic validator
+        // never sees a synthetic `now` overshoot a real event timestamp.
+        const lifecycleCandidates = [
+            entry.startTs,
+            entry.launchedTs,
+            entry.ackTs,
+            entry.completedTs,
+            entry.ts
+        ].filter((value) => typeof value === "string" && value.length > 0);
+        const earliestLifecycle = lifecycleCandidates.length > 0
+            ? lifecycleCandidates.reduce((min, candidate) => (candidate < min ? candidate : min))
+            : undefined;
+        const startTs = entry.startTs ?? earliestLifecycle ?? new Date().toISOString();
         if (entry.status === "waived" && !hasValidWaiverReason(entry.waiverReason)) {
             throw new Error("waived delegation entries require a non-empty waiverReason");
         }
@@ -442,6 +647,18 @@ export async function appendDelegation(projectRoot, entry) {
         if (prior.entries.some((existing) => existing.spanId === stamped.spanId && existing.status === stamped.status)) {
             return;
         }
+        validateMonotonicTimestamps(stamped, prior.entries);
+        if (stamped.status === "scheduled" && stamped.allowParallel !== true) {
+            const existing = findActiveSpanForPair(stamped.stage, stamped.agent, activeRunId, prior);
+            if (existing && existing.spanId && existing.spanId !== stamped.spanId) {
+                throw new DispatchDuplicateError({
+                    existingSpanId: existing.spanId,
+                    existingStatus: existing.status,
+                    newSpanId: stamped.spanId,
+                    pair: { stage: stamped.stage, agent: stamped.agent }
+                });
+            }
+        }
         await appendDelegationEvent(projectRoot, eventFromEntry(stamped));
         const ledger = {
             runId: activeRunId,

package/dist/internal/advance-stage/advance.js

@@ -12,6 +12,7 @@ import { extractReviewLoopEnvelopeFromArtifact } from "../../content/review-loop
 import { unique } from "./helpers.js";
 import { AUTO_REVIEW_LOOP_GATE_BY_STAGE, reviewLoopArtifactFixHint, reviewLoopEnvelopeExample, validateGateEvidenceShape } from "./review-loop.js";
 import { ensureProactiveDelegationTrace } from "./proactive-delegation-trace.js";
+import { consumeWaiverToken } from "../waiver-grant.js";
 function resolveSuccessorTransition(stage, track, transitionTargets, satisfiedGuards, selectedTransitionGuards) {
     const natural = transitionTargets[0] ?? null;
     const specialTargets = transitionTargets.filter((target) => target !== natural);
@@ -542,9 +543,30 @@ export async function runAdvanceStage(projectRoot, args, io) {
         }
         return 1;
     }
+    let approvalRecord = null;
+    if (args.acceptProactiveWaiver) {
+        const tokenRaw = args.acceptProactiveWaiverToken?.trim() ?? "";
+        if (tokenRaw.length === 0) {
+            io.stderr.write(`cclaw internal advance-stage: --accept-proactive-waiver now requires =<token>. Run \`cclaw-cli internal waiver-grant --stage ${args.stage} --reason "<why safe>"\` to issue one, then rerun with --accept-proactive-waiver=<token>.\n`);
+            return 2;
+        }
+        const consumed = await consumeWaiverToken(projectRoot, {
+            stage: args.stage,
+            token: tokenRaw,
+            consumedBy: "advance-stage"
+        });
+        if (!consumed.ok) {
+            io.stderr.write(`cclaw internal advance-stage: waiver token rejected (${consumed.reason}): ${consumed.detail}. Issue a fresh token via \`cclaw-cli internal waiver-grant --stage ${args.stage} --reason "<why safe>"\`.\n`);
+            return 2;
+        }
+        approvalRecord = consumed.record;
+    }
     const proactiveTrace = await ensureProactiveDelegationTrace(projectRoot, args.stage, {
         acceptWaiver: args.acceptProactiveWaiver,
         waiverReason: args.acceptProactiveWaiverReason,
+        approvalToken: approvalRecord?.token,
+        approvalReason: approvalRecord?.reason,
+        approvalIssuedAt: approvalRecord?.issuedAt,
         discoveryMode: flowState.discoveryMode,
         repoSignals: flowState.repoSignals
     });
@@ -600,7 +622,7 @@ export async function runAdvanceStage(projectRoot, args, io) {
         currentStage: successor ?? args.stage,
         interactionHints
     };
-    await writeFlowState(projectRoot, finalState);
+    await writeFlowState(projectRoot, finalState, { writerSubsystem: "advance-stage" });
     if (args.quiet) {
         io.stdout.write(`${JSON.stringify({
             ok: true,

package/dist/internal/advance-stage/parsers.d.ts

@@ -8,6 +8,14 @@ export interface AdvanceStageArgs {
     waiverReason?: string;
     acceptProactiveWaiver: boolean;
     acceptProactiveWaiverReason?: string;
+    /**
+     * Approval token issued by `cclaw-cli internal waiver-grant`. Required
+     * (via `--accept-proactive-waiver=<token>`) whenever the caller asserts
+     * `acceptProactiveWaiver`. Legacy `--accept-proactive-waiver` without a
+     * token is still parsed but rejected downstream by the advance-stage
+     * handler so operators see the error at runtime.
+     */
+    acceptProactiveWaiverToken?: string;
     skipQuestions: boolean;
     quiet: boolean;
     json: boolean;

package/dist/internal/advance-stage/parsers.js

@@ -12,6 +12,7 @@ export function parseAdvanceStageArgs(tokens) {
     let waiverReason;
     let acceptProactiveWaiver = false;
     let acceptProactiveWaiverReason;
+    let acceptProactiveWaiverToken;
     let skipQuestions = false;
     let quiet = false;
     let json = false;
@@ -81,6 +82,11 @@ export function parseAdvanceStageArgs(tokens) {
             acceptProactiveWaiver = true;
             continue;
         }
+        if (token.startsWith("--accept-proactive-waiver=")) {
+            acceptProactiveWaiver = true;
+            acceptProactiveWaiverToken = token.slice("--accept-proactive-waiver=".length).trim();
+            continue;
+        }
         if (token === "--skip-questions") {
             skipQuestions = true;
             continue;
@@ -107,6 +113,7 @@ export function parseAdvanceStageArgs(tokens) {
         waiverReason,
         acceptProactiveWaiver,
         acceptProactiveWaiverReason,
+        acceptProactiveWaiverToken,
         skipQuestions,
         quiet,
         json

package/dist/internal/advance-stage/proactive-delegation-trace.d.ts

@@ -16,6 +16,9 @@ export interface ProactiveDelegationTraceResult {
 export declare function ensureProactiveDelegationTrace(projectRoot: string, stage: FlowStage, options: {
     acceptWaiver: boolean;
     waiverReason?: string;
+    approvalToken?: string;
+    approvalReason?: string;
+    approvalIssuedAt?: string;
     discoveryMode: DiscoveryMode;
     repoSignals?: RepoSignals;
 }): Promise<ProactiveDelegationTraceResult>;

package/dist/internal/advance-stage/proactive-delegation-trace.js

@@ -31,7 +31,11 @@ export async function ensureProactiveDelegationTrace(projectRoot, stage, options
         return { missingRules: [] };
     if (!options.acceptWaiver)
         return { missingRules };
-    const waiverReason = options.waiverReason?.trim() || "accepted via --accept-proactive-waiver";
+    const approvalToken = options.approvalToken?.trim();
+    const approvalReason = options.approvalReason?.trim();
+    const waiverReason = options.waiverReason?.trim() ||
+        approvalReason ||
+        "accepted via --accept-proactive-waiver";
     for (const rule of missingRules) {
         await appendDelegation(projectRoot, {
             stage,
@@ -42,6 +46,9 @@ export async function ensureProactiveDelegationTrace(projectRoot, stage, options
             acceptedBy: "user-flag",
             conditionTrigger: rule.when,
             skill: rule.skill,
+            ...(approvalToken ? { approvalToken } : {}),
+            ...(approvalReason ? { approvalReason } : {}),
+            ...(options.approvalIssuedAt ? { approvalIssuedAt: options.approvalIssuedAt } : {}),
             ts: new Date().toISOString()
         });
     }

package/dist/internal/advance-stage/rewind.js

@@ -40,7 +40,7 @@ export async function runRewind(projectRoot, args, io) {
         const staleStages = { ...current.staleStages };
         delete staleStages[args.targetStage];
         const nextState = { ...current, staleStages };
-        await writeFlowState(projectRoot, nextState);
+        await writeFlowState(projectRoot, nextState, { writerSubsystem: "rewind-ack" });
         const payload = {
             ok: true,
             command: "rewind",
@@ -85,7 +85,7 @@ export async function runRewind(projectRoot, args, io) {
         staleStages,
         rewinds: [...current.rewinds, record]
     };
-    await writeFlowState(projectRoot, nextState);
+    await writeFlowState(projectRoot, nextState, { writerSubsystem: "rewind" });
     const payload = {
         ok: true,
         command: "rewind",

package/dist/internal/advance-stage/start-flow.js

@@ -209,7 +209,10 @@ export async function runStartFlow(projectRoot, args, io) {
     }
     const repoSignals = await collectRepoSignals(projectRoot);
     nextState = { ...nextState, repoSignals };
-    await writeFlowState(projectRoot, nextState, { allowReset: true });
+    await writeFlowState(projectRoot, nextState, {
+        allowReset: true,
+        writerSubsystem: "start-flow"
+    });
     await appendIdeaArtifact(projectRoot, args, current);
     const successPayload = {
         ok: true,

package/dist/internal/advance-stage.js

@@ -11,13 +11,34 @@ import { runRewind } from "./advance-stage/rewind.js";
 import { runVerifyFlowStateDiff, runVerifyCurrentState } from "./advance-stage/verify.js";
 import { runHookCommand } from "./advance-stage/hook.js";
 import { parseAdvanceStageArgs, parseCancelRunArgs, parseHookArgs, parseRewindArgs, parseStartFlowArgs, parseVerifyCurrentStateArgs, parseVerifyFlowStateDiffArgs } from "./advance-stage/parsers.js";
+import { parseFlowStateRepairArgs, runFlowStateRepair } from "./flow-state-repair.js";
+import { parseWaiverGrantArgs, runWaiverGrant } from "./waiver-grant.js";
+import { FlowStateGuardMismatchError, verifyFlowStateGuard } from "../run-persistence.js";
+import { DelegationTimestampError, DispatchDuplicateError } from "../delegation.js";
+/**
+ * Subcommands that mutate or consult flow-state.json via the CLI runtime.
+ * They all require the sha256 sidecar to match before continuing so a
+ * manual edit hard-blocks with exit code 2 (same contract as the inline
+ * hook checks).
+ */
+const GUARD_ENFORCED_SUBCOMMANDS = new Set([
+    "advance-stage",
+    "start-flow",
+    "cancel-run",
+    "rewind",
+    "verify-flow-state-diff",
+    "verify-current-state"
+]);
 export async function runInternalCommand(projectRoot, argv, io) {
     const [subcommand, ...tokens] = argv;
     if (!subcommand) {
-        io.stderr.write("cclaw internal requires a subcommand: advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook\n");
+        io.stderr.write("cclaw internal requires a subcommand: advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook | flow-state-repair | waiver-grant\n");
         return 1;
     }
     try {
+        if (GUARD_ENFORCED_SUBCOMMANDS.has(subcommand)) {
+            await verifyFlowStateGuard(projectRoot);
+        }
         if (subcommand === "advance-stage") {
             return await runAdvanceStage(projectRoot, parseAdvanceStageArgs(tokens), io);
         }
@@ -57,10 +78,28 @@ export async function runInternalCommand(projectRoot, argv, io) {
         if (subcommand === "hook") {
             return await runHookCommand(projectRoot, parseHookArgs(tokens), io);
         }
-        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook\n`);
+        if (subcommand === "flow-state-repair") {
+            return await runFlowStateRepair(projectRoot, parseFlowStateRepairArgs(tokens), io);
+        }
+        if (subcommand === "waiver-grant") {
+            return await runWaiverGrant(projectRoot, parseWaiverGrantArgs(tokens), io);
+        }
+        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook | flow-state-repair | waiver-grant\n`);
         return 1;
     }
     catch (err) {
+        if (err instanceof FlowStateGuardMismatchError) {
+            io.stderr.write(`cclaw internal ${subcommand}: ${err.message}\n`);
+            return 2;
+        }
+        if (err instanceof DelegationTimestampError) {
+            io.stderr.write(`error: delegation_timestamp_non_monotonic — ${err.field}: ${err.actual} < ${err.priorBound}\n`);
+            return 2;
+        }
+        if (err instanceof DispatchDuplicateError) {
+            io.stderr.write(`error: dispatch_duplicate — ${err.message}\n`);
+            return 2;
+        }
         io.stderr.write(`cclaw internal ${subcommand} failed: ${err instanceof Error ? err.message : String(err)}\n`);
         return 1;
     }

package/dist/internal/flow-state-repair.d.ts

@@ -0,0 +1,13 @@
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+export interface FlowStateRepairArgs {
+    reason: string;
+    json: boolean;
+    quiet: boolean;
+}
+export declare function parseFlowStateRepairArgs(tokens: string[]): FlowStateRepairArgs;
+export declare function runFlowStateRepair(projectRoot: string, args: FlowStateRepairArgs, io: InternalIo): Promise<number>;
+export {};