brainclaw 1.7.5 → 1.9.0

package/dist/commands/harvest.js

@@ -11,21 +11,17 @@
  * @module
  */
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
-import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
 import { CandidateSchema, LaneResultSchema } from '../core/schema.js';
+import { gitEvidence } from '../core/dispatch-status.js';
 import { listCandidates, listArchivedCandidates, saveCandidate } from '../core/candidates.js';
 import { createRuntimeEvent } from '../core/events.js';
 import { memoryExists } from '../core/io.js';
-/**
- * Returns the base directory where brainclaw-managed worktrees are stored
- * for the given project root: `~/.brainclaw/worktrees/<sha1-hash>/`.
- */
-function worktreesBaseDir(projectRoot) {
-    const hash = crypto.createHash('sha1').update(projectRoot).digest('hex').slice(0, 12);
-    return path.join(os.homedir(), '.brainclaw', 'worktrees', hash);
-}
+import { loadAssignment, transitionAssignment } from '../core/assignments.js';
+import { releaseClaimWithCascade, loadClaim } from '../core/claims.js';
+import { getCapabilityProfile, dispatchCanCommit } from '../core/agent-capability.js';
+import { commitWorktreeOnBehalf, worktreesBaseDir } from '../core/worktree.js';
 /**
  * Auto-detect all worktree directories under the brainclaw-managed base dir.
  * Returns subdirectories that exist on disk (may or may not have an inbox).
@@ -38,6 +34,44 @@ function autoDetectWorktreePaths(cwd) {
         .filter((entry) => entry.isDirectory())
         .map((entry) => path.join(base, entry.name));
 }
+/**
+ * sprint 1.5 — deterministic worktree resolution for one assignment. The
+ * auto-detect scan depends on the project-hash directory layout and missed a
+ * LANE-RESULT.json that demonstrably existed (asgn_ab11b801): the assignment's
+ * own worktree_path (and its claim's) are authoritative — scan them FIRST.
+ * Works regardless of assignment status (incl. expired — evidence arriving
+ * late must still be harvestable).
+ */
+function resolveAssignmentWorktreePaths(assignmentId, cwd) {
+    const paths = [];
+    const assignment = loadAssignment(assignmentId, cwd);
+    if (assignment?.worktree_path)
+        paths.push(assignment.worktree_path);
+    if (assignment?.claim_id) {
+        try {
+            const claim = loadClaim(assignment.claim_id, cwd);
+            if (claim.worktree_path)
+                paths.push(claim.worktree_path);
+        }
+        catch { /* claim gone — assignment path may still resolve */ }
+    }
+    return [...new Set(paths)].filter((p) => {
+        try {
+            return fs.existsSync(p);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** Scan list for a lane harvest: explicit paths win; otherwise the assignment's
+ * own worktrees first, then the auto-detected pool (deduped). */
+function resolveLaneScanPaths(options, cwd) {
+    if (options.worktreePaths && options.worktreePaths.length > 0)
+        return options.worktreePaths;
+    const assignmentPaths = options.assignmentId ? resolveAssignmentWorktreePaths(options.assignmentId, cwd) : [];
+    return [...new Set([...assignmentPaths, ...autoDetectWorktreePaths(cwd)])];
+}
 /**
  * Collect all `cnd_*.json` files from a worktree's candidate inbox.
  *
@@ -213,9 +247,7 @@ export function harvestLaneResults(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const agent = options.agent ?? 'coordinator';
     const result = { harvested: [], skipped: [], errors: [] };
-    const worktreePaths = (options.worktreePaths && options.worktreePaths.length > 0)
-        ? options.worktreePaths
-        : autoDetectWorktreePaths(cwd);
+    const worktreePaths = resolveLaneScanPaths(options, cwd);
     for (const worktreePath of worktreePaths) {
         const file = getLaneResultPath(worktreePath);
         if (!fs.existsSync(file))
@@ -253,7 +285,7 @@ export function harvestLaneResults(options = {}) {
                     },
                 }, cwd);
                 fs.mkdirSync(path.dirname(marker), { recursive: true });
-                fs.writeFileSync(marker, new Date(0).toISOString(), 'utf-8');
+                fs.writeFileSync(marker, new Date().toISOString(), 'utf-8');
             }
             catch (err) {
                 result.errors.push(`Failed to ingest lane result for ${lane.assignment_id}: ${err instanceof Error ? err.message : String(err)}`);
@@ -264,16 +296,461 @@ export function harvestLaneResults(options = {}) {
     }
     return result;
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// pln#534 — worktree-as-contract: integrate a worker's lane on its behalf.
+//
+// LEVER #1 from the LeaseUp frontier (can_100f1e8c). The worker's contract is
+// reduced to "edit files in this worktree + drop LANE-RESULT.json". brainclaw
+// carries the rest for a worker that cannot (a sandboxed agent whose root
+// excludes `.git`, i.e. dispatchCanCommit=false): it COMMITS the worktree diff
+// on the worker's behalf so the code lands on the lane branch, then lifecycles
+// the assignment and releases the claim (with plan cascade). Self-commit / MCP /
+// self-lifecycle become PROGRESSIVE enrichments, not prerequisites.
+//
+// Strictly ADDITIVE + opt-in: nothing here runs unless a caller invokes
+// integrateLaneResults / `brainclaw harvest --integrate`. Existing harvest stays
+// report-only.
+// ─────────────────────────────────────────────────────────────────────────────
+/** Happy-path assignment FSM chain walked when force-completing on behalf. */
+const ASSIGNMENT_COMPLETE_CHAIN = ['created', 'offered', 'accepted', 'started', 'completed'];
+/**
+ * Walk a still-open assignment forward to `completed` through the valid FSM
+ * chain (offered→accepted→started→completed), attaching artifacts on the final
+ * step. Idempotent (already-completed → true; transitions no-op). Returns false
+ * for assignments parked off the happy path (failed/blocked/timed_out) — those
+ * are not silently force-completed.
+ */
+function forceCompleteAssignment(assignmentId, artifacts, statusReason, actor, cwd) {
+    const current = loadAssignment(assignmentId, cwd);
+    if (!current)
+        return false;
+    if (current.status === 'completed')
+        return true;
+    // can_948acfd6 — expired→completed: a LANE-RESULT arriving after an
+    // administrative expiry is the truth; converge instead of FSM-blocking.
+    if (current.status === 'expired') {
+        try {
+            transitionAssignment(assignmentId, 'completed', {
+                actor, artifacts, status_reason: `${statusReason} (late evidence after administrative expiry)`,
+            }, cwd);
+        }
+        catch { /* concurrent transition */ }
+        return loadAssignment(assignmentId, cwd)?.status === 'completed';
+    }
+    const startIdx = ASSIGNMENT_COMPLETE_CHAIN.indexOf(current.status);
+    if (startIdx === -1)
+        return false; // off the happy path (failed/blocked/…): leave it.
+    for (let i = startIdx + 1; i < ASSIGNMENT_COMPLETE_CHAIN.length; i++) {
+        const next = ASSIGNMENT_COMPLETE_CHAIN[i];
+        try {
+            transitionAssignment(assignmentId, next, next === 'completed' ? { actor, artifacts, status_reason: statusReason } : { actor }, cwd);
+        }
+        catch {
+            // A concurrent explicit transition may have moved it; stop walking.
+            break;
+        }
+    }
+    return loadAssignment(assignmentId, cwd)?.status === 'completed';
+}
+/**
+ * Integrate completed lanes on behalf of workers that cannot self-commit.
+ *
+ * For each LANE-RESULT.json found (optionally filtered to one assignment):
+ *  1. resolve the assignment + the worker agent's commit capability;
+ *  2. when the worker CANNOT commit (sandboxed) and the worktree is dirty,
+ *     commit the diff on its behalf onto the lane branch (guarded to the linked
+ *     worktree only — never the main repo);
+ *  3. lifecycle the assignment (status=completed → walk to completed with the
+ *     commit + files as artifacts; status=blocked/failed → best-effort
+ *     transition) and release the claim with plan cascade.
+ *
+ * A worker that CAN commit is left to its self-commit handoff — brainclaw only
+ * lifecycles/releases, it does not author commits for it.
+ */
+export function integrateLaneResults(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const actor = options.agent ?? 'coordinator';
+    const result = { integrated: [], skipped: [], errors: [] };
+    const worktreePaths = resolveLaneScanPaths(options, cwd);
+    for (const worktreePath of worktreePaths) {
+        const file = getLaneResultPath(worktreePath);
+        if (!fs.existsSync(file))
+            continue;
+        let lane;
+        try {
+            lane = LaneResultSchema.parse(JSON.parse(fs.readFileSync(file, 'utf-8')));
+        }
+        catch (err) {
+            result.errors.push(`Failed to parse ${file}: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+        if (options.assignmentId && lane.assignment_id !== options.assignmentId)
+            continue;
+        const assignment = loadAssignment(lane.assignment_id, cwd);
+        if (!assignment) {
+            result.skipped.push(lane.assignment_id);
+            result.errors.push(`No assignment record for lane ${lane.assignment_id} — cannot integrate`);
+            continue;
+        }
+        const profile = getCapabilityProfile(assignment.agent);
+        // No profile ⇒ assume it can commit (conservative: don't author for an
+        // unknown agent), so brainclaw only lifecycles.
+        const workerCanCommit = profile ? dispatchCanCommit(profile) : true;
+        const entry = {
+            assignment_id: lane.assignment_id,
+            worker_agent: assignment.agent,
+            lane_status: lane.status,
+            worker_can_commit: workerCanCommit,
+            committed_on_behalf: false,
+            files_changed: lane.files_changed ?? [],
+            assignment_completed: false,
+            claim_released: false,
+            reason: '',
+        };
+        const reasons = [];
+        // 1. Commit on behalf (only when the worker cannot, and there is a diff).
+        if (!workerCanCommit) {
+            if (options.dryRun) {
+                reasons.push('(dry-run) would commit worktree diff on behalf');
+            }
+            else {
+                const message = `chore(lane): integrate ${assignment.agent} work for ${lane.assignment_id}\n\n`
+                    + `${lane.summary}\n\n[brainclaw committed on behalf — worker sandbox cannot self-commit (pln#534)]`;
+                const commit = commitWorktreeOnBehalf(worktreePath, message, {
+                    authorName: `${assignment.agent} (via brainclaw)`,
+                    authorEmail: 'brainclaw@on-behalf.local',
+                });
+                entry.committed_on_behalf = commit.committed;
+                entry.commit_sha = commit.sha;
+                if (commit.committed)
+                    entry.files_changed = commit.files_changed;
+                reasons.push(commit.reason);
+            }
+        }
+        else {
+            reasons.push('worker can self-commit — no on-behalf commit');
+        }
+        // 2. Lifecycle + release.
+        if (!options.dryRun) {
+            if (lane.status === 'completed') {
+                const artifacts = [
+                    ...(entry.commit_sha ? [{ type: 'commit', ref: entry.commit_sha, description: 'on-behalf integration commit' }] : []),
+                    ...entry.files_changed.slice(0, 50).map((f) => ({ type: 'file', ref: f })),
+                ];
+                entry.assignment_completed = forceCompleteAssignment(lane.assignment_id, artifacts, `pln#534 on-behalf integration: ${lane.summary.slice(0, 120)}`, actor, cwd);
+                try {
+                    const rel = releaseClaimWithCascade(assignment.claim_id, { planStatus: 'done', cwd });
+                    entry.claim_released = rel.claim.status === 'released';
+                }
+                catch (err) {
+                    reasons.push(`claim release failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            else {
+                // blocked / failed: best-effort lifecycle (FSM may reject from offered).
+                const target = lane.status === 'blocked' ? 'blocked' : 'failed';
+                try {
+                    transitionAssignment(lane.assignment_id, target, { actor, status_reason: lane.summary.slice(0, 200) }, cwd);
+                }
+                catch (err) {
+                    reasons.push(`assignment ${target} transition rejected: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                try {
+                    const rel = releaseClaimWithCascade(assignment.claim_id, {
+                        planStatus: lane.status === 'blocked' ? 'blocked' : undefined,
+                        cwd,
+                    });
+                    entry.claim_released = rel.claim.status === 'released';
+                }
+                catch (err) {
+                    reasons.push(`claim release failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            // Durable trace of the integration.
+            try {
+                createRuntimeEvent({
+                    agent: actor,
+                    event_type: 'lane_integrated',
+                    text: `Integrated lane ${lane.assignment_id} (${lane.status}) on behalf of ${assignment.agent}`,
+                    tags: ['harvest', 'integrate', 'worktree-as-contract', lane.status],
+                    assignment_id: lane.assignment_id,
+                    metadata: {
+                        assignment_id: lane.assignment_id,
+                        worker_agent: assignment.agent,
+                        committed_on_behalf: entry.committed_on_behalf,
+                        commit_sha: entry.commit_sha ?? null,
+                        files_changed: entry.files_changed,
+                        assignment_completed: entry.assignment_completed,
+                        claim_released: entry.claim_released,
+                    },
+                }, cwd);
+            }
+            catch { /* event is best-effort */ }
+        }
+        entry.reason = reasons.join('; ');
+        result.integrated.push(entry);
+    }
+    return result;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// pln#554 step 3 — `harvest --orphaned`: recover a dead worker that left NO
+// LANE-RESULT. Codifies the manual recovery executed twice on 2026-06-10
+// (42 and 41 files, zero loss): inspect the worktree, typecheck if possible,
+// commit on-behalf with the standard marker, lifecycle when the FSM allows,
+// release the claim. NEVER deletes or resets anything.
+// ─────────────────────────────────────────────────────────────────────────────
+export const ORPHANED_COMMIT_MARKER = '[brainclaw committed on behalf — worker died before delivering; coordinator harvest --orphaned]';
+function countUntracked(worktreePath) {
+    const r = spawnSync('git', ['-C', worktreePath, 'status', '--short'], { encoding: 'utf-8', timeout: 15000 });
+    if (r.status !== 0)
+        return 0;
+    return (r.stdout ?? '').split('\n').filter((l) => l.startsWith('??')).length;
+}
+/** `npx tsc --noEmit` in the worktree; skips gracefully when node_modules is absent. */
+function typecheckWorktree(worktreePath) {
+    if (!fs.existsSync(path.join(worktreePath, 'node_modules'))) {
+        return {
+            status: 'skipped_no_node_modules',
+            output: 'node_modules absent in worktree — link it from the main repo (Windows junction / symlink) to typecheck locally; the coordinator validates centrally after harvest.',
+        };
+    }
+    // Fixed command string (no user input) — shell needed for npx on Windows.
+    const r = spawnSync('npx tsc --noEmit', { cwd: worktreePath, shell: true, encoding: 'utf-8', timeout: 300_000 });
+    if (r.status === 0)
+        return { status: 'passed' };
+    const out = `${r.stdout ?? ''}${r.stderr ?? ''}`.trim();
+    return { status: 'failed', output: out.slice(0, 2000) };
+}
+/**
+ * Recover an orphaned lane: a worker died without writing LANE-RESULT.json.
+ *
+ * Evidence-first and strictly non-destructive:
+ *  - LANE-RESULT present → not orphaned; refuse and point at the normal harvest;
+ *  - tracked changes → typecheck (best effort), then commit on-behalf with
+ *    ORPHANED_COMMIT_MARKER;
+ *  - clean tree + no commits ahead → 'nothing to recover', state untouched;
+ *  - then lifecycle the assignment when the FSM allows and release the claim.
+ */
+export function harvestOrphaned(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const actor = options.agent ?? 'coordinator';
+    const baseRef = options.baseRef ?? 'master';
+    const report = {
+        assignment_id: options.assignmentId,
+        worktree_path: undefined,
+        commits_ahead: 0,
+        dirty_tracked: 0,
+        untracked: 0,
+        nothing_to_recover: false,
+        typecheck: 'not_run',
+        committed_on_behalf: false,
+        files_changed: [],
+        assignment_completed: false,
+        claim_released: false,
+        errors: [],
+        recommended_next_action: '',
+    };
+    let worktree = options.worktreePath;
+    if (!worktree && options.assignmentId) {
+        worktree = resolveAssignmentWorktreePaths(options.assignmentId, cwd)[0];
+    }
+    if (!worktree || !fs.existsSync(worktree)) {
+        report.errors.push('No worktree resolved — pass --worktree <path> explicitly, or patch claim.worktree_path.');
+        report.recommended_next_action = 'Resolve the worktree path first; nothing was touched.';
+        return report;
+    }
+    report.worktree_path = worktree;
+    if (fs.existsSync(getLaneResultPath(worktree))) {
+        report.errors.push('LANE-RESULT.json present — this lane is NOT orphaned. Use `brainclaw harvest <assignment_id> [--integrate]` instead.');
+        report.recommended_next_action = 'Run the normal lane harvest; nothing was touched.';
+        return report;
+    }
+    const evidence = gitEvidence(worktree, baseRef);
+    if (!evidence) {
+        report.errors.push(`Could not read git evidence from ${worktree} (base ref '${baseRef}') — is it a git worktree and does the base ref exist?`);
+        report.recommended_next_action = 'Fix the base ref (--base) or inspect the worktree manually; nothing was touched.';
+        return report;
+    }
+    report.commits_ahead = evidence.commitsAhead;
+    report.dirty_tracked = evidence.dirtyTracked;
+    report.untracked = countUntracked(worktree);
+    if (evidence.dirtyTracked === 0 && evidence.commitsAhead === 0) {
+        report.nothing_to_recover = true;
+        report.recommended_next_action = report.untracked > 0
+            ? `Nothing to recover (no tracked changes, no commits ahead). ${report.untracked} untracked file(s) present — inspect them manually before any cleanup. State left untouched.`
+            : 'Nothing to recover — worktree clean with no commits ahead. State left untouched.';
+        return report;
+    }
+    // Tracked changes → typecheck (best effort), then commit on-behalf.
+    if (evidence.dirtyTracked > 0) {
+        if (options.dryRun) {
+            report.recommended_next_action = `(dry-run) would typecheck + commit ${evidence.dirtyTracked} tracked change(s) on behalf.`;
+        }
+        else {
+            const tc = typecheckWorktree(worktree);
+            report.typecheck = tc.status;
+            report.typecheck_output = tc.output;
+            const message = `chore(lane): recover orphaned worker output${options.assignmentId ? ` for ${options.assignmentId}` : ''}\n\n${ORPHANED_COMMIT_MARKER}`;
+            const commit = commitWorktreeOnBehalf(worktree, message, {
+                authorName: 'brainclaw (orphaned recovery)',
+                authorEmail: 'brainclaw@on-behalf.local',
+            });
+            report.committed_on_behalf = commit.committed;
+            report.commit_sha = commit.sha;
+            report.files_changed = commit.files_changed;
+            if (!commit.committed)
+                report.errors.push(`commit on behalf failed: ${commit.reason}`);
+        }
+    }
+    else if (options.dryRun) {
+        // commits ahead with a clean tree — the worker delivered before dying.
+        report.recommended_next_action = `(dry-run) nothing to commit (${evidence.commitsAhead} commit(s) already on the branch); would lifecycle the assignment + release the claim.`;
+    }
+    // Lifecycle + claim release (only with an assignment to converge, never dry-run).
+    if (!options.dryRun && options.assignmentId) {
+        const assignment = loadAssignment(options.assignmentId, cwd);
+        if (assignment) {
+            const artifacts = [
+                ...(report.commit_sha ? [{ type: 'commit', ref: report.commit_sha, description: 'orphaned-recovery commit (on behalf)' }] : []),
+                ...report.files_changed.slice(0, 50).map((f) => ({ type: 'file', ref: f })),
+            ];
+            report.assignment_completed = forceCompleteAssignment(options.assignmentId, artifacts, 'pln#554 harvest --orphaned: worker died before delivering; work recovered from worktree', actor, cwd);
+            try {
+                const rel = releaseClaimWithCascade(assignment.claim_id, { planStatus: 'done', cwd });
+                report.claim_released = rel.claim.status === 'released';
+            }
+            catch (err) {
+                report.errors.push(`claim release failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        else {
+            report.errors.push(`No assignment record for ${options.assignmentId} — recovered the worktree but skipped lifecycle/claim release.`);
+        }
+    }
+    if (!options.dryRun) {
+        try {
+            createRuntimeEvent({
+                agent: actor,
+                event_type: 'lane_integrated',
+                text: `Orphaned lane recovered${options.assignmentId ? ` for ${options.assignmentId}` : ''}: ${report.files_changed.length} file(s) committed on behalf (typecheck=${report.typecheck})`,
+                tags: ['harvest', 'orphaned', 'recovery'],
+                assignment_id: options.assignmentId,
+                metadata: {
+                    assignment_id: options.assignmentId ?? null,
+                    worktree_path: worktree,
+                    commit_sha: report.commit_sha ?? null,
+                    files_changed: report.files_changed,
+                    typecheck: report.typecheck,
+                    commits_ahead: report.commits_ahead,
+                    assignment_completed: report.assignment_completed,
+                    claim_released: report.claim_released,
+                },
+            }, cwd);
+        }
+        catch { /* event is best-effort */ }
+        const tcWarn = report.typecheck === 'failed'
+            ? ' WARNING: typecheck FAILED — fix the branch before merging (output captured in the report).'
+            : report.typecheck === 'skipped_no_node_modules'
+                ? ' Typecheck was skipped (no node_modules) — validate centrally.'
+                : '';
+        report.recommended_next_action =
+            `Run targeted tests for the recovered files, then merge the lane branch.${tcWarn}`;
+    }
+    return report;
+}
 export function runHarvestLane(assignmentId, options = {}) {
     const cwd = options.cwd ?? process.cwd();
     if (!memoryExists(cwd)) {
         console.error('Error: .brainclaw/ not found. Run `brainclaw init` first.');
         process.exit(1);
     }
-    if (!assignmentId && !options.all) {
+    if (!assignmentId && !options.all && !(options.orphaned && options.worktree?.length)) {
         console.error('Error: provide an <assignment_id>, or pass --all to harvest every lane result.');
         process.exit(1);
     }
+    // pln#554 — `--orphaned`: the worker died WITHOUT a lane-result. Recover its
+    // worktree (typecheck + commit on behalf), lifecycle, and release. Never
+    // deletes or resets anything.
+    if (options.orphaned) {
+        const report = harvestOrphaned({
+            assignmentId,
+            worktreePath: options.worktree?.[0],
+            baseRef: options.base,
+            dryRun: options.dryRun,
+            cwd,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(report, null, 2));
+            process.exitCode = report.errors.length > 0 ? 1 : 0;
+            return;
+        }
+        const dry = options.dryRun ? ' (dry-run)' : '';
+        console.log(`Orphaned-lane recovery${dry} for ${assignmentId ?? report.worktree_path ?? '(unresolved)'}:`);
+        if (report.worktree_path)
+            console.log(`  worktree: ${report.worktree_path}`);
+        console.log(`  evidence: commits_ahead=${report.commits_ahead} dirty_tracked=${report.dirty_tracked} untracked=${report.untracked}`);
+        if (report.nothing_to_recover) {
+            console.log('  → nothing to recover; state left untouched.');
+        }
+        else {
+            if (report.typecheck !== 'not_run') {
+                console.log(`  typecheck: ${report.typecheck}`);
+                if (report.typecheck_output)
+                    console.log(`    ${report.typecheck_output.split('\n').slice(0, 12).join('\n    ')}`);
+            }
+            if (report.committed_on_behalf) {
+                console.log(`  ✔ committed on behalf: ${report.commit_sha?.slice(0, 10)} (${report.files_changed.length} file(s))`);
+            }
+            console.log(`  assignment_completed=${report.assignment_completed} claim_released=${report.claim_released}`);
+        }
+        for (const err of report.errors)
+            console.error(`  ✗ ${err}`);
+        if (report.recommended_next_action)
+            console.log(`  → ${report.recommended_next_action}`);
+        process.exitCode = report.errors.length > 0 ? 1 : 0;
+        return;
+    }
+    // pln#534 — `--integrate` upgrades harvest from report-only to converge-the-
+    // lane: commit the worktree diff on behalf of a sandboxed worker, lifecycle
+    // the assignment, and release the claim. Runs alongside the normal ingest.
+    if (options.integrate) {
+        const integ = integrateLaneResults({
+            assignmentId: options.all ? undefined : assignmentId,
+            worktreePaths: options.worktree,
+            dryRun: options.dryRun,
+            cwd,
+        });
+        if (options.json) {
+            console.log(JSON.stringify(integ, null, 2));
+            return;
+        }
+        const dry = options.dryRun ? ' (dry-run)' : '';
+        if (integ.integrated.length === 0 && integ.errors.length === 0) {
+            if (assignmentId) {
+                const checked = resolveLaneScanPaths({ assignmentId, worktreePaths: options.worktree }, cwd);
+                console.log(`No LANE-RESULT.json to integrate for ${assignmentId}.`);
+                console.log(checked.length > 0
+                    ? `  Checked worktree(s): ${checked.slice(0, 5).join(', ')}${checked.length > 5 ? ` (+${checked.length - 5} more)` : ''}`
+                    : '  No worktree resolved for this assignment — pass --worktree <path> explicitly, or patch claim.worktree_path.');
+            }
+            else {
+                console.log('No lane results to integrate.');
+            }
+            return;
+        }
+        for (const e of integ.integrated) {
+            console.log(`  ✔ Integrated [${e.assignment_id}] ${e.lane_status} (worker=${e.worker_agent}, can_commit=${e.worker_can_commit})`);
+            if (e.committed_on_behalf)
+                console.log(`      committed on behalf: ${e.commit_sha?.slice(0, 10)} (${e.files_changed.length} file(s))`);
+            console.log(`      assignment_completed=${e.assignment_completed} claim_released=${e.claim_released}`);
+            if (e.reason)
+                console.log(`      ${e.reason}`);
+        }
+        for (const err of integ.errors)
+            console.error(`  ✗ ${err}`);
+        console.log(`\n✔ Lane integrate complete${dry}: ${integ.integrated.length} integrated, ${integ.errors.length} error(s).`);
+        return;
+    }
     const result = harvestLaneResults({
         assignmentId: options.all ? undefined : assignmentId,
         worktreePaths: options.worktree,
@@ -290,7 +767,16 @@ export function runHarvestLane(assignmentId, options = {}) {
     }
     const dryTag = options.dryRun ? ' (dry-run)' : '';
     if (result.harvested.length === 0 && result.skipped.length === 0 && result.errors.length === 0) {
-        console.log(assignmentId ? `No LANE-RESULT.json found for ${assignmentId}.` : 'No lane results found in any worktree.');
+        if (assignmentId) {
+            const checked = resolveLaneScanPaths({ assignmentId, worktreePaths: options.worktree }, cwd);
+            console.log(`No LANE-RESULT.json found for ${assignmentId}.`);
+            console.log(checked.length > 0
+                ? `  Checked worktree(s): ${checked.slice(0, 5).join(', ')}${checked.length > 5 ? ` (+${checked.length - 5} more)` : ''}`
+                : '  No worktree resolved for this assignment — pass --worktree <path> explicitly, or patch claim.worktree_path.');
+        }
+        else {
+            console.log('No lane results found in any worktree.');
+        }
         return;
     }
     for (const lane of result.harvested) {