@indigoai-us/hq-cli 5.293.0 → 5.294.0

package/dist/commands/lanes.js

@@ -17,11 +17,13 @@ import { createLaneMoveHandlers } from "./lanes-move.js";
 import { createLaneQuestionsHandlers } from "./lanes-questions.js";
 import { createLaneResumeHandlers } from "./lanes-resume.js";
 import { createLaneWatchHandlers } from "./lanes-watch.js";
+import { createLaneStoryHandlers } from "./lanes-stories.js";
 import { callerMatchesSessionSenior, assertPlacementEnabled, defaultLanePlacementEnabled, parsePlacementPolicy, processLanePlacementCompany, readClaudeAccountBalanceSignalsEnabled, readLanePlacementEnabled, } from "./lanes-shared.js";
 export { CLAUDE_ACCOUNT_BALANCE_SIGNALS_FLAG, LANE_OUTPOST_LOAD_BALANCING_FLAG } from "./lanes-shared.js";
 export { resolveAnswerChoice } from "./lanes-questions.js";
 import { registerOutpostPrunerCommand } from "./outpost-pruner.js";
 import { registerLaneKpisCommand } from "./lanes-kpis.js";
+import { registerLaneAutopilotReportCommand } from "./lanes-autopilot.js";
 import { registerLaneChecksCommand } from "./lanes-checks.js";
 import { registerLaneReportCommands } from "./lanes-report.js";
 import { registerLaneRepoMergeHoldCommand } from "./lanes-hold.js";
@@ -55,7 +57,7 @@ import { sessionIdFromEnv } from "../lib/mesh/live/session-identity.js";
 import { listLaneReviews } from "../lib/lanes/reviews.js";
 import { effectiveAccountHome } from "../lib/lanes/account-home.js";
 import { AccountResolutionError, compareLaneQueueOrder, LANE_PROVIDERS, LANE_STATES, QUESTION_STATUSES, SENIOR_KINDS, accountStatus, appendCappedHistory, canonicalizeHome, createLane, decideAdmission, defaultLivenessDeps, defaultSystemdUserDir, defaultThrottleDeps, installReconcileTimer, providerPathEnv, probeDrainHookRegistration, isLanesError, isLaneVersionConflict, isTerminalLaneState, aliveDirectChildren, assignedChildHireGrants, hireGrantCapacityError, planHireGrantBackfill, terminalChildResumeHireGrantError, withHireGrantAdmission, laneStoryLedgerEnabled, validateProjectStories, buildLaneStatusSnapshot, formatLaneStatusHuman, listLaneIds, listQuestionIds, loadLanesConfig, laneRunsHere, MAX_LANE_DEPTH, MONITOR_ERROR_EXIT_CODE, readLiveMonitorEvidence, resolveMachineIdentity as lookupMachineIdentity, loadLivenessIndex, parseLaneProvider, parseLaneRecord, parseLaneState, parseQuestionRecord, parseSeniorKind, readAllLanes, readLane, sanitizeHostComponent, retryUpdateLane, syncLaneRecordFromOwner, readQuestion, resolveAccount, resolveLaneWorker, ignoredWorkerProfileFields, loadWorkerProfile, loadWorkerProfileWithRegistry, registryWorkerRecord, runReconcilePass, sessionLiveness, tryReadLane, uninstallReconcileTimer, updateLane, updateQuestion, dropboxDir, laneDeliveryMechanism, hasActiveAdmissionReservation, hasActivePendingResume, hasRecordedSessionId, hasEarlierEligibleQueuedLane, laneAdmissionCapReason, providerSupportsSessionResume, providerSessionPortable, sessionNotPortableMessage, withLaneAdmissionLock, withAllLaneAdmissionLocks, readWorkerRunResult, resumeCommandRefusal, withLaneHireLocks, raiseLaneQuestion, sha256Text, } from "../lib/lanes/index.js";
-import { activeLaneStories, laneStories, laneStory, storyWarning, } from "../lib/lanes/stories.js";
+import { laneStories, storyWarning, } from "../lib/lanes/stories.js";
 import { resolveLaneKeepAlive } from "../lib/lanes/profile.js";
 import { resolveLaneCompany } from "../lib/lanes/lane-company.js";
 import { doneKeepAliveVerdict, hasPendingKeepAliveWork, keepAliveExclusion, LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, loadRetiredLaneIds, } from "../lib/lanes/keep-alive.js";
@@ -5295,6 +5297,13 @@ function appendCallerSeniorReason(message, authorization) {
         ? message
         : `${message}; authorization refused: ${callerSeniorReason(authorization)}`;
 }
+function assertQuestionAnswerAuthorized(ctx, lane) {
+    const authorization = callerSeniorAuthorization(ctx, lane.senior);
+    if (authorization.authorized)
+        return;
+    const reason = callerSeniorReason(authorization);
+    throw new LanesError("question_answer_unauthorized", appendCallerSeniorReason(`Only senior ${seniorKey(lane.senior)} may answer lane ${lane.lane_id}'s Outpost question`, authorization), { lane_id: lane.lane_id, senior: lane.senior, reason });
+}
 function laneGrantTargetHostedHere(ctx, lane) {
     if (lane.host.kind === "local") {
         return laneRunsHere(lane, reconcileHostFromCtx(ctx));
@@ -6447,84 +6456,6 @@ function laneWithRecoveredProviderSession(hqRoot, lane) {
             : {}),
     };
 }
-function storyCommandTarget(lane, storyId, project) {
-    const projectId = project?.trim() || lane.project_id;
-    const normalizedStoryId = storyId.trim();
-    if (!projectId) {
-        throw new LanesError("missing_project", "--project is required", {});
-    }
-    if (!normalizedStoryId) {
-        throw new LanesError("missing_story", "<story-id> is required", {});
-    }
-    const story = laneStory(lane, projectId, normalizedStoryId);
-    if (!story) {
-        throw new LanesError("story_not_on_lane", `Story ${projectId}/${normalizedStoryId} is not carried by lane ${lane.lane_id}`, { lane_id: lane.lane_id, project_id: projectId, story_id: normalizedStoryId });
-    }
-    return { projectId, storyId: normalizedStoryId, story };
-}
-function updateCarriedStory(lane, projectId, storyId, status, at, extras = {}) {
-    const stories = laneStories(lane).map((story) => story.project_id === projectId && story.story_id === storyId
-        ? {
-            ...story,
-            status,
-            updated_at: at,
-            blocked_reason: extras.blocked_reason,
-            verified_at: extras.verified_at,
-            verified_by: extras.verified_by,
-        }
-        : story);
-    return {
-        ...lane,
-        project_id: projectId,
-        story_id: storyId,
-        stories,
-    };
-}
-function addCarriedStory(lane, projectId, storyId, at) {
-    if (laneStory(lane, projectId, storyId)) {
-        throw new LanesError("story_already_on_lane", `Story ${projectId}/${storyId} is already carried by lane ${lane.lane_id}`, {
-            lane_id: lane.lane_id,
-            project_id: projectId,
-            story_id: storyId,
-        });
-    }
-    return {
-        ...lane,
-        ...(lane.story_id.trim() ? {} : { project_id: projectId, story_id: storyId }),
-        stories: [
-            ...laneStories(lane),
-            { project_id: projectId, story_id: storyId, status: "in_progress", added_at: at, updated_at: at },
-        ],
-    };
-}
-function callerMayVerifyStory(ctx, lane) {
-    const callerLaneId = ctx.env.HQ_LANE_ID?.trim();
-    if (callerLaneId) {
-        return lane.senior.kind === "lane" && lane.senior.id === callerLaneId;
-    }
-    if (lane.senior.kind === "user")
-        return true;
-    if (lane.senior.kind === "lane")
-        return false;
-    return sessionIdFromEnv(ctx.env) === lane.senior.id;
-}
-async function ensureStoryThread(ctx, lane, projectId, storyId = lane.story_id) {
-    const company = lane.mesh_company ?? lane.company;
-    if (!company)
-        return lane;
-    return ensureLaneThreadRecord(ctx, lane, projectId, storyId);
-}
-async function ensureStoryThreadForTransition(ctx, lane, projectId, storyId) {
-    try {
-        return { lane: await ensureStoryThread(ctx, lane, projectId, storyId) };
-    }
-    catch (err) {
-        const warning = storyNotOnBoardWarning(err);
-        if (warning === undefined)
-            throw err;
-        return { lane, warning };
-    }
-}
 async function ensureLaneThreadRecord(ctx, lane, projectId = lane.project_id, storyId = lane.story_id, laneStatus = lane.state) {
     const company = lane.mesh_company ?? lane.company;
     if (!company)
@@ -6546,228 +6477,6 @@ async function ensureLaneThreadRecord(ctx, lane, projectId = lane.project_id, st
     }
     return updated;
 }
-async function emitStoryTransition(ctx, lane, projectId, storyId, event, status, payload = {}, skipStoryStatusPatch = false) {
-    const company = lane.mesh_company ?? lane.company;
-    if (!company)
-        return;
-    const ready = await ensureStoryThread(ctx, lane, projectId, storyId);
-    if (!ready.thread_id)
-        return;
-    await emitLaneMeshEvent(ctx, company, ready.thread_id, event, {
-        lane_id: ready.lane_id,
-        project_id: projectId,
-        story_id: storyId,
-        ...payload,
-        lane_status: lane.state,
-    });
-    if (!skipStoryStatusPatch && projectId?.trim() && storyId?.trim()) {
-        await ctx.mesh.patchStoryStatus(company, projectId, storyId, status === "blocked" ? "in_progress" : status);
-    }
-}
-function sameCommittedStory(current, expected, projectId, storyId) {
-    const currentStory = laneStory(current, projectId, storyId);
-    const expectedStory = laneStory(expected, projectId, storyId);
-    return (current.project_id === expected.project_id &&
-        current.story_id === expected.story_id &&
-        JSON.stringify(currentStory) === JSON.stringify(expectedStory));
-}
-async function commitStoryTransition(ctx, before, next, projectId, storyId, event, status, payload = {}, skipStoryStatusPatch = false) {
-    try {
-        await emitStoryTransition(ctx, next, projectId, storyId, event, status, payload, skipStoryStatusPatch);
-        return undefined;
-    }
-    catch (err) {
-        const warning = storyNotOnBoardWarning(err);
-        if (warning !== undefined)
-            return warning;
-        try {
-            const current = readLane(ctx.hqRoot(), next.lane_id);
-            if (!sameCommittedStory(current, next, projectId, storyId)) {
-                throw new LanesError("story_transition_rollback_conflict", `Story ${projectId}/${storyId} changed while mesh publication failed`, { lane_id: next.lane_id, project_id: projectId, story_id: storyId });
-            }
-            updateLane(ctx.hqRoot(), next.lane_id, current.version, "command", (latest) => {
-                if (!sameCommittedStory(latest, next, projectId, storyId)) {
-                    throw new LanesError("story_transition_rollback_conflict", `Story ${projectId}/${storyId} changed before rollback`, { lane_id: next.lane_id, project_id: projectId, story_id: storyId });
-                }
-                return {
-                    ...latest,
-                    project_id: before.project_id,
-                    story_id: before.story_id,
-                    stories: before.stories,
-                };
-            });
-        }
-        catch (rollbackErr) {
-            process.stderr.write(`hq lanes: story transition rollback failed for ${next.lane_id}/${projectId}/${storyId}: ${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)}\n`);
-        }
-        throw err;
-    }
-}
-async function runStoryList(ctx, laneId) {
-    const lane = readLane(ctx.hqRoot(), laneId);
-    printJson({
-        ok: true,
-        action: "story.list",
-        lane_id: laneId,
-        stories: laneStories(lane),
-        active_stories: activeLaneStories(lane),
-        story_warning: storyWarning(lane) ?? null,
-    });
-}
-async function runStoryAdd(ctx, laneId, storyId, opts) {
-    const hqRoot = ctx.hqRoot();
-    let lane = readLane(hqRoot, laneId);
-    assertLaneRunsHereForOperatorMutation(ctx, lane, "update story status for");
-    const projectId = opts.project?.trim() || lane.project_id;
-    if (!projectId)
-        throw new LanesError("missing_project", "--project is required", {});
-    const normalizedStoryId = storyId.trim();
-    if (!normalizedStoryId)
-        throw new LanesError("missing_story", "<story-id> is required", {});
-    if (ctx.storyLedgerEnabled()) {
-        validateProjectStories(hqRoot, projectId, [normalizedStoryId], lane.company?.slug);
-    }
-    const company = lane.mesh_company ?? lane.company;
-    const warnings = [];
-    let storyKnownAbsent = false;
-    if (company) {
-        const boardCheck = await storyBoardCheck(ctx, company, projectId, [normalizedStoryId]);
-        if (boardCheck.warning !== undefined)
-            warnings.push(boardCheck.warning);
-        storyKnownAbsent = boardCheck.absentStoryIds.has(normalizedStoryId);
-    }
-    const at = ctx.now().toISOString();
-    const thread = await ensureStoryThreadForTransition(ctx, lane, projectId, normalizedStoryId);
-    lane = thread.lane;
-    if (thread.warning !== undefined)
-        warnings.push(thread.warning);
-    const before = lane;
-    const next = casUpdateLane(hqRoot, laneId, (current) => {
-        assertLaneRunsHereForOperatorMutation(ctx, current, "update story status for");
-        const added = addCarriedStory(current, projectId, normalizedStoryId, at);
-        return {
-            ...added,
-            no_story_reason: undefined,
-        };
-    });
-    const transitionWarning = await commitStoryTransition(ctx, before, next, projectId, normalizedStoryId, "lane_started", "in_progress", {}, storyKnownAbsent);
-    if (transitionWarning !== undefined)
-        warnings.push(transitionWarning);
-    const finalLane = readLane(hqRoot, laneId);
-    printJson({
-        ok: true,
-        action: "story.add",
-        lane_id: laneId,
-        project_id: projectId,
-        story_id: normalizedStoryId,
-        status: "in_progress",
-        story_warning: combinedStoryWarning(finalLane, warnings),
-        lane: finalLane,
-    });
-}
-async function runStoryStart(ctx, laneId, storyId, opts) {
-    const hqRoot = ctx.hqRoot();
-    let lane = readLane(hqRoot, laneId);
-    assertLaneRunsHereForOperatorMutation(ctx, lane, "update story status for");
-    const target = storyCommandTarget(lane, storyId, opts.project);
-    if (target.story.status === "done") {
-        throw new LanesError("story_already_done", `Story ${target.projectId}/${target.storyId} is done and cannot be started again`, {
-            lane_id: laneId,
-            project_id: target.projectId,
-            story_id: target.storyId,
-        });
-    }
-    const at = ctx.now().toISOString();
-    const warnings = [];
-    const thread = await ensureStoryThreadForTransition(ctx, lane, target.projectId, target.storyId);
-    lane = thread.lane;
-    if (thread.warning !== undefined)
-        warnings.push(thread.warning);
-    const before = lane;
-    const next = casUpdateLane(hqRoot, laneId, (current) => {
-        assertLaneRunsHereForOperatorMutation(ctx, current, "update story status for");
-        return updateCarriedStory(current, target.projectId, target.storyId, "in_progress", at);
-    });
-    const transitionWarning = await commitStoryTransition(ctx, before, next, target.projectId, target.storyId, "lane_started", "in_progress");
-    if (transitionWarning !== undefined)
-        warnings.push(transitionWarning);
-    const finalLane = readLane(hqRoot, laneId);
-    printJson({ ok: true, action: "story.start", lane_id: laneId, project_id: target.projectId, story_id: target.storyId, status: "in_progress", story_warning: combinedStoryWarning(finalLane, warnings), lane: finalLane });
-}
-async function runStoryBlock(ctx, laneId, storyId, opts) {
-    const hqRoot = ctx.hqRoot();
-    let lane = readLane(hqRoot, laneId);
-    assertLaneRunsHereForOperatorMutation(ctx, lane, "update story status for");
-    const target = storyCommandTarget(lane, storyId, opts.project);
-    if (target.story.status === "done") {
-        throw new LanesError("story_already_done", `Story ${target.projectId}/${target.storyId} is done and cannot be blocked again`, {
-            lane_id: laneId,
-            project_id: target.projectId,
-            story_id: target.storyId,
-        });
-    }
-    const reason = opts.reason?.trim();
-    if (!reason)
-        throw new LanesError("missing_block_reason", "--reason is required", {});
-    const at = ctx.now().toISOString();
-    const warnings = [];
-    const thread = await ensureStoryThreadForTransition(ctx, lane, target.projectId, target.storyId);
-    lane = thread.lane;
-    if (thread.warning !== undefined)
-        warnings.push(thread.warning);
-    const before = lane;
-    const next = casUpdateLane(hqRoot, laneId, (current) => {
-        assertLaneRunsHereForOperatorMutation(ctx, current, "update story status for");
-        return updateCarriedStory(current, target.projectId, target.storyId, "blocked", at, { blocked_reason: reason });
-    });
-    const transitionWarning = await commitStoryTransition(ctx, before, next, target.projectId, target.storyId, "lane_blocked", "blocked", { blocked_reason: reason });
-    if (transitionWarning !== undefined)
-        warnings.push(transitionWarning);
-    const finalLane = readLane(hqRoot, laneId);
-    printJson({ ok: true, action: "story.block", lane_id: laneId, project_id: target.projectId, story_id: target.storyId, status: "blocked", blocked_reason: reason, story_warning: combinedStoryWarning(finalLane, warnings), lane: finalLane });
-}
-async function runStoryDone(ctx, laneId, storyId, opts) {
-    const hqRoot = ctx.hqRoot();
-    let lane = readLane(hqRoot, laneId);
-    assertLaneRunsHereForOperatorMutation(ctx, lane, "update story status for");
-    if (!opts.verified) {
-        throw new LanesError("senior_verification_required", "Only a senior may mark a story done; pass --verified after reviewing or merging it", { lane_id: laneId });
-    }
-    if (!callerMayVerifyStory(ctx, lane)) {
-        throw new LanesError("senior_verification_required", `Caller is not the senior for lane ${laneId}`, {
-            lane_id: laneId,
-            senior: lane.senior,
-        });
-    }
-    const target = storyCommandTarget(lane, storyId, opts.project);
-    if (target.story.status !== "review") {
-        throw new LanesError("story_not_ready_for_verification", `Story ${target.projectId}/${target.storyId} must be in review before senior verification`, {
-            lane_id: laneId,
-            project_id: target.projectId,
-            story_id: target.storyId,
-            status: target.story.status,
-        });
-    }
-    const at = ctx.now().toISOString();
-    const warnings = [];
-    const thread = await ensureStoryThreadForTransition(ctx, lane, target.projectId, target.storyId);
-    lane = thread.lane;
-    if (thread.warning !== undefined)
-        warnings.push(thread.warning);
-    const before = lane;
-    const next = casUpdateLane(hqRoot, laneId, (current) => {
-        assertLaneRunsHereForOperatorMutation(ctx, current, "update story status for");
-        return updateCarriedStory(current, target.projectId, target.storyId, "done", at, {
-            verified_at: at,
-            verified_by: current.senior,
-        });
-    });
-    const transitionWarning = await commitStoryTransition(ctx, before, next, target.projectId, target.storyId, "lane_done", "done", { summary: "Senior verification complete" });
-    if (transitionWarning !== undefined)
-        warnings.push(transitionWarning);
-    const finalLane = readLane(hqRoot, laneId);
-    printJson({ ok: true, action: "story.done", lane_id: laneId, project_id: target.projectId, story_id: target.storyId, status: "done", verified: true, story_warning: combinedStoryWarning(finalLane, warnings), lane: finalLane });
-}
 /**
  * Registration state of the drain hook in the lane's account home, read the
  * way the provider reads it. Null when the lane has no bound account yet
@@ -8052,6 +7761,19 @@ function attachJsonNoop(cmd) {
 }
 export function registerLanesCommand(parent, deps = {}) {
     const ctx = resolveDeps(deps);
+    const storyHandlers = createLaneStoryHandlers({
+        assertLaneRunsHereForOperatorMutation,
+        casUpdateLane,
+        combinedStoryWarning,
+        emitLaneMeshEvent,
+        ensureLaneThreadRecord,
+        printJson,
+        readLane,
+        storyBoardCheck,
+        storyNotOnBoardWarning,
+        updateLane,
+        validateProjectStories,
+    });
     const accountHandlers = createLaneAccountsHandlers({
         automaticBalanceMoveHistoryReason,
         ensureDir,
@@ -8069,6 +7791,7 @@ export function registerLanesCommand(parent, deps = {}) {
         MAX_PLACEMENT_OUTPOSTS,
         OUTPOST_QUESTION_LOOKUP_CONCURRENCY,
         assertLaneRunsHereForOperatorMutation,
+        assertQuestionAnswerAuthorized,
         assertQuestionCompanyMatchesLane,
         casUpdateQuestion,
         effectiveLaneQuestionCompany,
@@ -8207,6 +7930,11 @@ export function registerLanesCommand(parent, deps = {}) {
     }, wrap);
     registerOutpostPrunerCommand(lanes);
     registerLaneKpisCommand(lanes, { hqRoot: ctx.hqRoot, now: ctx.now, wrap });
+    registerLaneAutopilotReportCommand(lanes, {
+        hqRoot: ctx.hqRoot,
+        now: ctx.now,
+        currentHost: () => resolveAdmissionHost({ hostname: ctx.hostname, readOutpostIdentity: ctx.readOutpostIdentity }),
+    }, wrap);
     const noStoryOption = new Option("--no-story <reason>", "Create a lane without a story and record why");
     noStoryOption.attributeName = () => "noStory";
     lanes
@@ -8418,7 +8146,7 @@ export function registerLanesCommand(parent, deps = {}) {
         .description("List the stories carried by a lane")
         .argument("<lane-id>", "Lane id")
         .action(wrap(async (laneId) => {
-        await runStoryList(ctx, laneId);
+        await storyHandlers.runStoryList(ctx, laneId);
     }));
     stories
         .command("add")
@@ -8427,7 +8155,7 @@ export function registerLanesCommand(parent, deps = {}) {
         .argument("<story-id>", "Story id")
         .option("--project <slug>", "Project id; defaults to the lane's current project")
         .action(wrap(async (laneId, storyId, opts) => {
-        await runStoryAdd(ctx, laneId, storyId, opts);
+        await storyHandlers.runStoryAdd(ctx, laneId, storyId, opts);
     }));
     stories
         .command("start")
@@ -8436,7 +8164,7 @@ export function registerLanesCommand(parent, deps = {}) {
         .argument("<story-id>", "Story id")
         .option("--project <slug>", "Project id; defaults to the lane's current project")
         .action(wrap(async (laneId, storyId, opts) => {
-        await runStoryStart(ctx, laneId, storyId, opts);
+        await storyHandlers.runStoryStart(ctx, laneId, storyId, opts);
     }));
     stories
         .command("block")
@@ -8446,7 +8174,7 @@ export function registerLanesCommand(parent, deps = {}) {
         .requiredOption("--reason <text>", "Why the story is blocked")
         .option("--project <slug>", "Project id; defaults to the lane's current project")
         .action(wrap(async (laneId, storyId, opts) => {
-        await runStoryBlock(ctx, laneId, storyId, opts);
+        await storyHandlers.runStoryBlock(ctx, laneId, storyId, opts);
     }));
     stories
         .command("done")
@@ -8456,7 +8184,7 @@ export function registerLanesCommand(parent, deps = {}) {
         .requiredOption("--verified", "Confirm senior review or merge")
         .option("--project <slug>", "Project id; defaults to the lane's current project")
         .action(wrap(async (laneId, storyId, opts) => {
-        await runStoryDone(ctx, laneId, storyId, opts);
+        await storyHandlers.runStoryDone(ctx, laneId, storyId, opts);
     }));
     lanes
         .command("message")
@@ -8745,9 +8473,11 @@ export function registerLanesCommand(parent, deps = {}) {
         .action(wrap(async (opts) => {
         await runPickup(ctx, opts);
     }));
-    lanes
-        .command("autopilot")
-        .description("Check registered team leads and wake them for ready work")
+    const autopilot = lanes.commands.find((command) => command.name() === "autopilot");
+    if (!autopilot)
+        throw new Error("Lanes autopilot command group was not registered");
+    autopilot
+        .description("Run lead autopilot checks and report follow-through metrics")
         .command("run")
         .description("Run one lead autopilot check pass")
         .option("--dry-run", "Report proposed wakes without writing them")

package/dist/fast-core.js

@@ -18,43 +18,71 @@ export async function runFastCore(argv) {
     const parsed = parseFastCore(argv);
     if (!parsed)
         return;
-    // `root: "live"` — resolve the live HQ root and run the script in it, exactly
-    // as core.ts's runEntry does. Fail soft: if no root can be resolved, run the
-    // script anyway with the inherited environment (the hook already carries
-    // CLAUDE_PROJECT_DIR, and each script has its own root fallback) rather than
-    // crashing a Stop hook on a resolution error.
+    const entry = parsed.entry;
+    // The full graph's process gate accepts textual true/false overrides. It ignores
+    // numeric env values, so preserve that behavior for family flags here too.
+    const familyEnabled = entry.kind !== "native" || !entry.familyFlagKey ||
+        await (await import("./native-fast-route.js")).fastFlagEnabled(entry.familyFlagKey, process.env, { numericEnvironmentOverride: false });
+    const useShell = entry.kind === "native" && Boolean(entry.familyFlagKey) && !familyEnabled;
+    const shouldInjectRoot = useShell
+        ? entry.shellHqRoot === "live" || (entry.shellHqRoot === "reconcile-default" &&
+            !parsed.args.includes("--hq-root") && !parsed.args.includes("--help") && !parsed.args.includes("-h"))
+        : entry.kind === "shell"
+            ? true
+            : entry.root === "live";
+    // `root: "live"` — resolve the live HQ root using the same resolver as the
+    // full command graph. Existing shell fast entries keep their historical
+    // fail-soft behavior; newly routed commands fall back to the full graph so
+    // its expected-user-error formatting remains authoritative.
     let hqRoot;
-    try {
-        hqRoot = resolveLiveRoot(parsed.hqRootArg ? { hqRoot: parsed.hqRootArg } : {});
-    }
-    catch {
-        hqRoot = undefined;
+    if (shouldInjectRoot) {
+        try {
+            hqRoot = resolveLiveRoot(parsed.hqRootArg ? { hqRoot: parsed.hqRootArg } : {});
+        }
+        catch {
+            if (entry.kind === "native") {
+                const { runCli } = await import("./main.js");
+                await runCli();
+                return;
+            }
+            hqRoot = undefined;
+        }
     }
-    if (parsed.entry.kind === "native") {
-        const handlerModule = await import(parsed.entry.modulePath);
-        const handler = handlerModule[parsed.entry.exportName];
+    if (entry.kind === "native" && !useShell) {
+        const { installFastPathStreamErrorHandlers } = await import("./utils/fast-stream-errors.js");
+        installFastPathStreamErrorHandlers();
+        const handlerModule = await import(entry.modulePath);
+        const handler = handlerModule[entry.exportName];
         if (typeof handler !== "function") {
-            throw new Error(`Native fast handler ${parsed.entry.exportName} was not exported`);
+            throw new Error(`Native fast handler ${entry.exportName} was not exported`);
         }
         const chunks = [];
-        for await (const chunk of process.stdin)
-            chunks.push(chunk);
-        const code = await handler(argv, Buffer.concat(chunks).toString("utf8"), process.cwd(), hqRoot);
+        if (entry.readsStdin) {
+            for await (const chunk of process.stdin)
+                chunks.push(chunk);
+        }
+        const code = await handler(parsed.args, entry.readsStdin ? Buffer.concat(chunks).toString("utf8") : "", process.cwd(), hqRoot, entry.name.split(" ").at(-1) ?? entry.name, parsed.hqRootArg);
         // Let Node drain handler output before terminating. The timeout guard's
         // stderr message must survive the native route's process boundary.
         process.exitCode = code;
         return;
     }
-    // Keep the CHILD in the caller's cwd, unlike the generic "live" dispatch. The
-    // relocated scripts read their data tree from the injected root, not cwd, and
-    // hq-session's Work Mesh registration serializes $PWD — so changing directory
-    // to the HQ root would mislabel a bind made from inside a project/worktree.
+    const asset = entry.asset;
+    if (!asset)
+        throw new Error(`Fast route ${entry.name} has no shell companion`);
+    // Some historical registrations run from the live root, others preserve the
+    // caller cwd and only inject HQ_ROOT. Keep those choices explicit per entry.
+    const cwd = entry.kind === "native" && entry.shellCwd === "live"
+        ? hqRoot ?? process.cwd()
+        : process.cwd();
+    const injectRoot = entry.kind === "shell" || entry.kind === "native" &&
+        (entry.shellHqRoot === "live" || entry.shellHqRoot === "reconcile-default" && shouldInjectRoot);
     const { code } = runBundledScript({
-        asset: parsed.entry.asset,
+        asset,
         args: parsed.args,
-        cwd: process.cwd(),
-        hqRoot,
-        env: parsed.entry.name === "hq-session" ? { HQ_HQ_SESSION_NO_CLI: "1" } : undefined,
+        cwd,
+        ...(injectRoot ? { hqRoot } : {}),
+        env: entry.name === "hq-session" ? { HQ_HQ_SESSION_NO_CLI: "1" } : undefined,
     });
     // Propagate verbatim: these scripts use their exit code as their interface.
     process.exit(code);

package/dist/fast-scaffold.d.ts

@@ -15,16 +15,29 @@ export type FastScaffoldScript = {
     kind: "shell";
     /** Path under `assets/scaffold/`, e.g. `core/scripts/foo.sh`. */
     asset: string;
+    root?: "live";
 } | {
-    /** Direct subcommand name — `hq core <name>`. */
+    /** Command path, joined with spaces, e.g. `policy frontmatter`. */
     name: string;
     kind: "native";
     /** Relative ESM module specifier, resolved from fast-core.js. */
     modulePath: string;
     /** Named export which accepts the native fast-handler contract. */
     exportName: string;
-    /** Default-off registry flag for this native route. */
+    /** Existing default-off gate for the whole fast route. */
     flagKey: string;
+    /** Existing family gate that chooses this native handler or its shell companion. */
+    familyFlagKey?: string;
+    /** Shell rollback companion used while the family gate is off. */
+    asset?: string;
+    /** Root context used by the native handler. */
+    root?: "live" | "cwd" | "passthrough";
+    /** Cwd used for a shell rollback companion. Defaults to the caller cwd. */
+    shellCwd?: "caller" | "live";
+    /** Root injection behavior for a shell rollback companion. */
+    shellHqRoot?: "none" | "live" | "reconcile-default";
+    /** Whether this handler consumes stdin. Shell companions inherit stdin directly. */
+    readsStdin?: boolean;
 };
 /** The relocated scripts that qualify for the entrypoint fast path. */
 export declare const FAST_SCAFFOLD_SCRIPTS: readonly FastScaffoldScript[];