cclaw-cli 6.12.0 → 6.13.1

package/dist/delegation.js

@@ -8,6 +8,8 @@ import { exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
 import { HARNESS_ADAPTERS } from "./harness-adapters.js";
 import { readFlowState } from "./runs.js";
 import { mandatoryAgentsFor, stageSchema } from "./content/stage-schema.js";
+import { effectiveWorktreeExecutionMode } from "./flow-state.js";
+import { compareCanonicalUnitIds, mergeParallelWaveDefinitions, parseImplementationUnitParallelFields, parseImplementationUnits, parseParallelExecutionPlanWaves, parseWavePlanDirectory } from "./internal/plan-split-waves.js";
 const execFileAsync = promisify(execFile);
 const TERMINAL_DELEGATION_STATUSES = new Set(["completed", "failed", "waived", "stale"]);
 export const DELEGATION_DISPATCH_SURFACES = [
@@ -43,7 +45,8 @@ export const DELEGATION_PHASES = [
     "green",
     "refactor",
     "refactor-deferred",
-    "doc"
+    "doc",
+    "resolve-conflict"
 ];
 export const DELEGATION_LEDGER_SCHEMA_VERSION = 3;
 function delegationLogPath(projectRoot) {
@@ -238,7 +241,23 @@ function isDelegationEntry(value) {
             (typeof o.sliceId === "string" && o.sliceId.length > 0)) &&
         (o.phase === undefined ||
             (typeof o.phase === "string" &&
-                DELEGATION_PHASES.includes(o.phase))));
+                DELEGATION_PHASES.includes(o.phase))) &&
+        (o.claimToken === undefined || typeof o.claimToken === "string") &&
+        (o.ownerLaneId === undefined || typeof o.ownerLaneId === "string") &&
+        (o.leasedUntil === undefined || typeof o.leasedUntil === "string") &&
+        (o.leaseState === undefined ||
+            o.leaseState === "claimed" ||
+            o.leaseState === "expired" ||
+            o.leaseState === "released" ||
+            o.leaseState === "reclaimed") &&
+        (o.dependsOn === undefined ||
+            (Array.isArray(o.dependsOn) && o.dependsOn.every((item) => typeof item === "string"))) &&
+        (o.integrationState === undefined ||
+            o.integrationState === "pending" ||
+            o.integrationState === "applied" ||
+            o.integrationState === "conflict" ||
+            o.integrationState === "resolved" ||
+            o.integrationState === "abandoned"));
 }
 function isDelegationDispatchSurface(value) {
     return typeof value === "string" && DELEGATION_DISPATCH_SURFACES.includes(value);
@@ -348,7 +367,12 @@ export async function readDelegationLedger(projectRoot) {
 const NON_DELEGATION_AUDIT_EVENTS = new Set([
     "mandatory_delegations_skipped_by_track",
     "artifact_validation_demoted_by_track",
-    "expansion_strategist_skipped_by_track"
+    "expansion_strategist_skipped_by_track",
+    "cclaw_slice_lease_expired",
+    "cclaw_fanin_applied",
+    "cclaw_fanin_conflict",
+    "cclaw_fanin_resolved",
+    "cclaw_fanin_abandoned"
 ]);
 function isAuditEventLine(parsed) {
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
@@ -356,13 +380,47 @@ function isAuditEventLine(parsed) {
     const evt = parsed.event;
     return typeof evt === "string" && NON_DELEGATION_AUDIT_EVENTS.has(evt);
 }
+const FAN_IN_AUDIT_EVENT_KINDS = new Set([
+    "cclaw_fanin_applied",
+    "cclaw_fanin_conflict",
+    "cclaw_fanin_resolved",
+    "cclaw_fanin_abandoned"
+]);
+function isFanInAuditRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const o = value;
+    const evt = o.event;
+    if (typeof evt !== "string" || !FAN_IN_AUDIT_EVENT_KINDS.has(evt)) {
+        return false;
+    }
+    return typeof o.ts === "string" && o.ts.length > 0;
+}
+/**
+ * Append a deterministic fan-in audit row (not a delegation lifecycle event).
+ */
+export async function recordCclawFanInAudit(projectRoot, params) {
+    const filePath = delegationEventsPath(projectRoot);
+    const payload = {
+        event: params.kind,
+        runId: params.runId,
+        laneId: params.laneId,
+        sliceIds: params.sliceIds,
+        integrationBranch: params.integrationBranch,
+        details: params.details,
+        ts: new Date().toISOString()
+    };
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.appendFile(filePath, `${JSON.stringify(payload)}\n`, { encoding: "utf8", mode: 0o600 });
+}
 export async function readDelegationEvents(projectRoot) {
     const filePath = delegationEventsPath(projectRoot);
     if (!(await exists(filePath))) {
-        return { events: [], corruptLines: [] };
+        return { events: [], corruptLines: [], fanInAudits: [] };
     }
     const events = [];
     const corruptLines = [];
+    const fanInAudits = [];
     const text = await fs.readFile(filePath, "utf8").catch(() => "");
     const lines = text.split(/\r?\n/gu);
     for (let index = 0; index < lines.length; index += 1) {
@@ -374,6 +432,9 @@ export async function readDelegationEvents(projectRoot) {
             if (isDelegationEvent(parsed)) {
                 events.push(parsed);
             }
+            else if (isFanInAuditRecord(parsed)) {
+                fanInAudits.push(parsed);
+            }
             else if (isAuditEventLine(parsed)) {
                 // Wave 24 audit-only row (e.g. mandatory_delegations_skipped_by_track).
                 // Not a delegation lifecycle event but valid audit content.
@@ -387,7 +448,7 @@ export async function readDelegationEvents(projectRoot) {
             corruptLines.push(index + 1);
         }
     }
-    return { events, corruptLines };
+    return { events, corruptLines, fanInAudits };
 }
 async function appendDelegationEvent(projectRoot, event) {
     const filePath = delegationEventsPath(projectRoot);
@@ -605,12 +666,118 @@ export class DispatchCapError extends Error {
         this.pair = params.pair;
     }
 }
+/**
+ * v6.13.0 — claim / lease contract violation for worktree-first TDD rows.
+ */
+export class DispatchClaimInvalidError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DispatchClaimInvalidError";
+    }
+}
 /**
  * v6.10.0 (P2) — default cap on active `slice-implementer` spans in a
  * single TDD run. Aligned with evanflow's parallel cap. Override via
  * `CCLAW_MAX_PARALLEL_SLICE_IMPLEMENTERS=<int>` (validated `>=1`).
  */
 export const MAX_PARALLEL_SLICE_IMPLEMENTERS = 5;
+/**
+ * Return up to `cap` slice units whose dependsOn are satisfied, avoiding
+ * `claimedPaths` intersections with already-selected units and active holders.
+ */
+export function selectReadySlices(units, opts) {
+    const pool = opts.legacyContinuation ? units.filter((u) => u.parallelizable) : units;
+    const ordered = [...pool].sort((a, b) => compareCanonicalUnitIds(a.unitId, b.unitId));
+    const selected = [];
+    const blockedPaths = new Set();
+    for (const holder of opts.activePathHolders) {
+        for (const p of holder.paths) {
+            blockedPaths.add(p);
+        }
+    }
+    for (const u of ordered) {
+        if (opts.completedUnitIds.has(u.unitId))
+            continue;
+        if (!u.dependsOn.every((d) => opts.completedUnitIds.has(d)))
+            continue;
+        let clash = false;
+        for (const p of u.claimedPaths) {
+            if (blockedPaths.has(p)) {
+                clash = true;
+                break;
+            }
+        }
+        if (clash)
+            continue;
+        for (const v of selected) {
+            for (const pu of u.claimedPaths) {
+                if (v.claimedPaths.includes(pu)) {
+                    clash = true;
+                    break;
+                }
+            }
+            if (clash)
+                break;
+        }
+        if (clash)
+            continue;
+        selected.push(u);
+        for (const p of u.claimedPaths) {
+            blockedPaths.add(p);
+        }
+        if (selected.length >= opts.cap)
+            break;
+    }
+    return selected;
+}
+/**
+ * v6.13.1 — build scheduler rows from merged parallel wave definitions + plan units.
+ */
+export function readySliceUnitsFromMergedWaves(mergedWaves, planMarkdown, options) {
+    const units = parseImplementationUnits(planMarkdown);
+    const metaByUnit = new Map(units.map((u) => {
+        const m = parseImplementationUnitParallelFields(u, options);
+        return [m.unitId, m];
+    }));
+    const sliceSet = new Set();
+    for (const w of mergedWaves) {
+        for (const m of w.members) {
+            sliceSet.add(m.sliceId);
+        }
+    }
+    const out = [];
+    for (const sliceId of [...sliceSet].sort((a, b) => a.localeCompare(b))) {
+        const member = mergedWaves.flatMap((w) => w.members).find((x) => x.sliceId === sliceId);
+        if (!member)
+            continue;
+        const meta = metaByUnit.get(member.unitId);
+        if (!meta) {
+            out.push({
+                unitId: member.unitId,
+                sliceId,
+                dependsOn: [],
+                claimedPaths: [],
+                parallelizable: true
+            });
+            continue;
+        }
+        out.push({
+            unitId: meta.unitId,
+            sliceId,
+            dependsOn: meta.dependsOn,
+            claimedPaths: meta.claimedPaths,
+            parallelizable: meta.parallelizable
+        });
+    }
+    return out;
+}
+/**
+ * v6.13.1 — load merged wave plan (Parallel Execution Plan block + wave-plans/) and map to `ReadySliceUnit[]`.
+ */
+export async function loadTddReadySlicePool(planMarkdown, artifactsDir, options) {
+    const merged = mergeParallelWaveDefinitions(parseParallelExecutionPlanWaves(planMarkdown), await parseWavePlanDirectory(artifactsDir));
+    return readySliceUnitsFromMergedWaves(merged, planMarkdown, options);
+}
 function readMaxParallelOverrideFromEnv() {
     const raw = process.env.CCLAW_MAX_PARALLEL_SLICE_IMPLEMENTERS;
     if (typeof raw !== "string" || raw.trim().length === 0)
@@ -740,8 +907,45 @@ async function writeSubagentTracker(projectRoot, entries) {
     }));
     await writeFileSafe(subagentsStatePath(projectRoot), `${JSON.stringify({ active, updatedAt: new Date().toISOString() }, null, 2)}\n`, { mode: 0o600 });
 }
+function latestClaimTokenForSpan(entries, spanId) {
+    if (!spanId)
+        return null;
+    let latest = null;
+    for (const e of entries) {
+        if (e.spanId !== spanId)
+            continue;
+        if (typeof e.claimToken === "string" && e.claimToken.trim().length > 0) {
+            latest = e.claimToken.trim();
+        }
+    }
+    return latest;
+}
+function assertSliceClaimInvariant(flow, stamped, prior) {
+    if (stamped.stage !== "tdd" || stamped.agent !== "slice-implementer")
+        return;
+    if (effectiveWorktreeExecutionMode(flow) !== "worktree-first")
+        return;
+    if (stamped.status === "scheduled" && typeof stamped.sliceId === "string" && stamped.sliceId.length > 0) {
+        const tok = stamped.claimToken?.trim() ?? "";
+        if (tok.length === 0) {
+            throw new DispatchClaimInvalidError("dispatch_claim_invalid — worktree-first requires --claim-token when scheduling slice-implementer with --slice");
+        }
+    }
+    if (!TERMINAL_DELEGATION_STATUSES.has(stamped.status))
+        return;
+    if (stamped.status === "waived" || stamped.status === "stale")
+        return;
+    const expected = latestClaimTokenForSpan(prior, stamped.spanId);
+    if (!expected)
+        return;
+    const got = stamped.claimToken?.trim() ?? "";
+    if (got !== expected) {
+        throw new DispatchClaimInvalidError("dispatch_claim_invalid — claimToken must match the scheduled claim for this span");
+    }
+}
 export async function appendDelegation(projectRoot, entry) {
-    const { activeRunId } = await readFlowState(projectRoot);
+    const flowState = await readFlowState(projectRoot);
+    const { activeRunId } = flowState;
     await withDirectoryLock(delegationLockPath(projectRoot), async () => {
         const filePath = delegationLogPath(projectRoot);
         const prior = await readDelegationLedger(projectRoot);
@@ -802,6 +1006,7 @@ export async function appendDelegation(projectRoot, entry) {
         if (prior.entries.some((existing) => existing.spanId === stamped.spanId && existing.status === stamped.status)) {
             return;
         }
+        assertSliceClaimInvariant(flowState, stamped, prior.entries);
         validateMonotonicTimestamps(stamped, prior.entries);
         if (stamped.status === "scheduled") {
             // v6.10.0 (P1+P2): for slice-implementer rows with declared
@@ -839,6 +1044,39 @@ export async function appendDelegation(projectRoot, entry) {
         await writeSubagentTracker(projectRoot, ledger.entries);
     });
 }
+/**
+ * Scan delegation events for expired `leasedUntil` timestamps and append
+ * best-effort `cclaw_slice_lease_expired` audit rows (one per span/slice key).
+ */
+export async function reclaimExpiredDelegationClaims(projectRoot, now = new Date()) {
+    const { events } = await readDelegationEvents(projectRoot);
+    const seen = new Set();
+    let count = 0;
+    const ts = now.toISOString();
+    const filePath = delegationEventsPath(projectRoot);
+    const cutoff = Date.parse(ts);
+    for (const e of events) {
+        if (e.leaseState !== "claimed")
+            continue;
+        if (typeof e.leasedUntil !== "string" || e.leasedUntil.length === 0)
+            continue;
+        if (Date.parse(e.leasedUntil) > cutoff)
+            continue;
+        const key = `${e.spanId ?? ""}|${e.sliceId ?? ""}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        await fs.appendFile(filePath, `${JSON.stringify({
+            event: "cclaw_slice_lease_expired",
+            spanId: e.spanId,
+            sliceId: e.sliceId,
+            leasedUntil: e.leasedUntil,
+            eventTs: ts
+        })}\n`, { encoding: "utf8", mode: 0o600 });
+        count += 1;
+    }
+    return count;
+}
 /**
  * Aggregate the fulfillment mode cclaw expects for the active harness set.
  * Priority native > generic-dispatch > role-switch > waiver — the best

package/dist/flow-state.d.ts

@@ -136,7 +136,27 @@ export interface FlowState {
      * sync hasn't visited yet.
      */
     tddCutoverSliceId?: string;
+    /**
+     * v6.13.0 — when `worktree-first` (default for newly initialized runs),
+     * slice-implementer work happens in isolated git worktrees with explicit
+     * claims/leases and deterministic fan-in integration.
+     *
+     * Omitted on legacy `flow-state.json` files: treated as `single-tree` via
+     * `effectiveWorktreeExecutionMode`.
+     */
+    worktreeExecutionMode?: "single-tree" | "worktree-first";
+    /**
+     * v6.13.0 — set by `cclaw-cli sync` when the plan predates parallel-metadata
+     * fields. Relaxes some plan linters for existing implementation units and
+     * defaults scheduler parallelism to opt-in only for those units.
+     */
+    legacyContinuation?: boolean;
 }
+/**
+ * Effective worktree mode: legacy state files without the field keep
+ * single-tree scheduling to avoid breaking existing runs on upgrade.
+ */
+export declare function effectiveWorktreeExecutionMode(state: FlowState): "single-tree" | "worktree-first";
 export interface StageInteractionHint {
     skipQuestions?: boolean;
     sourceStage?: FlowStage;

package/dist/flow-state.js

@@ -44,6 +44,13 @@ export function createInitialCloseoutState() {
         compoundPromoted: 0
     };
 }
+/**
+ * Effective worktree mode: legacy state files without the field keep
+ * single-tree scheduling to avoid breaking existing runs on upgrade.
+ */
+export function effectiveWorktreeExecutionMode(state) {
+    return state.worktreeExecutionMode ?? "single-tree";
+}
 export function isFlowTrack(value) {
     return typeof value === "string" && FLOW_TRACKS.includes(value);
 }

package/dist/gate-evidence.d.ts

@@ -66,6 +66,11 @@ export interface VerifyCurrentStageGateEvidenceOptions {
     extraStageFlags?: string[];
 }
 export declare function verifyCurrentStageGateEvidence(projectRoot: string, flowState: FlowState, options?: VerifyCurrentStageGateEvidenceOptions): Promise<GateEvidenceCheckResult>;
+/**
+ * Validates that every lane-backed slice which reached REFACTOR has a matching
+ * `cclaw_fanin_applied` audit row for the active run (v6.13.0 worktree-first).
+ */
+export declare function verifyTddWorktreeFanInClosure(projectRoot: string, flowState: FlowState): Promise<string[]>;
 export declare function verifyCompletedStagesGateClosure(flowState: FlowState): CompletedStagesClosureResult;
 export interface GateReconciliationResult {
     stage: FlowStage;

package/dist/gate-evidence.js

@@ -5,7 +5,8 @@ import { ELICITATION_STAGES, evaluateQaLogFloor } from "./artifact-linter/shared
 import { resolveArtifactPath } from "./artifact-paths.js";
 import { RUNTIME_ROOT } from "./constants.js";
 import { stageSchema } from "./content/stage-schema.js";
-import { readDelegationLedger } from "./delegation.js";
+import { readDelegationLedger, readDelegationEvents } from "./delegation.js";
+import { effectiveWorktreeExecutionMode } from "./flow-state.js";
 import { exists } from "./fs-utils.js";
 import { computeEarlyLoopStatus, isEarlyLoopStage, normalizeEarlyLoopMaxIterations } from "./early-loop.js";
 import { detectPublicApiChanges } from "./internal/detect-public-api-changes.js";
@@ -487,6 +488,62 @@ export async function verifyCurrentStageGateEvidence(projectRoot, flowState, opt
         qaLogFloor
     };
 }
+function sliceHasTerminalRefactor(events, runId, sliceId) {
+    for (const e of events) {
+        if (e.runId !== runId || e.stage !== "tdd" || e.sliceId !== sliceId)
+            continue;
+        if (e.agent !== "slice-implementer" || e.status !== "completed")
+            continue;
+        if (e.phase === "refactor" || e.phase === "refactor-deferred")
+            return true;
+    }
+    return false;
+}
+function closedSlicesWithLane(events, runId) {
+    const withLane = new Set();
+    for (const e of events) {
+        if (e.runId !== runId || e.stage !== "tdd")
+            continue;
+        if (e.agent !== "slice-implementer" || e.status !== "completed" || e.phase !== "green")
+            continue;
+        if (!e.ownerLaneId?.trim() || !e.sliceId)
+            continue;
+        withLane.add(e.sliceId);
+    }
+    const out = new Set();
+    for (const sid of withLane) {
+        if (sliceHasTerminalRefactor(events, runId, sid))
+            out.add(sid);
+    }
+    return out;
+}
+/**
+ * Validates that every lane-backed slice which reached REFACTOR has a matching
+ * `cclaw_fanin_applied` audit row for the active run (v6.13.0 worktree-first).
+ */
+export async function verifyTddWorktreeFanInClosure(projectRoot, flowState) {
+    if (effectiveWorktreeExecutionMode(flowState) !== "worktree-first")
+        return [];
+    const runId = flowState.activeRunId;
+    const { events, fanInAudits } = await readDelegationEvents(projectRoot);
+    const needing = closedSlicesWithLane(events, runId);
+    if (needing.size === 0)
+        return [];
+    const applied = new Set();
+    for (const a of fanInAudits) {
+        if (a.runId !== runId || a.event !== "cclaw_fanin_applied")
+            continue;
+        for (const s of a.sliceIds ?? [])
+            applied.add(s);
+    }
+    const issues = [];
+    for (const sid of needing) {
+        if (!applied.has(sid)) {
+            issues.push(`tdd worktree fan-in closure: slice ${sid} completed on a lane but cclaw_fanin_applied is missing for run ${runId}.`);
+        }
+    }
+    return issues;
+}
 export function verifyCompletedStagesGateClosure(flowState) {
     const issues = [];
     const openStages = [];

package/dist/install.js

@@ -25,7 +25,7 @@ import { LANGUAGE_RULE_PACK_DIR, LEGACY_LANGUAGE_RULE_PACK_FOLDERS } from "./con
 import { RESEARCH_PLAYBOOKS } from "./content/research-playbooks.js";
 import { SUBAGENT_CONTEXT_SKILLS } from "./content/subagent-context-skills.js";
 import { CCLAW_AGENTS } from "./content/core-agents.js";
-import { createInitialFlowState } from "./flow-state.js";
+import { createInitialFlowState, effectiveWorktreeExecutionMode } from "./flow-state.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
 import { ManagedResourceSession, setActiveManagedResourceSession } from "./managed-resources.js";
 import { ensureGitignore, removeGitignorePatterns } from "./gitignore.js";
@@ -33,7 +33,8 @@ import { HARNESS_ADAPTERS, harnessShimFileNames, harnessShimSkillNames, syncHarn
 import { validateHookDocument } from "./hook-schema.js";
 import { detectHarnesses } from "./init-detect.js";
 import { classifyCodexHooksFlag, codexConfigPath, readCodexConfig } from "./codex-feature-flag.js";
-import { CorruptFlowStateError, ensureRunSystem } from "./runs.js";
+import { CorruptFlowStateError, ensureRunSystem, readFlowState, writeFlowState } from "./runs.js";
+import { PLAN_SPLIT_DEFAULT_WAVE_SIZE, buildParallelExecutionPlanSection, formatNextParallelWaveSyncHint, mergeParallelWaveDefinitions, parseParallelExecutionPlanWaves, parseWavePlanDirectory, planArtifactLacksV613ParallelMetadata, upsertParallelExecutionPlanSection } from "./internal/plan-split-waves.js";
 import { FLOW_STAGES } from "./types.js";
 const OPENCODE_PLUGIN_REL_PATH = ".opencode/plugins/cclaw-plugin.mjs";
 const CURSOR_RULE_REL_PATH = ".cursor/rules/cclaw-workflow.mdc";
@@ -941,6 +942,67 @@ async function applyTddCutoverIfNeeded(projectRoot) {
     obj.tddCutoverSliceId = cutoverSliceId;
     await writeFileSafe(flowStatePath, `${JSON.stringify(obj, null, 2)}\n`, { mode: 0o600 });
 }
+const V613_LEGACY_PLAN_BANNER = "<!-- legacy-continuation: predates v6.13 parallel metadata. New units MAY add dependsOn/claimedPaths/parallelizable; existing units treated as best-effort serial. -->";
+/**
+ * v6.13.0 — when `05-plan.md` lacks parallel-metadata bullets on any
+ * implementation unit, stamp `flow-state.json::legacyContinuation`, insert
+ * a banner + managed Parallel Execution Plan stub, and keep behavior idempotent.
+ */
+async function applyPlanLegacyContinuationIfNeeded(projectRoot) {
+    const planArtifactPath = runtimePath(projectRoot, "artifacts", "05-plan.md");
+    let existingPlan;
+    try {
+        existingPlan = await fs.readFile(planArtifactPath, "utf8");
+    }
+    catch {
+        return;
+    }
+    if (!planArtifactLacksV613ParallelMetadata(existingPlan)) {
+        return;
+    }
+    let nextPlan = existingPlan;
+    if (!nextPlan.includes("legacy-continuation: predates v6.13")) {
+        if (nextPlan.startsWith("---\n")) {
+            const fmEnd = nextPlan.indexOf("\n---", 4);
+            if (fmEnd >= 0) {
+                const fmClose = fmEnd + 4;
+                const head = nextPlan.slice(0, fmClose);
+                const tail = nextPlan.slice(fmClose);
+                nextPlan = `${head}\n\n${V613_LEGACY_PLAN_BANNER}\n${tail}`;
+            }
+            else {
+                nextPlan = `${V613_LEGACY_PLAN_BANNER}\n\n${nextPlan}`;
+            }
+        }
+        else {
+            nextPlan = `${V613_LEGACY_PLAN_BANNER}\n\n${nextPlan}`;
+        }
+    }
+    const parallelStub = buildParallelExecutionPlanSection([], PLAN_SPLIT_DEFAULT_WAVE_SIZE);
+    if (!nextPlan.includes("<!-- parallel-exec-managed-start -->")) {
+        nextPlan = upsertParallelExecutionPlanSection(nextPlan, parallelStub);
+    }
+    if (nextPlan !== existingPlan) {
+        await writeFileSafe(planArtifactPath, nextPlan);
+    }
+    const flowStatePath = runtimePath(projectRoot, "state", "flow-state.json");
+    if (!(await exists(flowStatePath))) {
+        return;
+    }
+    try {
+        const state = await readFlowState(projectRoot);
+        if (state.legacyContinuation === true) {
+            return;
+        }
+        await writeFlowState(projectRoot, { ...state, legacyContinuation: true }, {
+            allowReset: true,
+            writerSubsystem: "plan-legacy-continuation-sync"
+        });
+    }
+    catch {
+        // Best-effort: corrupt/missing state is handled elsewhere on sync.
+    }
+}
 async function cleanLegacyArtifacts(projectRoot) {
     for (const legacyFolder of DEPRECATED_UTILITY_SKILL_FOLDERS) {
         await removeBestEffort(runtimePath(projectRoot, "skills", legacyFolder), true);
@@ -1073,6 +1135,28 @@ async function assertExpectedHarnessShims(projectRoot, harnesses) {
         }
     }
 }
+async function maybeLogParallelWaveDispatchHint(projectRoot) {
+    const flowPath = runtimePath(projectRoot, "state", "flow-state.json");
+    if (!(await exists(flowPath)))
+        return;
+    try {
+        const state = await readFlowState(projectRoot);
+        if (effectiveWorktreeExecutionMode(state) !== "worktree-first")
+            return;
+        const planPath = runtimePath(projectRoot, "artifacts", "05-plan.md");
+        if (!(await exists(planPath)))
+            return;
+        const planRaw = await fs.readFile(planPath, "utf8");
+        const merged = mergeParallelWaveDefinitions(parseParallelExecutionPlanWaves(planRaw), await parseWavePlanDirectory(runtimePath(projectRoot, "artifacts")));
+        const hint = formatNextParallelWaveSyncHint(merged);
+        if (hint) {
+            process.stdout.write(`cclaw: ${hint}\n`);
+        }
+    }
+    catch {
+        // best-effort note only
+    }
+}
 async function materializeRuntime(projectRoot, config, forceStateReset, operation = "sync") {
     await warnStaleInitSentinel(projectRoot, operation);
     const sentinelPath = await writeInitSentinel(projectRoot, operation);
@@ -1093,6 +1177,7 @@ async function materializeRuntime(projectRoot, config, forceStateReset, operatio
         await writeState(projectRoot, config, forceStateReset);
         if (operation === "sync" || operation === "upgrade") {
             await applyTddCutoverIfNeeded(projectRoot);
+            await applyPlanLegacyContinuationIfNeeded(projectRoot);
         }
         try {
             await ensureRunSystem(projectRoot, { createIfMissing: false });
@@ -1112,6 +1197,9 @@ async function materializeRuntime(projectRoot, config, forceStateReset, operatio
         await assertExpectedHarnessShims(projectRoot, harnesses);
         await writeCursorWorkflowRule(projectRoot, harnesses);
         await ensureGitignore(projectRoot);
+        if (operation === "sync" || operation === "upgrade") {
+            await maybeLogParallelWaveDispatchHint(projectRoot);
+        }
         await managedSession.commit();
         await fs.unlink(sentinelPath).catch(() => undefined);
     }

package/dist/integration-fanin.d.ts

@@ -0,0 +1,44 @@
+import { type FlowState } from "./flow-state.js";
+import type { WorktreeLaneId } from "./worktree-types.js";
+export type FanInEventKind = "applied" | "conflict" | "resolved" | "abandoned";
+export interface FanInLaneOptions {
+    projectRoot: string;
+    /** Lane directory under `.cclaw/worktrees/<laneId>`. */
+    laneId: WorktreeLaneId;
+    /** Integration branch to receive the patch (must already exist locally). */
+    integrationBranch: string;
+    /**
+     * Baseline ref for `git diff` in the lane (fork point vs integration).
+     * When omitted, computed as `git merge-base <integration> HEAD` in the lane.
+     */
+    baseRef?: string;
+}
+export interface FanInLaneResult {
+    ok: boolean;
+    event: FanInEventKind;
+    details: string;
+}
+/**
+ * Build a unified diff from `baseRef..HEAD` in the lane worktree and apply it
+ * to the integration branch in the main repo using three-way merge.
+ * On conflict, the integration branch working tree is reset and, when possible,
+ * git HEAD is restored to the branch that was checked out before fan-in.
+ */
+export declare function fanInLane(options: FanInLaneOptions): Promise<FanInLaneResult>;
+export interface ResolverDispatchHint {
+    sliceId: string;
+    command: string;
+}
+/**
+ * Returns the canonical CLI hint for resolving fan-in conflicts for a slice.
+ */
+export declare function buildResolveConflictDispatchHint(sliceId: string): ResolverDispatchHint;
+/**
+ * Merge every lane that recorded a completed GREEN `ownerLaneId` for the
+ * active run, then emit `cclaw_fanin_*` audit rows. Does nothing in
+ * `single-tree` mode or when git is unavailable.
+ */
+export declare function runTddDeterministicFanInBeforeAdvance(projectRoot: string, flowState: FlowState): Promise<{
+    ok: boolean;
+    issues: string[];
+}>;