@indigoai-us/hq-cli 5.126.0 → 5.127.0

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

@@ -7,6 +7,158 @@ export declare const LANE_SCHEMA_VERSION: "hq-lane.v1";
 export declare const QUESTION_SCHEMA_VERSION: "hq-lane-question.v1";
 export declare const ENVELOPE_SCHEMA_VERSION: "hq-lane-envelope.v1";
 export declare const CONFIG_SCHEMA_VERSION: "hq-lanes-config.v1";
+/**
+ * The envelope contract as a JSON schema. `parseLaneEnvelope` is the runtime
+ * check; this is the text handed to a worker on the repair turn (spec §4) so
+ * the two never drift apart in what they name.
+ */
+export declare const LANE_ENVELOPE_JSON_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly title: "hq-lane-envelope.v1";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["schema_version", "decision", "summary", "story_status", "artifacts"];
+    readonly properties: {
+        readonly schema_version: {
+            readonly const: "hq-lane-envelope.v1";
+        };
+        readonly decision: {
+            readonly enum: readonly ["done", "ask", "blocked"];
+        };
+        readonly summary: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly questions: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["question", "context", "options"];
+                readonly properties: {
+                    readonly question: {
+                        readonly type: "string";
+                    };
+                    readonly context: {
+                        readonly type: "string";
+                    };
+                    readonly options: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly recommended: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+        readonly story_status: {
+            readonly enum: readonly ["queued", "in_progress", "review", "done"];
+        };
+        readonly artifacts: {
+            readonly type: "array";
+        };
+        readonly blocked_reason: {
+            readonly type: "string";
+        };
+        readonly story_complete: {
+            readonly type: "boolean";
+        };
+        readonly story_complete_reason: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+    };
+    readonly allOf: readonly [{
+        readonly if: {
+            readonly properties: {
+                readonly decision: {
+                    readonly const: "ask";
+                };
+            };
+        };
+        readonly then: {
+            readonly required: readonly ["questions"];
+            readonly properties: {
+                readonly questions: {
+                    readonly minItems: 1;
+                };
+            };
+        };
+        readonly else: {
+            readonly not: {
+                readonly required: readonly ["questions"];
+            };
+        };
+    }, {
+        readonly if: {
+            readonly properties: {
+                readonly decision: {
+                    readonly const: "blocked";
+                };
+            };
+        };
+        readonly then: {
+            readonly required: readonly ["blocked_reason"];
+            readonly properties: {
+                readonly blocked_reason: {
+                    readonly minLength: 1;
+                };
+            };
+        };
+        readonly else: {
+            readonly not: {
+                readonly required: readonly ["blocked_reason"];
+            };
+        };
+    }, {
+        readonly if: {
+            readonly required: readonly ["story_complete"];
+            readonly properties: {
+                readonly story_complete: {
+                    readonly const: true;
+                };
+            };
+        };
+        readonly then: {
+            readonly required: readonly ["story_complete_reason"];
+            readonly properties: {
+                readonly story_status: {
+                    readonly const: "done";
+                };
+                readonly story_complete_reason: {
+                    readonly minLength: 1;
+                };
+            };
+        };
+        readonly else: {
+            readonly if: {
+                readonly required: readonly ["story_complete"];
+            };
+            readonly then: {
+                readonly required: readonly ["story_complete_reason"];
+                readonly properties: {
+                    readonly story_status: {
+                        readonly not: {
+                            readonly const: "done";
+                        };
+                    };
+                    readonly story_complete_reason: {
+                        readonly minLength: 1;
+                    };
+                };
+            };
+            readonly else: {
+                readonly not: {
+                    readonly required: readonly ["story_complete_reason"];
+                };
+            };
+        };
+    }];
+    readonly description: string;
+};
 export declare const LANE_STATES: readonly ["queued", "running", "awaiting_input", "blocked", "done", "failed", "interrupted", "cancelled", "killed"];
 export type LaneState = (typeof LANE_STATES)[number];
 /** Exact terminal set from spec §6.7. `awaiting_input` and `blocked` are not terminal. */
@@ -14,7 +166,7 @@ export declare const TERMINAL_LANE_STATES: readonly ["done", "failed", "interrup
 export type TerminalLaneState = (typeof TERMINAL_LANE_STATES)[number];
 export declare const LANE_PROVIDERS: readonly ["claude", "codex", "grok"];
 export type LaneProvider = (typeof LANE_PROVIDERS)[number];
-export declare const QUEUED_REASONS: readonly ["cap", "queue_position", "throttle"];
+export declare const QUEUED_REASONS: readonly ["cap", "queue_position", "throttle", "provider_binary_missing"];
 export type QueuedReason = (typeof QUEUED_REASONS)[number];
 export declare const HOST_KINDS: readonly ["local", "outpost"];
 export type HostKind = (typeof HOST_KINDS)[number];
@@ -24,6 +176,12 @@ export declare const ENVELOPE_DECISIONS: readonly ["done", "ask", "blocked"];
 export type EnvelopeDecision = (typeof ENVELOPE_DECISIONS)[number];
 export declare const STORY_STATUSES: readonly ["queued", "in_progress", "review", "done"];
 export type StoryStatus = (typeof STORY_STATUSES)[number];
+/**
+ * `expired` is accepted on read for records that already carry it. Spec §9
+ * ageing advances hop with `unanswered_timeout` and never expires a question,
+ * so reconcile (the only writer that may age without an operator) does not
+ * write this value. Kept in the enum so `--status expired` and old files parse.
+ */
 export declare const QUESTION_STATUSES: readonly ["pending", "answered", "cancelled", "expired"];
 export type QuestionStatus = (typeof QUESTION_STATUSES)[number];
 export declare const RAISED_VIA: readonly ["cli", "envelope"];
@@ -82,7 +240,8 @@ export interface LastEnvelopeRef {
 export interface LaneRecord {
     schema_version: typeof LANE_SCHEMA_VERSION | string;
     lane_id: string;
-    company: LaneCompanyRef;
+    /** `null` is a core/personal lane (spec §6.2 / §10). Not an empty slug. */
+    company: LaneCompanyRef | null;
     project_id: string;
     story_id: string;
     thread_id?: string;
@@ -93,14 +252,159 @@ export interface LaneRecord {
     queued_reason?: QueuedReason;
     priority: number;
     worker?: string;
+    /** Registry-relative directory of the resolved worker, when --worker was set. */
+    worker_path?: string;
+    /** Package name when the worker's realpath is under core/packages. */
+    worker_pack?: string;
     provider: LaneProvider;
     account?: string;
     host: LaneHost;
+    /**
+     * Creating machine's identity when `host.kind` is `outpost` (spec §5.2).
+     * Distinct from `host`, which names where the lane is meant to run.
+     */
+    origin_host?: string;
+    /** How `origin_host` was resolved. Required to compare like-with-like. */
+    origin_host_source?: "imds" | "hostname";
     version: number;
     created_at: string;
     updated_at: string;
     attribution_history: AttributionHistoryEntry[];
     last_envelope?: LastEnvelopeRef;
+    /** Effective model id recorded at create/spawn. Omitted when the provider chooses. */
+    model?: string;
+    /** Effective effort level passed to the provider at the last spawn (effort.ts). */
+    effort?: string;
+    /** Where `effort` came from. `cli` pins it across later spawns. */
+    effort_source?: "cli" | "account" | "provider" | "default_rule" | "none";
+    /** Time of the last operator message accepted for this lane. Drives compaction. */
+    last_message_at?: string;
+    /** Last automatic compaction of a resumed session (compaction.ts). */
+    last_compaction?: LaneCompactionRecord;
+    /**
+     * Copied from the last ingested envelope. Omitted when no envelope has
+     * been ingested — absence is not false.
+     */
+    story_complete?: boolean;
+    story_complete_reason?: string;
+    /** Copied from the last ingested envelope when present. */
+    story_status?: StoryStatus;
+    /** Set by the reconcile pass when `--timeout` has passed (spec §5.7). */
+    overdue?: boolean;
+    overdue_at?: string;
+    /** Executing-host heartbeat; stale values mean the host stopped reporting. */
+    last_host_report_at?: string;
+    /**
+     * Set by the watcher when a running worker has made no tool call and
+     * produced no output for the silence window; cleared on the next progress
+     * signal or terminal write. Not a verdict: a long single tool call looks
+     * the same as a hang. See watcher.ts.
+     */
+    stalled?: boolean;
+    stalled_at?: string;
+    stalled_reason?: string;
+    /** Set when the reconcile pass force-admits under the starvation bound. */
+    admitted_reason?: string;
+    terminal_reason?: string;
+    /**
+     * Structured detail behind a named `terminal_reason` (dispatch, pickup and
+     * spawn failures), or the missing-binary search path behind
+     * `provider_binary_missing`. Written by the command and spawn writers.
+     */
+    terminal_details?: Record<string, unknown>;
+    /** SSM command id of the `hq outposts exec` pickup that started this lane. */
+    outpost_command_id?: string;
+    /**
+     * Provider reset time copied from a 429 result. Absent when the text
+     * named none. Distinct from the operator's account enabled switch.
+     */
+    quota_reset_at?: string;
+    /** Set when a 429 refused one model for credits, e.g. "needs credits for claude-fable-5-1". */
+    model_quota_marker?: string;
+    /**
+     * Provider session id parsed from the worker's own stdout when a resumable
+     * provider exits: Claude's JSON `result.session_id`, Codex's
+     * `thread.started.thread_id`. Absent when the provider has none or the
+     * output carried none; `provider_session_id_absent` names why. Never a
+     * guessed or path-derived value.
+     */
+    provider_session_id?: string;
+    provider_session_id_absent?: string;
+    /** Set at spawn when this run continued a recorded session instead of starting fresh. */
+    last_resume?: LaneResumeRecord;
+    /** Cache counters from the last exited run's result. Nothing else from the payload. */
+    last_run_usage?: LaneRunUsage;
+    /**
+     * Spec §4: one repair turn when the final output fails parseLaneEnvelope.
+     * Written by the watcher before the repair spawn, updated on the repair
+     * run's exit. Absent when every envelope this lane wrote parsed first time.
+     */
+    envelope_repair?: LaneEnvelopeRepair;
+    /** Last successful lane_progress mesh delivery, preserved across watcher restarts. */
+    last_progress_event_at?: string;
+}
+/** The v1 fields that must exist on every durable lane record (spec §3). */
+export declare const REQUIRED_LANE_RECORD_FIELDS: readonly ["schema_version", "lane_id", "company", "project_id", "story_id", "depth", "senior", "senior_history", "state", "priority", "provider", "host", "version", "created_at", "updated_at", "attribution_history"];
+export declare const LANE_WRITERS: readonly ["creator", "command", "watcher", "reconcile", "spawn"];
+export type LaneWriter = (typeof LANE_WRITERS)[number];
+/** Field ownership at the durable-record mutation boundary (spec §10.1). */
+export declare const LANE_FIELD_WRITERS: Readonly<Record<keyof LaneRecord, readonly LaneWriter[]>>;
+export interface LaneEnvelopeRepair {
+    /** False when the parse failed but no repair turn could run (see `skipped_reason`). */
+    attempted: boolean;
+    /**
+     * How the repair turn ran: `resume` continues the recorded session (claude,
+     * codex); `fresh_turn` is a new single-turn invocation carrying the raw
+     * output (grok). Absent when no repair ran.
+     */
+    mode?: "resume" | "fresh_turn";
+    succeeded: boolean;
+    first_error: string;
+    /** Parser error from the repair run's output, when that also failed. */
+    second_error?: string;
+    /** Why no repair turn ran: the provider cannot resume, or no session id was recorded. */
+    skipped_reason?: string;
+    /** Envelope slot the repair was asked to rewrite. */
+    envelope_ref?: string;
+    at: string;
+}
+export interface LaneResumeRecord {
+    session_id: string;
+    at: string;
+    trigger: "answered_questions" | "message" | "resume";
+    message_id?: string;
+    /**
+     * `hq lanes resume` only: the state the lane was in when the operator
+     * resumed it (`interrupted`, `done` or `blocked`) and the text they sent.
+     */
+    resumed_from?: "interrupted" | "done" | "blocked";
+    text?: string;
+}
+export interface LaneRunUsage {
+    cache_read_input_tokens: number | null;
+    cache_creation_input_tokens: number | null;
+}
+export interface LaneCompactionRecord {
+    at: string;
+    /** `claude_print_compact`: `claude -p --resume <sid> "/compact"` before the resume. */
+    mechanism: "claude_print_compact";
+    session_id: string;
+    /** `compacted` only when the session transcript gained a compact boundary. */
+    outcome: "compacted" | "no_effect" | "failed";
+    reason?: string;
+    duration_ms: number;
+    /** Milliseconds between the reference time and the resume that compacted. */
+    elapsed_ms: number;
+    /** `last_message_at`, or `created_at` when no message was ever sent. */
+    reference_at: string;
+    /** Context size the provider recorded at the compact boundary. */
+    pre_tokens: number | null;
+    /** Usage of the last run before compaction. */
+    before: LaneRunUsage | null;
+    /** Usage of the first run after compaction, once that run has exited. */
+    after: LaneRunUsage | null;
+    /** `last_resume.at` of the run that followed this compaction. */
+    resume_at?: string;
 }
 export interface QuestionBodyRef {
     store: QuestionBodyStore;
@@ -115,16 +419,27 @@ export interface RoutingHistoryEntry {
 }
 export interface QuestionAnswer {
     choice: string;
+    /** Whether the answer selected an offered option or supplied new text. */
+    answer_kind?: "option" | "freeform";
     notes_ref?: string;
     answered_by: string;
     answered_at: string;
     answered_level: number;
 }
+/**
+ * A question whose options amount to "continue" or "stop" the brief's own
+ * work. The brief already authorises finishing everything it lists, so such a
+ * question is flagged for the operator; nothing answers it automatically.
+ */
+export type QuestionKind = "continue";
 export interface QuestionRecord {
     schema_version: typeof QUESTION_SCHEMA_VERSION | string;
     question_id: string;
     lane_id: string;
-    company: LaneCompanyRef;
+    /** Set by the raiser when the options are only continue/stop. */
+    question_kind?: QuestionKind;
+    /** `null` when the originating lane has no company. */
+    company: LaneCompanyRef | null;
     project_id: string;
     story_id: string;
     thread_id?: string;
@@ -140,6 +455,8 @@ export interface QuestionRecord {
     body: QuestionBodyRef;
     routing_history: RoutingHistoryEntry[];
     answer?: QuestionAnswer;
+    /** Merge-on-read preservation of answers retained by conflict sidecars. */
+    answer_history?: QuestionAnswer[];
 }
 export interface EnvelopeQuestion {
     question: string;
@@ -155,17 +472,42 @@ export interface LaneEnvelope {
     story_status: StoryStatus;
     artifacts: unknown[];
     blocked_reason?: string;
+    story_complete?: boolean;
+    story_complete_reason?: string;
 }
 export interface AccountConfig {
     home: string;
     enabled: boolean;
     disabled_reason?: string;
     max_running?: number;
+    /** Default model for this account. Beats the provider default; beaten by --model. */
+    model?: string;
+    /** Default effort for this account. Beats the provider default; beaten by --effort. */
+    effort?: string;
 }
 export interface ProviderConfig {
     max_running: number;
     max_queued: number;
-    default_account: string;
+    /**
+     * Accepted and ignored for selection. Kept so existing config files parse.
+     * Account pick is least-loaded among enabled, logged-in accounts.
+     */
+    default_account?: string;
+    /** Default model for this provider when the account does not set one. */
+    model?: string;
+    /** Default effort for this provider when the account does not set one. */
+    effort?: string;
+    /**
+     * Resume-time compaction threshold: a resumed session whose last message is
+     * at least this old is compacted first. Absent means the one-hour default.
+     */
+    compact_after_ms?: number;
+    /**
+     * Watcher throttle for `lane_progress` thread events: at most one per this
+     * interval, and only on a tick that saw new tool activity or output. Absent
+     * means the five-minute default.
+     */
+    progress_event_min_interval_ms?: number;
     accounts: Record<string, AccountConfig>;
 }
 export interface ThrottleConfig {

package/dist/lib/lanes/types.js

@@ -8,6 +8,73 @@ export const LANE_SCHEMA_VERSION = "hq-lane.v1";
 export const QUESTION_SCHEMA_VERSION = "hq-lane-question.v1";
 export const ENVELOPE_SCHEMA_VERSION = "hq-lane-envelope.v1";
 export const CONFIG_SCHEMA_VERSION = "hq-lanes-config.v1";
+/**
+ * The envelope contract as a JSON schema. `parseLaneEnvelope` is the runtime
+ * check; this is the text handed to a worker on the repair turn (spec §4) so
+ * the two never drift apart in what they name.
+ */
+export const LANE_ENVELOPE_JSON_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    title: "hq-lane-envelope.v1",
+    type: "object",
+    additionalProperties: false,
+    required: ["schema_version", "decision", "summary", "story_status", "artifacts"],
+    properties: {
+        schema_version: { const: "hq-lane-envelope.v1" },
+        decision: { enum: ["done", "ask", "blocked"] },
+        summary: { type: "string", minLength: 1 },
+        questions: {
+            type: "array",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["question", "context", "options"],
+                properties: {
+                    question: { type: "string" },
+                    context: { type: "string" },
+                    options: { type: "array", items: { type: "string" } },
+                    recommended: { type: "string" },
+                },
+            },
+        },
+        story_status: { enum: ["queued", "in_progress", "review", "done"] },
+        artifacts: { type: "array" },
+        blocked_reason: { type: "string" },
+        story_complete: { type: "boolean" },
+        story_complete_reason: { type: "string", minLength: 1 },
+    },
+    allOf: [
+        {
+            if: { properties: { decision: { const: "ask" } } },
+            then: { required: ["questions"], properties: { questions: { minItems: 1 } } },
+            else: { not: { required: ["questions"] } },
+        },
+        {
+            if: { properties: { decision: { const: "blocked" } } },
+            then: { required: ["blocked_reason"], properties: { blocked_reason: { minLength: 1 } } },
+            else: { not: { required: ["blocked_reason"] } },
+        },
+        {
+            if: { required: ["story_complete"], properties: { story_complete: { const: true } } },
+            then: {
+                required: ["story_complete_reason"],
+                properties: { story_status: { const: "done" }, story_complete_reason: { minLength: 1 } },
+            },
+            else: {
+                if: { required: ["story_complete"] },
+                then: {
+                    required: ["story_complete_reason"],
+                    properties: { story_status: { not: { const: "done" } }, story_complete_reason: { minLength: 1 } },
+                },
+                else: { not: { required: ["story_complete_reason"] } },
+            },
+        },
+    ],
+    description: "questions is present and non-empty exactly when decision is ask. " +
+        "blocked_reason is present exactly when decision is blocked. " +
+        "story_complete true requires story_status done; story_complete false requires story_status other than done; " +
+        "story_complete_reason is required whenever story_complete is present.",
+};
 export const LANE_STATES = [
     "queued",
     "running",
@@ -28,7 +95,7 @@ export const TERMINAL_LANE_STATES = [
     "killed",
 ];
 export const LANE_PROVIDERS = ["claude", "codex", "grok"];
-export const QUEUED_REASONS = ["cap", "queue_position", "throttle"];
+export const QUEUED_REASONS = ["cap", "queue_position", "throttle", "provider_binary_missing"];
 export const HOST_KINDS = ["local", "outpost"];
 export const SENIOR_KINDS = ["session", "lane", "user"];
 export const ENVELOPE_DECISIONS = ["done", "ask", "blocked"];
@@ -38,6 +105,12 @@ export const STORY_STATUSES = [
     "review",
     "done",
 ];
+/**
+ * `expired` is accepted on read for records that already carry it. Spec §9
+ * ageing advances hop with `unanswered_timeout` and never expires a question,
+ * so reconcile (the only writer that may age without an operator) does not
+ * write this value. Kept in the enum so `--status expired` and old files parse.
+ */
 export const QUESTION_STATUSES = [
     "pending",
     "answered",
@@ -112,6 +185,29 @@ export function parseSeniorKind(value) {
         return value;
     throw new LanesError("unknown_senior_kind", `Unknown senior kind ${JSON.stringify(value)}. Accepted: ${SENIOR_KINDS.join(", ")}`, { accepted: [...SENIOR_KINDS], value });
 }
+/** The v1 fields that must exist on every durable lane record (spec §3). */
+export const REQUIRED_LANE_RECORD_FIELDS = [
+    "schema_version", "lane_id", "company", "project_id", "story_id", "depth",
+    "senior", "senior_history", "state", "priority", "provider", "host",
+    "version", "created_at", "updated_at", "attribution_history",
+];
+export const LANE_WRITERS = ["creator", "command", "watcher", "reconcile", "spawn"];
+/** Field ownership at the durable-record mutation boundary (spec §10.1). */
+export const LANE_FIELD_WRITERS = {
+    schema_version: ["creator"], lane_id: ["creator"], company: ["creator"],
+    project_id: ["command"], story_id: ["command"], thread_id: ["creator", "command"],
+    depth: ["command"], senior: ["command"], senior_history: ["command"],
+    state: ["creator", "command", "watcher", "reconcile", "spawn"], queued_reason: ["creator", "command", "spawn", "reconcile"],
+    priority: ["command"], worker: ["creator"], worker_path: ["creator"], worker_pack: ["creator"],
+    provider: ["creator"], account: ["creator", "spawn"], host: ["creator"], origin_host: ["creator"], origin_host_source: ["creator"],
+    version: ["creator"], created_at: ["creator"], updated_at: ["creator"], attribution_history: ["command"],
+    last_envelope: ["watcher", "reconcile"], model: ["creator", "spawn"], effort: ["creator", "spawn"], effort_source: ["creator", "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: ["reconcile"], terminal_reason: ["command", "watcher", "spawn", "reconcile"], terminal_details: ["command", "spawn"],
+    quota_reset_at: ["watcher", "reconcile"], model_quota_marker: ["watcher", "reconcile"], outpost_command_id: ["command"],
+    provider_session_id: ["watcher"], provider_session_id_absent: ["watcher"], last_resume: ["spawn"], last_run_usage: ["watcher"], envelope_repair: ["watcher", "reconcile"], last_progress_event_at: ["watcher"],
+};
 function isPlainObject(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -145,6 +241,8 @@ export function parseLaneEnvelope(raw) {
         "story_status",
         "artifacts",
         "blocked_reason",
+        "story_complete",
+        "story_complete_reason",
     ].includes(key));
     if (extra.length > 0) {
         throw new LaneSchemaError(`Lane envelope rejects unknown properties: ${extra.join(", ")}`, { extra });
@@ -169,9 +267,7 @@ export function parseLaneEnvelope(raw) {
         }
     }
     else if (questions !== undefined) {
-        if (!Array.isArray(questions) || questions.length !== 0) {
-            throw new LaneSchemaError('questions must be omitted or empty unless decision is "ask"');
-        }
+        throw new LaneSchemaError('questions is present exactly when decision is "ask"');
     }
     if (raw.decision === "blocked") {
         if (typeof raw.blocked_reason !== "string" || raw.blocked_reason.length === 0) {
@@ -181,13 +277,50 @@ export function parseLaneEnvelope(raw) {
     else if (raw.blocked_reason !== undefined) {
         throw new LaneSchemaError('blocked_reason is present exactly when decision is "blocked"');
     }
+    const storyStatus = raw.story_status;
+    let storyComplete;
+    let storyCompleteReason;
+    if (raw.story_complete !== undefined) {
+        if (typeof raw.story_complete !== "boolean") {
+            throw new LaneSchemaError("story_complete must be a boolean", {
+                field: "story_complete",
+            });
+        }
+        if (typeof raw.story_complete_reason !== "string" ||
+            raw.story_complete_reason.trim().length === 0) {
+            throw new LaneSchemaError("story_complete_reason is required when story_complete is present", { field: "story_complete_reason" });
+        }
+        if (raw.story_complete === true && storyStatus !== "done") {
+            throw new LaneSchemaError("story_complete true requires story_status done", {
+                error: "story_complete_status_mismatch",
+                story_complete: true,
+                story_status: storyStatus,
+            });
+        }
+        if (raw.story_complete === false && storyStatus === "done") {
+            throw new LaneSchemaError("story_complete false forbids story_status done", {
+                error: "story_complete_status_mismatch",
+                story_complete: false,
+                story_status: storyStatus,
+            });
+        }
+        storyComplete = raw.story_complete;
+        storyCompleteReason = raw.story_complete_reason.trim();
+    }
+    else if (raw.story_complete_reason !== undefined) {
+        throw new LaneSchemaError("story_complete_reason is present exactly when story_complete is present", { field: "story_complete_reason" });
+    }
     const envelope = {
         schema_version: ENVELOPE_SCHEMA_VERSION,
         decision: raw.decision,
         summary,
-        story_status: raw.story_status,
+        story_status: storyStatus,
         artifacts: raw.artifacts,
     };
+    if (storyComplete !== undefined) {
+        envelope.story_complete = storyComplete;
+        envelope.story_complete_reason = storyCompleteReason;
+    }
     if (Array.isArray(questions) && questions.length > 0) {
         envelope.questions = questions.map((item, index) => {
             if (!isPlainObject(item)) {

package/dist/lib/lanes/watcher-main.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Detached entry for the per-lane watcher. Spawned with
+ * `detached: true` from `spawnLaneWorker`; not a session job.
+ *
+ * Usage: node watcher-main.js <lane-id>
+ * Requires HQ_ROOT in the environment.
+ */
+export {};
+//# sourceMappingURL=watcher-main.d.ts.map

package/dist/lib/lanes/watcher-main.js

@@ -0,0 +1,22 @@
+/**
+ * Detached entry for the per-lane watcher. Spawned with
+ * `detached: true` from `spawnLaneWorker`; not a session job.
+ *
+ * Usage: node watcher-main.js <lane-id>
+ * Requires HQ_ROOT in the environment.
+ */
+import { runWatcherLoop } from "./watcher.js";
+function main() {
+    const laneId = process.argv[2]?.trim();
+    const hqRoot = process.env.HQ_ROOT?.trim();
+    if (!laneId || !hqRoot) {
+        process.stderr.write("hq lanes watcher: requires lane id argv and HQ_ROOT in the environment\n");
+        process.exit(1);
+    }
+    void runWatcherLoop(hqRoot, laneId).catch((err) => {
+        process.stderr.write(`hq lanes watcher: ${err instanceof Error ? err.message : String(err)}${err instanceof Error && err.stack ? `\n${err.stack}` : ""}\n`);
+        process.exit(1);
+    });
+}
+main();
+//# sourceMappingURL=watcher-main.js.map