@indigoai-us/hq-cli 5.298.0 → 5.300.0

package/dist/lib/daemon/migrate.d.ts

@@ -17,11 +17,13 @@
  * folder, so nobody but root decides what gets installed there.
  */
 import type { RunCommand } from "../service-manager/launchd.js";
-import type { LegacyUnit } from "./legacy.js";
+import { type LegacyUnit } from "./legacy.js";
 export interface AdoptedUnit extends LegacyUnit {
     /** Where the unit's definition (plist, unit file, task XML) was moved. */
     movedTo: string;
     adoptedAt: number;
+    /** Launchd job was loaded, but its source plist no longer existed. */
+    definitionMissing?: true;
 }
 export interface MigrateDeps {
     run: RunCommand;
@@ -64,5 +66,12 @@ export interface RestoreResult {
 }
 export declare function readAdoptedUnits(recordPath: string): AdoptedUnit[];
 export declare function adoptLegacyUnits(units: readonly LegacyUnit[], deps: MigrateDeps): AdoptResult;
+/** Retire the migratable legacy mesh job and emit the daemon's operator-facing result lines. */
+export declare function retireLegacyMeshUnits(units: readonly LegacyUnit[], options: {
+    platform: NodeJS.Platform;
+    managed: boolean;
+    hosted: boolean;
+    meshEnabled: boolean;
+}, deps: MigrateDeps, log: (level: "info" | "warn", message: string) => void): AdoptResult;
 export declare function restoreLegacyUnits(deps: MigrateDeps): RestoreResult;
 //# sourceMappingURL=migrate.d.ts.map

package/dist/lib/daemon/migrate.js

@@ -18,6 +18,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { legacyMeshUnitsToRetire } from "./legacy.js";
 import { ensurePrivateDir } from "./paths.js";
 export function readAdoptedUnits(recordPath) {
     let text;
@@ -99,8 +100,10 @@ function adoptOne(unit, deps) {
             if (bootout.status !== 0 && deps.run("launchctl", ["print", target]).status === 0) {
                 must(deps.run, "launchctl", ["bootout", target]);
             }
+            if (!fs.existsSync(unit.path))
+                return { movedTo: unit.path, definitionMissing: true };
             moveFile(unit.path, to);
-            return to;
+            return { movedTo: to };
         }
         case "systemd-user":
         case "systemd-system": {
@@ -109,7 +112,7 @@ function adoptOne(unit, deps) {
             must(deps.run, ...systemctl(unit, deps, ["disable", "--now", unit.name]));
             moveFile(unit.path, to);
             deps.run(...systemctl(unit, deps, ["daemon-reload"]));
-            return to;
+            return { movedTo: to };
         }
         case "schtasks": {
             const xml = must(deps.run, "schtasks.exe", ["/Query", "/TN", unit.name, "/XML"]);
@@ -117,7 +120,7 @@ function adoptOne(unit, deps) {
             fs.writeFileSync(to, encodeTaskXml(xml), { mode: 0o600 });
             deps.run("schtasks.exe", ["/End", "/TN", unit.name]);
             must(deps.run, "schtasks.exe", ["/Delete", "/TN", unit.name, "/F"]);
-            return to;
+            return { movedTo: to };
         }
     }
 }
@@ -141,15 +144,15 @@ export function adoptLegacyUnits(units, deps) {
             continue;
         }
         const store = storeFor(unit.kind, deps);
-        let movedTo;
+        let adoptedFields;
         try {
-            movedTo = adoptOne(unit, deps);
+            adoptedFields = adoptOne(unit, deps);
         }
         catch (err) {
             result.failed.push({ unit, error: err.message });
             continue;
         }
-        const adopted = { ...unit, movedTo, adoptedAt: now() };
+        const adopted = { ...unit, ...adoptedFields, adoptedAt: now() };
         const next = [...recordOf(store), adopted];
         try {
             // Record each unit as soon as it is moved, so a failure later in the
@@ -165,7 +168,7 @@ export function adoptLegacyUnits(units, deps) {
                 restoreOne(adopted, deps);
             }
             catch (restoreErr) {
-                rollback = `; putting it back also failed (${restoreErr.message}), its definition is at ${movedTo}`;
+                rollback = `; putting it back also failed (${restoreErr.message}), its definition is at ${adopted.movedTo}`;
             }
             result.failed.push({ unit, error: `could not record the takeover: ${err.message}${rollback}` });
         }
@@ -192,6 +195,8 @@ function restoreOne(unit, deps) {
         case "launchd": {
             if (!unit.path)
                 throw new Error(`no plist path recorded for ${unit.name}`);
+            if (unit.definitionMissing)
+                throw new Error("the original LaunchAgent plist is missing; this unit cannot be restored");
             moveBack(unit, unit.path);
             must(deps.run, "launchctl", ["bootstrap", `gui/${deps.uid}`, unit.path]);
             return;
@@ -216,6 +221,16 @@ function restoreOne(unit, deps) {
             return;
     }
 }
+/** Retire the migratable legacy mesh job and emit the daemon's operator-facing result lines. */
+export function retireLegacyMeshUnits(units, options, deps, log) {
+    const selected = legacyMeshUnitsToRetire(units, options);
+    const result = adoptLegacyUnits(selected, deps);
+    for (const unit of result.adopted)
+        log("info", `retired legacy ${unit.unitId} unit ${unit.name}; hq daemon now owns mesh`);
+    for (const failure of result.failed)
+        log("warn", `could not retire legacy ${failure.unit.unitId} unit ${failure.unit.name}: ${failure.error}`);
+    return result;
+}
 function restoreFrom(record, deps, check, result) {
     const units = readAdoptedUnits(record);
     if (units.length === 0)

package/dist/lib/daemon/run.js

@@ -22,7 +22,7 @@ import { SUPERVISOR_HANDOFF_FLAG, readDaemonFlag } from "./flag.js";
 import { findLegacyUnits, legacyMeshUnitsToRetire, legacyOwnerLookup } from "./legacy.js";
 import { readLegacySyncEnv } from "./legacy-sync-env.js";
 import { acquireDaemonLock, isProcessAlive, processCommandLine, releaseDaemonLock } from "./lock.js";
-import { adoptLegacyUnits } from "./migrate.js";
+import { retireLegacyMeshUnits } from "./migrate.js";
 import { daemonDir as meshDaemonDir, daemonPidPath as meshDaemonPidPath } from "../mesh/live/daemon/paths.js";
 import { readPidLock } from "../mesh/live/daemon/pid-lock.js";
 import { daemonRootRefusal } from "./install.js";
@@ -72,6 +72,17 @@ export function probeLegacyUnits(platform, home) {
         home,
         existsSync: fs.existsSync,
         listDir: (dir) => fs.readdirSync(dir),
+        launchdJobLoaded: (label) => {
+            if (platform !== "darwin")
+                return false;
+            const uid = process.getuid?.() ?? 0;
+            const result = spawnSync("launchctl", ["print", `gui/${uid}/${label}`], {
+                encoding: "utf8",
+                windowsHide: true,
+                timeout: 15_000,
+            });
+            return result.status === 0;
+        },
         windowsTaskExists,
     });
 }
@@ -344,7 +355,12 @@ export async function runDaemon(opts) {
     if (legacyMesh.length > 0) {
         try {
             const uid = process.getuid?.() ?? 0;
-            const result = adoptLegacyUnits(legacyMesh, {
+            retireLegacyMeshUnits(legacyMesh, {
+                platform,
+                managed: opts.managed === true,
+                hosted: opts.host !== undefined,
+                meshEnabled: enabledServices(machineType, initial).includes("mesh"),
+            }, {
                 run: (command, args) => {
                     const r = spawnSync(command, args, { encoding: "utf8", windowsHide: true, timeout: 15_000 });
                     return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
@@ -356,11 +372,7 @@ export async function runDaemon(opts) {
                 systemAdoptedDir: "/var/lib/hq/daemon/adopted",
                 systemRecordPath: "/var/lib/hq/daemon/adopted.json",
                 systemUnitDir: "/etc/systemd/system",
-            });
-            for (const unit of result.adopted)
-                log("info", `retired legacy ${unit.unitId} unit ${unit.name}; hq daemon now owns mesh`);
-            for (const failure of result.failed)
-                log("warn", `could not retire legacy ${failure.unit.unitId} unit ${failure.unit.name}: ${failure.error}`);
+            }, (level, message) => log(level, message));
         }
         catch (err) {
             log("error", `could not retire legacy mesh units: ${err.message}`);

package/dist/lib/daemon/supervisor.js

@@ -28,6 +28,7 @@ export const BACKOFF_MAX_MS = 60_000;
 export const HEALTHY_RUN_MS = 60_000;
 export const STOP_ESCALATION_MS = 10_000;
 const MESH_OWNER_RECHECK_MS = 15_000;
+const MESH_OWNER_LOG_INTERVAL_MS = 10 * 60_000;
 /** After a handoff, how long a replaced unit must stay up before the next one is replaced. */
 export const HANDOFF_STAGGER_MS = 15_000;
 /** How long a draining unit may take to finish its work before it gets SIGTERM. */
@@ -297,11 +298,18 @@ export function createSupervisor(deps) {
             }
             const meshOwnerReason = slot.plan.service === "mesh" ? deps.meshOwnerReason?.() : undefined;
             if (meshOwnerReason) {
+                let lastLoggedReason;
+                let lastLoggedAt = Number.NEGATIVE_INFINITY;
                 const waitForOwner = (reason) => {
                     slot.state.status = "waiting";
                     slot.state.reason = reason;
                     slot.state.nextRunAt = now() + MESH_OWNER_RECHECK_MS;
-                    deps.log("warn", `${reason}; retrying mesh ownership check in ${MESH_OWNER_RECHECK_MS}ms`);
+                    const at = now();
+                    if (reason !== lastLoggedReason || at - lastLoggedAt >= MESH_OWNER_LOG_INTERVAL_MS) {
+                        deps.log("warn", `${reason}; retrying mesh ownership check in ${MESH_OWNER_RECHECK_MS}ms`);
+                        lastLoggedReason = reason;
+                        lastLoggedAt = at;
+                    }
                     slot.timer = setT(() => {
                         slot.timer = undefined;
                         const current = deps.meshOwnerReason?.();

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

@@ -89,6 +89,25 @@ export declare function quotaSignalFromFields(fields: {
 }, model: string | undefined, now: Date): QuotaSignal | null;
 export declare function readQuotaSignal(runDir: string, model: string | undefined, now: Date, workerOutOffset?: number): QuotaSignal | null;
 export declare function recordAccountQuota(hqRoot: string, provider: LaneProvider, accountId: string, signal: QuotaSignal): QuotaState;
+export interface ClearedModelQuotaReset {
+    model: string;
+    quota_reset_at: string;
+}
+export interface AccountQuotaClearResult {
+    all_models_quota_reset_at: string | null;
+    model_quota_resets: ClearedModelQuotaReset[];
+}
+export interface ClearAccountQuotaOptions {
+    /** Clear only this model's reset instead of every per-model reset. */
+    model?: string;
+    /** Clear only marks whose reset time is still ahead of now. */
+    futureOnly?: boolean;
+    now?: Date;
+}
+/** Clear quota reset marks and persist them with the quota file's atomic writer. */
+export declare function clearAccountQuota(hqRoot: string, provider: LaneProvider, accountId: string, options?: ClearAccountQuotaOptions): AccountQuotaClearResult;
+export declare function clearAccountQuotaAfterSuccessfulTurn(hqRoot: string, provider: LaneProvider, accountId: string, model: string, now: Date): AccountQuotaClearResult;
+export declare function clearAccountQuotaAfterSuccessfulTurnBestEffort(hqRoot: string, provider: LaneProvider, accountId: string, model: string, now: Date): void;
 export interface QuotaBlock {
     blocked: boolean;
     reason?: "account_quota_exhausted" | "account_model_unavailable";

package/dist/lib/lanes/quota.js

@@ -19,6 +19,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { withLaneRecordFileLock } from "./store.js";
 export const QUOTA_STATE_REL = path.join("personal", "lanes", "quota.json");
 export const QUOTA_SCHEMA_VERSION = "hq-lanes-quota.v1";
 /**
@@ -278,40 +279,116 @@ export function readQuotaSignal(runDir, model, now, workerOutOffset = 0) {
     return quotaSignalFromFields(fields, model, now);
 }
 export function recordAccountQuota(hqRoot, provider, accountId, signal) {
-    const state = loadQuotaState(hqRoot);
-    const accounts = state.providers[provider] ?? {};
-    const current = accounts[accountId] ?? { models: {} };
-    const models = { ...current.models };
-    if (signal.model) {
-        const prior = models[signal.model] ?? {};
-        const next = { ...prior };
-        if (signal.needs_credits) {
-            next.needs_credits = true;
-            next.marker = signal.marker ?? `needs credits for ${signal.model}`;
-            delete next.quota_reset_at;
+    return withLaneRecordFileLock(quotaStatePath(hqRoot), () => {
+        const state = loadQuotaState(hqRoot);
+        const accounts = state.providers[provider] ?? {};
+        const current = accounts[accountId] ?? { models: {} };
+        const models = { ...current.models };
+        if (signal.model) {
+            const prior = models[signal.model] ?? {};
+            const next = { ...prior };
+            if (signal.needs_credits) {
+                next.needs_credits = true;
+                next.marker = signal.marker ?? `needs credits for ${signal.model}`;
+                delete next.quota_reset_at;
+            }
+            if (signal.quota_reset_at &&
+                !signal.needs_credits &&
+                shouldReplaceReset(next.quota_reset_at, signal.quota_reset_at)) {
+                next.quota_reset_at = signal.quota_reset_at;
+            }
+            models[signal.model] = next;
         }
-        if (signal.quota_reset_at &&
-            !signal.needs_credits &&
-            shouldReplaceReset(next.quota_reset_at, signal.quota_reset_at)) {
-            next.quota_reset_at = signal.quota_reset_at;
+        const account = { ...current, models };
+        if (signal.account_wide && signal.quota_reset_at) {
+            if (shouldReplaceReset(current.all_models_quota_reset_at, signal.quota_reset_at)) {
+                account.all_models_quota_reset_at = signal.quota_reset_at;
+                account.reset_source = signal.reset_source ?? "provider";
+            }
+            else if (current.all_models_quota_reset_at) {
+                account.all_models_quota_reset_at = current.all_models_quota_reset_at;
+                account.reset_source = current.reset_source ?? "provider";
+            }
         }
-        models[signal.model] = next;
-    }
-    const account = { ...current, models };
-    if (signal.account_wide && signal.quota_reset_at) {
-        if (shouldReplaceReset(current.all_models_quota_reset_at, signal.quota_reset_at)) {
-            account.all_models_quota_reset_at = signal.quota_reset_at;
-            account.reset_source = signal.reset_source ?? "provider";
+        accounts[accountId] = account;
+        state.providers[provider] = accounts;
+        writeQuotaState(hqRoot, state);
+        return state;
+    });
+}
+/** Clear quota reset marks and persist them with the quota file's atomic writer. */
+export function clearAccountQuota(hqRoot, provider, accountId, options = {}) {
+    return withLaneRecordFileLock(quotaStatePath(hqRoot), () => {
+        const cleared = {
+            all_models_quota_reset_at: null,
+            model_quota_resets: [],
+        };
+        const state = loadQuotaState(hqRoot);
+        const account = state.providers[provider]?.[accountId];
+        if (!account)
+            return cleared;
+        const now = options.now ?? new Date();
+        const shouldClear = (reset) => reset !== undefined &&
+            (!options.futureOnly || resetStillAhead(reset, now));
+        let changed = false;
+        const accountWideReset = account.all_models_quota_reset_at;
+        if (shouldClear(accountWideReset)) {
+            cleared.all_models_quota_reset_at = accountWideReset;
+            delete account.all_models_quota_reset_at;
+            delete account.reset_source;
+            changed = true;
+        }
+        const modelNames = options.model === undefined
+            ? Object.keys(account.models).sort()
+            : [options.model];
+        for (const model of modelNames) {
+            const entry = account.models[model];
+            const modelReset = entry?.quota_reset_at;
+            if (!entry || !shouldClear(modelReset))
+                continue;
+            cleared.model_quota_resets.push({
+                model,
+                quota_reset_at: modelReset,
+            });
+            delete entry.quota_reset_at;
+            if (Object.keys(entry).length === 0)
+                delete account.models[model];
+            changed = true;
         }
-        else if (current.all_models_quota_reset_at) {
-            account.all_models_quota_reset_at = current.all_models_quota_reset_at;
-            account.reset_source = current.reset_source ?? "provider";
+        if (!changed)
+            return cleared;
+        if (account.all_models_quota_reset_at === undefined) {
+            delete account.reset_source;
         }
+        const accounts = state.providers[provider];
+        if (account.all_models_quota_reset_at === undefined &&
+            Object.keys(account.models).length === 0) {
+            delete accounts[accountId];
+            if (Object.keys(accounts).length === 0)
+                delete state.providers[provider];
+        }
+        else {
+            accounts[accountId] = account;
+        }
+        writeQuotaState(hqRoot, state);
+        return cleared;
+    });
+}
+export function clearAccountQuotaAfterSuccessfulTurn(hqRoot, provider, accountId, model, now) {
+    return clearAccountQuota(hqRoot, provider, accountId, {
+        model,
+        futureOnly: true,
+        now,
+    });
+}
+export function clearAccountQuotaAfterSuccessfulTurnBestEffort(hqRoot, provider, accountId, model, now) {
+    try {
+        clearAccountQuotaAfterSuccessfulTurn(hqRoot, provider, accountId, model, now);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`hq lanes: quota cleanup after successful turn failed for provider=${provider} account=${accountId} model=${model}: ${detail}\n`);
     }
-    accounts[accountId] = account;
-    state.providers[provider] = accounts;
-    writeQuotaState(hqRoot, state);
-    return state;
 }
 function shouldReplaceReset(current, incoming) {
     if (!current)

package/dist/lib/lanes/reconcile.js

@@ -27,11 +27,12 @@ import { appendDropboxMessage } from "./dropbox.js";
 import { DEFAULT_RUNAWAY_SEARCH_GUARD_CONFIG, listHostProcesses, runRunawayToolGuard, RUNAWAY_TOOL_GUARD_FLAG, } from "./runaway-tool-guard.js";
 import { LEAD_LANE_KEEP_ALIVE_FLAG, LEAD_LANE_KEEP_ALIVE_RESUME_BLOCKED_FLAG, LEAD_LANE_KEEP_ALIVE_BLOCKED_GRACE_MS, LEAD_LANE_KEEP_ALIVE_BLOCKED_RESUME_TEXT, queueLaneTerminalResume, LEAD_LANE_KEEP_ALIVE_INTERRUPTED_RESUME_TEXT, LEAD_LANE_KEEP_ALIVE_MAX_RESUMES, LEAD_LANE_KEEP_ALIVE_RESUME_TEXT, LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, doneKeepAliveVerdict, hasPendingKeepAliveWork, keepAliveExclusion, loadRetiredLaneIds, leadLaneKeepAliveBackoffMs, undeliveredAnsweredQuestions, } from "./keep-alive.js";
 import { providerSupportsSessionResume } from "./delivery.js";
-import { applyDefaultQuotaHold, readQuotaSignal, recordAccountQuota } from "./quota.js";
+import { applyDefaultQuotaHold, clearAccountQuotaAfterSuccessfulTurnBestEffort, readQuotaSignal, recordAccountQuota, } from "./quota.js";
 import { answeredQuestionEntries, questionRecordRefusalCode, raiseEnvelopeQuestions, resolveQuestionCompanyWithFallback, } from "./questions.js";
 import { SILENCE_MS, appendWatcherEvent, classifyLaneExit, isPidAlive, missingExpectedEnvelopeFile, readLatestEnvelopeFile, readLatestEnvelopeRecord, watcherEventsPath, watcherOutLogPath, writeWatcherDecision, } from "./watcher.js";
 import { createLaneMesh, emitLaneDecisionEvents, emitLaneTerminalStateEvent, laneMeshCompany, } from "./mesh-events.js";
 import { activeLaneStories, laneStories, terminalEnvelopeStoryStatus } from "./stories.js";
+import { applyStorySwitchEnvelope } from "./story-switch.js";
 import { decideEnvelopeRepair, envelopeQuestionIds, routeProviderFailure } from "./watcher.js";
 import { PROVIDER_REJECTED_REASON, providerRejectionDetails, readProviderRejection, } from "./provider-rejection.js";
 /** Spec §9: unanswered at the current hop for 60 minutes → one hop. */
@@ -1271,11 +1272,28 @@ async function heartbeatAndDeadHosts(hqRoot, lanes, summary, deps, now) {
                     }
                     if (terminalEnvelope && latest) {
                         const envelope = terminalEnvelope;
-                        const storyStatus = terminalEnvelopeStoryStatus(current, envelope.decision, envelope.story_status);
+                        next.last_envelope = {
+                            ref: latest.ref,
+                            decision: envelope.decision,
+                            at: nowIso,
+                            artifacts: envelope.artifacts,
+                            ...(envelope.blocked_reason !== undefined ? { blocked_reason: envelope.blocked_reason } : {}),
+                        };
+                        const storySwitch = applyStorySwitchEnvelope(current, envelope, nowIso, latest.ref);
+                        if (storySwitch.clearPending) {
+                            next.story_switch_pending = undefined;
+                        }
+                        if (storySwitch.storySwitchUnacknowledged !== undefined) {
+                            next.story_switch_unacknowledged = storySwitch.storySwitchUnacknowledged;
+                            next.attribution_history = storySwitch.attributionHistory ?? current.attribution_history;
+                        }
+                        const storyStatus = storySwitch.suppressCompletion
+                            ? "in_progress"
+                            : terminalEnvelopeStoryStatus(current, envelope.decision, envelope.story_status);
                         if (storyStatus !== undefined) {
-                            next.story_status = envelope.story_status;
-                            next.story_complete = envelope.story_complete;
-                            next.story_complete_reason = envelope.story_complete_reason;
+                            next.story_status = storySwitch.suppressCompletion ? "in_progress" : envelope.story_status;
+                            next.story_complete = storySwitch.suppressCompletion ? false : envelope.story_complete;
+                            next.story_complete_reason = storySwitch.suppressCompletion ? undefined : envelope.story_complete_reason;
                             next.stories = laneStories(current).map((story) => story.project_id === current.project_id && story.story_id === current.story_id
                                 ? {
                                     ...story,
@@ -1299,6 +1317,17 @@ async function heartbeatAndDeadHosts(hqRoot, lanes, summary, deps, now) {
                     }
                     return next;
                 }, deps.dryRun);
+                if (!deps.dryRun &&
+                    result.changed &&
+                    result.record.state === "done" &&
+                    terminalClassification.state === "done" &&
+                    terminalEnvelope?.decision === "done" &&
+                    !quota &&
+                    !providerRejection &&
+                    result.record.account &&
+                    result.record.model) {
+                    clearAccountQuotaAfterSuccessfulTurnBestEffort(hqRoot, result.record.provider, result.record.account, result.record.model, new Date(nowIso));
+                }
                 if (result.changed) {
                     summary.dead_host.push({
                         id: lane.lane_id,

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

@@ -43,6 +43,8 @@ export declare function sanitizeHostComponent(hostname: string): string;
 export declare function mintLaneId(deps?: Pick<StoreDeps, "now" | "hostname"> & Partial<Pick<StoreDeps, "generateLaneUlid">>): string;
 export declare function mintQuestionId(deps?: Pick<StoreDeps, "now" | "hostname">): string;
 export declare function appendCappedHistory<T>(history: readonly T[], entry: T, cap?: number): T[];
+/** Run a lane-owned file read/modify/write transaction under its sidecar lock. */
+export declare function withLaneRecordFileLock<T>(recordPath: string, fn: () => T): T;
 export declare function parseLaneRecord(raw: unknown, filePath?: string): LaneRecord;
 export declare function parseQuestionRecord(raw: unknown, filePath?: string): QuestionRecord;
 /**

package/dist/lib/lanes/store.js

@@ -222,6 +222,10 @@ function withRecordLock(recordPath, deps, fn) {
         }
     }
 }
+/** Run a lane-owned file read/modify/write transaction under its sidecar lock. */
+export function withLaneRecordFileLock(recordPath, fn) {
+    return withRecordLock(recordPath, defaultStoreDeps(), fn);
+}
 function readJsonFile(filePath, deps) {
     let text;
     try {

package/dist/lib/lanes/story-switch.d.ts

@@ -0,0 +1,21 @@
+import type { AttributionHistoryEntry, LaneEnvelope, LaneRecord, StorySwitchUnacknowledgedNote } from "./types.js";
+export declare function storySwitchNotice(previousProjectId: string, previousStoryId: string, projectId: string, storyId: string): string | undefined;
+export declare function artifactIdentityKeys(artifacts: readonly unknown[] | undefined): string[];
+export interface StorySwitchRollbackSnapshot {
+    message_id: string;
+    project_id: string;
+    story_id: string;
+    no_story_reason?: string;
+    added_story?: NonNullable<LaneRecord["stories"]>[number];
+    story_switch_unacknowledged: StorySwitchUnacknowledgedNote | undefined;
+}
+/** Restore only the attribution write owned by this failed command attempt. */
+export declare function rollbackStorySwitchAttribution(current: LaneRecord, snapshot: StorySwitchRollbackSnapshot): LaneRecord;
+/** Apply and consume one attribution-switch marker when the next envelope arrives. */
+export declare function applyStorySwitchEnvelope(lane: LaneRecord, envelope: LaneEnvelope, at: string, envelopeRef: string): {
+    suppressCompletion: boolean;
+    clearPending: boolean;
+    storySwitchUnacknowledged?: StorySwitchUnacknowledgedNote;
+    attributionHistory?: AttributionHistoryEntry[];
+};
+//# sourceMappingURL=story-switch.d.ts.map

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

@@ -0,0 +1,75 @@
+export function storySwitchNotice(previousProjectId, previousStoryId, projectId, storyId) {
+    if (previousProjectId === projectId && previousStoryId === storyId)
+        return undefined;
+    const from = `${previousProjectId}/${previousStoryId || "(no story)"}`;
+    const to = `${projectId}/${storyId || "(no story)"}`;
+    return `Story changed: ${from} -> ${to}. The previous story is closed; report only on the new story in this turn's envelope.`;
+}
+export function artifactIdentityKeys(artifacts) {
+    if (!Array.isArray(artifacts))
+        return [];
+    return artifacts.flatMap((artifact) => {
+        if (typeof artifact === "string" && artifact.trim())
+            return [`value:${artifact.trim()}`];
+        if (artifact === null || typeof artifact !== "object" || Array.isArray(artifact))
+            return [];
+        const record = artifact;
+        const url = typeof record.url === "string" ? record.url.trim() : "";
+        const path = typeof record.path === "string" ? record.path.trim() : "";
+        const values = [url && `url:${url}`, path && `path:${path}`].filter((value) => Boolean(value));
+        return values;
+    }).sort();
+}
+/** Restore only the attribution write owned by this failed command attempt. */
+export function rollbackStorySwitchAttribution(current, snapshot) {
+    if (current.story_switch_pending?.message_id !== snapshot.message_id)
+        return current;
+    const addedStory = snapshot.added_story;
+    const stories = (current.stories ?? []).filter((story) => !(addedStory && story.project_id === addedStory.project_id && story.story_id === addedStory.story_id &&
+        story.added_at === addedStory.added_at));
+    return {
+        ...current,
+        project_id: snapshot.project_id,
+        story_id: snapshot.story_id,
+        no_story_reason: snapshot.no_story_reason,
+        stories,
+        attribution_history: current.attribution_history.filter((entry) => entry.message_id !== snapshot.message_id),
+        story_switch_pending: undefined,
+        story_switch_unacknowledged: snapshot.story_switch_unacknowledged,
+    };
+}
+function sameKeys(left, right) {
+    return left.length > 0 && left.length === right.length && left.every((key, index) => key === right[index]);
+}
+/** Apply and consume one attribution-switch marker when the next envelope arrives. */
+export function applyStorySwitchEnvelope(lane, envelope, at, envelopeRef) {
+    const pending = lane.story_switch_pending;
+    if (!pending)
+        return { suppressCompletion: false, clearPending: false };
+    if (envelope.story_complete !== true)
+        return { suppressCompletion: false, clearPending: false };
+    const currentKeys = artifactIdentityKeys(envelope.artifacts);
+    const suppressCompletion = sameKeys(pending.previous_artifact_keys, currentKeys);
+    if (!suppressCompletion)
+        return { suppressCompletion: false, clearPending: true };
+    const note = {
+        event: "story_switch_unacknowledged",
+        previous_project_id: pending.previous_project_id,
+        previous_story_id: pending.previous_story_id,
+        project_id: pending.project_id,
+        story_id: pending.story_id,
+        message_id: pending.message_id,
+        envelope_ref: envelopeRef,
+        at,
+        artifact_keys: currentKeys,
+    };
+    return {
+        suppressCompletion: true,
+        clearPending: true,
+        storySwitchUnacknowledged: note,
+        attributionHistory: lane.attribution_history.map((entry) => entry.message_id === pending.message_id
+            ? { ...entry, story_switch_unacknowledged: note }
+            : entry),
+    };
+}
+//# sourceMappingURL=story-switch.js.map

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

@@ -351,6 +351,27 @@ export interface AttributionHistoryEntry {
     story_id: string;
     message_id: string;
     at: string;
+    story_switch_unacknowledged?: StorySwitchUnacknowledgedNote;
+}
+export interface StorySwitchPending {
+    previous_project_id: string;
+    previous_story_id: string;
+    project_id: string;
+    story_id: string;
+    message_id: string;
+    at: string;
+    previous_artifact_keys: string[];
+}
+export interface StorySwitchUnacknowledgedNote {
+    event: "story_switch_unacknowledged";
+    previous_project_id: string;
+    previous_story_id: string;
+    project_id: string;
+    story_id: string;
+    message_id: string;
+    envelope_ref: string;
+    at: string;
+    artifact_keys: string[];
 }
 export interface LastEnvelopeRef {
     ref: string;
@@ -573,6 +594,10 @@ export interface LaneRecord {
     envelope_summary?: string;
     attribution_history: AttributionHistoryEntry[];
     last_envelope?: LastEnvelopeRef;
+    /** Pending attribution change, consumed by the next terminal envelope. */
+    story_switch_pending?: StorySwitchPending;
+    /** Last completion suppressed because the new story repeated prior evidence. */
+    story_switch_unacknowledged?: StorySwitchUnacknowledgedNote;
     /** Effective model id recorded at create/spawn. Omitted when the provider chooses. */
     model?: string;
     /** Where the effective model came from; repaired models stay pinned across the account move. */

package/dist/lib/lanes/types.js

@@ -227,7 +227,7 @@ export const LANE_FIELD_WRITERS = {
     priority: ["command"], worker: ["creator", "command"], worker_path: ["creator", "command"], worker_pack: ["creator", "command"], worker_profile: ["creator", "command"], worker_profile_hash: ["creator", "command", "spawn"], registry_worker: ["creator", "command", "spawn"], registry_worker_approval_history: ["command", "watcher", "reconcile"], worker_profile_repin_history: ["command"], worker_profile_ignored: ["creator", "command", "spawn"], worker_policy_delivery: ["command", "spawn"],
     keep_alive: ["creator", "command"], keep_alive_standing: ["command"], keep_alive_opted_in_at: ["creator", "command"], keep_alive_blocked_reason: ["command", "reconcile"], keep_alive_resume_count: ["command", "reconcile"], keep_alive_history: ["reconcile"], keep_alive_blocked_resume_streak: ["reconcile", "spawn", "watcher"], keep_alive_last_resume_at: ["command", "reconcile"], keep_alive_next_eligible_at: ["command", "reconcile"], keep_alive_exhausted_at: ["command", "reconcile"],
     provider: ["creator"], account: ["creator", "spawn", "command", "watcher", "reconcile"], account_selection: ["creator", "command"], admission_accounts: ["creator", "command"], account_history: ["command", "spawn", "watcher", "reconcile"], failed_resume_history: ["command"], pending_resume: ["command", "spawn", "watcher", "reconcile"], placement_default: ["creator"], host: ["creator", "command"], origin_host: ["creator"], origin_host_source: ["creator"],
-    version: ["creator"], created_at: ["creator"], updated_at: ["creator"], ended_at: ["reconcile"], envelope_summary: ["reconcile"], attribution_history: ["command"],
+    version: ["creator"], created_at: ["creator"], updated_at: ["creator"], ended_at: ["reconcile"], envelope_summary: ["reconcile"], attribution_history: ["command", "watcher", "reconcile"], story_switch_pending: ["command", "watcher", "reconcile"], story_switch_unacknowledged: ["watcher", "reconcile"],
     last_envelope: ["watcher", "reconcile"], model: ["creator", "spawn", "command"], model_source: ["creator", "spawn", "command"], effort: ["creator", "spawn", "command"], effort_source: ["creator", "spawn", "command"], fast_mode: ["spawn"],
     last_message_at: ["command"], status_gate: ["spawn", "watcher"], status_gate_history: ["watcher", "reconcile"], blocker_freshness_state: ["watcher"], kr_freshness_state: ["watcher"], last_compaction: ["spawn"], story_complete: ["watcher", "reconcile"], story_complete_reason: ["watcher", "reconcile"], story_status: ["watcher", "reconcile"],
     overdue: ["reconcile"], overdue_at: ["reconcile"], last_host_report_at: ["watcher", "spawn", "reconcile"], stalled: ["watcher"], stalled_at: ["watcher"], stalled_reason: ["watcher"],