@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/commands/lanes-message.js

@@ -0,0 +1,946 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { appendCappedHistory, appendDropboxMessage, deliveryRefusalReason, dropboxInboxPath, laneAcceptsOperatorMessage, laneDeliveryMechanism, operatorMessageRefusalReason, providerSessionPortable, providerSupportsSessionResume, readLane, sessionNotPortableMessage, validateProjectStories, withLaneAdmissionLock } from "../lib/lanes/index.js";
+import { LanesError } from "../lib/lanes/errors.js";
+import { parseCliEffort } from "../lib/lanes/effort.js";
+import { parseOutpostHireGrantContext, sameHireGrantSenior } from "../lib/lanes/hire-grant-dispatch.js";
+import { dispatchLaneDelivery } from "../lib/lanes/delivery-core.js";
+import { dropboxInboxHasMessages, drainDropbox, formatDropboxMessages, formatMonitorEvent, requeueDropboxMessages } from "../lib/lanes/dropbox.js";
+import { isPidAlive, runWatcherLoop, WATCHER_OUT_MAX_BYTES, watcherOutLogPath, writeWatcherDecision } from "../lib/lanes/watcher.js";
+import { laneStories, laneStory, storyWarning } from "../lib/lanes/stories.js";
+import { artifactIdentityKeys, rollbackStorySwitchAttribution, storySwitchNotice } from "../lib/lanes/story-switch.js";
+import { laneRunDir, probePidRecord, readPidRecord, readProcStarttime, spawnLaneWorker } from "../lib/lanes/spawn.js";
+import { keepAliveExclusion, keepAliveSupersededBy, LANE_RUNNING_SUPERSEDED_MESSAGE_DELIVERY_FLAG, LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, loadRetiredLaneIds } from "../lib/lanes/keep-alive.js";
+import { readLanesRegistryFlag } from "../lib/lanes/registry-flag.js";
+import { lowDiskGuardEnabledForLane } from "../lib/lanes/disk-guard.js";
+import { resolveLaneCompany } from "../lib/lanes/lane-company.js";
+import { accountMoveSummary, accountRequestKeepsCurrentLane, assertCurrentResumeAccountAvailable, callerMatchesSessionSenior, recordedResumeEffort, resetKeepAliveProgress, resolveResumeEffort } from "./lanes-shared.js";
+export function createLaneMessageHandlers(deps) {
+    const { archiveResumeMessage, assertLaneRunsHereForAdmission, assertLaneRunsHereForOperatorMutation, assessLaneAdmission, casUpdateLane, dispatchOutpostLaneCommand, dispatchPrimaryLaneMessage, drainHookStatusFor, laneIsHostedHere, laneWithRecoveredProviderSession, loadAllLanes, mintMessageId, persistClaudeAccountSelection, prepareAccountMove, printJson, recordResumeSetup, resolveActiveQuestionCompany, resolveResumeProfile, selectAutomaticClaudeResumeAccount, validateResumeProfileModel, withResumeHireAdmission } = deps;
+    function currentSuccessorOf(lane, lanes, lineageAware, companyForLane) {
+        const validLanes = lanes.filter((candidate) => Number.isFinite(Date.parse(candidate.created_at)));
+        const newestFirst = [...validLanes].sort((left, right) => Date.parse(right.created_at) - Date.parse(left.created_at));
+        const visited = new Set([lane.lane_id]);
+        let current = lane;
+        for (let depth = 0; depth < validLanes.length; depth += 1) {
+            const next = keepAliveSupersededBy(current, newestFirst, lineageAware, companyForLane);
+            if (!next || visited.has(next.lane_id))
+                break;
+            current = next;
+            visited.add(next.lane_id);
+        }
+        return current.lane_id === lane.lane_id ? undefined : current;
+    }
+    function callerMayMessageSupersededLane(ctx, lane, lanes, lineageAware, companyForLane, callerLaneIdOverride, callerSessionIdOverride) {
+        if (lane.senior.kind === "session") {
+            const sessionSeniorId = lane.senior.id;
+            if (!sessionSeniorId)
+                return false;
+            if (callerLaneIdOverride !== undefined || ctx.env.HQ_LANE_ID?.trim())
+                return false;
+            if (callerSessionIdOverride === null)
+                return false;
+            return callerSessionIdOverride === undefined
+                ? callerMatchesSessionSenior(ctx, sessionSeniorId)
+                : callerSessionIdOverride === sessionSeniorId;
+        }
+        if (lane.senior.kind !== "lane")
+            return false;
+        const callerLaneId = callerLaneIdOverride ?? ctx.env.HQ_LANE_ID?.trim();
+        if (!callerLaneId)
+            return false;
+        const senior = lanes.find((candidate) => candidate.lane_id === lane.senior.id);
+        const caller = lanes.find((candidate) => candidate.lane_id === callerLaneId);
+        if (!senior || !caller)
+            return false;
+        const workerCompany = companyForLane(lane);
+        const seniorCompany = companyForLane(senior);
+        const callerCompany = companyForLane(caller);
+        const projectId = lane.project_id;
+        if (!workerCompany ||
+            seniorCompany?.uid !== workerCompany.uid ||
+            callerCompany?.uid !== workerCompany.uid ||
+            !projectId ||
+            senior.project_id !== projectId ||
+            caller.project_id !== projectId)
+            return false;
+        if (caller.lane_id === senior.lane_id)
+            return true;
+        const projectLanes = lanes.filter((candidate) => companyForLane(candidate)?.uid === workerCompany.uid && candidate.project_id === projectId);
+        return currentSuccessorOf(lane, projectLanes, lineageAware, companyForLane)?.lane_id === caller.lane_id;
+    }
+    function keepAliveLaneFromSnapshot(snapshot) {
+        if (snapshot.created_at === undefined || !Object.hasOwn(snapshot, "company"))
+            return undefined;
+        return {
+            lane_id: snapshot.lane_id,
+            created_at: snapshot.created_at,
+            senior: snapshot.senior,
+            company: snapshot.company ?? null,
+            project_id: snapshot.project_id ?? "",
+            ...(snapshot.worker_profile === undefined ? {} : { worker_profile: snapshot.worker_profile }),
+            ...(snapshot.hire_grant === undefined ? {} : { hire_grant: snapshot.hire_grant }),
+        };
+    }
+    async function messageLaneExclusion(ctx, lane, grantContext) {
+        if (lane.state === "killed" || lane.state === "cancelled") {
+            return { lane, exclusion: lane.state };
+        }
+        const companyForLane = (candidate) => resolveLaneCompany(ctx.hqRoot(), candidate).company;
+        const lineageAware = await readLanesRegistryFlag(LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, {
+            company: companyForLane(lane),
+            env: ctx.env,
+        });
+        let currentLane = readLane(ctx.hqRoot(), lane.lane_id);
+        if (currentLane.state === "killed" || currentLane.state === "cancelled") {
+            return { lane: currentLane, exclusion: currentLane.state };
+        }
+        const localLanes = loadAllLanes(ctx.hqRoot());
+        let lanes = localLanes;
+        let retiredLaneIds = loadRetiredLaneIds(ctx.hqRoot());
+        const dispatchedCallerId = grantContext?.superseded_message_caller_id;
+        const dispatchedSessionId = grantContext?.superseded_message_session_id;
+        let dispatchedContextBound = grantContext !== undefined &&
+            ctx.isSsmOwnerDispatch() &&
+            sameHireGrantSenior(grantContext.expected_senior, currentLane.senior);
+        let dispatchedSessionContext = dispatchedContextBound && currentLane.senior.kind === "session";
+        let dispatchedContextAuthorized = dispatchedContextBound && (dispatchedCallerId !== undefined ||
+            (dispatchedSessionId !== undefined && dispatchedSessionId === currentLane.senior.id));
+        if (dispatchedContextBound && grantContext &&
+            (dispatchedCallerId !== undefined || dispatchedSessionContext)) {
+            const merged = new Map(localLanes.map((record) => [record.lane_id, record]));
+            for (const snapshot of grantContext.hierarchy) {
+                const contextLane = keepAliveLaneFromSnapshot(snapshot);
+                if (contextLane)
+                    merged.set(contextLane.lane_id, contextLane);
+            }
+            merged.set(currentLane.lane_id, currentLane);
+            lanes = [...merged.values()];
+        }
+        let exclusion = keepAliveExclusion(currentLane, lanes, retiredLaneIds, lineageAware, companyForLane);
+        if (exclusion === "superseded" && currentLane.state !== "done" && currentLane.state !== "interrupted") {
+            const runningSupersededMessageDeliveryEnabled = await readLanesRegistryFlag(LANE_RUNNING_SUPERSEDED_MESSAGE_DELIVERY_FLAG, { company: companyForLane(currentLane), env: ctx.env });
+            if (runningSupersededMessageDeliveryEnabled) {
+                const latestLane = readLane(ctx.hqRoot(), currentLane.lane_id);
+                if (latestLane.state === "killed" || latestLane.state === "cancelled") {
+                    return { lane: latestLane, exclusion: latestLane.state };
+                }
+                const latestLocalLanes = loadAllLanes(ctx.hqRoot());
+                currentLane = latestLane;
+                let latestLanes = latestLocalLanes;
+                dispatchedContextBound =
+                    grantContext !== undefined &&
+                        ctx.isSsmOwnerDispatch() &&
+                        sameHireGrantSenior(grantContext.expected_senior, currentLane.senior);
+                dispatchedSessionContext = dispatchedContextBound && currentLane.senior.kind === "session";
+                dispatchedContextAuthorized = dispatchedContextBound && (dispatchedCallerId !== undefined ||
+                    (dispatchedSessionId !== undefined && dispatchedSessionId === currentLane.senior.id));
+                if (dispatchedContextBound && grantContext &&
+                    (dispatchedCallerId !== undefined || dispatchedSessionContext)) {
+                    const merged = new Map(latestLocalLanes.map((record) => [record.lane_id, record]));
+                    for (const snapshot of grantContext.hierarchy) {
+                        const contextLane = keepAliveLaneFromSnapshot(snapshot);
+                        if (contextLane)
+                            merged.set(contextLane.lane_id, contextLane);
+                    }
+                    merged.set(currentLane.lane_id, currentLane);
+                    latestLanes = [...merged.values()];
+                }
+                lanes = latestLanes;
+                retiredLaneIds = loadRetiredLaneIds(ctx.hqRoot());
+                exclusion = keepAliveExclusion(currentLane, lanes, retiredLaneIds, lineageAware, companyForLane);
+                if (exclusion === "superseded" && currentLane.state !== "done" && currentLane.state !== "interrupted") {
+                    const callerLaneId = dispatchedContextBound ? dispatchedCallerId : undefined;
+                    const callerSessionId = dispatchedContextBound
+                        ? (dispatchedSessionId === undefined ? null : dispatchedSessionId)
+                        : undefined;
+                    const callerMayMessage = callerMayMessageSupersededLane(ctx, currentLane, lanes, lineageAware, companyForLane, callerLaneId, callerSessionId);
+                    return {
+                        lane: currentLane,
+                        exclusion: undefined,
+                        ...(!dispatchedContextAuthorized && callerMayMessage && ctx.env.HQ_LANE_ID?.trim()
+                            ? { supersededMessageCallerId: ctx.env.HQ_LANE_ID.trim() }
+                            : {}),
+                        ...(callerMayMessage && !dispatchedContextBound && currentLane.senior.kind === "session" &&
+                            typeof currentLane.senior.id === "string" &&
+                            currentLane.senior.id.length > 0 &&
+                            callerMatchesSessionSenior(ctx, currentLane.senior.id)
+                            ? { supersededMessageSessionId: currentLane.senior.id }
+                            : {}),
+                        supersededMessageWarning: `A newer lead supersedes this ${currentLane.state} lane; message delivery is allowed while the lane remains active.`,
+                    };
+                }
+            }
+        }
+        const callerLaneId = dispatchedContextBound ? dispatchedCallerId : undefined;
+        const callerSessionId = dispatchedContextBound
+            ? (dispatchedSessionId === undefined ? null : dispatchedSessionId)
+            : undefined;
+        if (exclusion === "superseded" && callerMayMessageSupersededLane(ctx, currentLane, lanes, lineageAware, companyForLane, callerLaneId, callerSessionId)) {
+            return {
+                lane: currentLane,
+                exclusion: undefined,
+                ...(!dispatchedContextAuthorized && ctx.env.HQ_LANE_ID?.trim()
+                    ? { supersededMessageCallerId: ctx.env.HQ_LANE_ID.trim() }
+                    : {}),
+                ...(!dispatchedContextBound && currentLane.senior.kind === "session" &&
+                    typeof currentLane.senior.id === "string" &&
+                    currentLane.senior.id.length > 0 &&
+                    callerMatchesSessionSenior(ctx, currentLane.senior.id)
+                    ? { supersededMessageSessionId: currentLane.senior.id }
+                    : {}),
+            };
+        }
+        return { lane: currentLane, exclusion };
+    }
+    function recordMessageUndeliverable(ctx, lane, reason, messageCount) {
+        writeWatcherDecision(watcherOutLogPath(ctx.hqRoot(), lane.lane_id), {
+            event: "message_undeliverable",
+            at: ctx.now().toISOString(),
+            state: lane.state,
+            reason,
+            ...(messageCount === undefined ? {} : { message_count: messageCount }),
+        }, WATCHER_OUT_MAX_BYTES);
+    }
+    async function runMessage(ctx, laneId, opts) {
+        const hqRoot = ctx.hqRoot();
+        const requestedLaneId = laneId;
+        let accepted = false;
+        let claimedMessages = [];
+        let storySwitchRollback;
+        let storySwitchDeliveryStarted = false;
+        const readMessageText = (targetLaneId) => {
+            if (opts.text !== undefined && opts.textFile !== undefined) {
+                throw new LanesError("message_text_source_conflict", "Pass either --text or --text-file, not both", { lane_id: targetLaneId });
+            }
+            let messageText = opts.text;
+            if (opts.textFile !== undefined) {
+                const textPath = path.isAbsolute(opts.textFile)
+                    ? opts.textFile
+                    : path.resolve(ctx.callerCwd(), opts.textFile);
+                try {
+                    messageText = ctx.readFileSync(textPath, "utf8");
+                }
+                catch (err) {
+                    throw new LanesError("message_text_file_unreadable", `Could not read message text file ${opts.textFile}: ${err instanceof Error ? err.message : String(err)}`, { lane_id: targetLaneId, path: textPath });
+                }
+            }
+            if (messageText === undefined || messageText.length === 0) {
+                throw new LanesError("missing_text", "Pass non-empty message text with --text or --text-file", { lane_id: targetLaneId });
+            }
+            return messageText;
+        };
+        const markAccepted = () => {
+            accepted = true;
+            storySwitchDeliveryStarted = true;
+            opts.onAccepted?.();
+        };
+        let resolution;
+        try {
+            resolution = await deps.resolveCommandLane(ctx, laneId);
+        }
+        catch (err) {
+            const identity = ctx.readOutpostIdentity();
+            const failedOutpostIds = err instanceof LanesError ? err.details.failed_outpost_ids : undefined;
+            const probedOutpostIds = err instanceof LanesError ? err.details.probed_outpost_ids : undefined;
+            const primaryLookupFailed = Array.isArray(failedOutpostIds) && failedOutpostIds.includes("primary");
+            const primaryReportedMissing = Array.isArray(probedOutpostIds) && probedOutpostIds.includes("primary");
+            if (!(err instanceof LanesError) ||
+                err.error !== "lane_not_found" ||
+                identity.kind !== "id" ||
+                identity.id === "primary" ||
+                primaryLookupFailed ||
+                primaryReportedMissing) {
+                throw err;
+            }
+            const text = readMessageText(requestedLaneId);
+            await dispatchPrimaryLaneMessage(ctx, requestedLaneId, { ...opts, text });
+            return;
+        }
+        laneId = resolution.lane.lane_id;
+        let text = readMessageText(laneId);
+        const hireGrantContext = opts.grantContext === undefined
+            ? undefined
+            : (() => {
+                if (!ctx.isSsmOwnerDispatch()) {
+                    throw new LanesError("hire_grant_dispatch_unauthorized", "Message grant context is only valid on an Outpost owner dispatch", { lane_id: laneId });
+                }
+                return parseOutpostHireGrantContext(opts.grantContext, laneId);
+            })();
+        let lane = resolution.lane;
+        if (resolution.remoteOnly || (lane.host.kind === "outpost" && !laneIsHostedHere(ctx, lane))) {
+            const fallbackAt = lane.state === "awaiting_input" ? ctx.now().toISOString() : undefined;
+            const callerLaneId = ctx.env.HQ_LANE_ID?.trim();
+            const supersededMessageCallerId = callerLaneId === undefined || resolution.remoteOnly
+                ? undefined
+                : (await messageLaneExclusion(ctx, lane)).supersededMessageCallerId;
+            const sessionSeniorId = lane.senior.kind === "session" ? lane.senior.id : undefined;
+            const supersededMessageSessionId = !resolution.remoteOnly &&
+                typeof sessionSeniorId === "string" &&
+                sessionSeniorId.length > 0 &&
+                callerMatchesSessionSenior(ctx, sessionSeniorId)
+                ? sessionSeniorId
+                : undefined;
+            await dispatchOutpostLaneCommand(ctx, lane, "message", {
+                ...opts,
+                text,
+                ...(supersededMessageCallerId === undefined ? {} : { supersededMessageCallerId }),
+                ...(supersededMessageSessionId === undefined ? {} : { supersededMessageSessionId }),
+            }, {
+                ...(resolution.remoteOnly
+                    ? { syncPrimary: false, expectedOwnerHost: resolution.ownerHost }
+                    : {}),
+                ...(fallbackAt === undefined ? {} : {
+                    afterFallbackResume: () => deps.cancelFallbackQuestionsForLane(ctx, lane, "message", fallbackAt),
+                }),
+            });
+            return;
+        }
+        assertLaneRunsHereForOperatorMutation(ctx, lane, "message");
+        if (lane.state === "running") {
+            const workerPidPath = path.join(laneRunDir(hqRoot, laneId), "worker.pid");
+            const workerRecordExists = fs.existsSync(workerPidPath);
+            const worker = readPidRecord(workerPidPath);
+            if (workerRecordExists && worker === null) {
+                throw new LanesError("worker_pid_invalid", `Lane ${laneId} has a malformed worker PID record; message delivery cannot be classified safely`, { lane_id: laneId, worker_pid_path: workerPidPath });
+            }
+            // A fresh spawn may have committed running before publishing worker.pid;
+            // absence is not proof of exit. Reclassify only a recorded process that
+            // fails the PID plus start-time identity probe.
+            const processAlive = worker === null
+                ? true
+                : probePidRecord(worker, ctx.isAlive ?? isPidAlive, ctx.readStarttime ?? readProcStarttime).alive;
+            if (worker !== null && !processAlive) {
+                // The watcher may not have reached its next poll yet. Run the same
+                // classifier synchronously, then make the queue/resume choice again.
+                await runWatcherLoop(hqRoot, laneId, {
+                    ...ctx.watcherLoopDeps,
+                    now: () => ctx.now().getTime(),
+                    isAlive: ctx.isAlive ?? isPidAlive,
+                    readStarttime: ctx.readStarttime ?? readProcStarttime,
+                    mesh: null,
+                    resolveQuestionActiveCompany: () => resolveActiveQuestionCompany(ctx),
+                    deliverLaneSeniorMessage: async (seniorLaneId, seniorText) => {
+                        await runMessage(ctx, seniorLaneId, { text: seniorText, silent: true });
+                    },
+                });
+                lane = readLane(hqRoot, laneId);
+                // This invocation won the race to classify the dead worker, so the
+                // watcher callback did not own recovery. Fold any earlier queued
+                // messages into this resume to keep one provider turn and one delivery.
+                if (laneDeliveryMechanism(lane) === "resume" && dropboxInboxHasMessages(hqRoot, laneId)) {
+                    const queuedMessages = drainDropbox(hqRoot, laneId);
+                    if (queuedMessages.length > 0) {
+                        claimedMessages = queuedMessages;
+                        text = `${formatDropboxMessages(queuedMessages)}\n\n${text}`;
+                    }
+                }
+            }
+        }
+        try {
+            const eligibility = await messageLaneExclusion(ctx, lane, hireGrantContext);
+            lane = eligibility.lane;
+            const exclusion = eligibility.exclusion;
+            if (exclusion !== undefined) {
+                let messageCount;
+                if (dropboxInboxHasMessages(hqRoot, laneId)) {
+                    messageCount = drainDropbox(hqRoot, laneId, { archiveDirectory: "undeliverable" }).length;
+                }
+                recordMessageUndeliverable(ctx, lane, exclusion, messageCount);
+                const refusalMessage = deliveryRefusalReason(lane);
+                throw new LanesError("lane_not_accepting_messages", refusalMessage || `Lane ${laneId} cannot receive messages: ${exclusion}`, { lane_id: laneId, state: lane.state, reason: exclusion });
+            }
+            if (lane.state === "done" && dropboxInboxHasMessages(hqRoot, laneId)) {
+                const staleMessages = drainDropbox(hqRoot, laneId, { archiveDirectory: "undeliverable" });
+                if (staleMessages.length > 0) {
+                    recordMessageUndeliverable(ctx, lane, "done_before_queued_message", staleMessages.length);
+                }
+            }
+            const cliEffort = parseCliEffort(lane.provider, opts.effort);
+            if (cliEffort !== undefined && !providerSupportsSessionResume(lane.provider)) {
+                throw new LanesError("effort_resume_unsupported", `Provider ${lane.provider} cannot change effort on a resumed session`, { lane_id: laneId, provider: lane.provider });
+            }
+            // Check before transcript recovery, account probing, or message writes.
+            // The final state transition repeats this check under the senior lock.
+            await withResumeHireAdmission(ctx, lane, () => undefined, hireGrantContext);
+            lane = laneWithRecoveredProviderSession(hqRoot, lane);
+            const keepCurrentAccount = opts.account !== undefined && accountRequestKeepsCurrentLane(lane, opts.account);
+            if (keepCurrentAccount)
+                assertCurrentResumeAccountAvailable(ctx, lane);
+            // A real account move is refused on its own terms first: a running lane and
+            // a provider without session resume get the move's named errors, not the
+            // generic delivery refusal below. Naming the current account is a keep.
+            if (opts.account !== undefined && !keepCurrentAccount && lane.state === "running") {
+                throw new LanesError("lane_running", `Lane ${laneId} is running; stop it or wait for it to exit before moving its session`, {
+                    lane_id: laneId,
+                    state: lane.state,
+                });
+            }
+            if (opts.account !== undefined && !keepCurrentAccount && !providerSessionPortable(lane.provider)) {
+                throw new LanesError("provider_session_not_portable", sessionNotPortableMessage(lane.provider), { lane_id: laneId, provider: lane.provider });
+            }
+            const pendingAnswerableQuestion = lane.state === "awaiting_input"
+                ? await deps.hasPendingQuestionForLane(ctx, lane)
+                : false;
+            if (pendingAnswerableQuestion) {
+                const message = deliveryRefusalReason(lane);
+                throw new LanesError("lane_not_accepting_messages", message, {
+                    lane_id: laneId,
+                    state: lane.state,
+                    provider: lane.provider,
+                    message,
+                });
+            }
+            const awaitingInputFallback = lane.state === "awaiting_input" && !pendingAnswerableQuestion;
+            // One decision point for how a follow-up reaches this lane (delivery.ts).
+            // `none` refuses before anything is written: no inbox append, no spawn.
+            const mechanism = laneDeliveryMechanism(lane);
+            if (mechanism === "none") {
+                const message = deliveryRefusalReason(lane);
+                throw new LanesError("lane_not_accepting_messages", message, {
+                    lane_id: laneId,
+                    state: lane.state,
+                    provider: lane.provider,
+                    message,
+                });
+            }
+            if (keepCurrentAccount && opts.model !== undefined && mechanism !== "resume") {
+                throw new LanesError("model_requires_resume", "--model with --account requires a message that resumes the lane", { lane_id: laneId, state: lane.state });
+            }
+            if (opts.worker !== undefined && mechanism === "dropbox") {
+                throw new LanesError("worker_profile_requires_resume", `Lane ${laneId} is still running; --worker can only be applied when message starts a resumed provider turn`, { lane_id: laneId, state: lane.state });
+            }
+            if (cliEffort !== undefined && mechanism === "dropbox") {
+                throw new LanesError("lane_effort_requires_resume", `Lane ${laneId} is still running; --effort can only be applied when message starts a resumed provider turn`, { lane_id: laneId, state: lane.state });
+            }
+            const resumeProfile = opts.worker !== undefined
+                ? resolveResumeProfile(ctx, lane, opts.worker)
+                : undefined;
+            if (opts.model !== undefined && opts.account === undefined) {
+                throw new LanesError("model_requires_account", "--model on hq lanes message is only accepted together with --account", {});
+            }
+            let quotaHoldDeferred;
+            let automaticAccountSelection = undefined;
+            if (opts.account === undefined && mechanism === "resume") {
+                try {
+                    automaticAccountSelection = await selectAutomaticClaudeResumeAccount(ctx, lane, resumeProfile, {
+                        tolerateInvalidHostLaneLists: lane.host.kind === "local",
+                    });
+                }
+                catch (err) {
+                    const reasons = err instanceof LanesError && err.error === "claude_account_balance_no_eligible_account" &&
+                        Array.isArray(err.details.account_reasons)
+                        ? err.details.account_reasons.filter((reason) => reason !== null && typeof reason === "object" && !Array.isArray(reason))
+                        : [];
+                    const held = reasons.filter((reason) => reason.reason === "quota_held");
+                    if (held.length === 0)
+                        throw err;
+                    const resetTimes = held
+                        .map((reason) => reason.quota_reset_at)
+                        .filter((value) => typeof value === "string" && Number.isFinite(Date.parse(value)))
+                        .sort((a, b) => Date.parse(a) - Date.parse(b));
+                    quotaHoldDeferred = {
+                        ...(resetTimes[0] !== undefined ? { quota_reset_at: resetTimes[0] } : {}),
+                        ...(lane.model !== undefined ? { model: lane.model } : {}),
+                    };
+                    automaticAccountSelection = undefined;
+                }
+            }
+            const resumeEffort = resolveResumeEffort(ctx, lane, {
+                cliEffort,
+                profile: resumeProfile,
+                account: keepCurrentAccount ? lane.account : opts.account ?? automaticAccountSelection?.selection.account,
+                model: opts.model,
+            });
+            const messageId = mintMessageId();
+            const at = ctx.now().toISOString();
+            const projectId = opts.project?.trim() || lane.project_id;
+            const storyId = opts.story?.trim() || lane.story_id;
+            if (opts.story !== undefined && !opts.story.trim()) {
+                throw new LanesError("missing_story", "--story must be non-empty", {});
+            }
+            if ((opts.project !== undefined || opts.story !== undefined) && ctx.storyLedgerEnabled()) {
+                validateProjectStories(hqRoot, projectId, [storyId], lane.company?.slug);
+            }
+            const notice = storySwitchNotice(lane.project_id, lane.story_id, projectId, storyId);
+            const promptedText = notice === undefined ? text : `${notice}\n\n${text}`;
+            const framedMonitorEvent = opts.monitorEvent === undefined
+                ? undefined
+                : formatMonitorEvent({
+                    monitorId: opts.monitorEvent.monitor_id,
+                    description: opts.monitorEvent.description,
+                    sequence: opts.monitorEvent.sequence,
+                    text: promptedText,
+                });
+            const deliveryText = framedMonitorEvent ?? promptedText;
+            const messageHistoryTrigger = opts.monitorEvent !== undefined
+                ? "monitor_event"
+                : opts.messageSource ?? "message";
+            const isMonitorEvent = messageHistoryTrigger === "monitor_event";
+            const isSystemNotice = messageHistoryTrigger === "system_notice";
+            const dropboxMessage = {
+                at,
+                message_id: messageId,
+                text: promptedText,
+                project_id: projectId,
+                story_id: storyId,
+                ...(opts.monitorEvent === undefined ? {} : {
+                    kind: "monitor_event",
+                    monitor_id: opts.monitorEvent.monitor_id,
+                    description: opts.monitorEvent.description,
+                    sequence: opts.monitorEvent.sequence,
+                }),
+            };
+            if (projectId !== lane.project_id || storyId !== lane.story_id) {
+                lane = casUpdateLane(hqRoot, laneId, (current) => {
+                    const already = current.attribution_history.some((entry) => entry.message_id === messageId);
+                    if (already)
+                        return current;
+                    const existingStory = laneStory(current, projectId, storyId);
+                    storySwitchRollback = {
+                        message_id: messageId,
+                        project_id: current.project_id,
+                        story_id: current.story_id,
+                        no_story_reason: current.no_story_reason,
+                        ...(!existingStory ? {
+                            added_story: { project_id: projectId, story_id: storyId, status: "in_progress", added_at: at, updated_at: at },
+                        } : {}),
+                        story_switch_unacknowledged: current.story_switch_unacknowledged,
+                    };
+                    return {
+                        ...current,
+                        project_id: projectId,
+                        story_id: storyId,
+                        no_story_reason: storyId ? undefined : current.no_story_reason,
+                        stories: laneStory(current, projectId, storyId)
+                            ? laneStories(current)
+                            : [
+                                ...laneStories(current),
+                                { project_id: projectId, story_id: storyId, status: "in_progress", added_at: at, updated_at: at },
+                            ],
+                        attribution_history: appendCappedHistory(current.attribution_history, {
+                            project_id: projectId,
+                            story_id: storyId,
+                            message_id: messageId,
+                            at,
+                        }),
+                        story_switch_pending: {
+                            previous_project_id: current.project_id,
+                            previous_story_id: current.story_id,
+                            project_id: projectId,
+                            story_id: storyId,
+                            message_id: messageId,
+                            at,
+                            previous_artifact_keys: artifactIdentityKeys(current.last_envelope?.artifacts),
+                        },
+                        story_switch_unacknowledged: undefined,
+                    };
+                });
+            }
+            let resumed = null;
+            let move = null;
+            let queuedOnAdmission = false;
+            let queuedOnQuotaHold = false;
+            if (quotaHoldDeferred !== undefined) {
+                const sessionId = lane.provider_session_id;
+                if (!sessionId) {
+                    throw new LanesError("no_provider_session", `Lane ${laneId} has no provider session id to queue this message`, {
+                        lane_id: laneId,
+                        provider: lane.provider,
+                    });
+                }
+                lane = casUpdateLane(hqRoot, laneId, (current) => {
+                    if (current.version !== lane.version || current.state !== lane.state) {
+                        throw new LanesError("lane_admission_conflict", `Lane ${laneId} changed while its quota-held message was queued`, {
+                            lane_id: laneId,
+                            prepared_version: lane.version,
+                            version: current.version,
+                            state: current.state,
+                        });
+                    }
+                    return {
+                        ...current,
+                        state: "queued",
+                        queued_reason: "account_retry",
+                        queued_details: undefined,
+                        queued_at: at,
+                        admission_reserved_at: undefined,
+                        pending_resume: {
+                            session_id: sessionId,
+                            trigger: "message",
+                            caller: ctx.env.HQ_LANE_ID?.trim() || "user",
+                            text: deliveryText,
+                            ...(opts.monitorEvent === undefined ? {} : { monitor_event: true }),
+                            message_id: messageId,
+                            compact: opts.compact !== false,
+                            at,
+                        },
+                    };
+                });
+                queuedOnQuotaHold = true;
+                storySwitchDeliveryStarted = true;
+                markAccepted();
+                deps.onLaneMessageQueued?.(laneId, "quota_hold");
+            }
+            else if (opts.account !== undefined && !keepCurrentAccount) {
+                // A moved message is always a resume on the target account: a running
+                // lane (the dropbox mechanism) is refused inside prepareAccountMove.
+                move = await prepareAccountMove(ctx, lane, {
+                    account: opts.account,
+                    cliModel: opts.model?.trim() || undefined,
+                    ...(resumeProfile !== undefined ? { workerProfile: resumeProfile } : {}),
+                    ...(resumeEffort !== undefined ? { effort: resumeEffort } : {}),
+                    ...(hireGrantContext !== undefined ? { grantContext: hireGrantContext } : {}),
+                    pending: {
+                        trigger: messageHistoryTrigger,
+                        text: deliveryText,
+                        ...(isMonitorEvent ? { monitor_event: true } : {}),
+                        message_id: messageId,
+                        compact: opts.compact !== false,
+                    },
+                });
+                lane = move.lane;
+                if (move.queued) {
+                    storySwitchDeliveryStarted = true;
+                    deps.onLaneMessageQueued?.(laneId, "account_move");
+                    archiveResumeMessage(hqRoot, laneId, dropboxMessage);
+                }
+            }
+            else if (mechanism === "resume") {
+                const automatic = automaticAccountSelection;
+                if (automatic !== undefined) {
+                    const selection = automatic.selection;
+                    if (selection.account !== lane.account) {
+                        move = await prepareAccountMove(ctx, lane, {
+                            account: selection.account,
+                            cliModel: undefined,
+                            ...(automatic.historyReason !== undefined ? { accountHistoryReason: automatic.historyReason } : {}),
+                            ...(resumeProfile !== undefined ? { workerProfile: resumeProfile } : {}),
+                            ...(resumeEffort !== undefined ? { effort: resumeEffort } : {}),
+                            ...(hireGrantContext !== undefined ? { grantContext: hireGrantContext } : {}),
+                            pending: {
+                                trigger: messageHistoryTrigger,
+                                text: deliveryText,
+                                ...(isMonitorEvent ? { monitor_event: true } : {}),
+                                message_id: messageId,
+                                compact: opts.compact !== false,
+                            },
+                            accountSelection: selection,
+                        });
+                        lane = move.lane;
+                        if (move.queued) {
+                            storySwitchDeliveryStarted = true;
+                            deps.onLaneMessageQueued?.(laneId, "account_move");
+                            archiveResumeMessage(hqRoot, laneId, dropboxMessage);
+                        }
+                    }
+                    else {
+                        lane = persistClaudeAccountSelection(hqRoot, lane, selection);
+                    }
+                }
+            }
+            if (resumeProfile !== undefined && (opts.account === undefined || keepCurrentAccount)) {
+                validateResumeProfileModel(ctx, lane, resumeProfile.profile);
+            }
+            if (move === null && (resumeProfile !== undefined || resumeEffort !== undefined || (keepCurrentAccount && opts.model !== undefined))) {
+                lane = recordResumeSetup(ctx, lane, {
+                    ...(resumeProfile !== undefined ? { profile: resumeProfile } : {}),
+                    ...(resumeEffort !== undefined ? { effort: resumeEffort } : {}),
+                    ...(keepCurrentAccount && opts.model !== undefined ? { cliModel: opts.model } : {}),
+                });
+            }
+            let questionCancellation = null;
+            if (move?.queued || queuedOnQuotaHold) {
+                // Parked at the target's cap: reconcile resumes the session there.
+                markAccepted();
+                questionCancellation = awaitingInputFallback
+                    ? await deps.cancelFallbackQuestionsForLane(ctx, lane, "message", at)
+                    : null;
+            }
+            else {
+                const dispatched = await dispatchLaneDelivery(lane, {
+                    dropbox: () => {
+                        // Live (or about-to-be-live) process: the PreToolUse drain delivers it.
+                        if (!laneAcceptsOperatorMessage(lane)) {
+                            throw new LanesError("lane_not_accepting_messages", operatorMessageRefusalReason(lane.state), { lane_id: laneId, state: lane.state });
+                        }
+                        appendDropboxMessage(hqRoot, laneId, dropboxMessage);
+                        storySwitchDeliveryStarted = true;
+                        return null;
+                    },
+                    resume: async () => {
+                        // Exited worker with a recorded session: queue the message when capacity
+                        // is occupied, otherwise start its next turn under the shared admission lock.
+                        assertLaneRunsHereForAdmission(ctx, lane);
+                        return withLaneAdmissionLock(hqRoot, lane.provider, async () => {
+                            const admission = await assessLaneAdmission(ctx, lane, { queueAt: at });
+                            if (admission.action === "refuse" && admission.error)
+                                throw admission.error;
+                            const guardEnabled = admission.action === "queue" ? false : await lowDiskGuardEnabledForLane(hqRoot, lane);
+                            return withResumeHireAdmission(ctx, lane, () => {
+                                if (admission.action === "queue") {
+                                    const sessionId = lane.provider_session_id;
+                                    if (!sessionId) {
+                                        throw new LanesError("no_provider_session", `Lane ${laneId} has no provider session id to queue this message resume`, {
+                                            lane_id: laneId,
+                                            provider: lane.provider,
+                                        });
+                                    }
+                                    archiveResumeMessage(hqRoot, laneId, dropboxMessage);
+                                    queuedOnAdmission = true;
+                                    const queued = casUpdateLane(hqRoot, laneId, (current) => {
+                                        if (current.version !== lane.version || current.state !== lane.state) {
+                                            throw new LanesError("lane_admission_conflict", `Lane ${laneId} changed while message admission was checked`, {
+                                                lane_id: laneId,
+                                                prepared_version: lane.version,
+                                                version: current.version,
+                                                state: current.state,
+                                            });
+                                        }
+                                        return {
+                                            ...current,
+                                            state: "queued",
+                                            queued_reason: admission.reason ?? "throttle",
+                                            queued_details: undefined,
+                                            queued_at: at,
+                                            pending_resume: {
+                                                session_id: sessionId,
+                                                trigger: messageHistoryTrigger,
+                                                caller: ctx.env.HQ_LANE_ID?.trim() || "user",
+                                                text: deliveryText,
+                                                ...(isMonitorEvent ? { monitor_event: true } : {}),
+                                                message_id: messageId,
+                                                compact: opts.compact !== false,
+                                                at,
+                                            },
+                                        };
+                                    });
+                                    storySwitchDeliveryStarted = true;
+                                    deps.onLaneMessageQueued?.(laneId, "admission");
+                                    return queued;
+                                }
+                                const started = spawnLaneWorker(hqRoot, lane, {
+                                    lowDiskGuardEnabled: guardEnabled,
+                                    env: ctx.env,
+                                    modelDeps: {
+                                        readFileSync: ctx.readFileSync,
+                                        probe: ctx.probeProvider,
+                                        env: ctx.env,
+                                    },
+                                    existsSync: ctx.existsSync,
+                                    spawnProcess: ctx.spawnProcess,
+                                    proveDetached: ctx.proveDetached,
+                                    killProcess: ctx.killProcess,
+                                    now: ctx.now,
+                                    resolveMachineIdentity: ctx.resolveMachineIdentity,
+                                    runCompaction: ctx.runCompaction,
+                                    locateTranscript: ctx.locateTranscript,
+                                }, {
+                                    trigger: {
+                                        kind: "message",
+                                        text: deliveryText,
+                                        message_id: messageId,
+                                        ...(isMonitorEvent ? { monitor_event: true } : {}),
+                                        ...(isSystemNotice ? { system_notice: true } : {}),
+                                    },
+                                    compact: opts.compact !== false,
+                                    effort: resumeEffort ?? recordedResumeEffort(lane),
+                                });
+                                storySwitchDeliveryStarted = true;
+                                deps.onLaneWorkerStarted?.(laneId, "message");
+                                archiveResumeMessage(hqRoot, laneId, dropboxMessage);
+                                return started;
+                            }, hireGrantContext);
+                        }, ctx.sleep);
+                    },
+                }, mechanism);
+                if (dispatched.mechanism === "resume")
+                    resumed = dispatched.value;
+                markAccepted();
+                questionCancellation = awaitingInputFallback
+                    ? await deps.cancelFallbackQuestionsForLane(ctx, lane, "message", at)
+                    : null;
+            }
+            // Every accepted message moves the compaction reference forward.
+            const next = casUpdateLane(hqRoot, laneId, (current) => ({
+                ...resetKeepAliveProgress(current),
+                last_message_at: at,
+            }));
+            // What this command can claim when it returns: the message is durably
+            // written (accepted). Delivery to the model is asynchronous in both
+            // mechanisms. `dropbox` delivers on the worker's next tool call, and only
+            // if the drain hook is registered in the account home the worker was
+            // started from; `resume` has started a new worker with the message as its
+            // prompt. Neither is "delivered", so the response never says so.
+            const drainHook = drainHookStatusFor(ctx, next);
+            const deliveryStatus = move?.queued
+                ? "queued_on_target_account"
+                : queuedOnQuotaHold
+                    ? "queued_on_quota_hold"
+                    : queuedOnAdmission
+                        ? "queued_on_admission"
+                        : mechanism === "dropbox"
+                            ? "awaiting_next_tool_call"
+                            : "worker_spawned";
+            const warning = [
+                eligibility.supersededMessageWarning,
+                mechanism === "dropbox" && drainHook !== null && !drainHook.registered
+                    ? `The drain hook is not registered in ${drainHook.path}; the running worker will not receive this message. It stays in the inbox and is delivered on the lane's next start.`
+                    : mechanism === "dropbox" && next.stalled === true
+                        ? `The worker has made no tool call since ${next.stalled_at ?? "an unknown time"} (${next.stalled_reason ?? "stalled"}); delivery waits on its next tool call.`
+                        : null,
+            ].filter((message) => message !== undefined && message !== null).join(" ") || null;
+            if (!opts.silent)
+                printJson({
+                    ok: true,
+                    action: "message",
+                    lane_id: laneId,
+                    message_id: messageId,
+                    accepted: true,
+                    delivered: false,
+                    delivery: mechanism,
+                    delivered_to: { host: lane.host.id, lane_id: laneId, mechanism },
+                    delivery_status: deliveryStatus,
+                    ...(queuedOnQuotaHold ? {
+                        queued_reason: "account_quota_held",
+                        quota_hold: {
+                            reason: "account_quota_held",
+                            quota_reset_at: quotaHoldDeferred?.quota_reset_at ?? null,
+                            model: quotaHoldDeferred?.model ?? null,
+                        },
+                    } : {}),
+                    inbox_path: mechanism === "dropbox" ? dropboxInboxPath(hqRoot, laneId) : null,
+                    drain_hook: drainHook,
+                    warning,
+                    ...(questionCancellation === null ? {} : {
+                        cancelled_questions: questionCancellation.cancelled_question_ids,
+                        question_cancellation_failures: questionCancellation.failures,
+                    }),
+                    resumed_session_id: resumed?.last_resume?.session_id ?? null,
+                    compaction: resumed?.last_compaction && resumed.last_compaction.resume_at === resumed.last_resume?.at
+                        ? resumed.last_compaction
+                        : null,
+                    account_move: move ? accountMoveSummary(move) : null,
+                    project_id: next.project_id,
+                    story_id: next.story_id,
+                    stories: laneStories(next),
+                    story_warning: storyWarning(next) ?? null,
+                    lane: next,
+                });
+        }
+        catch (err) {
+            if (storySwitchRollback !== undefined && !storySwitchDeliveryStarted) {
+                try {
+                    casUpdateLane(hqRoot, laneId, (current) => rollbackStorySwitchAttribution(current, storySwitchRollback));
+                }
+                catch (rollbackErr) {
+                    const rollbackMessage = rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr);
+                    process.stderr.write(`Could not roll back story attribution after message failure: ${rollbackMessage}\n`);
+                }
+            }
+            if (claimedMessages.length > 0 && !accepted) {
+                const error = err instanceof Error ? err.message : String(err);
+                writeWatcherDecision(watcherOutLogPath(hqRoot, laneId), {
+                    event: "message_recovery_failed",
+                    at: ctx.now().toISOString(),
+                    state: lane.state,
+                    error,
+                    message_count: claimedMessages.length,
+                }, WATCHER_OUT_MAX_BYTES);
+                try {
+                    requeueDropboxMessages(hqRoot, laneId, claimedMessages);
+                }
+                catch (requeueErr) {
+                    const requeueMessage = requeueErr instanceof Error ? requeueErr.message : String(requeueErr);
+                    writeWatcherDecision(watcherOutLogPath(hqRoot, laneId), {
+                        event: "message_requeue_failed",
+                        at: ctx.now().toISOString(),
+                        state: lane.state,
+                        recovery_error: error,
+                        requeue_error: requeueMessage,
+                        message_count: claimedMessages.length,
+                    }, WATCHER_OUT_MAX_BYTES);
+                    throw new LanesError("message_requeue_failed", `Could not return ${claimedMessages.length} queued lane message(s) to the inbox after recovery failed: ${requeueMessage}`, { lane_id: laneId, message_count: claimedMessages.length, recovery_error: error });
+                }
+            }
+            throw err;
+        }
+    }
+    /**
+     * Watcher and reconcile call the hidden command below after they win the
+     * terminal transition. The inbox is claimed once with the normal atomic
+     * dropbox drain, and an accepted message is routed through runMessage so the
+     * existing provider, admission, account, worker-profile and senior checks
+     * remain authoritative.
+     */
+    async function recoverQueuedMessages(ctx, laneId) {
+        const hqRoot = ctx.hqRoot();
+        let lane = readLane(hqRoot, laneId);
+        if (!dropboxInboxHasMessages(hqRoot, laneId))
+            return { action: "none", message_count: 0 };
+        const eligibility = await messageLaneExclusion(ctx, lane);
+        lane = eligibility.lane;
+        const exclusion = eligibility.exclusion;
+        const refusal = exclusion ?? (lane.state === "done"
+            ? "done_before_envelope"
+            : lane.state === "awaiting_input"
+                ? "awaiting_input_requires_question_answer"
+                : laneDeliveryMechanism(lane) !== "resume"
+                    ? `no_resume_path_for_${lane.state}`
+                    : undefined);
+        if (refusal !== undefined) {
+            const messages = drainDropbox(hqRoot, laneId, { archiveDirectory: "undeliverable" });
+            if (messages.length > 0)
+                recordMessageUndeliverable(ctx, lane, refusal, messages.length);
+            return { action: messages.length > 0 ? "undeliverable" : "none", message_count: messages.length };
+        }
+        const messages = drainDropbox(hqRoot, laneId);
+        if (messages.length === 0)
+            return { action: "none", message_count: 0 };
+        let accepted = false;
+        try {
+            await runMessage(ctx, laneId, {
+                text: formatDropboxMessages(messages),
+                messageSource: messages.some((message) => message.kind === "monitor_event")
+                    ? "monitor_event"
+                    : messages.some((message) => message.kind === "system_notice")
+                        ? "system_notice"
+                        : undefined,
+                compact: false,
+                silent: true,
+                onAccepted: () => { accepted = true; },
+            });
+            return { action: "resumed", message_count: messages.length };
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            writeWatcherDecision(watcherOutLogPath(hqRoot, laneId), {
+                event: "message_recovery_failed",
+                at: ctx.now().toISOString(),
+                state: lane.state,
+                error,
+                message_count: messages.length,
+            }, WATCHER_OUT_MAX_BYTES);
+            if (!accepted) {
+                try {
+                    requeueDropboxMessages(hqRoot, laneId, messages);
+                }
+                catch (requeueErr) {
+                    const requeueMessage = requeueErr instanceof Error ? requeueErr.message : String(requeueErr);
+                    writeWatcherDecision(watcherOutLogPath(hqRoot, laneId), {
+                        event: "message_requeue_failed",
+                        at: ctx.now().toISOString(),
+                        state: lane.state,
+                        recovery_error: error,
+                        requeue_error: requeueMessage,
+                        message_count: messages.length,
+                    }, WATCHER_OUT_MAX_BYTES);
+                    throw new LanesError("message_requeue_failed", `Could not return ${messages.length} queued lane message(s) to the inbox after recovery failed: ${requeueMessage}`, { lane_id: laneId, message_count: messages.length, recovery_error: error });
+                }
+            }
+            throw err;
+        }
+    }
+    return { runMessage, recoverQueuedMessages };
+}
+//# sourceMappingURL=lanes-message.js.map