@indigoai-us/hq-cli 5.237.0 → 5.238.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [5.238.0] — 2026-09-27
+
+### Added: Lane orphan reporting
+
+- `hq lanes checks` includes an orphaned-lane check. The company-scoped
+  `hq lanes orphans` report lists candidates without changing their state. Add
+  `--stop --reason <text>` to stop candidates that remain orphaned on recheck
+  and record the reason in lane history.
+
 ## [5.237.0] — 2026-09-27
 
 ### Added

package/dist/command-catalog.generated.d.ts

@@ -7300,6 +7300,33 @@ export declare const COMMAND_CATALOG: readonly [{
         }, {
             readonly flags: "--project <slug>";
             readonly description: "Limit checks to one company project";
+        }, {
+            readonly flags: "--min-age <minutes>";
+            readonly description: "Minimum orphan lane age in minutes (default: 30)";
+        }, {
+            readonly flags: "--json";
+            readonly description: "JSON on stdout (always)";
+        }];
+        readonly subcommands: readonly [];
+    }, {
+        readonly name: "orphans";
+        readonly description: "Report lanes whose lane or session senior has ended";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options]";
+        readonly arguments: readonly [];
+        readonly options: readonly [{
+            readonly flags: "--company <slug>";
+            readonly description: "Select the company by slug";
+        }, {
+            readonly flags: "--min-age <minutes>";
+            readonly description: "Minimum orphan lane age in minutes (default: 30)";
+        }, {
+            readonly flags: "--stop";
+            readonly description: "Stop the reported lanes through their normal owner path";
+        }, {
+            readonly flags: "--reason <text>";
+            readonly description: "Required audit reason when --stop is set";
         }, {
             readonly flags: "--json";
             readonly description: "JSON on stdout (always)";
@@ -8159,6 +8186,9 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly variadic: false;
         }];
         readonly options: readonly [{
+            readonly flags: "--reason <text>";
+            readonly description: "Record the reason in the lane's terminal history";
+        }, {
             readonly flags: "--json";
             readonly description: "JSON on stdout (always)";
         }];

package/dist/command-catalog.generated.js

@@ -9436,6 +9436,41 @@ export const COMMAND_CATALOG = [
                         "flags": "--project <slug>",
                         "description": "Limit checks to one company project"
                     },
+                    {
+                        "flags": "--min-age <minutes>",
+                        "description": "Minimum orphan lane age in minutes (default: 30)"
+                    },
+                    {
+                        "flags": "--json",
+                        "description": "JSON on stdout (always)"
+                    }
+                ],
+                "subcommands": []
+            },
+            {
+                "name": "orphans",
+                "description": "Report lanes whose lane or session senior has ended",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options]",
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--company <slug>",
+                        "description": "Select the company by slug"
+                    },
+                    {
+                        "flags": "--min-age <minutes>",
+                        "description": "Minimum orphan lane age in minutes (default: 30)"
+                    },
+                    {
+                        "flags": "--stop",
+                        "description": "Stop the reported lanes through their normal owner path"
+                    },
+                    {
+                        "flags": "--reason <text>",
+                        "description": "Required audit reason when --stop is set"
+                    },
                     {
                         "flags": "--json",
                         "description": "JSON on stdout (always)"
@@ -10555,6 +10590,10 @@ export const COMMAND_CATALOG = [
                     }
                 ],
                 "options": [
+                    {
+                        "flags": "--reason <text>",
+                        "description": "Record the reason in the lane's terminal history"
+                    },
                     {
                         "flags": "--json",
                         "description": "JSON on stdout (always)"

package/dist/commands/lanes-checks.d.ts

@@ -6,6 +6,8 @@ export interface LaneChecksDeps {
     resolveCompany: (company?: string) => Promise<LaneCompanyRef>;
     trackerEnabled: (company: LaneCompanyRef) => boolean | Promise<boolean>;
     now: () => Date;
+    stopLane?: (laneId: string, reason: string) => Promise<void>;
+    sessionState?: (root: string, sessionId: string, now: Date) => string | null;
 }
 type WrapHandler = <Args extends unknown[]>(action: (...args: Args) => Promise<void>) => (...args: Args) => Promise<void>;
 export interface ProjectMapping {

package/dist/commands/lanes-checks.js

@@ -6,6 +6,9 @@ import { LanesError, isLanesError } from "../lib/lanes/errors.js";
 import { evaluateTrackerChecks } from "../lib/lanes/tracker-checks.js";
 import { LANE_STORE_UPGRADE_COMMAND, isLaneStoreVersionNewer, laneRecordPath, listLaneIds, listQuestionIds, questionRecordPath, readLane, readQuestion } from "../lib/lanes/store.js";
 import { createLocalTrackerStore } from "../lib/lanes/tracker-store.js";
+import { sessionLiveness } from "../lib/lanes/liveness.js";
+import { findOrphanLanes, parseOrphanMinAge } from "../lib/lanes/orphans.js";
+import { assertNoSecretText } from "../lib/lanes/text-scan.js";
 import { LANES_TRACKER_FLAG } from "./lanes-tracker.js";
 function fail(error, message, details = {}) {
     throw new LanesError(error, message, details);
@@ -320,6 +323,47 @@ function readScopedLanes(root, company, projects) {
         return [readLane(root, id)];
     });
 }
+function readCompanyLanes(root, company, projectId) {
+    return listLaneIds(root).flatMap((id) => {
+        const file = laneRecordPath(root, id);
+        const metadata = readJsonObject(file);
+        if (metadata === null)
+            return fail("tracker_checks_input_unreadable", "Lane record could not be read while checking its scope", { path: file });
+        const laneCompany = isObject(metadata.company) ? metadata.company : null;
+        if (laneCompany?.slug !== company.slug || laneCompany.uid !== company.uid)
+            return [];
+        if (projectId !== undefined && !laneMetadataMatchesScope(metadata, company, new Set([projectId])))
+            return [];
+        return [readLane(root, id)];
+    });
+}
+function orphanSessionState(root, sessionId, now, deps) {
+    if (deps.sessionState)
+        return deps.sessionState(root, sessionId, now);
+    return sessionLiveness(root, sessionId, { nowMs: now.getTime() });
+}
+function orphanFindings(root, company, now, minAgeMinutes, deps, projectId) {
+    const candidates = readCompanyLanes(root, company, projectId);
+    const lanes = [...candidates];
+    const known = new Set(lanes.map((lane) => lane.lane_id));
+    for (const candidate of candidates) {
+        if (candidate.senior.kind !== "lane" || candidate.senior.id === undefined || known.has(candidate.senior.id))
+            continue;
+        const file = laneRecordPath(root, candidate.senior.id);
+        const metadata = readJsonObject(file, "empty");
+        const laneCompany = metadata && isObject(metadata.company) ? metadata.company : null;
+        if (laneCompany?.slug !== company.slug || laneCompany.uid !== company.uid)
+            continue;
+        lanes.push(readLane(root, candidate.senior.id));
+        known.add(candidate.senior.id);
+    }
+    return findOrphanLanes({
+        lanes,
+        now,
+        minAgeMinutes,
+        sessionState: (sessionId, at) => orphanSessionState(root, sessionId, at, deps),
+    }).filter((finding) => candidates.some((lane) => lane.lane_id === finding.lane_id));
+}
 function sameCompanyLane(lane, company) {
     return lane.company?.slug === company.slug && lane.company.uid === company.uid;
 }
@@ -573,7 +617,7 @@ export async function resolveTrackerCompany(deps, requested) {
     }
     return company;
 }
-async function checkReport(root, company, projects, directiveProjects, projectFilter, now) {
+async function checkReport(root, company, projects, directiveProjects, projectFilter, minAgeMinutes, now, deps) {
     const selectedProjects = [...projects.values()];
     const laneRecords = readScopedLanes(root, company, selectedProjects);
     const warnings = laneRecords.flatMap((lane) => {
@@ -602,39 +646,113 @@ async function checkReport(root, company, projects, directiveProjects, projectFi
         team: project.team,
         ...(project.leadLaneId === undefined ? {} : { lead_lane_id: project.leadLaneId }),
     }));
+    const checks = evaluateTrackerChecks({
+        now,
+        thresholds: loadLanesConfig(root).tracker.checks,
+        questions: questionRecords,
+        teams,
+        ...trackerRecords,
+        directives: trackerRecords.directives,
+        directive_teams: directiveTeams,
+    });
+    const orphanedLanes = orphanFindings(root, company, now, minAgeMinutes, deps, projectFilter);
+    checks.push({
+        id: "orphaned_lane",
+        result: orphanedLanes.length === 0 ? "ok" : "failing",
+        items: orphanedLanes.map((finding) => ({
+            id: finding.lane_id,
+            reason: finding.senior_state === "missing" ? "missing_senior" :
+                finding.senior_state === "ended" ? "ended_session_senior" : "terminal_senior",
+            senior: finding.senior,
+            senior_state: finding.senior_state,
+            age_minutes: finding.age_minutes,
+            account: finding.account,
+            host: finding.host,
+        })),
+    });
     return {
         ok: true,
         company: company.slug,
         generated_at: now.toISOString(),
         ...(warnings.length === 0 ? {} : { warnings }),
-        checks: evaluateTrackerChecks({
-            now,
-            thresholds: loadLanesConfig(root).tracker.checks,
-            questions: questionRecords,
-            teams,
-            ...trackerRecords,
-            directives: trackerRecords.directives,
-            directive_teams: directiveTeams,
-        }),
+        checks,
     };
 }
+async function orphanReport(root, company, now, minAgeMinutes, deps, options) {
+    const reason = options.reason?.trim();
+    if (options.stop && !reason) {
+        fail("orphan_stop_reason_required", "--stop requires a non-empty --reason", {});
+    }
+    if (!options.stop && options.reason !== undefined) {
+        fail("orphan_reason_requires_stop", "--reason can only be used with --stop", {});
+    }
+    if (reason !== undefined)
+        assertNoSecretText("stop reason", reason);
+    const orphans = orphanFindings(root, company, now, minAgeMinutes, deps);
+    if (!options.stop) {
+        console.log(JSON.stringify({
+            ok: true,
+            action: "orphans",
+            company: company.slug,
+            generated_at: now.toISOString(),
+            min_age_minutes: minAgeMinutes,
+            orphans,
+        }, null, 2));
+        return;
+    }
+    if (!deps.stopLane)
+        fail("orphan_stop_unavailable", "The normal lane stop path is unavailable", {});
+    const stopped = [];
+    for (const finding of orphans) {
+        const fresh = orphanFindings(root, company, deps.now(), minAgeMinutes, deps)
+            .find((candidate) => candidate.lane_id === finding.lane_id);
+        if (!fresh)
+            continue;
+        await deps.stopLane(finding.lane_id, reason);
+        stopped.push({ lane_id: finding.lane_id, state: readLane(root, finding.lane_id).state });
+    }
+    console.log(JSON.stringify({
+        ok: true,
+        action: "orphans.stop",
+        company: company.slug,
+        generated_at: now.toISOString(),
+        min_age_minutes: minAgeMinutes,
+        reason,
+        orphans,
+        stopped,
+    }, null, 2));
+}
 export function registerLaneChecksCommand(parent, deps, wrap) {
     parent.command("checks")
         .description("Evaluate tracker and lane health checks")
         .option("--company <slug>", "Select the company by slug")
         .option("--project <slug>", "Limit checks to one company project")
+        .option("--min-age <minutes>", "Minimum orphan lane age in minutes (default: 30)")
         .action(wrap(async (options) => {
         const company = await resolveTrackerCompany(deps, options.company);
         const root = deps.hqRoot();
         const projectFilter = options.project === undefined ? undefined : validSegment(options.project, "project");
+        const minAgeMinutes = parseOrphanMinAge(options.minAge);
         const projects = loadProjectMappings(root, company.slug, projectFilter);
         const directiveProjects = projectFilter === undefined
             ? projects
             : loadProjectMappings(root, company.slug);
-        const report = await checkReport(root, company, projects, directiveProjects, projectFilter, deps.now());
+        const report = await checkReport(root, company, projects, directiveProjects, projectFilter, minAgeMinutes, deps.now(), deps);
         console.log(JSON.stringify(report, null, 2));
         if (report.checks.some((item) => item.result === "failing"))
             process.exitCode = 2;
     }));
+    parent.command("orphans")
+        .description("Report lanes whose lane or session senior has ended")
+        .option("--company <slug>", "Select the company by slug")
+        .option("--min-age <minutes>", "Minimum orphan lane age in minutes (default: 30)")
+        .option("--stop", "Stop the reported lanes through their normal owner path")
+        .option("--reason <text>", "Required audit reason when --stop is set")
+        .action(wrap(async (options) => {
+        const company = await deps.resolveCompany(options.company);
+        const root = deps.hqRoot();
+        const minAgeMinutes = parseOrphanMinAge(options.minAge);
+        await orphanReport(root, company, deps.now(), minAgeMinutes, deps, options);
+    }));
 }
 //# sourceMappingURL=lanes-checks.js.map

package/dist/commands/lanes.js

@@ -3462,6 +3462,10 @@ function outpostRejectedFailedResumeOption(result) {
     return result.exitCode !== 0 &&
         /unknown option\s+(?:['"])?--(?:from-failed|failed-resume-context)(?:['"])?(?:\s|$)/i.test(`${result.stderr}\n${result.stdout}`);
 }
+function outpostRejectedStopReasonOption(result) {
+    return result.exitCode !== 0 &&
+        /unknown option\s+(?:['"])?--reason(?:['"])?(?:\s|$)/i.test(`${result.stderr}\n${result.stdout}`);
+}
 function verifyOutpostProfileContent(hqRoot, lane) {
     if (lane.host.kind !== "outpost" || lane.worker_profile === undefined)
         return;
@@ -7635,7 +7639,7 @@ async function readOutpostTerminalLane(ctx, laneId, outpostId, stopCommandId) {
         commandId,
     };
 }
-async function dispatchOutpostLaneStop(ctx, lane) {
+async function dispatchOutpostLaneStop(ctx, lane, reason, quiet = false) {
     if (lane.host.kind !== "outpost") {
         throw new LanesError("outpost_dispatch_failed", `Lane ${lane.lane_id} has no Outpost host to dispatch stop to`, { lane_id: lane.lane_id });
     }
@@ -7644,7 +7648,7 @@ async function dispatchOutpostLaneStop(ctx, lane) {
     try {
         dispatched = await ctx.dispatchOutpostExec({
             outpostId,
-            command: buildOutpostLaneCommand({ action: "stop", laneId: lane.lane_id }),
+            command: buildOutpostLaneCommand({ action: "stop", laneId: lane.lane_id, reason }),
             timeoutSeconds: 120,
             waitMs: 120_000,
         });
@@ -7652,6 +7656,13 @@ async function dispatchOutpostLaneStop(ctx, lane) {
     catch (err) {
         throw new LanesError("outpost_dispatch_failed", `Could not dispatch stop for lane ${lane.lane_id} to Outpost ${outpostId}: ${dispatchErrorMessage(err)}`, { lane_id: lane.lane_id, outpost_id: outpostId });
     }
+    if (reason !== undefined && outpostRejectedStopReasonOption(dispatched)) {
+        throw new LanesError("outpost_cli_upgrade_required", `Outpost ${outpostId} needs an hq-cli release containing stop reason support before it can stop lane ${lane.lane_id}`, {
+            lane_id: lane.lane_id,
+            outpost_id: outpostId,
+            required_option: "--reason",
+        });
+    }
     const ownerError = ownerErrorFromOutput(dispatched.stdout);
     if (ownerError) {
         throw new LanesError("outpost_dispatch_failed", `Outpost ${outpostId} rejected the stop command: ${ownerError.message}`, {
@@ -7742,27 +7753,34 @@ async function dispatchOutpostLaneStop(ctx, lane) {
         cancelledQuestions = parseRemoteCancelledQuestionIds(remote.cancelled_questions, lane.lane_id, outpostId, commandId);
     }
     const updated = syncLaneRecordFromOwner(ctx.hqRoot(), lane.lane_id, outpostId, ownerLane);
-    printJson({
-        ok: true,
-        action: "stop",
-        lane: updated,
-        cancelled_questions: cancelledQuestions,
-        outpost_id: outpostId,
-        outpost_command_id: commandId,
-        ...(syncCommandId ? { outpost_sync_command_id: syncCommandId } : {}),
-        outpost_result: {
-            state,
-            already_terminal: alreadyTerminal,
-            status: dispatched.status,
-            exit_code: dispatched.exitCode,
-        },
-    });
+    if (!quiet)
+        printJson({
+            ok: true,
+            action: "stop",
+            lane: updated,
+            cancelled_questions: cancelledQuestions,
+            outpost_id: outpostId,
+            outpost_command_id: commandId,
+            ...(syncCommandId ? { outpost_sync_command_id: syncCommandId } : {}),
+            outpost_result: {
+                state,
+                already_terminal: alreadyTerminal,
+                status: dispatched.status,
+                exit_code: dispatched.exitCode,
+            },
+        });
 }
-async function runStop(ctx, laneId) {
+async function runStop(ctx, laneId, reason, quiet = false) {
+    const operatorReason = reason?.trim();
+    if (reason !== undefined && !operatorReason) {
+        throw new LanesError("lane_stop_reason_invalid", "Stop reason must not be empty", {});
+    }
+    if (operatorReason !== undefined)
+        assertNoSecretText("stop reason", operatorReason);
     const hqRoot = ctx.hqRoot();
     const lane = readLane(hqRoot, laneId);
     if (lane.host.kind === "outpost" && !laneRunsHereForOperatorMutation(ctx, lane)) {
-        await dispatchOutpostLaneStop(ctx, lane);
+        await dispatchOutpostLaneStop(ctx, lane, operatorReason, quiet);
         return;
     }
     assertLaneRunsHereForOperatorMutation(ctx, lane, "stop");
@@ -7779,6 +7797,16 @@ async function runStop(ctx, laneId) {
             ...current,
             state: stopCommittedState(current.state),
             queued_reason: undefined,
+            ...(operatorReason === undefined ? {} : {
+                stop_history: [
+                    ...(current.stop_history ?? []),
+                    { at, reason: operatorReason },
+                ],
+                terminal_details: {
+                    ...(current.terminal_details ?? {}),
+                    operator_reason: operatorReason,
+                },
+            }),
         };
     });
     if (updated.state === "killed") {
@@ -7790,12 +7818,13 @@ async function runStop(ctx, laneId) {
     }
     await emitLaneTerminalStateSoft(ctx, updated);
     const cancelled = cancelPendingQuestionsForLane(hqRoot, laneId, at);
-    printJson({
-        ok: true,
-        action: "stop",
-        lane: updated,
-        cancelled_questions: cancelled.map((q) => q.question_id),
-    });
+    if (!quiet)
+        printJson({
+            ok: true,
+            action: "stop",
+            lane: updated,
+            cancelled_questions: cancelled.map((q) => q.question_id),
+        });
 }
 async function runAsk(ctx, opts) {
     const hqRoot = ctx.hqRoot();
@@ -9206,6 +9235,12 @@ export function registerLanesCommand(parent, deps = {}) {
         resolveCompany: ctx.resolveCompany,
         trackerEnabled: ctx.laneTrackerEnabled,
         now: ctx.now,
+        stopLane: (laneId, reason) => runStop(ctx, laneId, reason, true),
+        sessionState: (root, sessionId, now) => sessionLiveness(root, sessionId, {
+            nowMs: now.getTime(),
+            presenceConnected: ctx.presenceConnected ?? false,
+            deps: ctx.livenessDeps,
+        }),
     }, wrap);
     registerLaneReportCommands(lanes, {
         hqRoot: ctx.hqRoot,
@@ -9542,8 +9577,9 @@ export function registerLanesCommand(parent, deps = {}) {
         .command("stop")
         .description("Cancel a queued lane or kill a running one")
         .argument("<lane-id>", "Lane id")
-        .action(wrap(async (laneId) => {
-        await runStop(ctx, laneId);
+        .option("--reason <text>", "Record the reason in the lane's terminal history")
+        .action(wrap(async (laneId, options) => {
+        await runStop(ctx, laneId, options.reason);
     }));
     lanes
         .command("ask")

package/dist/lib/lanes/orphans.d.ts

@@ -0,0 +1,18 @@
+import { type LaneRecord, type SeniorRef } from "./types.js";
+export declare const DEFAULT_ORPHAN_MIN_AGE_MINUTES = 30;
+export interface OrphanLaneFinding {
+    lane_id: string;
+    senior: SeniorRef;
+    senior_state: string;
+    age_minutes: number;
+    account: string | null;
+    host: LaneRecord["host"];
+}
+export declare function parseOrphanMinAge(value: string | undefined): number;
+export declare function findOrphanLanes(input: {
+    lanes: readonly LaneRecord[];
+    now: Date;
+    minAgeMinutes: number;
+    sessionState: (sessionId: string, now: Date) => string | null;
+}): OrphanLaneFinding[];
+//# sourceMappingURL=orphans.d.ts.map

package/dist/lib/lanes/orphans.js

@@ -0,0 +1,67 @@
+import { LanesError } from "./errors.js";
+import { isTerminalLaneState } from "./types.js";
+export const DEFAULT_ORPHAN_MIN_AGE_MINUTES = 30;
+const LIVE_LANE_STATES = new Set(["running", "queued", "blocked", "awaiting_input"]);
+export function parseOrphanMinAge(value) {
+    if (value === undefined)
+        return DEFAULT_ORPHAN_MIN_AGE_MINUTES;
+    if (!/^(0|[1-9]\d*)$/.test(value)) {
+        throw new LanesError("orphan_min_age_invalid", "Minimum orphan age must be a non-negative whole number of minutes", { value });
+    }
+    const minutes = Number(value);
+    if (!Number.isSafeInteger(minutes) || minutes > Math.floor(Number.MAX_SAFE_INTEGER / 60_000)) {
+        throw new LanesError("orphan_min_age_invalid", "Minimum orphan age is outside the supported range", { value });
+    }
+    return minutes;
+}
+export function findOrphanLanes(input) {
+    const nowMs = input.now.getTime();
+    if (!Number.isFinite(nowMs)) {
+        throw new LanesError("orphan_clock_invalid", "Current time for orphan detection is invalid", {});
+    }
+    const byId = new Map(input.lanes.map((lane) => [lane.lane_id, lane]));
+    const minAgeMs = input.minAgeMinutes * 60_000;
+    const findings = [];
+    for (const lane of input.lanes) {
+        if (!LIVE_LANE_STATES.has(lane.state))
+            continue;
+        if (lane.keep_alive_standing === true || lane.senior.kind === "user")
+            continue;
+        const createdAt = Date.parse(lane.created_at);
+        if (!Number.isFinite(createdAt)) {
+            throw new LanesError("orphan_lane_timestamp_invalid", `Lane ${lane.lane_id} has an invalid created_at timestamp`, { lane_id: lane.lane_id, field: "created_at" });
+        }
+        const ageMs = nowMs - createdAt;
+        if (ageMs < 0) {
+            throw new LanesError("orphan_lane_timestamp_future", `Lane ${lane.lane_id} was created after the current time`, { lane_id: lane.lane_id, created_at: lane.created_at });
+        }
+        if (ageMs < minAgeMs)
+            continue;
+        let seniorState;
+        if (lane.senior.kind === "lane") {
+            const senior = byId.get(lane.senior.id ?? "");
+            if (!senior) {
+                seniorState = "missing";
+            }
+            else if (isTerminalLaneState(senior.state)) {
+                seniorState = senior.state;
+            }
+        }
+        else if (lane.senior.kind === "session" && lane.senior.id !== undefined) {
+            if (input.sessionState(lane.senior.id, input.now) === "ended")
+                seniorState = "ended";
+        }
+        if (seniorState === undefined)
+            continue;
+        findings.push({
+            lane_id: lane.lane_id,
+            senior: { ...lane.senior },
+            senior_state: seniorState,
+            age_minutes: Math.floor(ageMs / 60_000),
+            account: lane.account ?? null,
+            host: { ...lane.host },
+        });
+    }
+    return findings.sort((a, b) => b.age_minutes - a.age_minutes || a.lane_id.localeCompare(b.lane_id));
+}
+//# sourceMappingURL=orphans.js.map

package/dist/lib/lanes/store.js

@@ -591,6 +591,24 @@ export function parseLaneRecord(raw, filePath) {
             path: filePath,
         });
     }
+    if (raw.stop_history !== undefined) {
+        if (!Array.isArray(raw.stop_history)) {
+            throw new LaneSchemaError("stop_history must be an array when present", {
+                path: filePath,
+                field: "stop_history",
+            });
+        }
+        for (const [index, entry] of raw.stop_history.entries()) {
+            const field = `stop_history[${index}]`;
+            if (!isPlainObject(entry) || Object.keys(entry).some((key) => !["at", "reason"].includes(key))) {
+                throw new LaneSchemaError(`${field} must be a stop history entry`, { path: filePath, field });
+            }
+            if (typeof entry.reason !== "string" || entry.reason.trim() === "") {
+                throw new LaneSchemaError(`${field}.reason must be a non-empty string`, { path: filePath, field });
+            }
+            requireTimestamp(entry.at, `${field}.at`, filePath);
+        }
+    }
     if (raw.worker_profile_repin_history !== undefined) {
         if (!Array.isArray(raw.worker_profile_repin_history)) {
             throw new LaneSchemaError("worker_profile_repin_history must be an array when present", {
@@ -907,6 +925,11 @@ export function mergeLaneRecords(live, sidecars) {
                 failed_resume_history: unionHistory(all.map((record) => record.failed_resume_history ?? []), entryIdentity, base.failed_resume_history ?? []),
             }
             : {}),
+        ...(all.some((record) => record.stop_history !== undefined)
+            ? {
+                stop_history: unionHistory(all.map((record) => record.stop_history ?? []), entryIdentity, base.stop_history ?? []),
+            }
+            : {}),
         stories: mergeLaneStories(all, base),
     };
 }

package/dist/lib/lanes/story-ledger.js

@@ -473,12 +473,16 @@ function setLaneEntry(story, lane, laneState, laneStoryStatus, prs, pendingQuest
         item.terminal === true);
     const stateChanged = oldState !== laneState;
     if (stateChanged || (terminal && !alreadyRecorded)) {
+        const operatorReason = lane.terminal_details?.operator_reason;
         history.push({
             lane_id: lane.lane_id,
             state: laneState,
             at,
             prs,
             ...(terminal ? { terminal: true } : {}),
+            ...(terminal && typeof operatorReason === "string" && operatorReason.trim() !== ""
+                ? { reason: operatorReason }
+                : {}),
         });
     }
     const entry = {

package/dist/lib/lanes/tracker-checks.d.ts

@@ -69,7 +69,7 @@ export interface TrackerCheckFinding {
     [key: string]: unknown;
 }
 export interface TrackerCheckResult {
-    id: "questions" | "lead_lanes" | "freshness" | "blockers" | "kpis" | "directives";
+    id: "questions" | "lead_lanes" | "freshness" | "blockers" | "kpis" | "directives" | "orphaned_lane";
     result: "ok" | "failing";
     items: TrackerCheckFinding[];
 }

package/dist/lib/lanes/types.d.ts

@@ -283,6 +283,10 @@ export interface SeniorHistoryEntry {
     by: string;
     reason: string;
 }
+export interface LaneStopHistoryEntry {
+    at: string;
+    reason: string;
+}
 /** Evidence for a senior-authorized Outpost worker-profile content re-pin. */
 export interface WorkerProfileRepinHistoryEntry {
     old_hash: string | null;
@@ -469,6 +473,8 @@ export interface LaneRecord {
     /** Set when the reconcile pass force-admits under the starvation bound. */
     admitted_reason?: string;
     terminal_reason?: string;
+    /** Reasons supplied to explicit stop commands, retained independently of optional project ledgers. */
+    stop_history?: LaneStopHistoryEntry[];
     /** Classification time when this lane entered interrupted; stable across later metadata writes. */
     interrupted_at?: string;
     /**

package/dist/lib/lanes/types.js

@@ -230,7 +230,7 @@ export const LANE_FIELD_WRITERS = {
     last_envelope: ["watcher", "reconcile"], model: ["creator", "spawn", "command"], model_source: ["creator", "spawn", "command"], effort: ["creator", "spawn", "command"], effort_source: ["creator", "spawn", "command"], fast_mode: ["spawn"],
     last_message_at: ["command"], last_compaction: ["spawn"], story_complete: ["watcher", "reconcile"], story_complete_reason: ["watcher", "reconcile"], story_status: ["watcher", "reconcile"],
     overdue: ["reconcile"], overdue_at: ["reconcile"], last_host_report_at: ["watcher", "spawn", "reconcile"], stalled: ["watcher"], stalled_at: ["watcher"], stalled_reason: ["watcher"],
-    admitted_reason: ["command", "reconcile"], terminal_reason: ["command", "watcher", "spawn", "reconcile"], interrupted_at: ["watcher", "reconcile"], terminal_details: ["command", "spawn", "watcher", "reconcile"],
+    admitted_reason: ["command", "reconcile"], terminal_reason: ["command", "watcher", "spawn", "reconcile"], stop_history: ["command"], interrupted_at: ["watcher", "reconcile"], terminal_details: ["command", "spawn", "watcher", "reconcile"],
     quota_reset_at: ["watcher", "reconcile"], model_quota_marker: ["watcher", "reconcile"], outpost_command_id: ["command"],
     provider_session_id: ["watcher", "command", "spawn"], provider_session_id_absent: ["watcher", "command"], provider_home_at_spawn: ["spawn"], last_resume: ["spawn"], last_run_usage: ["watcher"], envelope_repair: ["watcher", "reconcile"], envelope_validation_errors: ["watcher"], last_progress_event_at: ["watcher"],
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.237.0",
+  "version": "5.238.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {