@indigoai-us/hq-cli 5.314.0 → 5.315.0

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

@@ -0,0 +1,449 @@
+import type { LaneCompanyRef, LanePlacementPolicy, LaneRecord, LanesConfig, QuestionAnswer, QuestionBody, QuestionRecord, SeniorRef, AccountHistoryEntry, LaneAccountSelection, PendingResume, QueuedReason, ResolvedLaneWorker, LivenessDeps, MachineIdentity, MonitorEvidenceReader, ReconcileHost, RunCommand, ThrottleDeps, withLaneHireLocks } from "../lib/lanes/index.js";
+import type { OutpostIdentity } from "../lib/lanes/admission-host.js";
+import type { OutpostDispatchResult } from "../lib/lanes/outpost-dispatch.js";
+import type { CpuBusySource } from "../lib/lanes/throttle.js";
+import type { ProbeCommand } from "../lib/lanes/models.js";
+import type { KillProcessFn, ProveDetachedFn, SpawnProcessFn } from "../lib/lanes/spawn.js";
+import type { WatcherLoopDeps } from "../lib/lanes/watcher.js";
+import type { RunCompactionFn } from "../lib/lanes/compaction.js";
+import type { LaneMesh, LaneMeshEvent } from "../lib/lanes/mesh-events.js";
+import type { BalanceHostGap, BalanceHostSnapshot } from "../lib/lanes/claude-balance.js";
+import type { HostCapacitySnapshot } from "../lib/lanes/host-capacity.js";
+import { LANE_OUTPOST_LOAD_BALANCING_FLAG } from "../lib/lanes/flag-keys.js";
+import { type ResolvedEffort } from "../lib/lanes/effort.js";
+import type { SessionCopyResult } from "../lib/lanes/move-account.js";
+import type { WorkerProfile } from "../lib/lanes/profile.js";
+import type { OutpostHireGrantContext } from "../lib/lanes/hire-grant-dispatch.js";
+import { LanesError } from "../lib/lanes/errors.js";
+export type { LaneCompanyRef, LaneRecord } from "../lib/lanes/index.js";
+export interface LaneAccountMove {
+    lane: LaneRecord;
+    from: string | null;
+    to: string;
+    copy: SessionCopyResult;
+    queued: boolean;
+}
+export type ResolvedResumeProfile = ResolvedLaneWorker & {
+    profile: NonNullable<ResolvedLaneWorker["profile"]>;
+};
+export interface ResumeProfileRepinAuthorization {
+    kind: "senior" | "ssm-owner-dispatch";
+    expectedSenior: SeniorRef;
+    actor: string;
+    reason: "resume --worker";
+    newHash: string;
+}
+export interface LaneMessageOptions {
+    text?: string;
+    textFile?: string;
+    project?: string;
+    story?: string;
+    compact?: boolean;
+    account?: string;
+    model?: string;
+    effort?: string;
+    worker?: string;
+    grantContext?: string;
+    /** Primary-verified caller identity for a superseded Outpost message. */
+    supersededMessageCallerId?: string;
+    /** Primary-verified session senior for a superseded Outpost message. */
+    supersededMessageSessionId?: string;
+    monitorEvent?: {
+        monitor_id: string;
+        description: string;
+        sequence: number;
+    };
+    /** Source kind for a message recovered from the lane dropbox. */
+    messageSource?: "monitor_event" | "system_notice";
+    /** Internal recovery messages do not emit a second command response. */
+    silent?: boolean;
+    /** Internal recovery claim is safe to archive once this callback runs. */
+    onAccepted?: () => void;
+}
+export interface LaneResumeOptions {
+    text?: string;
+    fromFailed?: boolean;
+    reason?: string;
+    failedResumeContext?: string;
+    project?: string;
+    story?: string;
+    compact?: boolean;
+    account?: string;
+    model?: string;
+    effort?: string;
+    worker?: string;
+    keepAlive?: boolean;
+    meshCompany?: string;
+    profileRepinContext?: string;
+    grantContext?: string;
+}
+export interface LaneBalanceMoveTargetOptions {
+    account?: string;
+    fromAccount?: string;
+    expectedState?: string;
+}
+export interface AdmissionResult {
+    action: "start" | "queue" | "refuse";
+    reason?: QueuedReason;
+    error?: LanesError;
+    throttle?: {
+        last_busy: number | null;
+        busy_source: CpuBusySource | undefined;
+        sampled_at: string | undefined;
+    };
+}
+export interface PrepareAccountMoveInput {
+    account: string;
+    cliModel: string | undefined;
+    preservedModel?: string;
+    accountHistoryReason?: AccountHistoryEntry["reason"];
+    workerProfile?: ResolvedResumeProfile;
+    profileRepin?: ResumeProfileRepinAuthorization;
+    effort?: ResolvedEffort;
+    grantContext?: OutpostHireGrantContext;
+    pending?: Omit<PendingResume, "session_id" | "at"> & {
+        trigger: PendingResume["trigger"];
+    };
+    /** Copy the session and change account while preserving the between-turn state. */
+    deferTurnStart?: boolean;
+    accountSelection?: LaneAccountSelection;
+}
+export interface RecordResumeSetupInput {
+    profile?: ResolvedResumeProfile;
+    effort?: ResolvedEffort;
+    keepAlive?: boolean;
+    cliModel?: string;
+    meshCompany?: LaneCompanyRef;
+    threadId?: string;
+    profileRepin?: ResumeProfileRepinAuthorization;
+    /** Clear only the recoverable worker_profile_changed queue after its profile is revalidated. */
+    clearWorkerProfileChangedQueue?: boolean;
+}
+export declare function accountRequestKeepsCurrentLane(lane: LaneRecord, rawAccount: string): boolean;
+export declare function assertCurrentResumeAccountAvailable(ctx: Ctx, lane: LaneRecord): void;
+export declare function accountMoveSummary(move: LaneAccountMove): Record<string, unknown>;
+export declare function hasKeepAliveProgress(lane: LaneRecord): boolean;
+export declare function resetKeepAliveProgress(lane: LaneRecord): LaneRecord;
+export declare function resolveResumeEffort(ctx: Ctx, lane: LaneRecord, input: {
+    cliEffort?: string;
+    profile?: ResolvedResumeProfile;
+    account?: string;
+    model?: string;
+}): ResolvedEffort | undefined;
+export declare function recordedResumeEffort(lane: LaneRecord): ResolvedEffort;
+export type CommandLaneResolution = {
+    lane: LaneRecord;
+    remoteOnly: false;
+} | {
+    lane: LaneRecord;
+    remoteOnly: true;
+    outpostId: string;
+    ownerHost: LaneRecord["host"];
+};
+export interface FallbackQuestionCancellationResult {
+    cancelled_question_ids: string[];
+    failures: Array<{
+        question_id?: string;
+        error: string;
+    }>;
+}
+export interface OutpostLaneDispatchBehavior {
+    /** Keep remote-only lanes out of the primary lane store. */
+    syncPrimary?: boolean;
+    /** Host identity returned by the remote record lookup for a remote-only lane. */
+    expectedOwnerHost?: LaneRecord["host"];
+    /** Run after a successful remote awaiting_input fallback, before printing. */
+    afterFallbackResume?: () => Promise<FallbackQuestionCancellationResult>;
+}
+export interface LaneMessageHandlerDeps {
+    /** Test seam invoked after a provider worker has been started. */
+    onLaneWorkerStarted?: (laneId: string, command: "message" | "resume") => void;
+    /** Test seam invoked after a message has been durably queued for a lane. */
+    onLaneMessageQueued?: (laneId: string, path: "admission" | "account_move" | "quota_hold") => void;
+    archiveResumeMessage(hqRoot: string, laneId: string, message: {
+        message_id: string;
+        [key: string]: unknown;
+    }): void;
+    assertLaneRunsHereForAdmission(ctx: Ctx, lane: LaneRecord): void;
+    assertLaneRunsHereForOperatorMutation(ctx: Ctx, lane: LaneRecord, action: string): void;
+    assessLaneAdmission(ctx: Ctx, lane: LaneRecord, options: {
+        account?: string;
+        queueAt: string;
+        alreadyQueued?: boolean;
+    }): Promise<AdmissionResult>;
+    casUpdateLane(hqRoot: string, laneId: string, updater: (current: LaneRecord) => LaneRecord): LaneRecord;
+    dispatchOutpostLaneCommand(ctx: Ctx, lane: LaneRecord, action: "message" | "resume", options: LaneMessageOptions | LaneResumeOptions, behavior?: OutpostLaneDispatchBehavior): Promise<void>;
+    dispatchPrimaryLaneMessage(ctx: Ctx, laneId: string, options: LaneMessageOptions): Promise<void>;
+    drainHookStatusFor(ctx: Ctx, lane: LaneRecord): {
+        registered: boolean;
+        kind: string;
+        path: string;
+    } | null;
+    laneIsHostedHere(ctx: Ctx, lane: LaneRecord): boolean;
+    laneWithRecoveredProviderSession(hqRoot: string, lane: LaneRecord): LaneRecord;
+    loadAllLanes(hqRoot: string): LaneRecord[];
+    mintMessageId(): string;
+    prepareAccountMove(ctx: Ctx, lane: LaneRecord, input: PrepareAccountMoveInput): Promise<LaneAccountMove>;
+    persistClaudeAccountSelection(hqRoot: string, lane: LaneRecord, selection: LaneAccountSelection): LaneRecord;
+    printJson(value: unknown): void;
+    recordResumeSetup(ctx: Ctx, lane: LaneRecord, input: RecordResumeSetupInput): LaneRecord;
+    resolveCommandLane(ctx: Ctx, laneId: string): Promise<CommandLaneResolution>;
+    resolveActiveQuestionCompany(ctx: Ctx, message?: string): Promise<LaneCompanyRef>;
+    hasPendingQuestionForLane(ctx: Ctx, lane: LaneRecord): Promise<boolean>;
+    cancelFallbackQuestionsForLane(ctx: Ctx, lane: LaneRecord, trigger: "message" | "resume", at: string): Promise<FallbackQuestionCancellationResult>;
+    resolveResumeProfile(ctx: Ctx, lane: LaneRecord, workerId: string): ResolvedResumeProfile;
+    selectAutomaticClaudeResumeAccount(ctx: Ctx, lane: LaneRecord, workerProfile?: ResolvedResumeProfile, options?: {
+        repairUnavailableAccount?: boolean;
+        tolerateInvalidHostLaneLists?: boolean;
+    }): Promise<{
+        selection: LaneAccountSelection;
+        historyReason?: AccountHistoryEntry["reason"];
+        preservedModel?: string;
+    } | undefined>;
+    validateResumeProfileModel(ctx: Ctx, lane: LaneRecord, profile: WorkerProfile): void;
+    withResumeHireAdmission<T>(ctx: Ctx, lane: LaneRecord, fn: () => T, grantContext?: OutpostHireGrantContext): Promise<T>;
+}
+export interface LaneResumeHandlerDeps extends Pick<LaneMessageHandlerDeps, "onLaneWorkerStarted" | "archiveResumeMessage" | "assertLaneRunsHereForAdmission" | "assertLaneRunsHereForOperatorMutation" | "assessLaneAdmission" | "casUpdateLane" | "laneIsHostedHere" | "laneWithRecoveredProviderSession" | "mintMessageId" | "prepareAccountMove" | "persistClaudeAccountSelection" | "printJson" | "recordResumeSetup" | "resolveCommandLane" | "hasPendingQuestionForLane" | "cancelFallbackQuestionsForLane" | "resolveResumeProfile" | "selectAutomaticClaudeResumeAccount" | "validateResumeProfileModel" | "withResumeHireAdmission"> {
+    dispatchOutpostLaneCommand(ctx: Ctx, lane: LaneRecord, action: "resume", options: LaneResumeOptions, behavior?: OutpostLaneDispatchBehavior): Promise<void>;
+    authorizeFailedResume(ctx: Ctx, lane: LaneRecord, encodedContext?: string): string;
+    authorizeResumeProfileRepin(ctx: Ctx, lane: LaneRecord, profile: ResolvedResumeProfile | undefined, encodedContext: string | undefined): ResumeProfileRepinAuthorization | undefined;
+    automaticBalanceMoveHistoryReason(ctx: Ctx, lane: LaneRecord): AccountHistoryEntry["reason"];
+}
+export interface SpawnLoginResult {
+    status: number;
+}
+export type LanesMesh = LaneMesh;
+export interface Ctx {
+    hqRoot: () => string;
+    cwd: () => string;
+    /** Directory the process was in before hq lanes chdir'd to the HQ root. */
+    callerCwd: () => string;
+    env: NodeJS.ProcessEnv;
+    now: () => Date;
+    hostname: () => string;
+    resolveCompany: (company?: string) => Promise<LaneCompanyRef>;
+    resolveActiveCompany: (company: string) => Promise<LaneCompanyRef | null>;
+    listOutpostIds: () => Promise<string[]>;
+    listOutpostRoutes: () => Promise<OutpostRouteIdentity[]>;
+    readOutpostIdentity: () => OutpostIdentity;
+    spawnLogin: (opts: {
+        command: string;
+        args: string[];
+        env: NodeJS.ProcessEnv;
+        cwd?: string;
+    }) => Promise<SpawnLoginResult>;
+    throttleDeps: ThrottleDeps;
+    existsSync: (p: string) => boolean;
+    readFileSync: (p: string, encoding: "utf8") => string;
+    readStdin: () => string;
+    homedir: () => string;
+    mesh: LanesMesh;
+    sleep: (ms: number) => Promise<void>;
+    spawnProcess?: SpawnProcessFn;
+    proveDetached?: ProveDetachedFn;
+    killProcess?: KillProcessFn;
+    isAlive?: (pid: number) => boolean;
+    readStarttime?: (pid: number) => number | null;
+    watcherLoopDeps?: Pick<WatcherLoopDeps, "sleep" | "spawnRepair">;
+    stopSleepMs?: (ms: number) => void;
+    livenessDeps?: LivenessDeps;
+    presenceConnected?: boolean;
+    systemdRoot?: string;
+    runSystemctl?: RunCommand;
+    /** Runs a provider CLI probe (`grok models`, `claude --help`) for --model validation. */
+    probeProvider?: ProbeCommand;
+    resolveMachineIdentity: () => MachineIdentity;
+    runCompaction?: RunCompactionFn;
+    locateTranscript?: (home: string, sessionId: string) => string | null;
+    monitorEvidence: MonitorEvidenceReader;
+    stageOutpostPayload: (outpostId: string, bytes: Uint8Array) => Promise<{
+        getUrl: string;
+    }>;
+    dispatchOutpostExec: (input: {
+        outpostId: string;
+        command: string;
+        timeoutSeconds?: number;
+        waitMs?: number;
+    }) => Promise<OutpostDispatchResult>;
+    backfillOutpostIdentity: (expectedId: string) => "created" | "unchanged";
+    fetchText: (url: string) => Promise<string>;
+    lanePlacementEnabled: (company: LaneCompanyRef | undefined) => Promise<boolean>;
+    readLeadAutopilotFlag: (flag: string, options: {
+        company: LaneCompanyRef;
+    }) => Promise<boolean>;
+    storyLedgerEnabled: () => boolean;
+    isSsmOwnerDispatch: () => boolean;
+    withGrantHireLocks: typeof withLaneHireLocks;
+    mergeHoldEnabled?: (company: LaneCompanyRef) => boolean | Promise<boolean>;
+    mergeReviewEnabled?: (company: LaneCompanyRef) => boolean | Promise<boolean>;
+}
+export interface OutpostRouteIdentity {
+    outpostId: string;
+    instanceName?: string;
+}
+export { LANE_OUTPOST_LOAD_BALANCING_FLAG };
+export declare const CLAUDE_ACCOUNT_BALANCE_SIGNALS_FLAG = "lanes.claude-account-balance-signals";
+export declare function defaultLanePlacementEnabled(company: LaneCompanyRef | undefined): Promise<boolean>;
+export declare function readLanePlacementEnabled(ctx: Ctx, company: LaneCompanyRef | undefined): Promise<boolean>;
+export declare function processLanePlacementCompany(ctx: Ctx): LaneCompanyRef | undefined;
+export declare function readClaudeAccountBalanceSignalsEnabled(ctx: Ctx, company?: LaneCompanyRef): Promise<boolean>;
+export declare function parsePlacementPolicy(raw: string): LanePlacementPolicy;
+export declare function assertPlacementEnabled(ctx: Ctx, company: LaneCompanyRef | undefined, readPlacementEnabled?: () => Promise<boolean>): Promise<void>;
+/** Match a direct session-senior caller while refusing lane-worker identities. */
+export declare function callerMatchesSessionSenior(ctx: Pick<Ctx, "env">, seniorSessionId: string): boolean;
+export interface LaneWaitCommandOptions {
+    any?: string[];
+    for?: string[];
+    timeout?: string;
+    json?: boolean;
+}
+export interface MonitorCheckOptions {
+    session?: string;
+    engine?: string;
+    json?: boolean;
+    reminder?: boolean;
+}
+export interface LaneWatchOptions {
+    intervalMs?: string;
+    json?: boolean;
+}
+export interface LaneWatchHandlerDeps {
+    laneHostFromCtx(ctx: Ctx): LaneRecord["host"];
+    loadAllLanes(hqRoot: string): LaneRecord[];
+    loadClaudeBalanceHostSnapshots(ctx: Ctx, hqRoot: string, config: LanesConfig): Promise<{
+        snapshots: BalanceHostSnapshot[];
+        unavailableHosts: BalanceHostGap[];
+    }>;
+    printJson(value: unknown): void;
+    readOutpostCapacity(ctx: Ctx, outpostId: string): Promise<HostCapacitySnapshot>;
+}
+export interface LaneMoveHandlerDeps {
+    assertKnownOutpost(requested: string, known: string[]): void;
+    assertLaneRunsHereForOperatorMutation(ctx: Ctx, lane: LaneRecord, action: string): void;
+    dispatchCreatedOutpostLane(ctx: Ctx, input: {
+        hqRoot: string;
+        lane: LaneRecord;
+        outpostId: string;
+        briefText: string;
+        timeout?: {
+            timeout_secs: number;
+            deadline_at: string;
+        };
+        preserveQueuedOnFailure?: boolean;
+    }): Promise<LaneRecord>;
+    loadHostCapacitySnapshots(ctx: Ctx, hqRoot: string, config: LanesConfig): Promise<{
+        snapshots: HostCapacitySnapshot[];
+    }>;
+    ownerErrorFromOutput(stdout: string): {
+        error: string;
+        message: string;
+        details: Record<string, unknown>;
+    } | undefined;
+    parseRemoteJson(stdout: string, surface: string): Record<string, unknown> | null;
+    printJson(value: unknown): void;
+    readJsonFile(filePath: string): unknown | null;
+    reconcileHostFromCtx(ctx: Ctx): ReconcileHost;
+    runDir(hqRoot: string, laneId: string): string;
+    timeoutPath(hqRoot: string, laneId: string): string;
+}
+export interface PrimaryOwnedOutpostQuestion {
+    question: QuestionRecord;
+    lane: LaneRecord;
+    host: string;
+    audience: SeniorRef;
+}
+export interface OutpostQuestionListError {
+    host: string;
+    error: string;
+}
+export interface OutpostQuestionLoad {
+    questions: PrimaryOwnedOutpostQuestion[];
+    errors: OutpostQuestionListError[];
+}
+export interface OutpostQuestionRow {
+    question: QuestionRecord;
+    audience: SeniorRef;
+}
+export interface QuestionCompanyGroup {
+    company: LaneCompanyRef | null;
+    lanes: LaneRecord[];
+}
+export interface LaneAccountsHandlerDeps {
+    automaticBalanceMoveHistoryReason(ctx: Ctx, lane: LaneRecord): AccountHistoryEntry["reason"];
+    ensureDir(dir: string): void;
+    laneWithRecoveredProviderSession(hqRoot: string, lane: LaneRecord): LaneRecord;
+    loadClaudeBalanceHostSnapshots(ctx: Ctx, hqRoot: string, config: LanesConfig): Promise<{
+        snapshots: BalanceHostSnapshot[];
+        unavailableHosts: BalanceHostGap[];
+    }>;
+    parseRemoteJson(stdout: string, surface: string): Record<string, unknown> | null;
+    prepareAccountMove(ctx: Ctx, lane: LaneRecord, input: {
+        account: string;
+        cliModel: undefined;
+        accountHistoryReason: AccountHistoryEntry["reason"];
+        deferTurnStart: true;
+    }): Promise<{
+        lane: LaneRecord;
+        from: string | null;
+        to: string;
+    }>;
+    printJson(value: unknown): void;
+    readClaudeAccountBalanceSignalsEnabled(ctx: Ctx): Promise<boolean>;
+    reconcileHostFromCtx(ctx: Ctx): ReconcileHost;
+    resolveCallerPath(callerCwd: string, filePath: string): string;
+}
+export interface LaneQuestionsHandlerDeps {
+    CAPACITY_PROBE_TIMEOUT_MS: number;
+    MAX_PLACEMENT_OUTPOSTS: number;
+    OUTPOST_QUESTION_LOOKUP_CONCURRENCY: number;
+    assertLaneRunsHereForOperatorMutation(ctx: Ctx, lane: LaneRecord, action: string): void;
+    assertQuestionAnswerAuthorized(ctx: Ctx, lane: LaneRecord): void;
+    assertQuestionCompanyMatchesLane(question: QuestionRecord, lane: Pick<LaneRecord, "lane_id" | "company" | "mesh_company" | "project_id">, code: string, hqRoot?: string): void;
+    casUpdateQuestion(hqRoot: string, questionId: string, updater: (current: QuestionRecord) => QuestionRecord): QuestionRecord;
+    casUpdateLane(hqRoot: string, laneId: string, updater: (current: LaneRecord) => LaneRecord): LaneRecord;
+    effectiveLaneQuestionCompany(lane: Pick<LaneRecord, "company" | "mesh_company" | "project_id" | "lane_id">, hqRoot?: string): LaneCompanyRef | null;
+    emitLaneMeshEvent(ctx: Ctx, company: LaneCompanyRef | null | undefined, threadId: string | undefined, event: LaneMeshEvent, payload: Record<string, unknown>): Promise<void>;
+    groupQuestionLanesByCompany(hqRoot: string, lanes: LaneRecord[], fallbackCompany?: LaneCompanyRef): QuestionCompanyGroup[];
+    isQuestionAnswer(value: unknown): value is QuestionAnswer;
+    laneIsHostedHere(ctx: Ctx, lane: LaneRecord): boolean;
+    livenessDepsFromCtx(ctx: Ctx): LivenessDeps;
+    loadAllLanes(hqRoot: string): LaneRecord[];
+    loadAllQuestions(hqRoot: string): QuestionRecord[];
+    mapWithConcurrency<T, R>(values: readonly T[], concurrency: number, map: (value: T, index: number) => Promise<R>): Promise<R[]>;
+    mintMessageId(): string;
+    parseOutpostQuestionAudience(raw: unknown, outpostId: string, index: number): SeniorRef;
+    parseOutpostQuestionBody(raw: unknown, outpostId: string, questionId: string): QuestionBody | null;
+    parseRemoteJson(stdout: string, surface: string): Record<string, unknown> | null;
+    parseSeniorRef(raw: string): SeniorRef;
+    questionCompanyForLane(question: QuestionRecord, lane: Pick<LaneRecord, "company" | "mesh_company" | "project_id" | "lane_id">, hqRoot?: string): LaneCompanyRef | null;
+    questionCompanyRefMatches(recordCompany: LaneCompanyRef | null | undefined, filter: LaneCompanyRef): boolean;
+    questionListCompanyArg(company: LaneCompanyRef | null): string | undefined;
+    readOutpostQuestionRecords(ctx: Ctx, outpostId: string, company: LaneCompanyRef | null): Promise<OutpostQuestionRow[]>;
+    readQuestionBody(hqRoot: string, question: QuestionRecord): QuestionBody | null;
+    printJson(value: unknown): void;
+    readSessionMeta(hqRoot: string, sessionId: string, ctx: Ctx): Record<string, unknown> | null;
+    reconcileHostFromCtx(ctx: Ctx): ReconcileHost;
+    resolveActiveQuestionCompany(ctx: Ctx, message?: string): Promise<LaneCompanyRef>;
+    resolveAudience(hqRoot: string, question: QuestionRecord, ctx: Ctx): SeniorRef;
+    sameQuestionAnswer(left: QuestionAnswer | undefined, right: QuestionAnswer): boolean;
+    sameQuestionCompany(a: LaneCompanyRef | null, b: LaneCompanyRef | null): boolean;
+    seniorOfSession(hqRoot: string, sessionId: string, ctx: Ctx): SeniorRef;
+    writeAnswerDeliveryFailed(hqRoot: string, laneId: string, questionId: string, err: unknown, at: string): void;
+}
+export interface LaneStoryHandlerDeps {
+    assertLaneRunsHereForOperatorMutation(ctx: Ctx, lane: LaneRecord, action: string): void;
+    casUpdateLane(hqRoot: string, laneId: string, updater: (current: LaneRecord) => LaneRecord): LaneRecord;
+    combinedStoryWarning(lane: LaneRecord, additional?: readonly string[]): string | null;
+    emitLaneMeshEvent(ctx: Ctx, company: LaneCompanyRef | null | undefined, threadId: string | undefined, event: LaneMeshEvent, payload: Record<string, unknown>): Promise<void>;
+    ensureLaneThreadRecord(ctx: Ctx, lane: LaneRecord, projectId?: string, storyId?: string, laneStatus?: string): Promise<LaneRecord>;
+    printJson(value: unknown): void;
+    readLane(hqRoot: string, laneId: string): LaneRecord;
+    storyBoardCheck(ctx: Ctx, company: LaneCompanyRef, projectId: string, storyIds: readonly string[]): Promise<{
+        warning?: string;
+        absentStoryIds: ReadonlySet<string>;
+    }>;
+    storyNotOnBoardWarning(err: unknown): string | undefined;
+    updateLane(hqRoot: string, laneId: string, expectedVersion: number, source: "command", updater: (current: LaneRecord) => LaneRecord): LaneRecord;
+    validateProjectStories(hqRoot: string, projectId: string, storyIds: string[], companySlug?: string): void;
+}
+//# sourceMappingURL=lanes-shared.d.ts.map

package/dist/commands/lanes-shared.js

@@ -0,0 +1,170 @@
+import { resolveProcessFlagCompanyContext } from "../lib/flag-registry.js";
+import { readLanesRegistryFlag } from "../lib/lanes/registry-flag.js";
+import { LANE_OUTPOST_LOAD_BALANCING_FLAG } from "../lib/lanes/flag-keys.js";
+import { resolveLaneEffort } from "../lib/lanes/effort.js";
+import { LanesError } from "../lib/lanes/errors.js";
+import { AccountResolutionError, accountStatus, loadLanesConfig } from "../lib/lanes/index.js";
+import { resolveLaneModel } from "../lib/lanes/spawn.js";
+import { sessionIdFromEnv } from "../lib/mesh/live/session-identity.js";
+export function accountRequestKeepsCurrentLane(lane, rawAccount) {
+    const raw = rawAccount.trim();
+    const colon = raw.indexOf(":");
+    const requestedProvider = colon > 0 ? raw.slice(0, colon) : undefined;
+    const requestedAccount = colon > 0 ? raw.slice(colon + 1) : raw;
+    return requestedAccount.length > 0 &&
+        requestedAccount === lane.account &&
+        (requestedProvider === undefined || requestedProvider === lane.provider);
+}
+export function assertCurrentResumeAccountAvailable(ctx, lane) {
+    const config = loadLanesConfig(ctx.hqRoot());
+    const account = lane.account === undefined
+        ? undefined
+        : config.providers[lane.provider].accounts[lane.account];
+    if (account === undefined || !account.enabled) {
+        throw new AccountResolutionError(account === undefined ? "unknown_account" : "account_disabled", account === undefined
+            ? `Lane ${lane.lane_id} records account ${JSON.stringify(lane.account)} which is not configured for ${lane.provider}`
+            : `Account ${JSON.stringify(lane.account)} is disabled${account.disabled_reason ? `: ${account.disabled_reason}` : ""}`, { provider: lane.provider, account: lane.account ?? "", ...(account?.disabled_reason !== undefined ? { reason: account.disabled_reason } : {}) });
+    }
+    if (accountStatus(lane.provider, lane.account, config, {
+        existsSync: ctx.existsSync,
+        hostname: ctx.hostname(),
+        probe: ctx.probeProvider,
+        env: ctx.env,
+    }).logged_in !== true) {
+        throw new LanesError("account_not_logged_in", `Account ${lane.account} for ${lane.provider} is not logged in (no credential file)`, { provider: lane.provider, account: lane.account, lane_id: lane.lane_id });
+    }
+}
+export function accountMoveSummary(move) {
+    return {
+        from: move.from,
+        to: move.to,
+        queued: move.queued,
+        copied: move.copy.copied,
+        sources: move.copy.sources,
+        targets: move.copy.targets,
+        source_dir: move.copy.source_dir,
+        target_dir: move.copy.target_dir,
+    };
+}
+export function hasKeepAliveProgress(lane) {
+    return (lane.keep_alive_resume_count ?? 0) !== 0 ||
+        lane.keep_alive_last_resume_at !== undefined ||
+        lane.keep_alive_next_eligible_at !== undefined ||
+        lane.keep_alive_exhausted_at !== undefined;
+}
+export function resetKeepAliveProgress(lane) {
+    if (!hasKeepAliveProgress(lane))
+        return lane;
+    return {
+        ...lane,
+        keep_alive_resume_count: 0,
+        keep_alive_last_resume_at: undefined,
+        keep_alive_next_eligible_at: undefined,
+        keep_alive_exhausted_at: undefined,
+    };
+}
+export function resolveResumeEffort(ctx, lane, input) {
+    if (input.cliEffort === undefined && input.profile === undefined)
+        return undefined;
+    const config = loadLanesConfig(ctx.hqRoot());
+    const providerConfig = config.providers[lane.provider];
+    const accountId = input.account?.trim() || lane.account;
+    const accountConfig = accountId === undefined
+        ? undefined
+        : providerConfig.accounts[accountId];
+    const profileDefaultsApply = input.profile?.profile.meta.provider === lane.provider;
+    const pinnedModel = lane.pending_settings?.model ?? (lane.model_source === undefined || lane.model_source === "cli" || lane.model_source === "preserved"
+        ? lane.model
+        : undefined);
+    const model = resolveLaneModel({
+        cliModel: input.model?.trim() || pinnedModel,
+        profileModel: profileDefaultsApply ? input.profile?.profile.meta.model : undefined,
+        accountModel: accountConfig?.model,
+        providerModel: providerConfig.model,
+    });
+    return resolveLaneEffort({
+        cliEffort: input.cliEffort,
+        profileEffort: profileDefaultsApply ? input.profile?.profile.meta.effort : undefined,
+        accountEffort: accountConfig?.effort,
+        providerEffort: providerConfig.effort,
+        model,
+    });
+}
+export function recordedResumeEffort(lane) {
+    if (lane.pending_settings?.effort !== undefined) {
+        return { effort: lane.pending_settings.effort, source: "cli" };
+    }
+    return {
+        ...(lane.effort !== undefined ? { effort: lane.effort } : {}),
+        source: lane.effort_source ?? "none",
+    };
+}
+export { LANE_OUTPOST_LOAD_BALANCING_FLAG };
+export const CLAUDE_ACCOUNT_BALANCE_SIGNALS_FLAG = "lanes.claude-account-balance-signals";
+function lanePlacementFlagErrorCode(error) {
+    if (error && typeof error === "object") {
+        for (const key of ["code", "error", "name"]) {
+            const value = error[key];
+            if (typeof value === "string" && value.trim())
+                return value;
+        }
+    }
+    return "UnknownError";
+}
+function reportLanePlacementFlagReadFailure(error) {
+    process.stderr.write(`${JSON.stringify({
+        event: "lanes.outpost_load_balancing.flag_read_failed",
+        flag: LANE_OUTPOST_LOAD_BALANCING_FLAG,
+        error: lanePlacementFlagErrorCode(error),
+        fallback: false,
+    })}\n`);
+}
+export function defaultLanePlacementEnabled(company) {
+    return readLanesRegistryFlag(LANE_OUTPOST_LOAD_BALANCING_FLAG, {
+        company,
+        reportFailure: reportLanePlacementFlagReadFailure,
+    });
+}
+export async function readLanePlacementEnabled(ctx, company) {
+    try {
+        return await ctx.lanePlacementEnabled(company);
+    }
+    catch (error) {
+        reportLanePlacementFlagReadFailure(error);
+        return false;
+    }
+}
+export function processLanePlacementCompany(ctx) {
+    const context = resolveProcessFlagCompanyContext(ctx.env);
+    if (!context.companySlug)
+        return undefined;
+    return { slug: context.companySlug, uid: context.companyUid ?? "" };
+}
+export function readClaudeAccountBalanceSignalsEnabled(ctx, company) {
+    return readLanesRegistryFlag(CLAUDE_ACCOUNT_BALANCE_SIGNALS_FLAG, {
+        company: company ?? processLanePlacementCompany(ctx),
+        env: ctx.env,
+    });
+}
+export function parsePlacementPolicy(raw) {
+    const value = raw.trim();
+    if (value === "local")
+        return { kind: "local" };
+    if (value === "auto")
+        return { kind: "auto" };
+    const match = /^outpost:(.+)$/.exec(value);
+    const id = match?.[1]?.trim();
+    if (id)
+        return { kind: "outpost", id };
+    throw new LanesError("lane_placement_invalid", `Invalid placement ${JSON.stringify(raw)}. Accepted: local, auto, outpost:<id>`, { value: raw, accepted: ["local", "auto", "outpost:<id>"] });
+}
+export async function assertPlacementEnabled(ctx, company, readPlacementEnabled = () => readLanePlacementEnabled(ctx, company)) {
+    if (await readPlacementEnabled())
+        return;
+    throw new LanesError("lane_placement_disabled", `Lane placement options require hq-flags gate ${LANE_OUTPOST_LOAD_BALANCING_FLAG}`, { flag: LANE_OUTPOST_LOAD_BALANCING_FLAG });
+}
+/** Match a direct session-senior caller while refusing lane-worker identities. */
+export function callerMatchesSessionSenior(ctx, seniorSessionId) {
+    return !ctx.env.HQ_LANE_ID?.trim() && sessionIdFromEnv(ctx.env) === seniorSessionId;
+}
+//# sourceMappingURL=lanes-shared.js.map

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

@@ -0,0 +1,15 @@
+import type { Ctx, LaneStoryHandlerDeps } from "./lanes-shared.js";
+export interface StoryCommandOptions {
+    project?: string;
+    reason?: string;
+    verified?: boolean;
+}
+export declare function createLaneStoryHandlers(deps: LaneStoryHandlerDeps): {
+    runStoryList: (ctx: Ctx, laneId: string) => Promise<void>;
+    runStoryAdd: (ctx: Ctx, laneId: string, storyId: string, opts: StoryCommandOptions) => Promise<void>;
+    runStoryStart: (ctx: Ctx, laneId: string, storyId: string, opts: StoryCommandOptions) => Promise<void>;
+    runStoryReview: (ctx: Ctx, laneId: string, storyId: string, opts: StoryCommandOptions) => Promise<void>;
+    runStoryBlock: (ctx: Ctx, laneId: string, storyId: string, opts: StoryCommandOptions) => Promise<void>;
+    runStoryDone: (ctx: Ctx, laneId: string, storyId: string, opts: StoryCommandOptions) => Promise<void>;
+};
+//# sourceMappingURL=lanes-stories.d.ts.map