@indigoai-us/hq-cli 5.345.147 → 5.345.149

package/dist/commands/daemon.js

@@ -24,9 +24,9 @@ import { DEFAULT_SERVICES, SERVICE_DESCRIPTIONS, enabledServices, hqCloudUnits }
 import { applyServiceToggle, effectiveSyncOwner, readDaemonConfig, writeDaemonConfig } from "../lib/daemon/config.js";
 import { daemonUnitInstalled } from "../lib/daemon/handoff.js";
 import { adoptLegacyUnits, readAdoptedUnits, restoreLegacyUnits } from "../lib/daemon/migrate.js";
-import { ROOT_REFUSAL, SYSTEM_UNIT_DIR, daemonRootRefusal, installDaemonUnit, installScopeFor, uninstallDaemonUnit, } from "../lib/daemon/install.js";
+import { DAEMON_WINDOWS_TASK, ROOT_REFUSAL, SYSTEM_UNIT_DIR, WINDOWS_START_WAIT_MS, daemonRootRefusal, installDaemonUnit, installScopeFor, uninstallDaemonUnit, windowsInteractiveSession, } from "../lib/daemon/install.js";
 import { describeLegacyUnit, findLegacyUnits } from "../lib/daemon/legacy.js";
-import { isDaemonProcess, runningDaemonPid } from "../lib/daemon/lock.js";
+import { isDaemonProcess, liveDaemonLock, runningDaemonPid } from "../lib/daemon/lock.js";
 import { bundledHqCloud, managedHqCloud, managedHqCloudRoot, readHqCloudCopy, readHqCloudUpdateState } from "../lib/daemon/hq-cloud.js";
 import { MACHINE_TYPE_MARKER_PATH, detectMachineType, homeFromPasswd, } from "../lib/daemon/machine-type.js";
 import { daemonPaths, ensurePrivateDir } from "../lib/daemon/paths.js";
@@ -137,6 +137,8 @@ async function loadDefaults(over) {
         resolveHqRoot: over.resolveHqRoot ?? ((flag) => resolveDaemonHqRoot(flag, { env, cwd: process.cwd(), home })),
         userHome: over.userHome ?? ((user) => loginHome(user, run)),
         daemonAlive: over.daemonAlive ?? ((pid) => isDaemonProcess(pid)),
+        sleep: over.sleep,
+        interactiveSession: over.interactiveSession,
         windowsUser: over.windowsUser ?? (platform === "win32" ? mesh.resolveWindowsUser(env) : ""),
         windowsHeadlessLauncher: over.windowsHeadlessLauncher ?? (platform === "win32" ? mesh.resolveWindowsHeadlessLauncher(env) : undefined),
         systemUnitDir: over.systemUnitDir ?? SYSTEM_UNIT_DIR,
@@ -298,12 +300,42 @@ async function runInstall(d, opts) {
         d.writeFile(MACHINE_TYPE_MARKER_PATH, `type=${detected.type}\nuser=${runAsUser}\n`);
     }
     const runAsHome = runAsUser ? d.userHome(runAsUser) : undefined;
-    const result = installDaemonUnit(hostFor(d, paths, scope === "user"), { scope, runAsUser, runAsHome }, { run: d.run });
+    const result = installDaemonUnit(hostFor(d, paths, scope === "user"), { scope, runAsUser, runAsHome }, {
+        run: d.run,
+        sleep: d.sleep,
+        runningDaemon: () => liveDaemonLock(paths.lockPath, d.daemonAlive),
+    });
     handOver(d, { paths, detected, runAsUser });
+    if (result.warning)
+        d.err(result.warning);
     if (result.kind === "manual") {
         d.out(`This platform has no supported service manager. Start the daemon yourself with:\n  ${result.manualCommand}`);
         return;
     }
+    if (result.startPending) {
+        const signedIn = (d.interactiveSession ?? (() => windowsInteractiveSession(d.run, d.windowsUser ?? "")))();
+        // A missing daemon is not a failure when the user is signed out, or when
+        // Constrained Language Mode refuses the session check; the latter says the
+        // check did not run. A check that failed for any other reason (null) is
+        // treated like a known sign-in and exits non-zero.
+        if (signedIn === false || signedIn === "unavailable") {
+            d.out(`Installed: ${result.unitPath}`);
+            if (signedIn === "unavailable") {
+                d.out("HQ could not check whether you are signed in to Windows, so it could not confirm the daemon started.");
+            }
+            d.out("The daemon starts at your next sign-in to Windows. It is not running yet.");
+            d.out("Check it with: hq daemon status");
+            return;
+        }
+        const seconds = WINDOWS_START_WAIT_MS / 1000;
+        throw new DaemonCommandError([
+            signedIn
+                ? `Installed ${result.unitPath}, but the daemon did not start within ${seconds} seconds although you are signed in to Windows.`
+                : `Installed ${result.unitPath}, but the daemon did not start within ${seconds} seconds, and HQ could not check whether you are signed in to Windows.`,
+            "Check it with: hq daemon status",
+            `The task's last result: powershell -NoProfile -Command "(Get-ScheduledTaskInfo -TaskName '${DAEMON_WINDOWS_TASK}').LastTaskResult"`,
+        ].join("\n"));
+    }
     if (!result.running) {
         throw new DaemonCommandError(`Installed ${result.unitPath}, but it did not start: ${result.error ?? "unknown error"}`);
     }
@@ -354,6 +386,8 @@ async function runUninstall(d, opts) {
     }
     const result = uninstallDaemonUnit(hostFor(d, paths, false), { scope: installScopeFor(detected.type) }, { run: d.run });
     d.out(result.removed ? `Removed ${result.unitPath}` : "hq daemon was not installed.");
+    if (result.warning)
+        d.err(result.warning);
     if (opts.restoreLegacy) {
         const restored = restoreLegacyUnits(migrate);
         for (const u of restored.restored)

package/dist/commands/dm.js

@@ -4,6 +4,7 @@ import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { resolveDestinationCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
 import { isMachineIdentity } from "@indigoai-us/hq-cloud";
 import { peekIdToken } from "../utils/id-token.js";
+import { redactAgentInboxItem as redactInboxCredentials } from "../lib/agent-kit/inbox-redact.js";
 import { EMAIL_PATTERN, RECIPIENT_UID_PATTERN } from "../lib/notify-recipient.js";
 import { dmForwardCliEnabled } from "./dm-forward-flag.js";
 /**
@@ -1281,9 +1282,15 @@ function formatAgentInboxItem(item) {
     const text = str("text") || str("body") || str("subject");
     return `${chalk.bold(from)} ${chalk.dim(`[${channel}] ${id}${when ? ` ${when}` : ""}`)}\n  ${firstLine(text)}`;
 }
-/** Remove delegated execution context before agent inbox items can be emitted. */
+/**
+ * Stdout for `hq dm` drops the whole actingContext. Credential removal itself
+ * is redactInboxCredentials, shared with the mirror, so a later edit cannot
+ * leave a credential key on one path only. The extra omit stays here because
+ * terminal output must not grow the delegation block back.
+ */
 function redactAgentInboxItem(item) {
-    const { actingContext: _actingContext, ...safe } = item;
+    const redacted = redactInboxCredentials(item);
+    const { actingContext: _actingContext, ...safe } = redacted;
     return safe;
 }
 async function runAgentInbox(token, agentUid, opts) {
@@ -1458,7 +1465,15 @@ async function resolveChannel(token, target) {
 async function runDmChannel(target, opts) {
     try {
         const token = await ensureCognitoToken();
-        const channel = await resolveChannel(token, target);
+        // A channel id with --json needs no lookup: the id is exact and JSON output
+        // never uses the channel's name. Skipping the list saves fetching every
+        // channel the caller is in (~1000 for an owner), which is what made polled
+        // reads (the super-conductor message wake) take seconds instead of
+        // milliseconds.
+        const rawTarget = target.trim().replace(/^#/, "");
+        const channel = opts.json && /^chn_[A-Za-z0-9]+$/.test(rawTarget)
+            ? { channelId: rawTarget }
+            : await resolveChannel(token, target);
         const channelId = channel.channelId;
         const query = {};
         if (opts.limit)

package/dist/commands/doctor.d.ts

@@ -25,6 +25,7 @@ import { Command } from "commander";
 import { type DoctorRegistry } from "../lib/doctor/registry.js";
 import type { FamilyRun } from "../lib/doctor/types.js";
 import { type DoctorPlatform } from "../lib/doctor/report.js";
+import { type TempHomeSweepResult } from "../lib/doctor/temp-home-sweeper.js";
 /**
  * Marker directories that identify an HQ tree root. A directory is an HQ root
  * only when it contains ALL of these. `.claude` + `core` are present in both
@@ -126,6 +127,15 @@ export interface RunDoctorResult {
 export declare function runDoctor(options?: RunDoctorOptions): Promise<RunDoctorResult>;
 export declare function createClientHealthReasonCodeCompanyResolver(hqRoot: string): (companySlug: string | null) => Promise<boolean>;
 export declare function createClientHealthCheckStatusCompanyResolver(hqRoot: string): (companySlug: string | null) => Promise<boolean>;
+/** Test seams for {@link registerDoctorCommand}. */
+export interface DoctorCommandDeps {
+    /** Runs the temp-home sweep for `--sweep-temp-homes`. */
+    sweepTempHomes?: (options: {
+        dryRun: boolean;
+    }) => TempHomeSweepResult;
+}
+/** Text report for `hq doctor --sweep-temp-homes`. */
+export declare function renderTempHomeSweepText(result: TempHomeSweepResult): string;
 /** Register the top-level `hq doctor` command so it appears in `hq --help`. */
-export declare function registerDoctorCommand(program: Command): void;
+export declare function registerDoctorCommand(program: Command, deps?: DoctorCommandDeps): void;
 //# sourceMappingURL=doctor.d.ts.map

package/dist/commands/doctor.js

@@ -37,6 +37,7 @@ import { clientHealthCompanyScopeFromCheckId } from "../lib/doctor/checks/sync-h
 import { readCompaniesManifestMap } from "../lib/work-context/repo-remote.js";
 import * as readline from "node:readline";
 import { runSideEffectTests } from "../lib/doctor/deep/sandbox.js";
+import { sweepTempHomes, } from "../lib/doctor/temp-home-sweeper.js";
 /**
  * Marker directories that identify an HQ tree root. A directory is an HQ root
  * only when it contains ALL of these. `.claude` + `core` are present in both
@@ -315,8 +316,33 @@ export function createClientHealthCheckStatusCompanyResolver(hqRoot) {
         });
     };
 }
+/** Text report for `hq doctor --sweep-temp-homes`. */
+export function renderTempHomeSweepText(result) {
+    const lines = [];
+    const verb = result.dryRun ? "Would remove" : "Removed";
+    for (const entry of result.entries) {
+        if (entry.action === "removed" || entry.action === "would-remove") {
+            lines.push(`  ${verb.toLowerCase()} ${entry.path}`);
+        }
+        else if (entry.action === "failed") {
+            lines.push(`  failed ${entry.path}: ${entry.error ?? "unknown error"}`);
+        }
+        else if (entry.reason === "in-use") {
+            lines.push(`  kept ${entry.path} (in use)`);
+        }
+        else if (entry.reason === "in-use-unknown") {
+            lines.push(`  kept ${entry.path} (could not check whether it is in use: ${entry.error ?? "unknown error"})`);
+        }
+    }
+    const count = result.entries.filter((entry) => entry.action === "removed" || entry.action === "would-remove").length;
+    const failed = result.entries.filter((entry) => entry.action === "failed").length;
+    lines.push(`${verb} ${count} idle temp home${count === 1 ? "" : "s"}; ` +
+        `${result.dryRun ? "would free" : "freed"} ${result.gbFreed.toFixed(2)} GB.` +
+        (failed > 0 ? ` ${failed} could not be removed.` : ""));
+    return `${lines.join("\n")}\n`;
+}
 /** Register the top-level `hq doctor` command so it appears in `hq --help`. */
-export function registerDoctorCommand(program) {
+export function registerDoctorCommand(program, deps = {}) {
     program
         .command("doctor")
         .description("Verify HQ hook wiring, runtimes, and connection health (read-only; integrations uses one control-plane inventory read).")
@@ -330,9 +356,38 @@ export function registerDoctorCommand(program) {
         .option("--only <families>", "Run only these comma-separated check families (e.g. hooks). Unknown names are rejected; --json then records the scope.")
         .option("--fix", "Apply the allowlisted safe repairs (backs up first; read-only without this flag).")
         .addOption(new Option("--client-health-report", "Resolve the opt-in hq-flags gate used by the client-health report hook.").hideHelp())
+        .option("--sweep-temp-homes", "Delete idle temp homes (90+ minutes untouched, not in use): tmp.* folders holding .rustup or .cargo, and hq-temp-home.* folders left by the wrapper. Reports GB freed.")
+        .option("--dry-run", "With --sweep-temp-homes, list what would be removed and delete nothing.")
         .option("--yes", "Skip the interactive --fix confirmation (non-interactive use).")
         .option("--force", "Let --fix run despite uncommitted changes under .claude/, .codex/, or .grok/.")
         .action(async (opts, command) => {
+        // `--sweep-temp-homes` is a second write path with its own fixed
+        // scope (idle, unused temp homes in the temp dirs). Like `--fix`,
+        // it refuses a family scope it would otherwise ignore, and it does not
+        // combine with `--fix`.
+        if (opts.sweepTempHomes === true) {
+            if (parseOnly(opts.only) !== undefined || opts.fix === true) {
+                process.stderr.write(`hq doctor: --sweep-temp-homes cannot be combined with --only or --fix.\n` +
+                    `  It removes only idle temp homes in the temp folders; run it on its own.\n`);
+                process.exitCode = 1;
+                return;
+            }
+            const sweep = deps.sweepTempHomes ?? ((options) => sweepTempHomes(options));
+            const result = sweep({ dryRun: opts.dryRun === true });
+            if (opts.json === true) {
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+            }
+            else {
+                process.stdout.write(renderTempHomeSweepText(result));
+            }
+            process.exitCode = result.entries.some((entry) => entry.action === "failed") ? 1 : 0;
+            return;
+        }
+        if (opts.dryRun === true) {
+            process.stderr.write(`hq doctor: --dry-run only applies to --sweep-temp-homes.\n`);
+            process.exitCode = 1;
+            return;
+        }
         // `--fix` repairs the whole tree from its own allowlist and has no
         // notion of a check family, so a scope passed alongside it could only
         // be ignored. Ignoring it silently is the dangerous reading: an

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

@@ -1,7 +1,7 @@
 import { Command } from 'commander';
 import { AnywhereRuntimeDisabledError } from './anywhere-runtime-flag.js';
 import { type RuntimeHookTrustResult } from '../utils/hook-trust.js';
-import { type HookTarget } from '../lib/install/claude-targets.js';
+import { type ShimPathCheck } from '../lib/windows/user-path.js';
 export interface GlobalInstallOptions {
     /** HQ checkout to install from (absolute). */
     hqRoot: string;
@@ -28,14 +28,10 @@ export interface GlobalInstallOptions {
     marketplaceRepository?: string;
     /** Test seam for the Claude Code CLI; production uses `claude`. */
     runClaude?: (args: string[], home: string, env: NodeJS.ProcessEnv) => void;
+    /** 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;
@@ -58,6 +54,8 @@ export interface GlobalUninstallOptions {
     log?: (line: string) => void;
     /** Test seam for the Claude Code CLI; production uses `claude`. */
     runClaude?: (args: string[], home: string, env: NodeJS.ProcessEnv) => void;
+    /** Platform override for link creation (default process.platform). */
+    platform?: NodeJS.Platform;
 }
 /** Reverse every install step; non-HQ entries are left untouched. */
 export declare function uninstallGlobalClaude(opts?: GlobalUninstallOptions): string[];
@@ -83,6 +81,8 @@ export interface GlobalCommandOpts {
     cwd?: string;
     /** Test seam for trusting the Codex hooks a global install registers. */
     trustCodexHooks?: (cwd: string, keys: readonly string[]) => Promise<RuntimeHookTrustResult>;
+    /** Test seam: is the npm hq.cmd folder on the Windows PATH? Null off Windows. */
+    shimPathCheck?: () => ShimPathCheck | null;
 }
 export declare function resolveInstallRoot(explicit: string | undefined, options?: {
     env?: NodeJS.ProcessEnv;

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).
@@ -17,6 +18,7 @@ import { seedRegistryFromHqRoot } from './link.js';
 import { resolveHqRoot } from './doctor.js';
 import { anywhereRuntimeEnabled, AnywhereRuntimeDisabledError } from './anywhere-runtime-flag.js';
 import { resolveHqMcpEndpoint } from '../lib/daemon/mcp-endpoint.js';
+import { linkDirectory, removeLinkOnly, removeSkillEntry, skillCopySource } from '../utils/safe-link.js';
 import { chatgptConnectorInstructions } from '../lib/install/chatgpt-targets.js';
 import { anywhereRuntimeAllowed } from '../lib/anywhere-person-setting.js';
 import { grokConnectorInstructions } from '../lib/install/grok-targets.js';
@@ -24,33 +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, 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) {
@@ -206,6 +186,22 @@ function mcpManifest(opts) {
     }
     return { type: 'stdio', command, args: [entry, 'mcp', 'serve'], env: { PATH: MCP_SUBPROCESS_PATH } };
 }
+/**
+ * The folder an HQ skill entry stands for: a link's resolved target, or the
+ * source recorded in a marked copy. Null for anything else.
+ */
+function skillEntryTarget(skillsDir, entry) {
+    const st = fs.lstatSync(entry);
+    if (st.isSymbolicLink())
+        return path.resolve(skillsDir, fs.readlinkSync(entry));
+    return skillCopySource(entry);
+}
+function reportSkillCopies(kinds, log) {
+    const copies = kinds.filter((k) => k === 'copy').length;
+    if (copies === 0)
+        return;
+    log(`  ${copies} skill folder(s) were copied because Windows refused both a link and a junction. Copies do not follow HQ skill updates; turn on Developer Mode, then uninstall and install again to get links.`);
+}
 function skillLinkName(name) {
     return name.startsWith(SKILL_LINK_PREFIX) ? name : `${SKILL_LINK_PREFIX}${name}`;
 }
@@ -254,7 +250,7 @@ function planSkills(hqRoot, t) {
         }
         if (!st)
             plan.link.push(name);
-        else if (st.isSymbolicLink() && path.resolve(t.skillsDir, fs.readlinkSync(link)) === target)
+        else if (skillEntryTarget(t.skillsDir, link) === target)
             plan.already.push(name);
         else
             plan.skipped.push(name);
@@ -283,9 +279,8 @@ function hqSkillLinksForRoot(skillsDir, hqRoot) {
     return names.filter((name) => {
         const link = path.join(skillsDir, name);
         try {
-            if (!fs.lstatSync(link).isSymbolicLink())
-                return false;
-            return path.dirname(path.resolve(skillsDir, fs.readlinkSync(link))) === hqSkillsSource(hqRoot);
+            const target = skillEntryTarget(skillsDir, link);
+            return target !== null && path.dirname(target) === hqSkillsSource(hqRoot);
         }
         catch (error) {
             if (error.code === 'ENOENT')
@@ -301,8 +296,8 @@ function hqCompanySkillLinksForRoot(skillsDir, hqRoot) {
     const source = hqSkillsSource(hqRoot);
     return hqSkillLinksForRoot(skillsDir, hqRoot).filter((link) => {
         try {
-            const target = path.resolve(skillsDir, fs.readlinkSync(link));
-            if (path.dirname(target) !== source)
+            const target = skillEntryTarget(skillsDir, link);
+            if (target === null || path.dirname(target) !== source)
                 return false;
             const sourceName = path.basename(target);
             const separator = sourceName.indexOf(':');
@@ -492,22 +487,41 @@ export function installGlobalClaude(opts) {
             throw error;
         }
     }
-    writeFileAtomic(t.hqPointer, pointerNew);
-    if (mdOld !== mdNew) {
-        if (mdNew === null) {
-            if (fs.existsSync(t.claudeMd))
-                fs.unlinkSync(t.claudeMd);
+    // Skill links go first: they are the step most likely to fail (Windows
+    // without symlink privilege), and a failure here must not leave ~/.hq/root
+    // or the CLAUDE.md block behind. On any error, undo this run's writes.
+    const skillsDirExisted = fs.existsSync(t.skillsDir);
+    const createdLinks = [];
+    const linkKinds = [];
+    try {
+        if (!pluginSource)
+            fs.mkdirSync(t.skillsDir, { recursive: true });
+        for (const name of skills.link) {
+            const link = path.join(t.skillsDir, skillLinkName(name));
+            linkKinds.push(linkDirectory(path.join(hqSkillsSource(hqRoot), name), link, { platform: opts.platform }));
+            createdLinks.push(link);
+        }
+        writeFileAtomic(t.hqPointer, pointerNew);
+        if (mdOld !== mdNew) {
+            if (mdNew === null) {
+                if (fs.existsSync(t.claudeMd))
+                    fs.unlinkSync(t.claudeMd);
+            }
+            else
+                writeFileAtomic(t.claudeMd, mdNew);
         }
-        else
-            writeFileAtomic(t.claudeMd, mdNew);
     }
-    if (!pluginSource)
-        fs.mkdirSync(t.skillsDir, { recursive: true });
-    for (const name of skills.link) {
-        fs.symlinkSync(path.join(hqSkillsSource(hqRoot), name), path.join(t.skillsDir, skillLinkName(name)));
+    catch (error) {
+        rollbackLinkPhase({
+            createdLinks,
+            skillsDir: skillsDirExisted ? null : t.skillsDir,
+            files: [[t.hqPointer, pointerOld], [t.claudeMd, mdOld]],
+            log,
+        });
+        throw error;
     }
     for (const link of skillLinksToRemove)
-        fs.unlinkSync(link);
+        removeSkillEntry(link, log);
     if (pluginSource) {
         // Migrate a prior direct install: remove only our old hook/MCP entries while
         // retaining the original user settings for a later uninstall restore.
@@ -574,16 +588,49 @@ export function installGlobalClaude(opts) {
         installProviderWrappers(providerBin, home);
     log(`HQ installed for Claude Code from ${hqRoot}.`);
     log(`  skills linked: ${skills.link.length} new, ${skills.already.length} already present, ${skills.skipped.length} skipped`);
+    reportSkillCopies(linkKinds, log);
     reportSkippedSkills(skills, log, false);
     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`);
     return touched;
 }
+/**
+ * Undo the link phase of a failed install: remove only the links this run
+ * created (never recursing into them), put each file back to its pre-run
+ * bytes, and drop the skills folder if this run created it and it is empty.
+ * A copy that is kept instead of removed is reported through `log`.
+ */
+function rollbackLinkPhase(args) {
+    for (const link of [...args.createdLinks].reverse()) {
+        try {
+            removeSkillEntry(link, args.log);
+        }
+        catch { /* keep rolling back */ }
+    }
+    for (const [file, original] of args.files) {
+        try {
+            if (original === null) {
+                if (fs.existsSync(file))
+                    fs.unlinkSync(file);
+            }
+            else if (readOrNull(file) !== original)
+                writeFileAtomic(file, original);
+        }
+        catch { /* keep rolling back */ }
+    }
+    if (args.skillsDir) {
+        try {
+            if (fs.readdirSync(args.skillsDir).length === 0)
+                fs.rmdirSync(args.skillsDir);
+        }
+        catch { /* keep rolling back */ }
+    }
+}
 /** Reverse every install step; non-HQ entries are left untouched. */
 export function uninstallGlobalClaude(opts = {}) {
     const home = resolveEnv({ home: opts.home }).home;
@@ -621,11 +668,11 @@ export function uninstallGlobalClaude(opts = {}) {
     const links = [];
     try {
         for (const d of fs.readdirSync(t.skillsDir, { withFileTypes: true })) {
-            if (!d.name.startsWith(SKILL_LINK_PREFIX) || !d.isSymbolicLink())
+            if (!d.name.startsWith(SKILL_LINK_PREFIX) || !(d.isSymbolicLink() || d.isDirectory()))
                 continue;
             const link = path.join(t.skillsDir, d.name);
-            const target = path.resolve(t.skillsDir, fs.readlinkSync(link));
-            if (path.dirname(target) === source)
+            const target = skillEntryTarget(t.skillsDir, link);
+            if (target !== null && path.dirname(target) === source)
                 links.push(link);
         }
     }
@@ -693,7 +740,7 @@ export function uninstallGlobalClaude(opts = {}) {
         }
     }
     for (const link of links)
-        fs.unlinkSync(link);
+        removeSkillEntry(link, log);
     if (md !== null && mdNext !== md) {
         if (mdNext === null || (mdNext === '' && state?.claudeMd.original == null))
             fs.unlinkSync(t.claudeMd);
@@ -842,12 +889,34 @@ export function installGlobalCodex(opts) {
         log(lineDiff(codexConfigFormat.serialize(tomlDoc), codexConfigFormat.serialize(tomlNext)));
         return touched;
     }
-    writeFileAtomic(hqPointer, pointerNew);
-    writeFileAtomic(t.agentsMd, mdNew);
+    // Skill links go first so a link failure leaves no pointer or AGENTS.md
+    // block behind (see installGlobalClaude).
+    const skillsDirExisted = fs.existsSync(t.skillsDir);
+    const createdLinks = [];
+    const linkKinds = [];
+    try {
+        fs.mkdirSync(t.skillsDir, { recursive: true });
+        for (const name of skills.link) {
+            const link = path.join(t.skillsDir, skillLinkName(name));
+            linkKinds.push(linkDirectory(path.join(hqSkillsSource(hqRoot), name), link, { platform: opts.platform }));
+            createdLinks.push(link);
+        }
+        writeFileAtomic(hqPointer, pointerNew);
+        writeFileAtomic(t.agentsMd, mdNew);
+    }
+    catch (error) {
+        rollbackLinkPhase({
+            createdLinks,
+            skillsDir: skillsDirExisted ? null : t.skillsDir,
+            files: [[hqPointer, pointerOld], [t.agentsMd, mdOld]],
+            log,
+        });
+        throw error;
+    }
     // Legacy mirror: replace only when HQ-owned; record enough to put it back.
     let legacyRecord = prior?.legacy ?? { kind: 'none' };
     if (legacy.kind === 'hq-symlink') {
-        fs.unlinkSync(legacyPath);
+        removeLinkOnly(legacyPath);
         legacyRecord = { kind: 'symlink', target: legacy.target };
     }
     else if (legacy.kind === 'hq-dir') {
@@ -857,12 +926,8 @@ export function installGlobalCodex(opts) {
     }
     else if (legacy.kind === 'foreign')
         log(legacyWarning(t.skillsDir));
-    fs.mkdirSync(t.skillsDir, { recursive: true });
-    for (const name of skills.link) {
-        fs.symlinkSync(path.join(hqSkillsSource(hqRoot), name), path.join(t.skillsDir, skillLinkName(name)));
-    }
     for (const link of companySkillLinksToRemove)
-        fs.unlinkSync(link);
+        removeSkillEntry(link, log);
     writeConfigAtomic({
         target: t.hooksJson,
         pack: HQ_ANYWHERE_PACK,
@@ -905,8 +970,9 @@ export function installGlobalCodex(opts) {
         installProviderWrappers(providerBin, home);
     log(`HQ installed for Codex from ${hqRoot}.`);
     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;
 }
@@ -943,11 +1009,11 @@ export function uninstallGlobalCodex(opts = {}) {
     const links = [];
     try {
         for (const d of fs.readdirSync(t.skillsDir, { withFileTypes: true })) {
-            if (!d.name.startsWith(SKILL_LINK_PREFIX) || !d.isSymbolicLink())
+            if (!d.name.startsWith(SKILL_LINK_PREFIX) || !(d.isSymbolicLink() || d.isDirectory()))
                 continue;
             const link = path.join(t.skillsDir, d.name);
-            const target = path.resolve(t.skillsDir, fs.readlinkSync(link));
-            if (path.dirname(target) === source)
+            const target = skillEntryTarget(t.skillsDir, link);
+            if (target !== null && path.dirname(target) === source)
                 links.push(link);
         }
     }
@@ -1012,10 +1078,10 @@ export function uninstallGlobalCodex(opts = {}) {
         }
     }
     for (const link of links)
-        fs.unlinkSync(link);
+        removeSkillEntry(link, log);
     if (restoreLegacy && state) {
         if (state.legacy.kind === 'symlink')
-            fs.symlinkSync(state.legacy.target, legacyPath);
+            linkDirectory(state.legacy.target, legacyPath, { platform: opts.platform, allowCopy: false });
         else if (state.legacy.kind === 'dir' && fs.existsSync(state.legacy.backup))
             fs.renameSync(state.legacy.backup, legacyPath);
     }
@@ -1124,6 +1190,18 @@ 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))
+                (opts.log ?? console.log)(line);
+    }
 }
 /**
  * Codex skips untrusted hooks, so the hooks.json entries written above do

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

@@ -1,7 +1,7 @@
 import type { LaneCompanyRef, LanePlacementPolicy, LaneRecord, LanesConfig, QuestionAnswer, QuestionBody, QuestionRecord, SeniorRef, AccountHistoryEntry, LaneAccountSelection, PendingResume, QueuedReason, ResolvedLaneWorker, LivenessDeps, MachineIdentity, MonitorEvidenceReader, ReconcileHost, RunCommand, ThrottleDeps, withLaneAdmissionLock, withLaneHireLocks } from "../lib/lanes/index.js";
 import type { OutpostIdentity } from "../lib/lanes/admission-host.js";
 import type { OutpostDispatchResult } from "../lib/lanes/outpost-dispatch.js";
-import type { CpuBusySource } from "../lib/lanes/throttle.js";
+import type { CpuBusySource, MemoryHold } from "../lib/lanes/throttle.js";
 import type { ProbeCommand } from "../lib/lanes/models.js";
 import type { FocusGuardReason } from "../lib/lanes/focus-guard.js";
 import type { KillProcessFn, ProveDetachedFn, SpawnProcessFn } from "../lib/lanes/spawn.js";
@@ -100,6 +100,8 @@ export interface AdmissionResult {
         last_busy: number | null;
         busy_source: CpuBusySource | undefined;
         sampled_at: string | undefined;
+        /** Present when the memory gate holds: the signal, its value and the threshold. */
+        memory_hold?: MemoryHold;
     };
 }
 export interface PrepareAccountMoveInput {

package/dist/commands/lanes.d.ts

@@ -136,12 +136,12 @@ export declare function casUpdateLane(hqRoot: string, laneId: string, updater: (
  * reconcile pass resumes the lane once every question is answered.
  */
 export declare function checkpointInstruction(worker: Pick<ResolvedLaneWorker, "approvalRequired" | "humanCheckpoints">): string;
-export declare function composeWorkerBrief(worker: ResolvedLaneWorker, taskBrief: string): string;
+export declare function composeWorkerBrief(worker: ResolvedLaneWorker, taskBrief: string, hqRoot: string): string;
 /**
- * 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 declare function composeGeneralBrief(taskBrief: string): string;
+export declare function composeGeneralBrief(taskBrief: string, hqRoot: string): string;
 export declare const DISPATCH_TERMINAL_REASON: "outpost_dispatch_failed";
 /**
  * The CAS updater a pickup failure applies. A lane that is already terminal