@indigoai-us/hq-cli 5.345.148 → 5.345.150

package/dist/commands/install-global.d.ts

@@ -2,7 +2,6 @@ import { Command } from 'commander';
 import { AnywhereRuntimeDisabledError } from './anywhere-runtime-flag.js';
 import { type RuntimeHookTrustResult } from '../utils/hook-trust.js';
 import { type ShimPathCheck } from '../lib/windows/user-path.js';
-import { type HookTarget } from '../lib/install/claude-targets.js';
 export interface GlobalInstallOptions {
     /** HQ checkout to install from (absolute). */
     hqRoot: string;
@@ -32,13 +31,7 @@ export interface GlobalInstallOptions {
     /** Platform override for link creation (default process.platform). */
     platform?: NodeJS.Platform;
 }
-/** True when an hq daemon unit (launchd plist or systemd unit) exists. */
-export declare function isDaemonInstalled(home: string, platform?: NodeJS.Platform, queryTask?: (task: string) => boolean): boolean;
-/**
- * US-010: with hqd installed (and the checkout shipping the shim), hooks go to
- * the hqd shim; otherwise to master-hook.sh / the Codex adapter.
- */
-export declare function hookTargetFor(hqRoot: string, home: string, daemonInstalled?: boolean, env?: NodeJS.ProcessEnv): HookTarget;
+export { hookTargetFor, isDaemonInstalled } from '../lib/install/hook-target.js';
 export interface ClaudePluginSource {
     sourceDir: string;
     marketplaceName: string;

package/dist/commands/install-global.js

@@ -1,3 +1,4 @@
+import { hookTargetFor } from '../lib/install/hook-target.js';
 /**
  * `hq install --global --runtime claude` / `hq uninstall --global --runtime claude`
  * (hq-anywhere-runtime US-005).
@@ -25,34 +26,11 @@ import { readRegistry, registryDir, registryFile, writeRegistry } from '../lib/r
 import { readCompaniesManifestMap } from '../lib/work-context/repo-remote.js';
 import { resolveDefaultHqRoot } from '../utils/hq-root-resolver.js';
 import { trustCodexUserHooks } from '../utils/hook-trust.js';
-import { DAEMON_LAUNCHD_LABEL, DAEMON_SYSTEMD_UNIT, DAEMON_WINDOWS_TASK, SYSTEM_UNIT_DIR } from '../lib/daemon/install.js';
-import { readDaemonConfig } from '../lib/daemon/config.js';
-import { daemonPaths } from '../lib/daemon/paths.js';
 import { assertProviderWrappersInstallable, installProviderWrappers, providerWrapperInstallPaths, removeProviderWrappers } from '../lib/install/provider-wrappers.js';
-import { checkShimOnPath, shimPathWarning } from '../lib/windows/user-path.js';
+import { checkShimOnPath, ensureShimOnUserPath, shimPathWarning } from '../lib/windows/user-path.js';
 import { addAgentsMdBlock, addCodexHooks, classifyLegacySkills, codexAdapterPath, codexCharterSource, codexHookTrustKeys, codexTargets, hasAllCodexHooks, HQ_OWNED_MARKER, LEGACY_BACKUP_NAME, LEGACY_SKILLS_NAME, removeAgentsMdBlock, removeCodexHooks, } from '../lib/install/codex-targets.js';
 import { addClaudeMdBlock, addHqHooks, charterPath, claudeTargets, hasAllHqHooks, HQ_ANYWHERE_PACK, HQ_MCP_SERVER_NAME, hqSkillsSource, lineDiff, masterHookPath, shimPath, MCP_SUBPROCESS_PATH, removeClaudeMdBlock, removeHqHooks, SKILL_LINK_PREFIX, } from '../lib/install/claude-targets.js';
-/** True when an hq daemon unit (launchd plist or systemd unit) exists. */
-export function isDaemonInstalled(home, platform = process.platform, queryTask = (task) => spawnSync('schtasks.exe', ['/Query', '/TN', task], { encoding: 'utf8', windowsHide: true }).status === 0) {
-    if (platform === 'win32')
-        return queryTask(DAEMON_WINDOWS_TASK);
-    const candidates = platform === 'darwin'
-        ? [path.join(home, 'Library', 'LaunchAgents', `${DAEMON_LAUNCHD_LABEL}.plist`)]
-        : platform === 'linux'
-            ? [path.join(home, '.config', 'systemd', 'user', DAEMON_SYSTEMD_UNIT), path.join(SYSTEM_UNIT_DIR, DAEMON_SYSTEMD_UNIT)]
-            : [];
-    return candidates.some((p) => fs.existsSync(p));
-}
-/**
- * US-010: with hqd installed (and the checkout shipping the shim), hooks go to
- * the hqd shim; otherwise to master-hook.sh / the Codex adapter.
- */
-export function hookTargetFor(hqRoot, home, daemonInstalled, env = process.env) {
-    const installed = daemonInstalled ?? isDaemonInstalled(home);
-    const configuredRoot = readDaemonConfig(daemonPaths(home, env).configPath).hqRoot;
-    const daemonMatchesRoot = configuredRoot !== undefined && realpathOrSelf(configuredRoot) === realpathOrSelf(hqRoot);
-    return installed && daemonMatchesRoot && fs.existsSync(shimPath(hqRoot)) ? 'shim' : 'master';
-}
+export { hookTargetFor, isDaemonInstalled } from '../lib/install/hook-target.js';
 const HQ_PACKAGES_MARKETPLACE_REPOSITORY = 'indigoai-us/hq-packages';
 /** Resolve local overrides first, then the published HQ marketplace. */
 export function resolveClaudePluginSource(explicitDir, env = process.env, repository = HQ_PACKAGES_MARKETPLACE_REPOSITORY) {
@@ -615,7 +593,7 @@ export function installGlobalClaude(opts) {
     if (pluginSource)
         log(`  plugin: ${pluginSource.pluginId} installed from ${pluginSource.sourceDir}; direct hooks and MCP entries removed`);
     else {
-        log(`  hooks: ${hookTarget === 'shim' ? 'hqd-hook-shim.sh' : 'master-hook.sh'} registered in ${t.settingsJson}`);
+        log(`  hooks: ${typeof hookTarget === 'object' ? hookTarget.engine : hookTarget === 'shim' ? 'hqd-hook-shim.sh' : 'master-hook.sh'} registered in ${t.settingsJson}`);
         log(`  MCP: "${HQ_MCP_SERVER_NAME}" registered in ${t.claudeJson}`);
     }
     log(`  registry: ${seeded.length} manifest entr${seeded.length === 1 ? 'y' : 'ies'} seeded`);
@@ -994,7 +972,7 @@ export function installGlobalCodex(opts) {
     log(`  skills linked: ${skills.link.length} new, ${skills.already.length} already present, ${skills.skipped.length} skipped`);
     reportSkillCopies(linkKinds, log);
     reportSkippedSkills(skills, log, false);
-    log(`  hooks: ${hookTarget === 'shim' ? shimPath(hqRoot) : codexAdapterPath(hqRoot)} registered in ${t.hooksJson}`);
+    log(`  hooks: ${typeof hookTarget === 'object' ? hookTarget.engine : hookTarget === 'shim' ? shimPath(hqRoot) : codexAdapterPath(hqRoot)} registered in ${t.hooksJson}`);
     log(`  MCP: "${HQ_MCP_SERVER_NAME}" registered in ${t.configToml}`);
     return touched;
 }
@@ -1213,6 +1191,12 @@ export async function runInstallGlobal(opts) {
     if (runtime === 'codex' && !opts.dryRun)
         await trustInstalledCodexHooks(hqRoot, opts);
     if (!opts.dryRun) {
+        try {
+            ensureShimOnUserPath({ env, entry: process.argv[1] });
+        }
+        catch {
+            // The warning below is the fallback when the user Path cannot be updated.
+        }
         const shimPath = (opts.shimPathCheck ?? (() => checkShimOnPath({ env })))();
         if (shimPath)
             for (const line of shimPathWarning(shimPath))

package/dist/commands/lanes-questions.js

@@ -2,7 +2,7 @@ import * as path from "node:path";
 import { buildOutpostQuestionAnswerCommand, buildOutpostQuestionCancelCommand, buildOutpostQuestionShowCommand, dispatchErrorMessage } from "../lib/lanes/outpost-dispatch.js";
 import { assertNoSecretText } from "../lib/lanes/text-scan.js";
 import { sessionIdFromEnv } from "../lib/mesh/live/session-identity.js";
-import { appendCappedHistory, createQuestion, isLanesError, listSessionLiveness, parseLivenessState, parseQuestionRecord, parseQuestionStatus, readDaemonPresenceConnected, readLane, readQuestion, wakeAnsweredLaneNow, sessionLiveness, appendDropboxMessage, answerDropboxMessage, laneAcceptsDropboxDelivery, laneIdForAnswerDelivery, writeQuestionBody } from "../lib/lanes/index.js";
+import { appendCappedHistory, createQuestion, expandLocalLaneIdPrefix, isLanesError, listSessionLiveness, parseLivenessState, parseQuestionRecord, parseQuestionStatus, readDaemonPresenceConnected, readLane, readQuestion, wakeAnsweredLaneNow, sessionLiveness, appendDropboxMessage, answerDropboxMessage, laneAcceptsDropboxDelivery, laneIdForAnswerDelivery, writeQuestionBody } from "../lib/lanes/index.js";
 import { resolveQuestionCompanyWithFallback } from "../lib/lanes/questions.js";
 import { LanesError } from "../lib/lanes/errors.js";
 import { applyLoopStallAnswer, findLoopStallResult } from "../lib/lanes/loop.js";
@@ -565,6 +565,9 @@ export function createLaneQuestionsHandlers(deps) {
         const hqRoot = ctx.hqRoot();
         const status = opts.status ? parseQuestionStatus(opts.status) : undefined;
         const forFilter = opts.for ? parseForFilter(opts.for, ctx) : undefined;
+        // --from matches the full lane id; a short prefix expands only when it
+        // names exactly one local lane (ambiguous prefixes are refused).
+        const from = opts.from ? (expandLocalLaneIdPrefix(hqRoot, opts.from) ?? opts.from) : undefined;
         const company = opts.company
             ? await ctx.resolveCompany(opts.company)
             : await resolveActiveQuestionCompany(ctx, "Cannot access lane questions because the active HQ company could not be resolved; re-run with --company <slug>");
@@ -574,7 +577,7 @@ export function createLaneQuestionsHandlers(deps) {
             .filter((q) => {
             if (status && q.status !== status)
                 return false;
-            if (opts.from && q.lane_id !== opts.from && q.origin.id !== opts.from)
+            if (from && q.lane_id !== from && q.origin.id !== from)
                 return false;
             if (opts.project && q.project_id !== opts.project)
                 return false;
@@ -618,7 +621,7 @@ export function createLaneQuestionsHandlers(deps) {
             ? await loadPrimaryOwnedOutpostQuestions(ctx, hqRoot, company, undefined, {
                 sessionId: currentSessionId ?? undefined,
                 for: opts.for,
-                from: opts.from,
+                from,
                 project: opts.project,
                 story: opts.story,
                 status: opts.status,
@@ -651,7 +654,7 @@ export function createLaneQuestionsHandlers(deps) {
                 .filter(({ question: q, lane, audience }) => {
                 if (status && q.status !== status)
                     return false;
-                if (opts.from && q.lane_id !== opts.from && q.origin.id !== opts.from)
+                if (from && q.lane_id !== from && q.origin.id !== from)
                     return false;
                 if (opts.project && q.project_id !== opts.project)
                     return false;

package/dist/commands/lanes.js

@@ -78,7 +78,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 { remoteControlSelectionConfig, remoteControlSessionHome } from "../lib/lanes/remote-control-lane.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, isFinishedResumableHireChild, childrenHoldingHireGrantCarve, laneHoldsHireGrantCarve, assignedChildHireGrants, hireGrantCapacityError, planHireGrantBackfill, terminalChildResumeHireGrantError, withHireGrantAdmission, laneStoryLedgerEnabled, syncLaneToProjectStoryLedger, removeLaneFromProjectStoryLedger, validateProjectStories, buildLaneStatusSnapshot, formatLaneStatusHuman, listLaneIds, listQuestionIds, loadLanesConfig, laneRunsHere, MAX_LANE_DEPTH, MONITOR_ERROR_EXIT_CODE, readLiveMonitorEvidence, resolveMachineIdentity as lookupMachineIdentity, loadLivenessIndex, parseLaneProvider, isLaneProvider, parseLaneRecord, parseLaneState, parseQuestionRecord, parseSeniorKind, readAllLanes, readLane, sanitizeHostComponent, retryUpdateLane, syncLaneRecordFromOwner, readQuestion, resolveAccount, resolveLaneWorker, ignoredWorkerProfileFields, loadWorkerProfile, loadWorkerProfileWithRegistry, registryWorkerRecord, runReconcilePass, DEAD_HOST_MS, sessionLiveness, tryReadLane, uninstallReconcileTimer, updateLane, updateQuestion, dropboxDir, laneDeliveryMechanism, hasActiveAdmissionReservation, hasActivePendingResume, hasRecordedSessionId, hasEarlierEligibleQueuedLane, laneAdmissionCapReason, providerSupportsSessionResume, providerSessionPortable, isFailedQuotaKeepAliveLane, sessionNotPortableMessage, withLaneAdmissionLock, withAllLaneAdmissionLocks, readWorkerRunResult, resumeCommandRefusal, withLaneHireLocks, raiseLaneQuestion, sha256Text, } from "../lib/lanes/index.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, isFinishedResumableHireChild, childrenHoldingHireGrantCarve, laneHoldsHireGrantCarve, assignedChildHireGrants, hireGrantCapacityError, planHireGrantBackfill, terminalChildResumeHireGrantError, withHireGrantAdmission, laneStoryLedgerEnabled, syncLaneToProjectStoryLedger, removeLaneFromProjectStoryLedger, validateProjectStories, buildLaneStatusSnapshot, formatLaneStatusHuman, expandLocalLaneIdPrefix, listLaneIds, listQuestionIds, loadLanesConfig, laneRunsHere, MAX_LANE_DEPTH, MONITOR_ERROR_EXIT_CODE, readLiveMonitorEvidence, resolveMachineIdentity as lookupMachineIdentity, loadLivenessIndex, parseLaneProvider, isLaneProvider, parseLaneRecord, parseLaneState, parseQuestionRecord, parseSeniorKind, readAllLanes, readLane, sanitizeHostComponent, retryUpdateLane, syncLaneRecordFromOwner, readQuestion, resolveAccount, resolveLaneWorker, ignoredWorkerProfileFields, loadWorkerProfile, loadWorkerProfileWithRegistry, registryWorkerRecord, runReconcilePass, DEAD_HOST_MS, sessionLiveness, tryReadLane, uninstallReconcileTimer, updateLane, updateQuestion, dropboxDir, laneDeliveryMechanism, hasActiveAdmissionReservation, hasActivePendingResume, hasRecordedSessionId, hasEarlierEligibleQueuedLane, laneAdmissionCapReason, providerSupportsSessionResume, providerSessionPortable, isFailedQuotaKeepAliveLane, sessionNotPortableMessage, withLaneAdmissionLock, withAllLaneAdmissionLocks, readWorkerRunResult, resumeCommandRefusal, withLaneHireLocks, raiseLaneQuestion, sha256Text, } from "../lib/lanes/index.js";
 import { admitQueuedNow } from "../lib/lanes/reconcile.js";
 import { laneStories, storyWarning, } from "../lib/lanes/stories.js";
 import { resolveLaneKeepAlive } from "../lib/lanes/profile.js";
@@ -1979,6 +1979,11 @@ async function resolveCommandLaneTarget(ctx, laneId, options = {}) {
         if (localMatch)
             return { lane: readLane(ctx.hqRoot(), localMatch), remoteOnly: false };
     }
+    // A short prefix expands only to exactly one local lane; more than one is
+    // refused with the candidates listed (lane_id_ambiguous).
+    const prefixMatch = expandLocalLaneIdPrefix(ctx.hqRoot(), laneId);
+    if (prefixMatch)
+        return { lane: readLane(ctx.hqRoot(), prefixMatch), remoteOnly: false };
     const separator = laneId.lastIndexOf("_");
     const hostSuffix = separator < 0 ? "" : laneId.slice(separator + 1);
     const ownerLookupGate = !hostSuffix && requestedUlid !== undefined && options.allowHostlessOwnerLookup
@@ -4561,7 +4566,8 @@ async function runCreate(ctx, opts) {
         printJson({
             ok: true,
             action: "create",
-            admitted,
+            // lane_id stays ahead of `admitted`: callers that take the first lane id
+            // in this output must get the lane they created, not one it admitted.
             lane_id: started.lane_id,
             state: started.state,
             queued_reason: started.queued_reason ?? null,
@@ -4603,6 +4609,7 @@ async function runCreate(ctx, opts) {
                         .outpost_command_id,
                 }
                 : {}),
+            admitted,
             lane: started,
         });
     return started;
@@ -8942,10 +8949,10 @@ async function runCreateSubagent(ctx, opts) {
         }
         assertNoSecretText("focus override reason", opts.focusOverride.trim());
     }
+    // A subagent lane is a board record for work the senior session runs with
+    // its own host's subagent tool (Claude's Agent, Codex's spawn_agent). No
+    // process is spawned, so any provider is only attribution.
     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() });
     }
@@ -10277,7 +10284,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("--runner <kind>", "process (default) | subagent: register a lane an in-session subagent runs (Claude Agent, Codex spawn_agent); 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)")

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[];

package/dist/commands/library-add.js

@@ -28,7 +28,7 @@ import http from "node:http";
 import https from "node:https";
 import path from "node:path";
 import { Readable } from "node:stream";
-import { formatCloudAssetBlock, formatCloudPlaceholder, parseCloudPlaceholder, } from "@indigoai-us/hq-cloud";
+import { formatCloudAssetBlock, formatCloudPlaceholder, isCoveredByAny, parseCloudPlaceholder, resolvePullScope, } from "@indigoai-us/hq-cloud";
 import { PLACEHOLDER_SUFFIX, companyOffloadKey, containedPath, durablePlaceholderFs, renderPointer, resolvePlaceholder, } from "./storage-offload.js";
 import { formatPlanGateError, formatUpgradeRefusal, planGateErrorFromResponse, } from "../utils/plan-gate-error.js";
 /** Metadata key hq-pro binds to `checksumSha256` (sync's content hash). */
@@ -321,7 +321,74 @@ export async function runLibraryAdd(inputs, options, deps) {
                 .catch((err) => ({ status: "failed", note: err.message }));
         }
     }
-    return { company: slug, items };
+    const written = items.flatMap((item) => (item.ok && item.placeholderPath ? [item.placeholderPath] : []));
+    if (written.length === 0)
+        return { company: slug, items };
+    const syncScope = await ensureLibraryInSyncScope(company, dirRel, written, deps);
+    return { company: slug, items, ...(syncScope ? { syncScope } : {}) };
+}
+const LIBRARY_FOLDER = "library/";
+/**
+ * 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 async function ensureLibraryInSyncScope(company, dirRel, placeholderPaths, deps) {
+    if (!deps.syncScope || !deps.addPin)
+        return undefined;
+    const companyRel = (rel) => rel.split("/").slice(2).join("/");
+    const isLibrary = `${companyRel(dirRel)}/` === LIBRARY_FOLDER;
+    const targets = isLibrary ? [LIBRARY_FOLDER] : placeholderPaths.map(companyRel);
+    const command = isLibrary ? `hq files get ${LIBRARY_FOLDER} --company ${company.slug}` : undefined;
+    let scope;
+    try {
+        scope = await deps.syncScope(company);
+    }
+    catch (err) {
+        return {
+            status: "not-pinned",
+            pins: targets,
+            ...(command ? { command } : {}),
+            reason: `could not read your sync scope: ${err.message}`,
+        };
+    }
+    const missing = scope.syncMode === "all" ? [] : targets.filter((t) => !isCoveredByAny(t, scope.prefixSet ?? []));
+    if (missing.length === 0)
+        return { status: "in-scope", pins: [] };
+    try {
+        for (const target of missing)
+            deps.addPin(deps.hqRoot, company.slug, target);
+    }
+    catch (err) {
+        return {
+            status: "not-pinned",
+            pins: missing,
+            ...(command ? { command } : {}),
+            reason: `could not write the pin: ${err.message}`,
+        };
+    }
+    return { status: "pinned", pins: missing };
+}
+/**
+ * {@link resolvePullScope} answers `all` when any call fails. Report the
+ * failure instead, so a failed lookup is not mistaken for full sync.
+ */
+export async function resolveLibrarySyncScope(client, company, hqRoot) {
+    let failure;
+    const watch = (call) => call.catch((err) => {
+        failure ??= err;
+        throw err;
+    });
+    const scope = await resolvePullScope({
+        listMyMemberships: () => watch(client.listMyMemberships()),
+        getMembershipSyncConfig: (id) => watch(client.getMembershipSyncConfig(id)),
+        listMyExplicitGrants: (uid) => watch(client.listMyExplicitGrants(uid)),
+    }, company.uid, company.slug, hqRoot);
+    if (failure !== undefined)
+        throw failure instanceof Error ? failure : new Error(String(failure));
+    return scope;
 }
 async function writeAssetPlaceholder(p, options, deps, dirAbs) {
     const ts = offloadTimestamp(deps.now());

package/dist/commands/library.js

@@ -35,7 +35,7 @@ import { findHqRoot } from "../utils/manifest.js";
 import { networkTransportErrorCode } from "../utils/network-transport-error.js";
 import { resolveVaultCredentialForCapability } from "../utils/resolve-vault-credential.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
-import { defaultLibraryIo, runLibraryAdd, runLibraryTag, } from "./library-add.js";
+import { defaultLibraryIo, resolveLibrarySyncScope, runLibraryAdd, runLibraryTag, } from "./library-add.js";
 import { captionAddedAsset, extractCaptionFrames, runLibraryDescribe, runLocalClaude } from "./library-caption.js";
 import { LIBRARY_LINK_DEFAULT_MINUTES, LIBRARY_LINK_MAX_MINUTES, runLibraryLink } from "./library-link.js";
 /** Mirrors hq-pro's MAX_ASSET_SEARCH_TAGS / tag length bound. */
@@ -295,8 +295,39 @@ export function formatLibraryAddResult(result) {
             return `${line}\n  ${chalk.dim(`AI caption added (${item.caption.captionedBy}).`)}`;
         return `${line}\n  ${chalk.yellow(item.caption.note ?? "Captioning skipped.")}`;
     })
+        .concat(formatLibrarySyncScope(result))
         .join("\n");
 }
+function formatLibrarySyncScope({ company, syncScope }) {
+    if (!syncScope || syncScope.status === "in-scope")
+        return [];
+    const pins = syncScope.pins.map((pin) => `${company}:${pin}`).join(", ");
+    if (syncScope.status === "pinned") {
+        return [chalk.dim(`Pinned ${pins} so sync uploads these placeholders to the company vault.`)];
+    }
+    const fix = syncScope.command
+        ? `Pin the folder with: ${syncScope.command}`
+        : `Add ${syncScope.pins.join(", ")} under "${company}" in .hq/pins.json at the HQ root.`;
+    return [
+        chalk.yellow(`Warning: sync may not upload these placeholders (${syncScope.reason}). ` +
+            `Until it does, teammates and cloud search will not see them. ${fix}`),
+    ];
+}
+/** Sync scope wiring for `hq library add`; an API key has no sync tree to check. */
+async function librarySyncScopeDeps(credential, hqRoot) {
+    if (credential.kind !== "cognito")
+        return {};
+    const [{ VaultClient }, { buildVaultConfig }, { addPin }] = await Promise.all([
+        import("@indigoai-us/hq-cloud"),
+        import("../utils/cognito-session.js"),
+        import("./files-browse.js"),
+    ]);
+    const client = new VaultClient(buildVaultConfig(credential.token));
+    return {
+        syncScope: (company) => resolveLibrarySyncScope(client, company, hqRoot),
+        addPin,
+    };
+}
 /** GET a presigned URL. Errors never echo the URL, which carries a signature. */
 async function downloadPresigned(url) {
     const res = await fetch(url);
@@ -366,9 +397,11 @@ export function registerLibraryCommand(program) {
         .option("--json", "Print machine-readable JSON")
         .action(async (sources, options) => {
         try {
-            const { token } = await resolveVaultCredentialForCapability("files:write", "library add", {
+            const credential = await resolveVaultCredentialForCapability("files:write", "library add", {
                 interactive: true,
             });
+            const { token } = credential;
+            const hqRoot = findHqRoot();
             const result = await runLibraryAdd(sources, {
                 company: options.company,
                 to: options.to,
@@ -376,11 +409,12 @@ export function registerLibraryCommand(program) {
                 title: options.title,
                 note: options.note,
             }, {
-                hqRoot: findHqRoot(),
+                hqRoot,
                 now: () => new Date(),
                 resolveCompany: (slug) => libraryCompany(token, slug),
                 presign: (body) => vaultApiFetch({ token, path: "/v1/files/presign", method: "POST", body }),
                 ...defaultLibraryIo,
+                ...(await librarySyncScopeDeps(credential, hqRoot)),
                 ...(options.caption === false
                     ? {}
                     : {

package/dist/commands/members.d.ts

@@ -30,6 +30,23 @@ export interface ActiveMember {
     personName?: string;
     personSlug?: string;
 }
+/**
+ * The company's active Outpost, as listed beside the members by
+ * `GET /membership/company/{companyUid}`. It is read-only: it can be granted
+ * secrets (`hq secrets share --with out_…`, `hq groups add`), but it cannot be
+ * invited, promoted or removed.
+ */
+export interface CompanyOutpostMember {
+    uid: string;
+    kind: "outpost";
+    label: string;
+    outpostId: string;
+    readOnly: true;
+}
+export interface CompanyRoster {
+    members: ActiveMember[];
+    outposts: CompanyOutpostMember[];
+}
 export interface InviteOptions {
     target: string;
     role: string;
@@ -165,7 +182,25 @@ export declare function pendingInviteJson(inv: PendingInvite): {
     invited_at: string;
     membership_key: string;
 };
+/** JSON row for a company Outpost in `hq members list --json`. */
+export declare function companyOutpostJson(o: CompanyOutpostMember): {
+    person_id: string;
+    kind: "outpost";
+    label: string;
+    outpost_id: string;
+    read_only: true;
+};
 export declare function listActiveMembers(token: string, companyUid: string): Promise<ActiveMember[]>;
+/**
+ * Active members plus the company's active Outpost. Servers that predate
+ * Outpost listing omit `outposts`; that reads as none.
+ */
+export declare function listCompanyRoster(token: string, companyUid: string): Promise<CompanyRoster>;
+/**
+ * The company Outpost is listed read-only. hq-pro rejects promote, remove and
+ * revoke for it (OUTPOST_MEMBER_READ_ONLY); say so before any request goes out.
+ */
+export declare const OUTPOST_READ_ONLY_MESSAGE: string;
 /**
  * Resolve a role-change target to an active membership key.
  *

package/dist/commands/members.js

@@ -4,6 +4,7 @@ import { gateApiKeyCapabilities } from "../utils/api-key-command-gate.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
 import { isPlanGateError } from "../utils/plan-gate-error.js";
 import { queueCliFeatureUsed } from "../utils/cli-telemetry.js";
+import { OUTPOST_UID_PATTERN } from "./_patterns.js";
 const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
 const PERSON_UID_PATTERN = /^prs_[A-Za-z0-9_-]+$/;
 const AGENT_UID_PATTERN = /^agt_[A-Za-z0-9_-]+$/i;
@@ -261,7 +262,24 @@ export function pendingInviteJson(inv) {
         membership_key: inv.membershipKey,
     };
 }
+/** JSON row for a company Outpost in `hq members list --json`. */
+export function companyOutpostJson(o) {
+    return {
+        person_id: o.uid,
+        kind: "outpost",
+        label: o.label || "Outpost",
+        outpost_id: o.outpostId,
+        read_only: true,
+    };
+}
 export async function listActiveMembers(token, companyUid) {
+    return (await listCompanyRoster(token, companyUid)).members;
+}
+/**
+ * Active members plus the company's active Outpost. Servers that predate
+ * Outpost listing omit `outposts`; that reads as none.
+ */
+export async function listCompanyRoster(token, companyUid) {
     const res = await vaultApiFetch({
         token,
         path: `/membership/company/${encodeURIComponent(companyUid)}`,
@@ -270,10 +288,26 @@ export async function listActiveMembers(token, companyUid) {
         const err = (await res.json().catch(() => ({})));
         throw new InviteHttpError(res.status, err.message ?? err.error ?? res.statusText, err.code);
     }
-    // Server schema: `{ members: [...] }` — active members only, enriched with
-    // resolved person metadata (personEmail / personName / personSlug).
+    // Server schema: `{ members: [...], outposts: [...] }` — active members
+    // only, enriched with resolved person metadata (personEmail / personName /
+    // personSlug), plus the read-only company Outpost rows.
     const data = (await res.json());
-    return data?.members ?? [];
+    const outposts = (data?.outposts ?? []).filter((o) => o?.kind === "outpost" &&
+        typeof o.uid === "string" &&
+        OUTPOST_UID_PATTERN.test(o.uid));
+    return { members: data?.members ?? [], outposts };
+}
+/**
+ * The company Outpost is listed read-only. hq-pro rejects promote, remove and
+ * revoke for it (OUTPOST_MEMBER_READ_ONLY); say so before any request goes out.
+ */
+export const OUTPOST_READ_ONLY_MESSAGE = "An Outpost is shown read-only and cannot be invited, promoted or removed. " +
+    "To change what it can read, use `hq secrets share` / `hq secrets unshare` or `hq groups`.";
+function assertNotOutpost(target) {
+    const uid = (target.split("#")[0] ?? "").trim();
+    if (OUTPOST_UID_PATTERN.test(uid)) {
+        throw new Error(OUTPOST_READ_ONLY_MESSAGE);
+    }
 }
 /**
  * Resolve a role-change target to an active membership key.
@@ -283,6 +317,7 @@ export async function listActiveMembers(token, companyUid) {
  * active member list instead of synthesizing an `email:...#company` key.
  */
 export async function resolveRoleChangeTarget(token, companyUid, target) {
+    assertNotOutpost(target);
     if (target.includes("#"))
         return target;
     const detected = detectTarget(target);
@@ -325,6 +360,7 @@ export async function resolveRoleChangeTarget(token, companyUid, target) {
  * that exact email was just shown by `hq members list`.
  */
 export function resolveRevokeTargetToMembershipKey(arg, companyUid) {
+    assertNotOutpost(arg);
     if (arg.includes("#"))
         return arg;
     const detected = detectTarget(arg);
@@ -820,33 +856,48 @@ export function registerMembersCommand(program) {
             }
             // Default: list ACTIVE members so their emails drop straight into
             // `hq secrets share <path> --with <email>`.
-            const activeMembers = await listActiveMembers(token, companyUid);
+            // The company Outpost is listed after the people, read-only; its
+            // out_ id drops into `hq secrets share <path> --with out_…`.
+            const { members: activeMembers, outposts } = await listCompanyRoster(token, companyUid);
             if (opts.json) {
                 console.log(JSON.stringify({
                     company_uid: companyUid,
                     members: activeMembers.map(activeMemberJson),
+                    outposts: outposts.map(companyOutpostJson),
                 }, null, 2));
                 return;
             }
-            if (activeMembers.length === 0) {
+            if (activeMembers.length === 0 && outposts.length === 0) {
                 console.log(chalk.gray("No active members found for this company."));
                 return;
             }
-            const emailW = Math.max(5, ...activeMembers.map((m) => (m.personEmail ?? m.personUid).length));
-            const roleW = Math.max(4, ...activeMembers.map((m) => m.role.length));
-            const idW = Math.max(9, ...activeMembers.map((m) => m.personUid.length));
+            const rows = [
+                ...activeMembers.map((m) => ({
+                    email: m.personEmail ?? m.personUid,
+                    role: m.role,
+                    id: m.personUid,
+                    name: m.personName ?? m.personSlug ?? "",
+                })),
+                ...outposts.map((o) => ({
+                    email: o.uid,
+                    role: "outpost",
+                    id: o.uid,
+                    name: `${o.label || "Outpost"} (read-only)`,
+                })),
+            ];
+            const emailW = Math.max(5, ...rows.map((r) => r.email.length));
+            const roleW = Math.max(4, ...rows.map((r) => r.role.length));
+            const idW = Math.max(9, ...rows.map((r) => r.id.length));
             const header = ["EMAIL".padEnd(emailW), "ROLE".padEnd(roleW)];
             if (opts.ids)
                 header.push("PERSON_ID".padEnd(idW));
             header.push("NAME");
             console.log(chalk.bold(header.join("  ")));
-            for (const m of activeMembers) {
-                const email = m.personEmail ?? m.personUid;
-                const name = m.personName ?? m.personSlug ?? "";
-                const row = [email.padEnd(emailW), m.role.padEnd(roleW)];
+            for (const r of rows) {
+                const row = [r.email.padEnd(emailW), r.role.padEnd(roleW)];
                 if (opts.ids)
-                    row.push(m.personUid.padEnd(idW));
-                row.push(name);
+                    row.push(r.id.padEnd(idW));
+                row.push(r.name);
                 console.log(row.join("  "));
             }
         }

package/dist/commands/reindex.js

@@ -1,3 +1,5 @@
+import { reconcileHookRegistrations } from '../lib/hook-engine/reconcile.js';
+import { trustCodexUserHooks } from '../utils/hook-trust.js';
 /**
  * hq reindex — surface namespaced skills and commands, clean up retired
  * personal-overlay mirror links, capture coding-harness session logs, regenerate
@@ -775,6 +777,23 @@ export function registerReindexCommand(program) {
             // means a sync/rescue holds the shared operation lock and may be
             // rewriting .claude/settings.json right now, and this is an unlocked
             // whole-file read-modify-write.
+            // Registration reconcile is best-effort: a failure leaves the current
+            // registrations in place and must not stop the rest of reindex.
+            try {
+                // A file that failed is left as it was; the keys of files that were
+                // rewritten are still trusted so Codex keeps running their hooks.
+                const { codexUserKeys, failures } = reconcileHookRegistrations(hqRoot);
+                for (const failure of failures)
+                    console.warn(`reindex: hook registration reconcile skipped ${failure}`);
+                if (codexUserKeys.length) {
+                    const trust = await trustCodexUserHooks(hqRoot, codexUserKeys);
+                    if (trust.status === 'failed')
+                        console.warn(`reindex: Codex hook trust needs repair: ${trust.reason}`);
+                }
+            }
+            catch (error) {
+                console.warn(`reindex: hook registration reconcile skipped: ${error.message}`);
+            }
             dropProjectDefaultModeForBypassUser(hqRoot);
             await trustHqRuntimeHooks(hqRoot, undefined, {
                 rootAliases: [literalHqRoot],