cclaw-cli 6.7.0 → 6.8.0

package/dist/content/hooks.js

@@ -326,7 +326,7 @@ function hasPriorAck(events, args, runId) {
 function usage() {
   process.stderr.write([
     "Usage:",
-    "  node .cclaw/hooks/delegation-record.mjs --stage=<stage> --agent=<agent> --mode=<mandatory|proactive> --status=<scheduled|launched|acknowledged|completed|failed|waived|stale> --span-id=<id> [--dispatch-id=<id>] [--worker-run-id=<id>] [--dispatch-surface=<surface>] [--agent-definition-path=<path>] [--ack-ts=<iso>] [--launched-ts=<iso>] [--completed-ts=<iso>] [--evidence-ref=<ref>] [--waiver-reason=<text>] [--json]",
+    "  node .cclaw/hooks/delegation-record.mjs --stage=<stage> --agent=<agent> --mode=<mandatory|proactive> --status=<scheduled|launched|acknowledged|completed|failed|waived|stale> --span-id=<id> [--dispatch-id=<id>] [--worker-run-id=<id>] [--dispatch-surface=<surface>] [--agent-definition-path=<path>] [--ack-ts=<iso>] [--launched-ts=<iso>] [--completed-ts=<iso>] [--evidence-ref=<ref>] [--waiver-reason=<text>] [--supersede=<prevSpanId>] [--allow-parallel] [--json]",
     "  node .cclaw/hooks/delegation-record.mjs --rerecord --span-id=<id> --dispatch-id=<id> --dispatch-surface=<surface> --agent-definition-path=<path> [--ack-ts=<iso>] [--completed-ts=<iso>] [--evidence-ref=<ref>] [--json]",
     "  node .cclaw/hooks/delegation-record.mjs --repair --span-id=<id> --repair-reason=\"<why>\" [--json]",
     "",
@@ -335,6 +335,10 @@ function usage() {
     "",
     "Per-surface allowed --agent-definition-path prefixes:",
     ...VALID_DISPATCH_SURFACES.map((surface) => "  " + surface + ": " + (SURFACE_PATH_PREFIXES[surface].length === 0 ? "(any)" : SURFACE_PATH_PREFIXES[surface].join(", "))),
+    "",
+    "Dispatch dedup (v6.8.0):",
+    "  --supersede=<prevSpanId>  close the previous active span on this (stage, agent) as 'stale' before recording the new scheduled row",
+    "  --allow-parallel          record both spans as concurrent; new row is tagged allowParallel: true",
     ""
   ].join("\\n") + "\\n");
 }
@@ -350,6 +354,51 @@ function emitProblems(problems, json, code) {
   process.exitCode = exitCode;
 }
 
+function emitErrorJson(error, details, json) {
+  if (json) {
+    process.stdout.write(JSON.stringify({ ok: false, error, details }, null, 2) + "\\n");
+  } else {
+    process.stderr.write("[cclaw] delegation-record: error: " + error + " — " + JSON.stringify(details) + "\\n");
+  }
+  process.exit(2);
+}
+
+// keep in sync with validateMonotonicTimestamps in src/delegation.ts
+function validateMonotonicTimestampsInline(stamped, prior) {
+  const startTs = stamped.startTs;
+  if (stamped.launchedTs && startTs && stamped.launchedTs < startTs) {
+    return { field: "launchedTs", actual: stamped.launchedTs, bound: startTs };
+  }
+  if (stamped.ackTs) {
+    const ackBound = stamped.launchedTs || startTs;
+    if (ackBound && stamped.ackTs < ackBound) {
+      return { field: "ackTs", actual: stamped.ackTs, bound: ackBound };
+    }
+  }
+  if (stamped.completedTs) {
+    const completedBound = stamped.ackTs || stamped.launchedTs || startTs;
+    if (completedBound && stamped.completedTs < completedBound) {
+      return { field: "completedTs", actual: stamped.completedTs, bound: completedBound };
+    }
+  }
+  if (!stamped.spanId) return null;
+  const priorForSpan = (prior || []).filter((entry) => entry && entry.spanId === stamped.spanId);
+  if (priorForSpan.length === 0) return null;
+  const tsValues = priorForSpan
+    .map((entry) => entry.ts || entry.startTs || "")
+    .filter((ts) => ts.length > 0);
+  if (tsValues.length === 0) return null;
+  let latest = tsValues[0];
+  for (let i = 1; i < tsValues.length; i += 1) {
+    if (tsValues[i] > latest) latest = tsValues[i];
+  }
+  const stampedTs = stamped.ts || stamped.startTs || "";
+  if (stampedTs && stampedTs < latest) {
+    return { field: "ts", actual: stampedTs, bound: latest };
+  }
+  return null;
+}
+
 function normalizeRelPath(value) {
   return String(value || "").replace(/\\\\/gu, "/").replace(/^\\.\\//u, "");
 }
@@ -382,12 +431,15 @@ function normalizeEvidenceRefs(args) {
   return [];
 }
 
-function buildRow(args, status, runId, now) {
+function buildRow(args, status, runId, now, options) {
   const fulfillmentMode = args["dispatch-surface"] === "role-switch"
     ? "role-switch"
     : args["dispatch-surface"] === "cursor-task" || args["dispatch-surface"] === "generic-task"
       ? "generic-dispatch"
       : "isolated";
+  // Inherit the span's startTs from prior rows so monotonic validation
+  // can compare against the original schedule, not the row write time.
+  const startTs = (options && options.spanStartTs) || now;
   return {
     stage: args.stage,
     agent: args.agent,
@@ -402,13 +454,83 @@ function buildRow(args, status, runId, now) {
     waiverReason: args["waiver-reason"],
     evidenceRefs: normalizeEvidenceRefs(args),
     runId,
-    startTs: now,
+    startTs,
     ts: now,
     launchedTs: args["launched-ts"] || (status === "launched" ? now : undefined),
     ackTs: args["ack-ts"] || (status === "acknowledged" ? now : undefined),
     completedTs: args["completed-ts"] || (status === "completed" ? now : undefined),
     endTs: TERMINAL.has(status) ? now : undefined,
-    schemaVersion: LEDGER_SCHEMA_VERSION
+    schemaVersion: LEDGER_SCHEMA_VERSION,
+    allowParallel: args["allow-parallel"] === true ? true : undefined
+  };
+}
+
+async function readDelegationLedgerEntries(root) {
+  try {
+    const raw = await fs.readFile(path.join(root, RUNTIME_ROOT, "state", "delegation-log.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && Array.isArray(parsed.entries)) return parsed.entries;
+  } catch {
+    // empty / missing ledger is fine for dedup + monotonicity checks
+  }
+  return [];
+}
+
+// keep in sync with findActiveSpanForPair / DispatchDuplicateError in src/delegation.ts
+function findActiveSpanForPairInline(stage, agent, runId, entries) {
+  const ACTIVE_STATUSES = new Set(["scheduled", "launched", "acknowledged"]);
+  const effectiveTs = (entry) =>
+    entry.completedTs || entry.ackTs || entry.launchedTs || entry.endTs || entry.startTs || entry.ts || "";
+  const latestBySpan = new Map();
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object") continue;
+    if (typeof entry.spanId !== "string" || entry.spanId.length === 0) continue;
+    if (entry.runId && entry.runId !== runId) continue;
+    if (entry.stage !== stage || entry.agent !== agent) continue;
+    const existing = latestBySpan.get(entry.spanId);
+    if (!existing || effectiveTs(entry) >= effectiveTs(existing)) {
+      latestBySpan.set(entry.spanId, entry);
+    }
+  }
+  for (const entry of latestBySpan.values()) {
+    if (ACTIVE_STATUSES.has(entry.status)) return entry;
+  }
+  return null;
+}
+
+function enforceDispatchDedupInline(stamped, priorEntries, args) {
+  if (stamped.status !== "scheduled") return null;
+  if (args["allow-parallel"] === true) return null;
+  const existing = findActiveSpanForPairInline(
+    stamped.stage,
+    stamped.agent,
+    stamped.runId,
+    priorEntries
+  );
+  if (!existing || existing.spanId === stamped.spanId) return null;
+  if (typeof args.supersede === "string" && args.supersede.length > 0) {
+    if (args.supersede !== existing.spanId) {
+      return {
+        kind: "supersede-mismatch",
+        details: {
+          requested: args.supersede,
+          actualActiveSpanId: existing.spanId,
+          stage: stamped.stage,
+          agent: stamped.agent
+        }
+      };
+    }
+    return { kind: "supersede", existing };
+  }
+  return {
+    kind: "error",
+    details: {
+      existingSpanId: existing.spanId,
+      existingStatus: existing.status,
+      newSpanId: stamped.spanId,
+      pair: { stage: stamped.stage, agent: stamped.agent },
+      hint: "pass --supersede=" + existing.spanId + " to close the previous span as stale, or --allow-parallel to record both as concurrent"
+    }
   };
 }
 
@@ -490,7 +612,32 @@ async function persistEntry(root, runId, clean, event, options = {}) {
     await releaseDelegationLogLock(lockDir);
   }
 
-  const active = ledger.entries.filter((entry) => ["scheduled", "launched", "acknowledged"].includes(entry.status));
+  // keep in sync with computeActiveSubagents in src/delegation.ts
+  const ACTIVE_STATUSES = new Set(["scheduled", "launched", "acknowledged"]);
+  const effectiveTs = (entry) =>
+    entry.completedTs || entry.ackTs || entry.launchedTs || entry.endTs || entry.startTs || entry.ts || "";
+  const latestBySpan = new Map();
+  for (const entry of ledger.entries) {
+    if (!entry || typeof entry !== "object" || typeof entry.spanId !== "string" || entry.spanId.length === 0) continue;
+    const existing = latestBySpan.get(entry.spanId);
+    if (!existing) {
+      latestBySpan.set(entry.spanId, entry);
+      continue;
+    }
+    if (effectiveTs(entry) >= effectiveTs(existing)) {
+      latestBySpan.set(entry.spanId, entry);
+    }
+  }
+  const active = [];
+  for (const entry of latestBySpan.values()) {
+    if (ACTIVE_STATUSES.has(entry.status)) active.push(entry);
+  }
+  active.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;
+  });
   await fs.writeFile(path.join(stateDir, "subagents.json"), JSON.stringify({ active, updatedAt: event.eventTs }, null, 2) + "\\n", { encoding: "utf8", mode: 0o600 });
 }
 
@@ -814,9 +961,61 @@ async function main() {
   }
 
   const status = args.status;
-  const row = buildRow(args, status, runId, now);
+  const priorLedger = await readDelegationLedgerEntries(root);
+  const priorForSpan = priorLedger.filter((e) => e && e.spanId === args["span-id"]);
+  const inheritedStartTs = priorForSpan
+    .map((e) => e.startTs)
+    .filter((ts) => typeof ts === "string" && ts.length > 0)
+    .sort()[0];
+  // When no prior row exists, fall back to the earliest user-supplied
+  // event timestamp so the monotonic validator never sees the row write
+  // time overshoot the real event timestamps.
+  const lifecycleCandidates = [
+    inheritedStartTs,
+    args["launched-ts"],
+    args["ack-ts"],
+    args["completed-ts"],
+    now
+  ].filter((value) => typeof value === "string" && value.length > 0);
+  const spanStartTs = inheritedStartTs ||
+    lifecycleCandidates.reduce((min, candidate) => (candidate < min ? candidate : min), now);
+  const row = buildRow(args, status, runId, now, { spanStartTs });
   const clean = Object.fromEntries(Object.entries(row).filter(([, value]) => value !== undefined));
   const event = { ...clean, event: status, eventTs: now };
+
+  const violation = validateMonotonicTimestampsInline(clean, priorLedger);
+  if (violation) {
+    emitErrorJson("delegation_timestamp_non_monotonic", violation, json);
+    return;
+  }
+  const dedupViolation = enforceDispatchDedupInline(clean, priorLedger, args);
+  if (dedupViolation) {
+    if (dedupViolation.kind === "supersede") {
+      const stalenessTs = new Date(new Date(now).getTime() - 1).toISOString();
+      const staleRow = {
+        stage: dedupViolation.existing.stage,
+        agent: dedupViolation.existing.agent,
+        mode: dedupViolation.existing.mode,
+        status: "stale",
+        spanId: dedupViolation.existing.spanId,
+        runId,
+        startTs: dedupViolation.existing.startTs || stalenessTs,
+        ts: stalenessTs,
+        endTs: stalenessTs,
+        supersededBy: clean.spanId,
+        schemaVersion: LEDGER_SCHEMA_VERSION
+      };
+      const staleEvent = { ...staleRow, event: "stale", eventTs: stalenessTs };
+      await persistEntry(root, runId, staleRow, staleEvent);
+    } else if (dedupViolation.kind === "error") {
+      emitErrorJson("dispatch_duplicate", dedupViolation.details, json);
+      return;
+    } else if (dedupViolation.kind === "supersede-mismatch") {
+      emitErrorJson("dispatch_supersede_mismatch", dedupViolation.details, json);
+      return;
+    }
+  }
+
   await persistEntry(root, runId, clean, event);
   process.stdout.write(JSON.stringify({ ok: true, event }, null, 2) + "\\n");
 }

package/dist/content/skills.js

@@ -236,6 +236,8 @@ ${rows}
 Mandatory: ${mandatoryList}. Record lifecycle rows in \`${delegationLogRel}\` and append-only \`${delegationEventsRel}\` before completion.${runPhaseLegend}
 ### Harness Dispatch Contract — use true harness dispatch: Claude Task, Cursor generic dispatch, OpenCode \`.opencode/agents/<agent>.md\` via Task/@agent, Codex \`.codex/agents/<agent>.toml\`. Do not collapse OpenCode or Codex to role-switch by default. Worker ACK Contract: ACK must include \`spanId\`, \`dispatchId\`, \`dispatchSurface\`, \`agentDefinitionPath\`, and \`ackTs\`; never claim \`fulfillmentMode: "isolated"\` without matching lifecycle proof. Canonical helper (same flags as \`delegation-record.mjs --help\`): \`node .cclaw/hooks/delegation-record.mjs --stage=<stage> --agent=<agent> --mode=<mandatory|proactive> --status=<scheduled|launched|acknowledged|completed|...> --span-id=<id> --dispatch-id=<id> --dispatch-surface=<surface> --agent-definition-path=<path> [--ack-ts=<iso>] [--evidence-ref=<ref>] --json\`. Lifecycle order: \`scheduled → launched → acknowledged → completed\` on one span (reuse the same span id); completed isolated/generic rows require a prior ACK event for that span or \`--ack-ts=<iso>\`. For a partial audit trail, \`--repair --span-id=<id> --repair-reason="<why>"\` appends missing phases (see \`--help\`) instead of inventing shortcuts.
 
+If you must re-dispatch the same agent in the same stage before the previous span has a terminal row, pass \`--supersede=<prevSpanId>\` (closes the previous span as \`stale\` with \`supersededBy=<newSpanId>\`) or \`--allow-parallel\` (records both spans as concurrently active and tags the new row with \`allowParallel: true\`). Without one of those flags, a duplicate scheduled write on the same \`(stage, agent)\` pair fails with \`exit 2\` and \`{ ok: false, error: "dispatch_duplicate" }\`. Lifecycle timestamps are also validated: \`startTs ≤ launchedTs ≤ ackTs ≤ completedTs\` and per-span \`ts\` is non-decreasing — non-monotonic values fail with \`exit 2\` and \`{ ok: false, error: "delegation_timestamp_non_monotonic" }\`.
+
 ${perHarnessLifecycleRecipeBlock()}`;
 }
 function perHarnessLifecycleRecipeBlock() {

package/dist/delegation.d.ts

@@ -116,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 = {
@@ -144,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

@@ -222,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);
@@ -378,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,
@@ -392,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 });
 }
@@ -401,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");
         }
@@ -445,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.js

@@ -14,6 +14,7 @@ import { parseAdvanceStageArgs, parseCancelRunArgs, parseHookArgs, parseRewindAr
 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
@@ -91,6 +92,14 @@ export async function runInternalCommand(projectRoot, argv, io) {
             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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "6.7.0",
+  "version": "6.8.0",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {