@indigoai-us/hq-cli 5.345.161 → 5.345.163

package/dist/commands/feedback-triage.d.ts

@@ -0,0 +1,67 @@
+import { Command } from "commander";
+/**
+ * Staff triage commands on the feedback queue: `hq feedback list`,
+ * `hq feedback triage` and `hq feedback close`. `hq feedback assign` lives in
+ * feedback.ts next to the shared helpers.
+ *
+ * The server owns triagedAt, triagedBy and priority. These commands never
+ * send them.
+ */
+export declare const TRIAGE_KINDS: readonly ["bug", "feature", "question"];
+export type TriageKind = (typeof TRIAGE_KINDS)[number];
+export declare const MAX_TRIAGE_SUMMARY = 2000;
+export declare const DEFAULT_LIST_LIMIT = 50;
+export interface FeedbackListRow {
+    id: string;
+    title?: string;
+    plan?: string;
+    submittedAt?: string;
+    createdAt?: string;
+    [key: string]: unknown;
+}
+export type FeedbackListSelector = {
+    kind: "untriaged";
+} | {
+    kind: "assignee";
+    assignee: string;
+};
+/** Email claim of the caller's staff token, used by `list --mine`. */
+export declare function emailFromToken(token: string): string | null;
+/** Compact age such as `5m`, `3h` or `2d`. Unknown or unparsable times print `-`. */
+export declare function formatFeedbackAge(iso: string | undefined, now?: number): string;
+/**
+ * hq-pro's `GET /v1/feedback` returns the next page as `nextCursor` on every
+ * path (the untriaged queue also mirrors it as `cursor`) and reads it back from
+ * `?cursor=`. `nextToken` is accepted for older servers. The value always goes
+ * back as `?cursor=`.
+ */
+export declare function cursorFrom(data: unknown): string | null;
+/** Page through `GET /v1/feedback` until `limit` rows (or every row with `limit: null`). */
+export declare function listFeedback(opts: {
+    token: string;
+    selector: FeedbackListSelector;
+    status?: string;
+    limit: number | null;
+}): Promise<FeedbackListRow[]>;
+export declare function formatFeedbackTable(rows: FeedbackListRow[], now?: number): string;
+export declare function parseListLimit(raw: string): number;
+export declare function buildTriagePatch(opts: {
+    id: string;
+    kind: string;
+    area: string;
+    summary: string;
+    duplicateOf?: string;
+}): Record<string, string>;
+export declare function buildClosePatch(opts: {
+    reason: string;
+    wontFix?: boolean;
+}): Record<string, string>;
+/** PATCH one feedback row; returns the server's JSON, or the sent fields when the body is empty. */
+export declare function patchFeedback(opts: {
+    id: string;
+    token: string;
+    body: Record<string, string>;
+    action: string;
+}): Promise<unknown>;
+export declare function registerFeedbackTriageCommands(feedbackCmd: Command): void;
+//# sourceMappingURL=feedback-triage.d.ts.map

package/dist/commands/feedback-triage.js

@@ -0,0 +1,294 @@
+import chalk from "chalk";
+import { assertVaultApiRequestSupported, vaultApiFetch } from "../utils/vault-api.js";
+import { decodeJwtPayload } from "../utils/person-token-cache.js";
+import { assertFeedbackId, normalizeFeedbackAssignee, readFeedbackError, resolveStaffToken, } from "./feedback.js";
+/**
+ * Staff triage commands on the feedback queue: `hq feedback list`,
+ * `hq feedback triage` and `hq feedback close`. `hq feedback assign` lives in
+ * feedback.ts next to the shared helpers.
+ *
+ * The server owns triagedAt, triagedBy and priority. These commands never
+ * send them.
+ */
+export const TRIAGE_KINDS = ["bug", "feature", "question"];
+export const MAX_TRIAGE_SUMMARY = 2000;
+export const DEFAULT_LIST_LIMIT = 50;
+/** Safety stop for --all so a server that never ends its cursor can't loop forever. */
+const MAX_LIST_PAGES = 100;
+function fail(err) {
+    console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+    process.exit(1);
+}
+/** Email claim of the caller's staff token, used by `list --mine`. */
+export function emailFromToken(token) {
+    const claims = decodeJwtPayload(token);
+    const email = claims?.email;
+    return typeof email === "string" && email.includes("@") ? email.toLowerCase() : null;
+}
+/** Compact age such as `5m`, `3h` or `2d`. Unknown or unparsable times print `-`. */
+export function formatFeedbackAge(iso, now = Date.now()) {
+    if (!iso)
+        return "-";
+    const at = Date.parse(iso);
+    if (Number.isNaN(at))
+        return "-";
+    const minutes = Math.max(0, Math.floor((now - at) / 60_000));
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 48)
+        return `${hours}h`;
+    return `${Math.floor(hours / 24)}d`;
+}
+function rowsFrom(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return [];
+    const items = data.items;
+    if (!Array.isArray(items))
+        return [];
+    return items.filter((row) => !!row && typeof row === "object" && typeof row.id === "string");
+}
+/**
+ * hq-pro's `GET /v1/feedback` returns the next page as `nextCursor` on every
+ * path (the untriaged queue also mirrors it as `cursor`) and reads it back from
+ * `?cursor=`. `nextToken` is accepted for older servers. The value always goes
+ * back as `?cursor=`.
+ */
+export function cursorFrom(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return null;
+    for (const name of ["nextCursor", "cursor", "nextToken"]) {
+        const value = data[name];
+        if (typeof value === "string" && value.length > 0)
+            return value;
+    }
+    return null;
+}
+/** Server page cap (FEEDBACK_LIST_PAGE_MAX). The plain list path rejects a cursor without a limit. */
+const LIST_PAGE_SIZE = 200;
+/** Page through `GET /v1/feedback` until `limit` rows (or every row with `limit: null`). */
+export async function listFeedback(opts) {
+    const base = opts.selector.kind === "untriaged"
+        ? { triage: "untriaged" }
+        : { assignee: opts.selector.assignee };
+    if (opts.status)
+        base.status = opts.status;
+    const rows = [];
+    let cursor = null;
+    for (let page = 0; page < MAX_LIST_PAGES; page++) {
+        const pageSize = opts.limit === null ? LIST_PAGE_SIZE : Math.min(LIST_PAGE_SIZE, opts.limit - rows.length);
+        const query = { ...base, limit: String(pageSize) };
+        if (cursor)
+            query.cursor = cursor;
+        const res = await vaultApiFetch({ token: opts.token, path: "/v1/feedback", query });
+        if (!res.ok) {
+            throw new Error(`Failed to list feedback: ${await readFeedbackError(res)}`);
+        }
+        const data = (await res.json());
+        rows.push(...rowsFrom(data));
+        if (opts.limit !== null && rows.length >= opts.limit)
+            return rows.slice(0, opts.limit);
+        cursor = cursorFrom(data);
+        if (!cursor)
+            return rows;
+    }
+    return rows;
+}
+export function formatFeedbackTable(rows, now = Date.now()) {
+    const header = ["ID", "AGE", "PLAN", "TITLE"];
+    const body = rows.map((row) => [
+        row.id,
+        formatFeedbackAge(row.submittedAt ?? row.createdAt, now),
+        typeof row.plan === "string" && row.plan.length > 0 ? row.plan : "-",
+        typeof row.title === "string" ? row.title : "",
+    ]);
+    const widths = [0, 1, 2].map((col) => Math.max(header[col].length, ...body.map((cells) => cells[col].length)));
+    return [header, ...body]
+        .map((cells) => cells.map((cell, col) => (col < 3 ? cell.padEnd(widths[col]) : cell)).join("  ").trimEnd())
+        .join("\n");
+}
+export function parseListLimit(raw) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1) {
+        throw new Error(`Invalid --limit '${raw}': expected a positive whole number.`);
+    }
+    return n;
+}
+export function buildTriagePatch(opts) {
+    if (!TRIAGE_KINDS.includes(opts.kind)) {
+        throw new Error(`Invalid --kind '${opts.kind}': expected one of ${TRIAGE_KINDS.join(", ")}.`);
+    }
+    const area = opts.area.trim();
+    if (!area)
+        throw new Error("--area must not be empty.");
+    const summary = opts.summary.trim();
+    if (!summary)
+        throw new Error("--summary must not be empty.");
+    if (summary.length > MAX_TRIAGE_SUMMARY) {
+        throw new Error(`--summary is ${summary.length} characters; the limit is ${MAX_TRIAGE_SUMMARY}.`);
+    }
+    const body = {
+        triageStatus: opts.duplicateOf === undefined ? "triaged" : "duplicate",
+        triageKind: opts.kind,
+        area,
+        summary,
+    };
+    if (opts.duplicateOf !== undefined) {
+        assertFeedbackId(opts.duplicateOf);
+        if (opts.duplicateOf === opts.id) {
+            throw new Error("--duplicate-of must name a different feedback item.");
+        }
+        body.duplicateOf = opts.duplicateOf;
+    }
+    return body;
+}
+export function buildClosePatch(opts) {
+    const reason = opts.reason.trim();
+    if (!reason)
+        throw new Error("--reason must not be empty.");
+    return { status: opts.wontFix ? "wont_fix" : "resolved", resolution: reason };
+}
+/** PATCH one feedback row; returns the server's JSON, or the sent fields when the body is empty. */
+export async function patchFeedback(opts) {
+    const res = await vaultApiFetch({
+        token: opts.token,
+        path: `/v1/feedback/${opts.id}`,
+        method: "PATCH",
+        body: opts.body,
+    });
+    if (!res.ok) {
+        throw new Error(`Failed to ${opts.action} ${opts.id}: ${await readFeedbackError(res)}`);
+    }
+    const data = (await res.json().catch(() => null));
+    return data ?? { id: opts.id, ...opts.body };
+}
+function registerListSubcommand(feedbackCmd) {
+    feedbackCmd
+        .command("list")
+        .description("List feedback: untriaged (default), yours, or one person's")
+        .option("--untriaged", "Items nobody has triaged yet (the default)")
+        .option("--mine", "Items assigned to you")
+        .option("--assignee <person>", "Items assigned to this email address or prs_ uid")
+        .option("--status <status>", "Only items with this status")
+        .option("--limit <n>", `Stop after this many items (default ${DEFAULT_LIST_LIMIT})`)
+        .option("--all", "Fetch every page")
+        .option("--json", "Print { items, count } as JSON")
+        .action(async (opts) => {
+        try {
+            const picked = [opts.untriaged, opts.mine, opts.assignee !== undefined].filter(Boolean);
+            if (picked.length > 1) {
+                throw new Error("Use only one of --untriaged, --mine and --assignee.");
+            }
+            if (opts.all && opts.limit !== undefined) {
+                throw new Error("Use --limit or --all, not both.");
+            }
+            if (opts.status !== undefined && !opts.status.trim()) {
+                throw new Error("--status must not be empty.");
+            }
+            const limit = opts.all
+                ? null
+                : opts.limit === undefined
+                    ? DEFAULT_LIST_LIMIT
+                    : parseListLimit(opts.limit);
+            const token = await resolveStaffToken();
+            let selector = { kind: "untriaged" };
+            if (opts.mine) {
+                const email = emailFromToken(token);
+                if (!email) {
+                    throw new Error("--mine needs a person login with an email (hq login). Use --assignee <person> instead.");
+                }
+                selector = { kind: "assignee", assignee: email };
+            }
+            else if (opts.assignee !== undefined) {
+                selector = {
+                    kind: "assignee",
+                    assignee: normalizeFeedbackAssignee(opts.assignee, "--assignee"),
+                };
+            }
+            assertVaultApiRequestSupported({ token, path: "/v1/feedback" });
+            const items = await listFeedback({
+                token,
+                selector,
+                status: opts.status?.trim(),
+                limit,
+            });
+            if (opts.json) {
+                console.log(JSON.stringify({ items, count: items.length }));
+            }
+            else if (items.length === 0) {
+                console.log("No feedback items match.");
+            }
+            else {
+                console.log(formatFeedbackTable(items));
+            }
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+}
+function registerTriageSubcommand(feedbackCmd) {
+    feedbackCmd
+        .command("triage")
+        .description("Label a feedback item with its kind, area and summary, or mark it a duplicate")
+        .argument("<id>", "Feedback id (feedback_<uuid>)")
+        .requiredOption("--kind <kind>", `One of ${TRIAGE_KINDS.join(", ")}`)
+        .requiredOption("--area <area>", "Product area, for example sync or desktop")
+        .requiredOption("--summary <text>", `One-line triage summary (at most ${MAX_TRIAGE_SUMMARY} characters)`)
+        .option("--duplicate-of <id>", "Mark this item a duplicate of another feedback id")
+        .option("--json", "Print the updated item as JSON")
+        .action(async (id, opts) => {
+        try {
+            assertFeedbackId(id);
+            const body = buildTriagePatch({ id, ...opts });
+            const token = await resolveStaffToken();
+            assertVaultApiRequestSupported({ token, path: `/v1/feedback/${id}` });
+            const result = await patchFeedback({ id, token, body, action: "triage" });
+            if (opts.json) {
+                console.log(JSON.stringify(result));
+            }
+            else if (body.duplicateOf) {
+                console.log(`Marked duplicate: ${id} -> ${body.duplicateOf}`);
+            }
+            else {
+                console.log(`Triaged: ${id} (${body.triageKind}, ${body.area})`);
+            }
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+}
+function registerCloseSubcommand(feedbackCmd) {
+    feedbackCmd
+        .command("close")
+        .description("Close a feedback item as resolved (or won't fix) with a reason")
+        .argument("<id>", "Feedback id (feedback_<uuid>)")
+        .requiredOption("--reason <text>", "Why it is closed: the fix, PR or version, or the decision")
+        .option("--wont-fix", "Close as won't fix instead of resolved")
+        .option("--json", "Print the updated item as JSON")
+        .action(async (id, opts) => {
+        try {
+            assertFeedbackId(id);
+            const body = buildClosePatch(opts);
+            const token = await resolveStaffToken();
+            assertVaultApiRequestSupported({ token, path: `/v1/feedback/${id}` });
+            const result = await patchFeedback({ id, token, body, action: "close" });
+            if (opts.json) {
+                console.log(JSON.stringify(result));
+            }
+            else {
+                console.log(`Closed: ${id} (${body.status})`);
+            }
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+}
+export function registerFeedbackTriageCommands(feedbackCmd) {
+    registerListSubcommand(feedbackCmd);
+    registerTriageSubcommand(feedbackCmd);
+    registerCloseSubcommand(feedbackCmd);
+}
+//# sourceMappingURL=feedback-triage.js.map

package/dist/commands/feedback.d.ts

@@ -76,6 +76,13 @@ export declare function submitFeedback(opts: FeedbackSubmitOptions): Promise<Fee
 export declare const PUBLIC_TICKET_STATES: readonly ["triaged", "in-progress", "shipped", "verified", "resolved"];
 export type PublicTicketState = (typeof PUBLIC_TICKET_STATES)[number];
 export declare function assertFeedbackId(id: string): void;
+/**
+ * The staff feedback routes gate on the id token's email claim, so send the
+ * cached id token when a person session has one. Machine identities already
+ * get their id token back from ensureCognitoToken.
+ */
+export declare function resolveStaffToken(): Promise<string>;
+export declare function readFeedbackError(res: Response): Promise<string>;
 /** Resolve (and lazily mint) the public tracking link for a ticket. */
 export declare function fetchFeedbackLink(opts: {
     id: string;
@@ -92,7 +99,7 @@ export declare function postFeedbackUpdate(opts: {
     slack: string | null;
 }>;
 /** Mirror of hq-pro normalizeAssignee: a prs_ uid as-is, an email lowercased. */
-export declare function normalizeFeedbackAssignee(value: string): string;
+export declare function normalizeFeedbackAssignee(value: string, label?: string): string;
 /**
  * Reassign a ticket. A person's own login may move a ticket that another
  * person claimed; agent and operator service tokens get 409
@@ -103,5 +110,10 @@ export declare function assignFeedback(opts: {
     token: string;
     assignee: string;
 }): Promise<void>;
+/**
+ * Pick the new assignee from the positional `[person]` or the `--to` flag.
+ * Either form works; naming two different people is an error.
+ */
+export declare function resolveAssignTarget(person: string | undefined, to: string | undefined): string;
 export declare function registerFeedbackCommand(program: Command): void;
 //# sourceMappingURL=feedback.d.ts.map

package/dist/commands/feedback.js

@@ -9,6 +9,7 @@ import { uploadLogBundle } from "../utils/feedback-log-bundle.js";
 import { resolveProcessFlagGate } from "../lib/flag-registry.js";
 import { cachedLatestVersion } from "../utils/version-check.js";
 import { registerFeedbackShowCommand } from "./feedback-show.js";
+import { registerFeedbackTriageCommands } from "./feedback-triage.js";
 export const FEEDBACK_LATEST_VERSION_FLAG = "feedback.latest-version";
 export const FEEDBACK_LATEST_VERSION_FLAG_FALLBACK = false;
 export const FEEDBACK_REPORTER_KIND_FLAG = "feedback.reporter-kind";
@@ -229,14 +230,14 @@ export function assertFeedbackId(id) {
  * cached id token when a person session has one. Machine identities already
  * get their id token back from ensureCognitoToken.
  */
-async function resolveStaffToken() {
+export async function resolveStaffToken() {
     const token = await ensureCognitoToken({ interactive: false });
     const cached = loadCachedTokens();
     return typeof cached?.idToken === "string" && cached.idToken.length > 0
         ? cached.idToken
         : token;
 }
-async function readFeedbackError(res) {
+export async function readFeedbackError(res) {
     const data = await res.json().catch(() => ({}));
     return data &&
         typeof data === "object" &&
@@ -287,10 +288,10 @@ export async function postFeedbackUpdate(opts) {
 }
 const ASSIGNEE_RE = /^(?:prs_[A-Za-z0-9]+|[^\s@]+@[^\s@]+\.[^\s@]+)$/;
 /** Mirror of hq-pro normalizeAssignee: a prs_ uid as-is, an email lowercased. */
-export function normalizeFeedbackAssignee(value) {
+export function normalizeFeedbackAssignee(value, label = "--to") {
     const trimmed = value.trim();
     if (!ASSIGNEE_RE.test(trimmed)) {
-        throw new Error(`Invalid --to '${value}': expected an email address or a prs_ uid.`);
+        throw new Error(`Invalid ${label} '${value}': expected an email address or a prs_ uid.`);
     }
     return trimmed.startsWith("prs_") ? trimmed : trimmed.toLowerCase();
 }
@@ -315,20 +316,42 @@ export async function assignFeedback(opts) {
     }
     throw new Error(`Failed to assign ${opts.id}: ${message}`);
 }
+/**
+ * Pick the new assignee from the positional `[person]` or the `--to` flag.
+ * Either form works; naming two different people is an error.
+ */
+export function resolveAssignTarget(person, to) {
+    if (person === undefined && to === undefined) {
+        throw new Error("Name the new assignee: hq feedback assign <id> <person> (or --to <person>).");
+    }
+    const fromPerson = person === undefined ? undefined : normalizeFeedbackAssignee(person, "person");
+    const fromTo = to === undefined ? undefined : normalizeFeedbackAssignee(to);
+    if (fromPerson !== undefined && fromTo !== undefined && fromPerson !== fromTo) {
+        throw new Error(`Conflicting assignees '${person}' and --to '${to}': give only one.`);
+    }
+    return (fromPerson ?? fromTo);
+}
 function registerAssignSubcommand(feedbackCmd) {
     feedbackCmd
         .command("assign")
         .description("Reassign a ticket to a person, including one another person has claimed")
         .argument("<id>", "Feedback id (feedback_<uuid>)")
-        .requiredOption("--to <assignee>", "New assignee: an email address or a prs_ uid")
-        .action(async (id, opts) => {
+        .argument("[person]", "New assignee: an email address or a prs_ uid")
+        .option("--to <assignee>", "New assignee: an email address or a prs_ uid")
+        .option("--json", "Print the result as JSON")
+        .action(async (id, person, opts) => {
         try {
             assertFeedbackId(id);
-            const assignee = normalizeFeedbackAssignee(opts.to);
+            const assignee = resolveAssignTarget(person, opts.to);
             const token = await resolveStaffToken();
             assertVaultApiRequestSupported({ token, path: `/v1/feedback/${id}` });
             await assignFeedback({ id, token, assignee });
-            console.log(`Assigned: ${id} -> ${assignee}`);
+            if (opts.json) {
+                console.log(JSON.stringify({ id, assignee }));
+            }
+            else {
+                console.log(`Assigned: ${id} -> ${assignee}`);
+            }
         }
         catch (err) {
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
@@ -499,5 +522,6 @@ export function registerFeedbackCommand(program) {
     registerUpdateSubcommand(feedbackCmd);
     registerFeedbackShowCommand(feedbackCmd);
     registerAssignSubcommand(feedbackCmd);
+    registerFeedbackTriageCommands(feedbackCmd);
 }
 //# sourceMappingURL=feedback.js.map

package/dist/commands/lanes-loop.js

@@ -7,7 +7,7 @@ import { readLatestEnvelopeRecord } from "../lib/lanes/watcher.js";
 import { spawnLaneWorker } from "../lib/lanes/spawn.js";
 import { raiseLaneQuestion } from "../lib/lanes/questions.js";
 import { isTerminalLaneState } from "../lib/lanes/types.js";
-import { clearLoopControllerPid, loopAdmissionPath, runLoopLane, setLoopControllerPid } from "../lib/lanes/loop.js";
+import { HANDOFF_HOLD_CHOICES, clearLoopControllerPid, loopAdmissionPath, runLoopLane, setLoopControllerPid } from "../lib/lanes/loop.js";
 import { laneStories } from "../lib/lanes/stories.js";
 import { readLanesRegistryFlagFailOpen } from "../lib/lanes/registry-flag.js";
 import { LANE_LOOP_HANDOFF_REPAIR_FLAG } from "../lib/lanes/flag-keys.js";
@@ -255,7 +255,7 @@ export async function runLaneLoopController(ctx, laneId, deps) {
                     signal.removeEventListener("abort", abortPhase);
                 }
             },
-            raiseQuestion: ({ envelope, envelopeId, attempt, error, questionId }) => {
+            raiseQuestion: ({ envelope, envelopeId, attempt, error, questionId, reason }) => {
                 const current = readLane(hqRoot, laneId);
                 const data = envelope;
                 raiseLaneQuestion({
@@ -265,11 +265,11 @@ export async function runLaneLoopController(ctx, laneId, deps) {
                     raisedVia: "cli",
                     at: ctx.now().toISOString(),
                     body: {
-                        question: `Loop phase ${String(data.phase ?? envelopeId)} stalled twice. How should it proceed?`,
-                        context: `${error}\nThe phase is parked; later envelopes remain queued. Stall attempt: ${attempt}.`,
-                        options: ["Retry with a longer deadline", "Reroute to another worker", "Drop this phase and block the story"],
-                        recommended: "Retry with a longer deadline",
-                        loop_stall: { lane_id: laneId, envelope_id: envelopeId, attempt },
+                        question: reason === "handoff_needs_repair" ? `Loop phase ${String(data.phase ?? envelopeId)} has an invalid handoff. How should it proceed?` : `Loop phase ${String(data.phase ?? envelopeId)} stalled twice. How should it proceed?`,
+                        context: reason === "handoff_needs_repair" ? `${error}\nThe worker file is preserved and the phase is parked; later envelopes remain queued. Repair the handoff file before accepting it. Retrying can repeat external effects.` : `${error}\nThe phase is parked; later envelopes remain queued. Stall attempt: ${attempt}.`,
+                        options: reason === "handoff_needs_repair" ? [...HANDOFF_HOLD_CHOICES] : ["Retry with a longer deadline", "Reroute to another worker", "Drop this phase and block the story"],
+                        recommended: reason === "handoff_needs_repair" ? HANDOFF_HOLD_CHOICES[0] : "Retry with a longer deadline",
+                        loop_stall: { lane_id: laneId, envelope_id: envelopeId, attempt, ...(reason ? { reason } : {}) },
                     },
                 });
             },

package/dist/commands/lanes-questions.js

@@ -1,4 +1,5 @@
 import * as path from "node:path";
+import { readSessionCompanyLock } from "../lib/session-company-lock.js";
 import { isQuestionImported } from "../lib/lanes/imported-question.js";
 import { buildOutpostQuestionAnswerCommand, buildOutpostQuestionCancelCommand, buildOutpostQuestionShowCommand, dispatchErrorMessage } from "../lib/lanes/outpost-dispatch.js";
 import { assertNoSecretText } from "../lib/lanes/text-scan.js";
@@ -6,7 +7,7 @@ import { sessionIdFromEnv } from "../lib/mesh/live/session-identity.js";
 import { appendCappedHistory, createQuestion, expandLocalLaneIdPrefix, isLanesError, listSessionLiveness, parseLivenessState, parseQuestionRecord, parseQuestionStatus, readDaemonPresenceConnected, readLane, readQuestion, wakeAnsweredLaneNow, sessionLiveness, appendDropboxMessage, answerDropboxMessage, laneAcceptsDropboxDelivery, laneIdForAnswerDelivery, writeQuestionBody } from "../lib/lanes/index.js";
 import { resolveQuestionCompanyWithFallback } from "../lib/lanes/questions.js";
 import { LanesError } from "../lib/lanes/errors.js";
-import { applyLoopStallAnswer, findLoopStallResult } from "../lib/lanes/loop.js";
+import { HANDOFF_HOLD_CHOICES, applyLoopStallAnswer, findLoopStallResult, loopHandoffHoldIdentity } from "../lib/lanes/loop.js";
 export function resolveAnswerChoice(choice, options, freeform) {
     const trimmed = choice.trim();
     if (/^[0-9]+$/.test(trimmed)) {
@@ -847,11 +848,48 @@ export function createLaneQuestionsHandlers(deps) {
         const retryingSameLoopAnswer = isLoopStallQuestion && question.status === "answered" && question.answer?.choice === choice &&
             question.answer.answer_kind === incomingAnswerKind && incomingNotesMatch &&
             deps.sameQuestionAnswer(question.answer, { ...question.answer });
-        if (question.status !== "pending" && !retryingSameLoopAnswer)
-            throwIfQuestionNotPending(question);
         const loopStallResult = isLoopStallQuestion
             ? findLoopStallResult(path.join(hqRoot, "workspace", "lanes-runs", askingLane.lane_id), questionId)
             : undefined;
+        if (loopStallResult?.hold_reason === "handoff_needs_repair" && !HANDOFF_HOLD_CHOICES.includes(choice)) {
+            throw new LanesError("invalid_handoff_disposition", "Choose an explicit handoff repair disposition", { question_id: questionId });
+        }
+        const handoffIdentity = askingLane.loop_mode ? loopHandoffHoldIdentity(path.join(hqRoot, "workspace", "lanes-runs", askingLane.lane_id)) : undefined;
+        const changingHeldAnswer = body.loop_stall?.reason === "handoff_needs_repair" && isLoopStallQuestion &&
+            question.status === "answered" && question.answer?.choice === HANDOFF_HOLD_CHOICES[2] &&
+            choice !== HANDOFF_HOLD_CHOICES[2] && handoffIdentity?.unresolved === true &&
+            handoffIdentity.question_id === questionId && handoffIdentity.envelope_id === body.loop_stall.envelope_id &&
+            loopStallResult?.hold_reason === "handoff_needs_repair";
+        if (question.status !== "pending" && !retryingSameLoopAnswer && !changingHeldAnswer)
+            throwIfQuestionNotPending(question);
+        const isHandoffQuestion = body.loop_stall?.reason === "handoff_needs_repair" || loopStallResult?.hold_reason === "handoff_needs_repair" || handoffIdentity !== undefined;
+        if (isHandoffQuestion) {
+            assertQuestionAnswerAuthorized(ctx, askingLane);
+            assertLaneRunsHereForOperatorMutation(ctx, askingLane, "resolve a handoff repair hold on");
+            const targetCompany = questionCompanyForLane(question, askingLane, hqRoot);
+            const lock = readSessionCompanyLock({ ...ctx.env, HQ_ROOT: hqRoot });
+            const actorLaneId = ctx.env.HQ_LANE_ID?.trim();
+            if (actorLaneId) {
+                const actorLane = readLane(hqRoot, actorLaneId);
+                const actorCompany = actorLane.company ?? actorLane.mesh_company;
+                if (!targetCompany || !actorCompany || !sameQuestionCompany(actorCompany, targetCompany))
+                    throw new LanesError("handoff_answer_company_mismatch", "Caller lane does not own this handoff company", { question_id: questionId });
+            }
+            // Lane-only callers may use their owned lane identity; a present session lock
+            // always constrains that identity and may never be widened by HQ_LANE_ID.
+            if ((lock || !actorLaneId) && (!lock || !targetCompany || !lock.companies.includes(targetCompany.slug))) {
+                throw new LanesError("handoff_answer_company_mismatch", "The current session is not bound to this handoff company", { question_id: questionId });
+            }
+            if (!isLoopStallQuestion || body.loop_stall?.reason !== "handoff_needs_repair" ||
+                (handoffIdentity && (handoffIdentity.question_id !== questionId || handoffIdentity.envelope_id !== body.loop_stall.envelope_id)) ||
+                (loopStallResult && loopStallResult.envelope_id !== body.loop_stall.envelope_id)) {
+                throw new LanesError("handoff_question_identity_mismatch", "The persisted handoff question and hold identities do not match", { question_id: questionId });
+            }
+            if (!HANDOFF_HOLD_CHOICES.includes(choice))
+                throw new LanesError("invalid_handoff_disposition", "Choose an explicit handoff repair disposition", { question_id: questionId });
+            if (!loopStallResult && question.status === "pending")
+                throw new LanesError("handoff_result_missing", "The handoff hold result is missing; no disposition was applied", { question_id: questionId });
+        }
         const at = ctx.now().toISOString();
         const answeredBy = sessionIdFromEnv(ctx.env)
             ? `session:${sessionIdFromEnv(ctx.env)}`
@@ -860,7 +898,14 @@ export function createLaneQuestionsHandlers(deps) {
             if (retryingSameLoopAnswer && current.status === "answered" && current.answer?.choice === choice &&
                 deps.sameQuestionAnswer(current.answer, question.answer))
                 return current;
-            throwIfQuestionNotPending(current);
+            const currentHold = changingHeldAnswer ? loopHandoffHoldIdentity(path.join(hqRoot, "workspace", "lanes-runs", askingLane.lane_id)) : undefined;
+            const stillHeld = changingHeldAnswer && current.status === "answered" &&
+                current.answer?.choice === HANDOFF_HOLD_CHOICES[2] &&
+                deps.sameQuestionAnswer(current.answer, question.answer) &&
+                currentHold?.unresolved === true && currentHold.question_id === questionId &&
+                currentHold.envelope_id === body.loop_stall?.envelope_id;
+            if (!stillHeld)
+                throwIfQuestionNotPending(current);
             assertQuestionCompanyAccess(current, askingLane, requestedCompany, hqRoot);
             const recordedCompany = current.company ?? questionCompany;
             const currentForBody = current.company === null
@@ -882,6 +927,7 @@ export function createLaneQuestionsHandlers(deps) {
                 body: nextBody,
                 status: "answered",
                 delivered_at: null,
+                ...(stillHeld && current.answer ? { answer_history: [...(current.answer_history ?? []), current.answer] } : {}),
                 answer: {
                     choice,
                     answer_kind: freeform ? "freeform" : "option",
@@ -911,6 +957,10 @@ export function createLaneQuestionsHandlers(deps) {
                 printJson({ ok: true, action: "questions.answer", lane_id: askingLane.lane_id, question: updated, loop_action: resolved.action });
                 return;
             }
+            if (isHandoffQuestion && resolved.action === "parked") {
+                printJson({ ok: true, action: "questions.answer", lane_id: askingLane.lane_id, question: updated, loop_action: "parked" });
+                return;
+            }
             const controllerPid = await deps.restartLoopController(ctx, askingLane.lane_id);
             printJson({ ok: true, action: "questions.answer", lane_id: askingLane.lane_id, question: updated, loop_action: resolved.action, controller_pid: controllerPid });
             return;

package/dist/commands/lanes.js

@@ -717,7 +717,8 @@ export function parseQuestionBody(raw) {
         typeof obj.loop_stall.envelope_id !== "string" ||
         typeof obj.loop_stall.attempt !== "number" ||
         !Number.isSafeInteger(obj.loop_stall.attempt) ||
-        obj.loop_stall.attempt < 1))
+        obj.loop_stall.attempt < 1 ||
+        (obj.loop_stall.reason !== undefined && obj.loop_stall.reason !== "handoff_needs_repair")))
         return null;
     const options = obj.options.filter((item) => typeof item === "string");
     const body = {