@indigoai-us/hq-cli 5.345.147 → 5.345.149

package/dist/commands/lanes.js

@@ -47,6 +47,7 @@ import { appendProjectFocusOverride, readProjectStoryFocusData, removeProjectFoc
 import { appendLaneFocusOverride, assertFocusGuardAllows, makeFocusOverride } from "../lib/lanes/focus-guard.js";
 import { LANE_FOCUS_GUARD_FLAG, LANE_FOCUS_DASHBOARD_FLAG, LANE_HIRE_GRANT_FINISHED_LANES_FLAG, LANE_LIST_SKIP_REMOTE_REFRESH_FLAG, LANE_MESSAGE_ROUTE_OWNER_HOST_FLAG, LANE_ORPHANED_BARE_ID_DROPBOX_REPAIR_FLAG, LANE_PROFILE_PIN_EXHAUSTED_FALLBACK_FLAG, LANE_STATUS_ROW_FIELDS_FLAG, LANE_REAP_STOP_FLAG, LANE_REUSE_REFRESHES_PROFILE_FLAG, LANE_WORKER_CONTINUITY_FLAG, LANE_CONDUCT_LOOP_FLAG, LANE_ENVELOPE_REPAIR_GUIDANCE_FLAG, } from "../lib/lanes/flag-keys.js";
 import { applyContinuitySettings, findWorkerContinuityLane, sameLaneHost, workerContinuityPrompt } from "../lib/lanes/worker-continuity.js";
+import { localHostIdsReferToSameMachine, observeLocalHostIdentity, resolveLocalHostIdentity } from "../lib/lanes/local-host-identity.js";
 import { commitIdleLoopStop, enqueueLoopEnvelope, interruptLoopQueue, interruptLoopQueueForStory, loopControllerIsAlive, loopLaneIsIdle, loopStatus, validateLoopEnvelope } from "../lib/lanes/loop.js";
 import { LOOP_CONTROLLER_RECOVERY_REASON, LOOP_STALL_RESTART_REASON, runLaneLoopController, startLaneLoopController } from "./lanes-loop.js";
 import { configuredCodexRolloutHomes, retainCodexRollouts } from "../lib/lanes/disk-guard.js";
@@ -92,7 +93,9 @@ import { LanesError } from "../lib/lanes/errors.js";
 import { LedgerCorrupt, capacityOptionsFromEnv, readCollectorMark, readNow, rebuildNow, } from "../lib/capacity/ledger.js";
 import { pickAccount } from "../lib/capacity/route.js";
 import { capacityViewAge } from "../lib/capacity/freshness.js";
-import { readLatestEnvelopeRecord } from "../lib/lanes/watcher.js";
+import { applyTerminalToLane, classifyLaneExit, readLatestEnvelopeRecord } from "../lib/lanes/watcher.js";
+import { isSubagentLane, parseLaneEnvelope, parseLaneRunner } from "../lib/lanes/types.js";
+import { nextEnvelopePath } from "../lib/lanes/spawn.js";
 import { loadQuotaState, quotaBlockFor } from "../lib/lanes/quota.js";
 import { SESSION_MOVE_REASON } from "../lib/lanes/move-account.js";
 import { readCompaniesManifestMap } from "../lib/work-context/repo-remote.js";
@@ -101,7 +104,7 @@ import { blockerFreshnessFingerprint, resolveBlockerFreshnessForLane, } from "..
 import { resolveKrFreshnessForShow } from "../lib/lanes/kr-freshness.js";
 import { ensureSessionHome } from "../lib/lanes/session-relink.js";
 import { defaultProbe, validateProfileLaneModel, validateLaneModel, } from "../lib/lanes/models.js";
-import { parseCliModel, refuseOutpostSelfTarget, resolveLaneModel, FOREGROUND_ONLY_RULE, STANDING_AUTHORIZATION, spawnLaneWorker, spawnEnvelopeRepairRequest, laneRunDir, readSpawnManifest, stopLaneProcesses, } from "../lib/lanes/spawn.js";
+import { parseCliModel, refuseOutpostSelfTarget, resolveLaneModel, FOREGROUND_ONLY_RULE, STANDING_AUTHORIZATION, tempHomeRule, spawnLaneWorker, spawnEnvelopeRepairRequest, laneRunDir, readSpawnManifest, stopLaneProcesses, } from "../lib/lanes/spawn.js";
 import { handOffInstallHere } from "../lib/daemon/handoff.js";
 export { spawnLaneWorker };
 export function openPullRequestsForProject(hqRoot, metadata) {
@@ -609,6 +612,7 @@ async function finalizeIdleLoopStop(ctx, lane) {
 function reconcileHostFromCtx(ctx) {
     return resolveAdmissionHost({
         hostname: ctx.hostname,
+        homedir: ctx.homedir,
         readOutpostIdentity: ctx.readOutpostIdentity,
     });
 }
@@ -1409,6 +1413,50 @@ function outpostIdentityUnknownError(message, expectedId, details = {}) {
         fix: `Run ${command} from a registered host, or write ${JSON.stringify(`${expected}\n`)} to ${OUTPOST_ID_PATH}.`,
     });
 }
+function localStableHost(ctx) {
+    const hostname = ctx.hostname().trim();
+    if (!hostname) {
+        throw new LanesError("host_identity_unknown", "Cannot resolve this host for lane placement", {});
+    }
+    const identity = resolveLocalHostIdentity({ homedir: ctx.homedir(), hostname });
+    return { kind: "local", id: identity.id };
+}
+/** Read the stable id when one exists. Does not create or update `~/.hq/lane-host.json`. */
+function recordedLocalHost(ctx) {
+    const hostname = ctx.hostname().trim();
+    if (!hostname) {
+        throw new LanesError("host_identity_unknown", "Cannot resolve this host for lane placement", {});
+    }
+    const observed = observeLocalHostIdentity({ homedir: ctx.homedir(), hostname });
+    if (observed)
+        return { kind: "local", id: observed.id };
+    return { kind: "local", id: hostname };
+}
+function observedLocalMatch(ctx, stableId) {
+    const hostname = ctx.hostname().trim();
+    const observed = observeLocalHostIdentity({ homedir: ctx.homedir(), hostname });
+    return {
+        hostname,
+        machineId: observed?.id ?? stableId,
+        ...(observed ? { aliases: observed.aliases } : {}),
+    };
+}
+function laneCountsOnHost(lane, host, ctx) {
+    if (lane.host.kind !== host.kind)
+        return false;
+    if (host.kind !== "local")
+        return lane.host.id === host.id;
+    if (lane.host.id === host.id)
+        return true;
+    return localHostIdsReferToSameMachine(lane.host.id, observedLocalMatch(ctx, host.id));
+}
+function localLaneContinuesHere(ctx, previous, current) {
+    if (sameLaneHost(previous, current))
+        return true;
+    if (previous.kind !== "local" || current.kind !== "local")
+        return false;
+    return localHostIdsReferToSameMachine(previous.id, observedLocalMatch(ctx, current.id));
+}
 function laneHostFromCtx(ctx, expectedId) {
     const identity = ctx.readOutpostIdentity();
     if (identity.kind === "unknown") {
@@ -1416,11 +1464,7 @@ function laneHostFromCtx(ctx, expectedId) {
     }
     if (identity.kind === "id")
         return { kind: "outpost", id: identity.id };
-    const hostname = ctx.hostname().trim();
-    if (!hostname) {
-        throw new LanesError("host_identity_unknown", "Cannot resolve this host for lane placement", {});
-    }
-    return { kind: "local", id: hostname };
+    return recordedLocalHost(ctx);
 }
 async function readOutpostCapacity(ctx, outpostId) {
     return readOutpostCapacityUncached(ctx, outpostId);
@@ -2118,14 +2162,14 @@ async function loadClaudeBalanceHostSnapshots(ctx, hqRoot, config, options = {})
     });
     const snapshots = [{
             capacity: local,
-            lanes: localLanes.filter((lane) => lane.host.kind === localHost.kind && lane.host.id === localHost.id),
+            lanes: localLanes.filter((lane) => laneCountsOnHost(lane, localHost, ctx)),
             laneListAvailable: true,
         }];
     if (localHost.kind === "outpost") {
         const hostname = ctx.hostname().trim();
         const actualLocalHost = { kind: "local", id: hostname };
         const actualLocalLanes = hostname
-            ? localLanes.filter((lane) => lane.host.kind === "local" && lane.host.id === hostname)
+            ? localLanes.filter((lane) => laneCountsOnHost(lane, actualLocalHost, ctx))
             : [];
         if (hostname) {
             snapshots.push({
@@ -2759,6 +2803,7 @@ async function applyThrottle(hqRoot, config, ctx, current, provider, pinnedAccou
         last_busy: state.last_busy ?? null,
         busy_source: state.busy_source,
         sampled_at: state.sampled_at,
+        ...(state.memory_hold !== undefined ? { memory_hold: state.memory_hold } : {}),
     };
     if (current.action === "queue")
         return { action: "queue", reason: "throttle", throttle };
@@ -2913,7 +2958,7 @@ export function checkpointInstruction(worker) {
         ...names.map((name) => `- ${name}`),
     ].join("\n");
 }
-export function composeWorkerBrief(worker, taskBrief) {
+export function composeWorkerBrief(worker, taskBrief, hqRoot) {
     const yaml = worker.workerYaml;
     const name = yaml.worker?.name ?? worker.id;
     const description = yaml.worker?.description ?? worker.description ?? "";
@@ -2968,13 +3013,15 @@ export function composeWorkerBrief(worker, taskBrief) {
         "",
         FOREGROUND_ONLY_RULE,
         "",
+        tempHomeRule(hqRoot),
+        "",
     ].join("\n");
 }
 /**
- * A lane with no worker still carries the standing authorization paragraph
- * and the foreground-only rule.
+ * A lane with no worker still carries the standing authorization paragraph,
+ * the foreground-only rule and the temp-home rule.
  */
-export function composeGeneralBrief(taskBrief) {
+export function composeGeneralBrief(taskBrief, hqRoot) {
     return [
         taskBrief.replace(/\s+$/, ""),
         "",
@@ -2983,6 +3030,8 @@ export function composeGeneralBrief(taskBrief) {
         "",
         FOREGROUND_ONLY_RULE,
         "",
+        tempHomeRule(hqRoot),
+        "",
     ].join("\n");
 }
 function parseMaxRuntimeSeconds(raw, workerId) {
@@ -3387,6 +3436,9 @@ function mintMessageId() {
     return `msg_${Date.now().toString(36)}_${randomBytes(3).toString("hex")}`;
 }
 async function runCreate(ctx, opts) {
+    if (opts.runner !== undefined && parseLaneRunner(opts.runner) === "subagent") {
+        return runCreateSubagent(ctx, opts);
+    }
     const hqRoot = ctx.hqRoot();
     const requestedHireGrant = opts.hireGrant === undefined
         ? undefined
@@ -3673,6 +3725,7 @@ async function runCreate(ctx, opts) {
             provider,
             company: company ?? meshCompany,
             freshThread: opts.freshThread,
+            runsHere: (lane) => laneRunsHereForOperatorMutation(ctx, lane),
         })
         : { resumable: false };
     const profileDefaultsApply = profile !== undefined && profile.meta.provider === provider;
@@ -3757,14 +3810,21 @@ async function runCreate(ctx, opts) {
     if (placementToApply !== undefined) {
         const currentHost = laneHostFromCtx(ctx);
         if (placementToApply.kind === "local") {
-            placementBalanceHostOverride = currentHost;
-            placementHostOverride = { kind: "local", id: ctx.hostname() };
+            if (currentHost.kind === "local") {
+                const stable = localStableHost(ctx);
+                placementBalanceHostOverride = stable;
+                placementHostOverride = stable;
+            }
+            else {
+                placementBalanceHostOverride = currentHost;
+                placementHostOverride = localStableHost(ctx);
+            }
             outpostId = undefined;
         }
         else if (placementToApply.kind === "outpost") {
             if (currentHost.kind === "outpost" && currentHost.id === placementToApply.id) {
                 placementBalanceHostOverride = currentHost;
-                placementHostOverride = { kind: "local", id: ctx.hostname() };
+                placementHostOverride = localStableHost(ctx);
                 outpostId = undefined;
             }
             else {
@@ -3803,7 +3863,7 @@ async function runCreate(ctx, opts) {
             if (!localHostname) {
                 throw new LanesError("host_identity_unknown", "Cannot resolve this host for automatic lane placement", {});
             }
-            const localHost = { kind: "local", id: localHostname };
+            const localHost = localStableHost(ctx);
             let chosenHostIsCaller = chosenHost.id === currentHost.id ||
                 sanitizeHostComponent(chosenHost.id) === sanitizeHostComponent(localHostname);
             if (!chosenHostIsCaller && chosenHost.kind === "outpost") {
@@ -4021,12 +4081,18 @@ async function runCreate(ctx, opts) {
     const allowedAccounts = validatedAccounts.size > 0 ? [...validatedAccounts] : profileAccounts;
     let accountSelection;
     if (provider === "claude") {
+        const persistedLocalHost = outpostId === undefined && placementHostOverride === undefined
+            ? localStableHost(ctx)
+            : undefined;
+        // Balance against this process. On an Outpost, laneHostFromCtx is that
+        // Outpost id. The stable local id is only what a lane stores when it
+        // spawns here without --outpost.
         const targetHost = placementBalanceHostOverride ?? placementHostOverride ?? (outpostId !== undefined
             ? { kind: "outpost", id: outpostId }
             : laneHostFromCtx(ctx));
         const actualTargetHost = placementHostOverride ?? (outpostId !== undefined
             ? { kind: "outpost", id: outpostId }
-            : { kind: "local", id: ctx.hostname() });
+            : persistedLocalHost);
         balanceTargetHost = targetHost;
         balanceHostLoad = await loadClaudeBalanceHostSnapshots(ctx, hqRoot, config);
         const selected = selectClaudeAccount({
@@ -4059,7 +4125,7 @@ async function runCreate(ctx, opts) {
     const persist = async () => {
         const host = placementHostOverride ?? (outpostId !== undefined
             ? { kind: "outpost", id: outpostId }
-            : { kind: "local", id: ctx.hostname() });
+            : localStableHost(ctx));
         if (opts.loop === true && host.kind === "outpost") {
             throw new LanesError("loop_lane_outpost_unsupported", "Loop lanes currently require the local host", { outpost_id: host.id });
         }
@@ -4075,9 +4141,10 @@ async function runCreate(ctx, opts) {
                 provider,
                 company: company ?? meshCompany,
                 freshThread: opts.freshThread,
+                runsHere: (lane) => laneRunsHereForOperatorMutation(ctx, lane),
             });
             if (workerContinuity.resumable && workerContinuity.previous &&
-                !sameLaneHost(workerContinuity.previous.host, host)) {
+                !localLaneContinuesHere(ctx, workerContinuity.previous.host, host)) {
                 workerContinuity = { previous: workerContinuity.previous, resumable: false, fallbackReason: "host_mismatch" };
             }
         }
@@ -4087,7 +4154,7 @@ async function runCreate(ctx, opts) {
             balanceHostLoad !== undefined && balanceTargetHost !== undefined) {
             const localHost = laneHostFromCtx(ctx);
             if (localHost.kind === balanceTargetHost.kind && localHost.id === balanceTargetHost.id) {
-                const localLanes = loadAllLanes(hqRoot).filter((lane) => lane.host.kind === localHost.kind && lane.host.id === localHost.id);
+                const localLanes = loadAllLanes(hqRoot).filter((lane) => laneCountsOnHost(lane, localHost, ctx));
                 const refreshedLocal = {
                     capacity: buildHostCapacitySnapshot({
                         host: localHost,
@@ -4107,7 +4174,7 @@ async function runCreate(ctx, opts) {
                     : host);
                 const actualTargetHostForPersist = placementHostOverride ?? (outpostId !== undefined
                     ? { kind: "outpost", id: outpostId }
-                    : { kind: "local", id: ctx.hostname() });
+                    : localStableHost(ctx));
                 const selected = selectClaudeAccount({
                     hosts,
                     targetHost: balanceTargetHost,
@@ -4412,8 +4479,8 @@ async function runCreate(ctx, opts) {
     const briefText = `${workerContinuity.resumable && workerContinuity.previous
         ? workerContinuityPrompt(workerContinuity.previous, previousResult?.envelope.summary, previousResult?.ref)
         : ""}${resolvedWorker
-        ? composeWorkerBrief(resolvedWorker, taskBrief)
-        : composeGeneralBrief(taskBrief)}`;
+        ? composeWorkerBrief(resolvedWorker, taskBrief, hqRoot)
+        : composeGeneralBrief(taskBrief, hqRoot)}`;
     fs.writeFileSync(path.join(dest, "brief.md"), briefText);
     if (workerContinuity.resumable && lane.pending_resume) {
         const newBriefPath = path.join(dest, "brief.md");
@@ -7158,6 +7225,7 @@ async function runAdmit(ctx, laneId, opts) {
                     last_busy: state.last_busy ?? null,
                     busy_source: state.busy_source,
                     sampled_at: state.sampled_at,
+                    ...(state.memory_hold !== undefined ? { memory_hold: state.memory_hold } : {}),
                 };
             }
             else if (hasEarlierEligibleQueuedLane(lanes, lane, config, host, (row) => row.worker_profile === undefined
@@ -8810,6 +8878,278 @@ async function dispatchOutpostLaneStop(ctx, lane, reason, quiet = false, behavio
             },
         });
 }
+/**
+ * Register a lane that an in-session subagent runs. The record carries the
+ * same attribution as a process lane (company, project, story, worker, brief,
+ * senior, model) so it shows on the lanes board, but admission and capacity
+ * are skipped and no provider process or watcher starts. The lane is
+ * `running` from creation; `hq lanes progress` reports lines and the result.
+ */
+async function runCreateSubagent(ctx, opts) {
+    const unsupported = [
+        ["keepAlive", "--keep-alive"],
+        ["loop", "--loop"],
+        ["remoteControl", "--remote-control"],
+        ["title", "--title"],
+        ["account", "--account"],
+        ["outpost", "--outpost"],
+        ["placement", "--placement"],
+        ["defaultPlacement", "--default-placement"],
+        ["freshThread", "--fresh-thread"],
+        ["hireGrant", "--hire-grant"],
+        ["timeout", "--timeout"],
+        ["allowExtraUsage", "--allow-extra-usage"],
+    ];
+    for (const [key, flag] of unsupported) {
+        if (opts[key] !== undefined && opts[key] !== false) {
+            throw new LanesError("subagent_runner_option_unsupported", `${flag} is not supported with --runner subagent; the subagent runs inside its senior session`, { option: flag });
+        }
+    }
+    const hqRoot = ctx.hqRoot();
+    const project = opts.project?.trim();
+    const story = opts.story?.trim();
+    const noStoryReason = opts.noStory?.trim();
+    const additionalStories = (opts.additionalStory ?? []).map((value) => value.trim());
+    const briefFile = opts.briefFile?.trim();
+    if (!project)
+        throw new LanesError("missing_project", "--project is required", {});
+    if (opts.story !== undefined && opts.noStory !== undefined) {
+        throw new LanesError("story_selection_conflict", "Pass either --story or --no-story, not both", {});
+    }
+    if (opts.noStory !== undefined && !noStoryReason) {
+        throw new LanesError("missing_no_story_reason", "--no-story requires a non-empty reason", {});
+    }
+    if (!story && !noStoryReason)
+        throw new LanesError("missing_story", "--story is required", {});
+    if (noStoryReason && additionalStories.length > 0) {
+        throw new LanesError("story_selection_conflict", "--additional-story requires --story and cannot be used with --no-story", {});
+    }
+    if (additionalStories.some((value) => value.length === 0)) {
+        throw new LanesError("missing_story", "--additional-story values must be non-empty", {});
+    }
+    const storyIds = story ? [story, ...additionalStories] : [];
+    if (new Set(storyIds).size !== storyIds.length) {
+        throw new LanesError("duplicate_story", "A lane cannot carry the same project/story more than once", {
+            project_id: project,
+            stories: storyIds,
+        });
+    }
+    if (!briefFile)
+        throw new LanesError("missing_brief_file", "--brief-file is required", {});
+    if (opts.focusOverride !== undefined) {
+        if (!opts.focusOverride.trim()) {
+            throw new LanesError("focus_override_reason_required", "--focus-override requires a non-empty reason", {});
+        }
+        assertNoSecretText("focus override reason", opts.focusOverride.trim());
+    }
+    const provider = opts.provider ? parseLaneProvider(opts.provider) : "claude";
+    if (provider !== "claude") {
+        throw new LanesError("subagent_runner_requires_claude", "--runner subagent records a Claude subagent; use --provider claude or omit it", { provider });
+    }
+    if (ctx.env.HQ_LANE_ID?.trim()) {
+        throw new LanesError("subagent_runner_requires_session", "A subagent lane belongs to the session that runs the subagent; a lane worker cannot register one", { caller_lane_id: ctx.env.HQ_LANE_ID.trim() });
+    }
+    const senior = opts.senior ? parseSeniorRef(opts.senior) : defaultSenior(ctx);
+    if (senior.kind === "lane") {
+        throw new LanesError("subagent_runner_requires_session", "A subagent lane's senior must be the session running the subagent (session:<id>) or user", { senior });
+    }
+    assertSeniorExists(hqRoot, senior, ctx);
+    let company = opts.company?.trim() ? await ctx.resolveCompany(opts.company.trim()) : null;
+    const seniorCompany = companyOfSenior(hqRoot, senior, ctx);
+    if (company === null && seniorCompany.binding === "company") {
+        const seniorCompanyIdentifier = seniorCompany.slug ?? (seniorCompany.uid
+            ? canonicalCompanySlugForUid(hqRoot, seniorCompany.uid, senior)
+            : undefined);
+        if (seniorCompanyIdentifier)
+            company = await ctx.resolveCompany(seniorCompanyIdentifier);
+    }
+    let meshCompany = null;
+    if (opts.meshCompany?.trim()) {
+        meshCompany = await ctx.resolveCompany(opts.meshCompany.trim());
+        if (company && (company.uid !== meshCompany.uid || company.slug !== meshCompany.slug)) {
+            throw new LanesError("mesh_company_mismatch", "--mesh-company must match --company when both are provided", {
+                company: company.slug,
+                mesh_company: meshCompany.slug,
+            });
+        }
+    }
+    const depthCap = laneDepthCap(hqRoot, company?.slug);
+    const laneDepth = derivedLaneDepth(hqRoot, senior, ctx);
+    if (laneDepth > depthCap.max) {
+        throw maxLaneDepthError(laneDepth, seniorLaneChain(hqRoot, senior, ctx), `Creating lane at depth ${laneDepth} is refused`, depthCap);
+    }
+    const resolvedWorker = opts.worker !== undefined
+        ? resolveLaneWorker(hqRoot, opts.worker, company?.slug)
+        : undefined;
+    const cliModel = parseCliModel(opts.model);
+    const cliEffort = parseCliEffort(provider, opts.effort);
+    const priority = Number.parseInt(opts.priority ?? "1", 10);
+    if (!Number.isInteger(priority)) {
+        throw new LanesError("invalid_priority", "--priority must be an integer", { value: opts.priority });
+    }
+    const briefAbs = resolveCallerPath(ctx.callerCwd(), briefFile);
+    if (!ctx.existsSync(briefAbs)) {
+        throw new LanesError("brief_not_found", `Brief file not found: ${briefAbs}`, { path: briefAbs });
+    }
+    const taskBrief = fs.readFileSync(briefAbs, "utf8");
+    const createdAt = ctx.now().toISOString();
+    const lane = createLane(hqRoot, {
+        company,
+        ...(company === null && meshCompany ? { mesh_company: meshCompany } : {}),
+        project_id: project,
+        story_id: story ?? "",
+        ...(noStoryReason ? { no_story_reason: noStoryReason } : {}),
+        stories: storyIds.map((storyId) => ({
+            project_id: project,
+            story_id: storyId,
+            status: "in_progress",
+            added_at: createdAt,
+            updated_at: createdAt,
+        })),
+        depth: laneDepth,
+        senior,
+        hire_grant: 0,
+        senior_history: [],
+        state: "running",
+        priority,
+        ...(resolvedWorker ? { worker: resolvedWorker.id, worker_path: resolvedWorker.path } : {}),
+        ...(resolvedWorker?.pack ? { worker_pack: resolvedWorker.pack } : {}),
+        keep_alive: false,
+        provider,
+        runner: "subagent",
+        provider_source: opts.provider ? "cli" : "default",
+        ...(cliModel !== undefined ? { model: cliModel } : {}),
+        model_source: cliModel !== undefined ? "cli" : "none",
+        ...(cliEffort !== undefined ? { effort: cliEffort } : {}),
+        effort_source: cliEffort !== undefined ? "cli" : "none",
+        host: { kind: "local", id: ctx.hostname() },
+        attribution_history: [],
+        created_at: createdAt,
+        updated_at: createdAt,
+    });
+    const dest = runDir(hqRoot, lane.lane_id);
+    ensureDir(path.join(dest, "logs"));
+    ensureDir(path.join(dest, "envelopes"));
+    ensureDir(path.join(dest, "questions"));
+    fs.writeFileSync(path.join(dest, "brief.md"), taskBrief);
+    if (!opts.quiet)
+        printJson({
+            ok: true,
+            action: "create",
+            admitted: [],
+            lane_id: lane.lane_id,
+            state: lane.state,
+            runner: "subagent",
+            queued_reason: null,
+            priority: lane.priority,
+            provider: lane.provider,
+            account: null,
+            model: lane.model ?? null,
+            effort: lane.effort ?? null,
+            effort_source: lane.effort_source ?? null,
+            host: lane.host,
+            company: lane.company,
+            project_id: lane.project_id,
+            story_id: lane.story_id,
+            stories: laneStories(lane),
+            thread_id: null,
+            senior: lane.senior,
+            depth: lane.depth,
+            timeout_secs: null,
+            lane,
+        });
+    return lane;
+}
+/** Longest progress line kept; `hq lanes list` clips its last line further. */
+const SUBAGENT_PROGRESS_LINE_MAX = 500;
+/**
+ * Report on a subagent lane: append a progress line, record the final
+ * envelope (state follows its decision, as for a process lane), or mark it
+ * failed when the subagent ended without one.
+ */
+async function runProgress(ctx, laneId, opts) {
+    const hqRoot = ctx.hqRoot();
+    const line = opts.line?.replace(/\s+/g, " ").trim();
+    const failedReason = opts.failed?.replace(/\s+/g, " ").trim();
+    if (opts.line !== undefined && !line)
+        throw new LanesError("progress_line_empty", "--line must not be empty", {});
+    if (opts.failed !== undefined && !failedReason)
+        throw new LanesError("progress_failed_reason_empty", "--failed requires a non-empty reason", {});
+    if (opts.envelope !== undefined && opts.failed !== undefined) {
+        throw new LanesError("progress_result_conflict", "Pass either --envelope or --failed, not both", {});
+    }
+    if (line === undefined && opts.envelope === undefined && failedReason === undefined) {
+        throw new LanesError("progress_nothing_to_report", "Pass --line, --envelope, or --failed", {});
+    }
+    const lane = readLane(hqRoot, laneId);
+    if (!isSubagentLane(lane)) {
+        throw new LanesError("lane_not_subagent", `Lane ${lane.lane_id} runs as an HQ process; its watcher reports progress`, { lane_id: lane.lane_id });
+    }
+    if (isTerminalLaneState(lane.state)) {
+        throw new LanesError("already_terminal", `Lane ${lane.lane_id} is already ${lane.state}`, { lane_id: lane.lane_id, state: lane.state });
+    }
+    const dest = runDir(hqRoot, lane.lane_id);
+    const appendLine = (text) => {
+        const clipped = text.length > SUBAGENT_PROGRESS_LINE_MAX ? `${text.slice(0, SUBAGENT_PROGRESS_LINE_MAX - 1)}…` : text;
+        ensureDir(path.join(dest, "logs"));
+        fs.appendFileSync(path.join(dest, "logs", "last-message.txt"), `${clipped}\n`);
+    };
+    if (line !== undefined) {
+        assertNoSecretText("progress line", line);
+        appendLine(line);
+    }
+    if (failedReason !== undefined)
+        assertNoSecretText("failure reason", failedReason);
+    const at = ctx.now().toISOString();
+    let updated = lane;
+    let envelopeRef;
+    if (opts.envelope !== undefined) {
+        const envelopeAbs = resolveCallerPath(ctx.callerCwd(), opts.envelope);
+        let text;
+        try {
+            text = fs.readFileSync(envelopeAbs, "utf8");
+        }
+        catch (err) {
+            throw new LanesError("envelope_not_found", `Envelope file not readable: ${envelopeAbs}`, {
+                path: envelopeAbs,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        let envelope;
+        try {
+            envelope = parseLaneEnvelope(JSON.parse(text), { storyBound: lane.no_story_reason === undefined });
+        }
+        catch (err) {
+            throw new LanesError("envelope_invalid", `Envelope is not a valid hq-lane-envelope.v1: ${err instanceof Error ? err.message : String(err)}`, {
+                path: envelopeAbs,
+            });
+        }
+        ensureDir(path.join(dest, "envelopes"));
+        const target = nextEnvelopePath(dest);
+        fs.writeFileSync(target, text.endsWith("\n") ? text : `${text}\n`);
+        envelopeRef = path.posix.join("envelopes", path.basename(target));
+        if (envelope.summary)
+            appendLine(envelope.summary.replace(/\s+/g, " ").trim());
+        updated = applyTerminalToLane(hqRoot, lane.lane_id, classifyLaneExit({ envelope, hasPartialOutput: false }), {
+            envelope,
+            envelopeRef,
+            at,
+        });
+    }
+    else if (failedReason !== undefined) {
+        appendLine(failedReason);
+        updated = applyTerminalToLane(hqRoot, lane.lane_id, { state: "failed", reason: "subagent_failed" }, { at });
+    }
+    printJson({
+        ok: true,
+        action: "progress",
+        lane_id: updated.lane_id,
+        state: updated.state,
+        ...(line !== undefined ? { line } : {}),
+        ...(envelopeRef !== undefined ? { envelope_ref: envelopeRef } : {}),
+        ...(updated.terminal_reason ? { terminal_reason: updated.terminal_reason } : {}),
+    });
+}
 async function runStop(ctx, laneId, reason, quiet = false) {
     const operatorReason = reason?.trim();
     if (reason !== undefined && !operatorReason) {
@@ -9914,7 +10254,11 @@ export function registerLanesCommand(parent, deps = {}) {
     registerLaneAutopilotReportCommand(lanes, {
         hqRoot: ctx.hqRoot,
         now: ctx.now,
-        currentHost: () => resolveAdmissionHost({ hostname: ctx.hostname, readOutpostIdentity: ctx.readOutpostIdentity }),
+        currentHost: () => resolveAdmissionHost({
+            hostname: ctx.hostname,
+            homedir: ctx.homedir,
+            readOutpostIdentity: ctx.readOutpostIdentity,
+        }),
     }, wrap);
     const noStoryOption = new Option("--no-story <reason>", "Create a lane without a story and record why");
     noStoryOption.attributeName = () => "noStory";
@@ -9933,6 +10277,7 @@ export function registerLanesCommand(parent, deps = {}) {
         .option("--fresh-thread", "Skip worker continuity and start a cold provider session")
         .option("--loop", "Keep one worker lane registered to process queued phase envelopes")
         .option("--provider <name>", "claude | codex | grok")
+        .option("--runner <kind>", "process (default) | subagent: register a lane an in-session Claude subagent runs; skips admission and starts no process")
         .option("--remote-control", "Open a Claude lane in Remote Control using account a for login and the selected account for inference")
         .option("--title <text>", "Human-readable Claude Remote Control session title; required with --remote-control")
         .option("--account <id>", "Provider account id, or 'auto' to pick the account with the most room (all accounts are one pool across companies)")
@@ -9950,6 +10295,16 @@ export function registerLanesCommand(parent, deps = {}) {
         .action(wrap(async (opts) => {
         await withCliFeatureUsed("lane_create", () => runCreate(ctx, opts));
     }));
+    lanes
+        .command("progress")
+        .description("Report on a subagent lane: a progress line, the final envelope, or a failure")
+        .argument("<lane-id>", "Lane id")
+        .option("--line <text>", "Progress line shown as the lane's last line")
+        .option("--envelope <path>", "Final hq-lane-envelope.v1 file; the lane state follows its decision")
+        .option("--failed <reason>", "Mark the lane failed when the subagent ended without an envelope")
+        .action(wrap(async (laneId, opts) => {
+        await runProgress(ctx, laneId, opts);
+    }));
     lanes
         .command("approve-target", { hidden: true })
         .argument("<lane-id>", "Lane id")

package/dist/commands/library-add.d.ts

@@ -1,5 +1,5 @@
 import { Readable } from "node:stream";
-import { type CloudAssetMediaKind } from "@indigoai-us/hq-cloud";
+import { type CloudAssetMediaKind, type PullScope, type PullScopeClient } from "@indigoai-us/hq-cloud";
 import type { LibraryCaptionNote, LibraryCaptionRequest } from "./library-caption.js";
 export interface LibraryCompany {
     uid: string;
@@ -37,6 +37,13 @@ export interface LibraryAddDeps {
      * a caption failure never fails the upload. Absent = no captioning.
      */
     caption?: (request: LibraryCaptionRequest) => Promise<LibraryCaptionNote>;
+    /**
+     * The membership's sync scope for the company. Throws when it cannot be
+     * read. Absent = the scope is not checked and nothing is pinned.
+     */
+    syncScope?: (company: LibraryCompany) => Promise<Pick<PullScope, "syncMode" | "prefixSet">>;
+    /** `hq files get`'s pin writer (`.hq/pins.json`). */
+    addPin?: (hqRoot: string, companySlug: string, prefix: string) => void;
 }
 export interface LibraryAddOptions {
     company?: string;
@@ -60,9 +67,19 @@ export interface LibraryAddItem {
     /** AI caption outcome, set when captioning ran for this item. */
     caption?: LibraryCaptionNote;
 }
+export interface LibrarySyncScopeNote {
+    status: "in-scope" | "pinned" | "not-pinned";
+    /** Company-relative pins written (`pinned`) or still needed (`not-pinned`). */
+    pins: string[];
+    /** Set when not pinned and `hq files get` can pin by hand (the library folder). */
+    command?: string;
+    reason?: string;
+}
 export interface LibraryAddResult {
     company: string;
     items: LibraryAddItem[];
+    /** Set when at least one placeholder was written and the scope was checked. */
+    syncScope?: LibrarySyncScopeNote;
 }
 export declare function contentTypeFor(name: string, served?: string): string;
 export declare function mediaKindFor(contentType: string): CloudAssetMediaKind;
@@ -89,6 +106,19 @@ export declare function offloadTimestamp(now: Date): string;
  * only that source.
  */
 export declare function runLibraryAdd(inputs: readonly string[], options: LibraryAddOptions, deps: LibraryAddDeps): Promise<LibraryAddResult>;
+/**
+ * A `shared` or `custom` sync pushes only paths inside the membership's
+ * prefix set (explicit grants plus pins), so a placeholder written outside it
+ * never reaches the vault. Pin it with `hq files get`'s pin writer: the
+ * default library folder as a whole, and for any other `--to` folder only the
+ * written placeholders, so the rest of that folder stays out of sync.
+ */
+export declare function ensureLibraryInSyncScope(company: LibraryCompany, dirRel: string, placeholderPaths: readonly string[], deps: Pick<LibraryAddDeps, "hqRoot" | "syncScope" | "addPin">): Promise<LibrarySyncScopeNote | undefined>;
+/**
+ * {@link resolvePullScope} answers `all` when any call fails. Report the
+ * failure instead, so a failed lookup is not mistaken for full sync.
+ */
+export declare function resolveLibrarySyncScope(client: Required<PullScopeClient>, company: LibraryCompany, hqRoot: string): Promise<PullScope>;
 export interface LibraryTagResult {
     placeholderPath: string;
     tags: string[];