brainclaw 1.8.0 → 1.9.0

package/dist/commands/estimation-report.js

@@ -1,5 +1,47 @@
 import { loadState } from '../core/state.js';
 import { memoryExists } from '../core/io.js';
+/** Default wall-clock outlier cutoff: a single plan's "actual" over 24h is almost certainly idle, not work. */
+export const DEFAULT_OUTLIER_THRESHOLD_MINUTES = 1440;
+/**
+ * Sum of per-step estimates — only when EVERY step carries one. A mixed plan
+ * (some steps estimated, some not) returns undefined so the caller falls back
+ * to the plan-level estimate rather than mixing half-measured data (pln#495).
+ */
+function sumStepEstimates(plan) {
+    const steps = plan.steps ?? [];
+    if (steps.length === 0)
+        return undefined;
+    if (!steps.every((s) => typeof s.estimated_effort === 'number'))
+        return undefined;
+    return steps.reduce((acc, s) => acc + s.estimated_effort, 0);
+}
+/**
+ * Sum of per-step actual durations — only when EVERY step is measurable, via an
+ * explicit `actual_effort` string OR both `started_at`+`completed_at`. Returns
+ * undefined otherwise (→ fall back to plan-level). This is the key win: summing
+ * per-step durations excludes the idle time BETWEEN steps that plan-level
+ * wall-clock wrongly counts as work (pln#495, the pln#494 step-6 bias).
+ */
+function sumStepActuals(plan) {
+    const steps = plan.steps ?? [];
+    if (steps.length === 0)
+        return undefined;
+    let total = 0;
+    for (const s of steps) {
+        let dur;
+        if (s.actual_effort) {
+            dur = parseEffortMinutes(s.actual_effort);
+        }
+        else if (s.started_at && s.completed_at) {
+            const d = (new Date(s.completed_at).getTime() - new Date(s.started_at).getTime()) / 60000;
+            dur = d > 0 ? d : undefined;
+        }
+        if (dur === undefined)
+            return undefined; // any unmeasurable step → no step-level actual
+        total += dur;
+    }
+    return total > 0 ? total : undefined;
+}
 /** Parse legacy actual_effort strings ("30min", "2h", "1h30m", "1d", "45m") → minutes.
  *  Still needed for actual_effort which remains a free string. */
 export function parseEffortMinutes(effort) {
@@ -23,7 +65,7 @@ export function parseEffortMinutes(effort) {
     }
     if (!matched) {
         const bare = parseFloat(s);
-        if (!isNaN(bare))
+        if (!isNaN(bare) && /^\d+(?:\.\d+)?$/.test(s))
             return bare;
         return undefined;
     }
@@ -65,37 +107,78 @@ export function buildEstimationReport(options = {}) {
     const state = loadState(options.cwd);
     const done = state.plan_items.filter((p) => p.status === 'done' && (!options.agent || p.author === options.agent));
     const entries = done.map((p) => {
+        // Estimate: prefer the sum of per-step estimates when ALL steps carry one,
+        // else the plan-level estimate (pln#495).
+        const stepEstimate = sumStepEstimates(p);
         const entry = {
             id: p.id,
             text: p.text,
             author: p.author,
-            estimated_minutes: p.estimated_effort, // already a number after schema coercion
+            estimated_minutes: stepEstimate ?? p.estimated_effort,
             actual_effort: p.actual_effort,
             completed_at: p.completed_at,
         };
-        // Compute elapsed from wall-clock timestamps
-        const endTime = p.completed_at ?? p.updated_at;
-        const startTime = p.started_at ?? p.created_at;
-        if (endTime && startTime) {
-            const elapsed = (new Date(endTime).getTime() - new Date(startTime).getTime()) / 60000;
-            if (elapsed > 0)
-                entry.elapsed_minutes = Math.round(elapsed);
+        // Actual + source, in fallback order (pln#495):
+        //   step durations (idle-gap-free) > plan.actual_effort string > plan wall-clock.
+        let actualMinutes;
+        let source;
+        const stepActual = sumStepActuals(p);
+        if (stepActual !== undefined) {
+            actualMinutes = stepActual;
+            source = 'step';
         }
-        // Resolve actual minutes: explicit actual_effort string > elapsed wall-clock
-        const actualMinutes = p.actual_effort
-            ? parseEffortMinutes(p.actual_effort)
-            : entry.elapsed_minutes;
-        if (actualMinutes !== undefined)
+        else if (p.actual_effort) {
+            actualMinutes = parseEffortMinutes(p.actual_effort);
+            source = 'plan_string';
+        }
+        else {
+            const endTime = p.completed_at ?? p.updated_at;
+            const startTime = p.started_at ?? p.created_at;
+            if (endTime && startTime) {
+                const elapsed = (new Date(endTime).getTime() - new Date(startTime).getTime()) / 60000;
+                if (elapsed > 0)
+                    actualMinutes = elapsed;
+            }
+            source = 'plan_wallclock';
+        }
+        if (actualMinutes !== undefined) {
             entry.elapsed_minutes = Math.round(actualMinutes);
+            entry.source = source;
+        }
         if (entry.estimated_minutes !== undefined && actualMinutes !== undefined && actualMinutes > 0) {
             entry.ratio = parseFloat((entry.estimated_minutes / actualMinutes).toFixed(2));
         }
         return entry;
     });
+    // Wall-clock outlier filter (pln#495 step 7): a plan whose actual is plan-level
+    // wall-clock AND exceeds the threshold is flagged and dropped from the summary
+    // stats — it would otherwise drag the median/mean (the post-restoration +9900%
+    // accident). Step- and string-derived actuals are trusted at any size. A
+    // threshold of 0 disables the filter. Outliers keep their ratio and stay in
+    // `entries` so the chart still shows them, just marked.
+    const threshold = options.outlierThresholdMinutes ?? DEFAULT_OUTLIER_THRESHOLD_MINUTES;
+    if (threshold > 0) {
+        for (const e of entries) {
+            if (e.source === 'plan_wallclock' && e.elapsed_minutes !== undefined && e.elapsed_minutes > threshold) {
+                e.excluded_from_stats = true;
+            }
+        }
+    }
     const withBoth = entries.filter((e) => e.ratio !== undefined);
-    const ratios = withBoth.map((e) => e.ratio);
+    const included = withBoth.filter((e) => !e.excluded_from_stats);
+    const ratios = included.map((e) => e.ratio);
     const medianRatio = ratios.length > 0 ? parseFloat(median(ratios).toFixed(2)) : undefined;
     const meanRatio = ratios.length > 0 ? parseFloat(mean(ratios).toFixed(2)) : undefined;
+    // Per-source median (pln#495): exposes how much calibration noise is wall-clock
+    // contamination vs idle-gap-free step measurement. Excludes flagged outliers.
+    const bySource = {};
+    for (const src of ['step', 'plan_string', 'plan_wallclock']) {
+        const srcRatios = included.filter((e) => e.source === src).map((e) => e.ratio);
+        if (srcRatios.length > 0) {
+            bySource[src] = { count: srcRatios.length, median_ratio: parseFloat(median(srcRatios).toFixed(2)) };
+        }
+    }
+    const outliersExcluded = withBoth.filter((e) => e.excluded_from_stats).length;
     return {
         entries,
         summary: {
@@ -105,6 +188,8 @@ export function buildEstimationReport(options = {}) {
             median_ratio: medianRatio,
             mean_ratio: meanRatio,
             calibration_hint: medianRatio !== undefined ? buildCalibrationHint(medianRatio) : undefined,
+            by_source: Object.keys(bySource).length > 0 ? bySource : undefined,
+            outliers_excluded: outliersExcluded > 0 ? outliersExcluded : undefined,
         },
     };
 }
@@ -129,6 +214,19 @@ export function runEstimationReport(options = {}) {
         console.log(`\nMedian ratio (estimated÷actual): ${summary.median_ratio}x · Mean: ${summary.mean_ratio}x`);
         console.log(`→ ${summary.calibration_hint}`);
     }
+    if (summary.outliers_excluded) {
+        console.log(`(${summary.outliers_excluded} wall-clock outlier(s) >24h excluded from the stats above — shown ⚠ in the chart)`);
+    }
+    if (summary.by_source) {
+        const labels = {
+            step: 'step-derived', plan_string: 'plan-string', plan_wallclock: 'plan-wallclock',
+        };
+        const parts = ['step', 'plan_string', 'plan_wallclock']
+            .filter((s) => summary.by_source[s])
+            .map((s) => `${labels[s]}: ${summary.by_source[s].median_ratio}x (n=${summary.by_source[s].count})`);
+        console.log(`By measurement quality — ${parts.join(' · ')}`);
+        console.log('  (step-derived excludes inter-step idle; plan-wallclock is the noisiest)');
+    }
     // Chart — only plans with ratio data
     const chartable = entries.filter((e) => e.ratio !== undefined);
     if (chartable.length > 0) {
@@ -149,7 +247,8 @@ export function runEstimationReport(options = {}) {
                 : ` OVER  +${Math.round((1 / e.ratio - 1) * 100)}%`;
             const est = e.estimated_minutes !== undefined ? `${e.estimated_minutes}min` : '?';
             const act = e.elapsed_minutes !== undefined ? `${e.elapsed_minutes}min` : '?';
-            console.log(`  ${label} ${bar} ${e.ratio}x  ${est}→${act}${pct}`);
+            const srcTag = e.excluded_from_stats ? ' ⚠outlier' : e.source === 'step' ? ' ✓step' : e.source === 'plan_wallclock' ? ' ~wall' : '';
+            console.log(`  ${label} ${bar} ${e.ratio}x  ${est}→${act}${pct}${srcTag}`);
         }
         console.log('');
     }

package/dist/commands/harvest.js

@@ -11,25 +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';
 import { loadAssignment, transitionAssignment } from '../core/assignments.js';
-import { releaseClaimWithCascade } from '../core/claims.js';
+import { releaseClaimWithCascade, loadClaim } from '../core/claims.js';
 import { getCapabilityProfile, dispatchCanCommit } from '../core/agent-capability.js';
-import { commitWorktreeOnBehalf } from '../core/worktree.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 { 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).
@@ -42,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.
  *
@@ -217,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))
@@ -257,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)}`);
@@ -298,6 +326,17 @@ function forceCompleteAssignment(assignmentId, artifacts, statusReason, actor, c
         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.
@@ -332,9 +371,7 @@ export function integrateLaneResults(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const actor = options.agent ?? 'coordinator';
     const result = { integrated: [], 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))
@@ -455,16 +492,224 @@ export function integrateLaneResults(options = {}) {
     }
     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.
@@ -481,7 +726,16 @@ export function runHarvestLane(assignmentId, options = {}) {
         }
         const dry = options.dryRun ? ' (dry-run)' : '';
         if (integ.integrated.length === 0 && integ.errors.length === 0) {
-            console.log(assignmentId ? `No LANE-RESULT.json to integrate for ${assignmentId}.` : 'No lane results to integrate.');
+            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) {
@@ -513,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) {