@indigoai-us/hq-cli 5.343.0 → 5.344.0

package/dist/lib/work-context/config.js

@@ -9,6 +9,10 @@ import { DefaultCompanyUnavailableError, UnsafeConfigPathError, WorkContextError
 import { workContextConfigPath } from "./paths.js";
 import { assertWindowsOwnerOnlyAcl } from "./windows-acl.js";
 const DEVICE_CONFIG_SCHEMA_VERSION = 1;
+/** A person principal uid, as carried in the `custom:entityUid` token claim. */
+export function isPersonUid(value) {
+    return typeof value === "string" && /^prs_[A-Za-z0-9]+$/.test(value);
+}
 const CONFIG_LOCK_TIMEOUT_MS = 5_000;
 const CONFIG_LOCK_RETRY_MS = 10;
 function waitForConfigLock(ms) {
@@ -146,6 +150,44 @@ function sanitizeRepoCompanyMap(raw) {
     }
     return Object.keys(out).length > 0 ? out : null;
 }
+/** Parse a raw usageAttribution value; anything malformed is dropped (fail closed). */
+export function sanitizeUsageAttribution(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const v = raw;
+    if (v.mode !== "default-company")
+        return undefined;
+    const companyUid = typeof v.companyUid === "string" ? v.companyUid.trim() : "";
+    const personUid = typeof v.personUid === "string" ? v.personUid.trim() : "";
+    const optedInAt = typeof v.optedInAt === "string" ? v.optedInAt.trim() : "";
+    if (!companyUid.startsWith("cmp_") ||
+        !isPersonUid(personUid) ||
+        !optedInAt ||
+        !Number.isFinite(Date.parse(optedInAt))) {
+        return undefined;
+    }
+    return { mode: "default-company", companyUid, personUid, optedInAt };
+}
+/**
+ * The opt-in that is in effect: present, for the uid of the current enabled
+ * default company, and given by the signed-in person. Mirrors the hq-cloud
+ * reader. No signed-in person means no opt-in.
+ */
+export function effectiveUsageAttribution(cfg, personUid) {
+    const opt = cfg.usageAttribution;
+    if (!opt || !isPersonUid(personUid) || opt.personUid !== personUid)
+        return null;
+    const def = cfg.defaultCompany;
+    if (!opt || !def || def.enabled !== true || def.source === "disabled")
+        return null;
+    if (!def.uid || def.uid !== opt.companyUid)
+        return null;
+    return opt;
+}
+/** Keep `usageAttribution` next to `defaultCompany`, omitting it when absent. */
+function usageAttributionField(value) {
+    return value ? { usageAttribution: value } : {};
+}
 /**
  * Refuse a config path that is a symlink (every platform) or writable by
  * anyone other than the owner.
@@ -216,6 +258,7 @@ export function readDeviceConfig(deps) {
             defaultCompany: legacyNullDefault
                 ? { slug: "", enabled: false, source: "disabled" }
                 : raw.defaultCompany ?? null,
+            ...usageAttributionField(sanitizeUsageAttribution(raw.usageAttribution)),
             migrationCapability: raw.migrationCapability ?? null,
             repoCompanyMap: sanitizeRepoCompanyMap(raw.repoCompanyMap),
             defaultCompanyMemberships: sanitizeMembershipSnapshot(raw.defaultCompanyMemberships),
@@ -287,9 +330,36 @@ export async function setDefaultCompany(slug, deps) {
         };
         if (resolvedUid)
             defaultCompany.uid = resolvedUid;
+        const choice = deps.usageAttribution ?? "keep-if-same";
+        let usageAttribution;
+        const personUid = isPersonUid(deps.personUid) ? deps.personUid : undefined;
+        if (choice === "opt-in") {
+            if (!resolvedUid?.startsWith("cmp_")) {
+                throw new WorkContextError("UsageAttributionUnavailable", `Cannot count usage toward "${trimmed}": its company uid is unknown`);
+            }
+            if (!personUid) {
+                throw new WorkContextError("UsageAttributionUnavailable", `Cannot count usage toward "${trimmed}": the signed-in person could not be determined`);
+            }
+            usageAttribution = {
+                mode: "default-company",
+                companyUid: resolvedUid,
+                personUid,
+                optedInAt: now().toISOString(),
+            };
+        }
+        else if (choice === "keep-if-same") {
+            usageAttribution =
+                resolvedUid &&
+                    personUid &&
+                    prior.usageAttribution?.companyUid === resolvedUid &&
+                    prior.usageAttribution.personUid === personUid
+                    ? prior.usageAttribution
+                    : undefined;
+        }
         const next = {
             schemaVersion: DEVICE_CONFIG_SCHEMA_VERSION,
             defaultCompany,
+            ...usageAttributionField(usageAttribution),
             migrationCapability: prior.migrationCapability ?? null,
             repoCompanyMap: prior.repoCompanyMap ?? null,
             defaultCompanyMemberships: prior.defaultCompanyMemberships ?? null,
@@ -300,6 +370,69 @@ export async function setDefaultCompany(slug, deps) {
         return next;
     });
 }
+/**
+ * Record or remove the usage-attribution opt-in for the current default
+ * company. Opting in requires an enabled, explicitly chosen default with a
+ * cmp_ uid that equals `companyUid` (the company the person was asked about);
+ * an automatic single-company default is never opted in.
+ */
+export function setUsageAttribution(optIn, deps) {
+    const now = deps.now ?? (() => new Date());
+    return withDeviceConfigLock(deps.root, () => {
+        const prior = readDeviceConfig(deps);
+        let usageAttribution;
+        if (optIn) {
+            const def = prior.defaultCompany;
+            if (!def ||
+                def.enabled !== true ||
+                def.source !== "chosen" ||
+                !def.uid?.startsWith("cmp_") ||
+                def.uid !== optIn.companyUid ||
+                !isPersonUid(optIn.personUid)) {
+                throw new WorkContextError("UsageAttributionUnavailable", "Usage can only be counted toward a default company you chose on this device");
+            }
+            usageAttribution = {
+                mode: "default-company",
+                companyUid: def.uid,
+                personUid: optIn.personUid,
+                optedInAt: now().toISOString(),
+            };
+        }
+        const next = {
+            schemaVersion: DEVICE_CONFIG_SCHEMA_VERSION,
+            defaultCompany: prior.defaultCompany ?? null,
+            ...usageAttributionField(usageAttribution),
+            migrationCapability: prior.migrationCapability ?? null,
+            repoCompanyMap: prior.repoCompanyMap ?? null,
+            defaultCompanyMemberships: prior.defaultCompanyMemberships ?? null,
+            repairHeldWithDefault: prior.repairHeldWithDefault === true,
+            updatedAt: now().toISOString(),
+        };
+        writeDeviceConfig({ root: deps.root }, next);
+        return next;
+    });
+}
+/**
+ * Drop the usage-attribution opt-in unless it was given by `personUid`. Called
+ * on login (identity may have changed) and logout (null: always drop). A
+ * config with no opt-in, or one already matching, is left untouched.
+ */
+export function retainUsageAttributionForPerson(personUid, deps) {
+    if (!fs.existsSync(workContextConfigPath(deps.root)))
+        return false;
+    return withDeviceConfigLock(deps.root, () => {
+        const prior = readDeviceConfig(deps);
+        const opt = prior.usageAttribution;
+        if (!opt)
+            return false;
+        if (isPersonUid(personUid) && opt.personUid === personUid)
+            return false;
+        const now = deps.now ?? (() => new Date());
+        const { usageAttribution: _dropped, ...rest } = prior;
+        writeDeviceConfig({ root: deps.root }, { ...rest, updatedAt: now().toISOString() });
+        return true;
+    });
+}
 export function clearDefaultCompany(deps) {
     const now = deps.now ?? (() => new Date());
     return withDeviceConfigLock(deps.root, () => {
@@ -307,6 +440,8 @@ export function clearDefaultCompany(deps) {
         const next = {
             schemaVersion: DEVICE_CONFIG_SCHEMA_VERSION,
             defaultCompany: { slug: "", enabled: false, source: "disabled" },
+            // usageAttribution is intentionally omitted: clearing the default also
+            // withdraws the opt-in to count usage toward it.
             migrationCapability: prior.migrationCapability ?? null,
             repoCompanyMap: prior.repoCompanyMap ?? null,
             defaultCompanyMemberships: prior.defaultCompanyMemberships ?? null,
@@ -355,6 +490,7 @@ export function setRepoCompany(key, mapping, deps) {
         const next = {
             schemaVersion: DEVICE_CONFIG_SCHEMA_VERSION,
             defaultCompany: prior.defaultCompany ?? null,
+            ...usageAttributionField(prior.usageAttribution),
             migrationCapability: prior.migrationCapability ?? null,
             repoCompanyMap: nextMap,
             defaultCompanyMemberships: prior.defaultCompanyMemberships ?? null,
@@ -373,6 +509,7 @@ export function recordMigrationCapabilitySnapshot(snapshot, deps) {
         const next = {
             schemaVersion: DEVICE_CONFIG_SCHEMA_VERSION,
             defaultCompany: prior.defaultCompany ?? null,
+            ...usageAttributionField(prior.usageAttribution),
             migrationCapability: {
                 unlocked: snapshot.unlocked,
                 offline: snapshot.offline,
@@ -414,6 +551,7 @@ export function recordDefaultCompanyMemberships(snapshot, deps) {
         const next = {
             schemaVersion: DEVICE_CONFIG_SCHEMA_VERSION,
             defaultCompany: prior.defaultCompany ?? null,
+            ...usageAttributionField(prior.usageAttribution),
             migrationCapability: prior.migrationCapability ?? null,
             repoCompanyMap: prior.repoCompanyMap ?? null,
             defaultCompanyMemberships: {
@@ -435,6 +573,7 @@ export function invalidateDefaultCompanyMemberships(deps) {
         const next = {
             schemaVersion: DEVICE_CONFIG_SCHEMA_VERSION,
             defaultCompany: prior.defaultCompany ?? null,
+            ...usageAttributionField(prior.usageAttribution),
             migrationCapability: prior.migrationCapability ?? null,
             repoCompanyMap: prior.repoCompanyMap ?? null,
             defaultCompanyMemberships: null,
@@ -468,6 +607,8 @@ export function setAutoDefaultCompany(membership, deps) {
                 enabled: true,
                 source: "auto_single",
             },
+            // usageAttribution is intentionally omitted: an automatic default is
+            // never opted in to usage attribution.
             migrationCapability: prior.migrationCapability ?? null,
             repoCompanyMap: prior.repoCompanyMap ?? null,
             defaultCompanyMemberships: prior.defaultCompanyMemberships ?? null,
@@ -485,6 +626,7 @@ export function setRepairHeldWithDefault(enabled, deps) {
         const next = {
             schemaVersion: DEVICE_CONFIG_SCHEMA_VERSION,
             defaultCompany: prior.defaultCompany ?? null,
+            ...usageAttributionField(prior.usageAttribution),
             migrationCapability: prior.migrationCapability ?? null,
             repoCompanyMap: prior.repoCompanyMap ?? null,
             defaultCompanyMemberships: prior.defaultCompanyMemberships ?? null,

package/dist/lib/work-context/person-identity.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Signed-in person identity for the usage-attribution opt-in.
+ *
+ * Source: the cached Cognito person session (`~/.hq/cognito-tokens.json`,
+ * read through `loadCachedTokens`). The person uid is the `custom:entityUid`
+ * claim of the ID token (falling back to the access token), and only a
+ * `prs_` value counts. Agent (`agt_`) or unknown identities return null, so
+ * no opt-in is written or kept for them. Claims are read without
+ * verification; this decides only whether local consent belongs to the
+ * account that is signed in, never authorization.
+ */
+export declare function personUidFromTokens(tokens: {
+    idToken?: string;
+    accessToken?: string;
+} | null | undefined): string | null;
+//# sourceMappingURL=person-identity.d.ts.map

package/dist/lib/work-context/person-identity.js

@@ -0,0 +1,39 @@
+/**
+ * Signed-in person identity for the usage-attribution opt-in.
+ *
+ * Source: the cached Cognito person session (`~/.hq/cognito-tokens.json`,
+ * read through `loadCachedTokens`). The person uid is the `custom:entityUid`
+ * claim of the ID token (falling back to the access token), and only a
+ * `prs_` value counts. Agent (`agt_`) or unknown identities return null, so
+ * no opt-in is written or kept for them. Claims are read without
+ * verification; this decides only whether local consent belongs to the
+ * account that is signed in, never authorization.
+ */
+import { isPersonUid } from "./config.js";
+function claimsOf(token) {
+    if (typeof token !== "string")
+        return null;
+    const part = token.split(".")[1];
+    if (!part)
+        return null;
+    try {
+        const parsed = JSON.parse(Buffer.from(part, "base64url").toString("utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function personUidFromTokens(tokens) {
+    if (!tokens)
+        return null;
+    for (const token of [tokens.idToken, tokens.accessToken]) {
+        const uid = claimsOf(token)?.["custom:entityUid"];
+        if (isPersonUid(uid))
+            return uid;
+    }
+    return null;
+}
+//# sourceMappingURL=person-identity.js.map

package/dist/utils/cli-telemetry.js

@@ -186,7 +186,11 @@ export async function emitCliFeatureUsed(usage, timeoutMs = TELEMETRY_TIMEOUT_MS
                             consentBasis,
                             schemaVersion: 1,
                             ...(companyUid ? { companyUid } : {}),
-                            properties: { kind: usage.kind, outcome: usage.outcome },
+                            properties: {
+                                kind: usage.kind,
+                                outcome: usage.outcome,
+                                version: CLI_VERSION.slice(0, 40),
+                            },
                         },
                     ],
                 },

package/dist/utils/client-health.d.ts

@@ -32,7 +32,7 @@
  */
 import { isExpiring, loadCachedTokens } from "./cognito-session.js";
 import { type VersionInfo } from "./feedback-versions.js";
-import { type ClientHealthArch, type ClientHealthHeartbeat, type ClientHealthLocalFilesOverview, type ClientHealthPlatform } from "./client-health-contract.js";
+import { type ClientHealthArch, type ClientHealthFailureReason, type ClientHealthHeartbeat, type ClientHealthLocalFilesOverview, type ClientHealthPlatform } from "./client-health-contract.js";
 export declare const CLIENT_HEALTH_STATE_FILE = "cli-client-health.json";
 /**
  * Single-flight marker for the journal observation below. Held only for the
@@ -141,6 +141,8 @@ export interface BuildCliHeartbeatInput {
     now: Date;
     platform?: ClientHealthPlatform | null;
     arch?: ClientHealthArch | null;
+    /** Closed, typed reason from the terminal sync runner; never free-form text. */
+    failureReason?: ClientHealthFailureReason;
     /**
      * Bounded local log/journal file facts (US-016). Only ever attached for
      * `sync_success` / `sync_failure` kinds — support asked for this on the
@@ -148,6 +150,8 @@ export interface BuildCliHeartbeatInput {
      */
     localFilesOverview?: ClientHealthLocalFilesOverview | null;
 }
+/** Classify sync failures using typed error identity/code fields only. */
+export declare function classifySyncFailure(err: unknown): ClientHealthFailureReason;
 /**
  * Build one contract-valid CLI heartbeat, or null when this environment
  * cannot be represented in the closed contract enums (unknown platform/arch)
@@ -184,7 +188,7 @@ export interface ClientHealthDeps {
  * ignores its abort signal) must never delay a command past the bound. On
  * timeout the pending work is abandoned silently.
  */
-export declare function contributeClientHealth(kind: ClientHealthEventKind, deps?: ClientHealthDeps): Promise<void>;
+export declare function contributeClientHealth(kind: ClientHealthEventKind, deps?: ClientHealthDeps, failureReason?: ClientHealthFailureReason): Promise<void>;
 /**
  * Fire-once-per-process invocation heartbeat (commander preAction seam, next
  * to `emitCliSessionStarted`). Reports the real CLI + Core versions, platform,
@@ -194,7 +198,7 @@ export declare function reportCliClientHealthInvocation(deps?: ClientHealthDeps)
 export interface SyncHealthReport {
     /** Report the terminal outcome. Bounded, swallowed, safe to await. */
     succeeded(): Promise<void>;
-    failed(): Promise<void>;
+    failed(reason?: ClientHealthFailureReason): Promise<void>;
 }
 /**
  * Report a CLI sync command run: an attempt heartbeat now (fire-and-forget)

package/dist/utils/client-health.js

@@ -37,6 +37,7 @@ import { getStateDir, listJournals } from "@indigoai-us/hq-cloud";
 import { isExpiring, isMachineIdentity, loadCachedTokens, } from "./cognito-session.js";
 import { vaultApiFetch } from "./vault-api.js";
 import { collectVersions } from "./feedback-versions.js";
+import { isAuthError } from "./auth-error.js";
 import { CLIENT_HEALTH_CONTRACT_VERSION, parseClientHealthHeartbeat, } from "./client-health-contract.js";
 import { collectLocalFilesOverview } from "./local-files-overview.js";
 /** Same bound as CLI telemetry: a heartbeat may never stall a command. */
@@ -314,6 +315,25 @@ function acquireJournalObservationLock(stateDir, nowMs, staleMs) {
         }
     };
 }
+/** Classify sync failures using typed error identity/code fields only. */
+export function classifySyncFailure(err) {
+    if (isAuthError(err))
+        return "AUTH_EXPIRED";
+    let current = err;
+    for (let depth = 0; depth < 3; depth += 1) {
+        if (current === null || typeof current !== "object")
+            break;
+        const value = current;
+        if (value.code === "ENOSPC" || value.code === "EDQUOT") {
+            return "DISK_FULL";
+        }
+        if (value.code === "EACCES" || value.code === "EPERM") {
+            return "PERMISSION_DENIED";
+        }
+        current = value.cause;
+    }
+    return "RUNNER_FAILED";
+}
 /**
  * Build one contract-valid CLI heartbeat, or null when this environment
  * cannot be represented in the closed contract enums (unknown platform/arch)
@@ -388,6 +408,9 @@ export function buildCliHeartbeat(input) {
     if (input.state.lastSyncAttemptAt !== undefined) {
         heartbeat.lastSyncAttemptAt = input.state.lastSyncAttemptAt;
     }
+    if (input.kind === "sync_failure" && input.failureReason !== undefined) {
+        heartbeat.failureReason = input.failureReason;
+    }
     if (lastSyncSuccessAt !== null) {
         heartbeat.lastSyncSuccessAt = lastSyncSuccessAt;
     }
@@ -435,10 +458,10 @@ function settleWithin(work, ms) {
  * ignores its abort signal) must never delay a command past the bound. On
  * timeout the pending work is abandoned silently.
  */
-export async function contributeClientHealth(kind, deps = {}) {
-    await settleWithin(contributeClientHealthUnbounded(kind, deps), deps.timeoutMs ?? CLIENT_HEALTH_TIMEOUT_MS);
+export async function contributeClientHealth(kind, deps = {}, failureReason) {
+    await settleWithin(contributeClientHealthUnbounded(kind, deps, failureReason), deps.timeoutMs ?? CLIENT_HEALTH_TIMEOUT_MS);
 }
-async function contributeClientHealthUnbounded(kind, deps) {
+async function contributeClientHealthUnbounded(kind, deps, failureReason) {
     try {
         const now = (deps.now ?? (() => new Date()))();
         const stateDir = (deps.stateDir ?? getStateDir)();
@@ -546,6 +569,7 @@ async function contributeClientHealthUnbounded(kind, deps) {
             journalLastSyncAt,
             now,
             localFilesOverview,
+            failureReason,
         });
         if (!heartbeat)
             return;
@@ -587,12 +611,12 @@ export function reportCliClientHealthInvocation(deps) {
  */
 export function beginSyncHealthReport(deps = {}) {
     const attempt = contributeClientHealth("sync_attempt", deps);
-    const finish = (kind) => attempt
-        .then(() => contributeClientHealth(kind, deps))
+    const finish = (kind, failureReason) => attempt
+        .then(() => contributeClientHealth(kind, deps, failureReason))
         .catch(() => undefined);
     return {
         succeeded: () => finish("sync_success"),
-        failed: () => finish("sync_failure"),
+        failed: (reason) => finish("sync_failure", reason),
     };
 }
 //# sourceMappingURL=client-health.js.map

package/dist/utils/install-tree-torn.d.ts

@@ -278,7 +278,8 @@ type VersionGatePhase = "preflight" | "lock_acquired" | "installer_running" | "v
 /**
  * Poll until the install tree has been continuously READY for `quietMs`, or the
  * wait exhausts its bounds. READY means: (i) no FRESH update lock held by another
- * pid, (ii) the missing target is present, and — when `packageRoot` is known —
+ * pid and no live recorded updater while the tree is in flight, (ii) the missing
+ * target is present, and — when `packageRoot` is known —
  * (iii) `<packageRoot>/package.json` parses with `name === CLI_NAME` and (iv) no
  * `.<leaf>-<rand>` retired sibling remains beside it. Every filesystem error makes
  * its condition "not ready" rather than throwing.
@@ -295,20 +296,22 @@ type VersionGatePhase = "preflight" | "lock_acquired" | "installer_running" | "v
  *     any installer before attempting a repair. Any observed signature change
  *     keeps the ordinary settle deadline in force. `deadlineMs === 0` evaluates
  *     readiness once.
- *   - LOCKED time — wall time observed under a fresh foreign lock held by a live
- *     pid — is bounded SEPARATELY by `lockWaitMs` (default the lock contract's own
- *     10-minute staleness window) and does NOT consume the settle budget. When
- *     that ceiling is reached with the lock still held, the result is unsettled
- *     with `lockHeldAtEnd` true so the seam can report a distinct `lock-held`
- *     outcome and remedy rather than telling the user to reinstall over a live
- *     writer.
- * Each poll's REAL elapsed interval (now() deltas) is attributed to the locked or
- * unlocked bucket by whether a fresh foreign lock was held when the interval
- * began, so a starved event loop only makes the wait coarser, never unbounded. A
+ *   - WRITER time — wall time observed under a fresh foreign lock, or while a
+ *     recorded foreign updater pid is alive and the tree has an in-flight signal
+ *     — is bounded SEPARATELY by `lockWaitMs` (default the lock contract's own
+ *     10-minute staleness window) and does NOT consume the settle budget. This
+ *     also covers a still-running updater whose lock became stale by age. When
+ *     that ceiling is reached, the result is unsettled; `lockHeldAtEnd` remains
+ *     reserved for a fresh lock held at the end.
+ * Each poll's REAL elapsed interval (now() deltas) is attributed to the writer or
+ * unlocked bucket by whether a fresh lock or qualifying live updater was observed
+ * when the interval began, so a starved event loop only makes the wait coarser,
+ * never unbounded. A
  * stale lock (dead pid, older than the staleness window, unparseable) or our own
- * pid never extends anything. The whole wait is bounded (≤ `deadlineMs +
+ * pid never extends anything by itself. The whole wait is bounded (≤ `deadlineMs +
  * lockWaitMs`), and the unchanged-tree path normally returns after the much
- * shorter `staleProbeMs` observation window.
+ * shorter `staleProbeMs` observation window unless a live updater pid is still
+ * present with an in-flight tree signal.
  */
 export declare function waitForInstallTreeSettled(args: WaitForInstallTreeSettledArgs): Promise<WaitForInstallTreeSettledResult>;
 export interface InstallRewriteSignalArgs {

package/dist/utils/install-tree-torn.js

@@ -714,6 +714,28 @@ function updaterPidAlive(lockPath, fs, isPidAlive) {
         return "unknown";
     }
 }
+/** Whether the lock names a live process other than this CLI invocation. */
+function liveForeignUpdaterPid(lockPath, fs, isPidAlive) {
+    try {
+        const lock = JSON.parse(fs.readFileSync(lockPath, "utf-8"));
+        if (typeof lock.startedAt !== "string" ||
+            Number.isNaN(Date.parse(lock.startedAt)) ||
+            typeof lock.tool !== "string" ||
+            lock.tool.length === 0 ||
+            typeof lock.version !== "string" ||
+            lock.version.length === 0) {
+            return false;
+        }
+        return typeof lock.pid === "number" &&
+            Number.isSafeInteger(lock.pid) &&
+            lock.pid > 0 &&
+            lock.pid !== process.pid &&
+            isPidAlive(lock.pid);
+    }
+    catch {
+        return false;
+    }
+}
 /** Snapshot retired sibling trees so changes below their root stay observable. */
 function retiredSiblingActivitySignature(packageRoot, fs) {
     const { leaf } = cliNameParts();
@@ -917,7 +939,8 @@ const DEFAULT_INSTALL_TREE_STALE_PROBE_MS = 1_500;
 /**
  * Poll until the install tree has been continuously READY for `quietMs`, or the
  * wait exhausts its bounds. READY means: (i) no FRESH update lock held by another
- * pid, (ii) the missing target is present, and — when `packageRoot` is known —
+ * pid and no live recorded updater while the tree is in flight, (ii) the missing
+ * target is present, and — when `packageRoot` is known —
  * (iii) `<packageRoot>/package.json` parses with `name === CLI_NAME` and (iv) no
  * `.<leaf>-<rand>` retired sibling remains beside it. Every filesystem error makes
  * its condition "not ready" rather than throwing.
@@ -934,20 +957,22 @@ const DEFAULT_INSTALL_TREE_STALE_PROBE_MS = 1_500;
  *     any installer before attempting a repair. Any observed signature change
  *     keeps the ordinary settle deadline in force. `deadlineMs === 0` evaluates
  *     readiness once.
- *   - LOCKED time — wall time observed under a fresh foreign lock held by a live
- *     pid — is bounded SEPARATELY by `lockWaitMs` (default the lock contract's own
- *     10-minute staleness window) and does NOT consume the settle budget. When
- *     that ceiling is reached with the lock still held, the result is unsettled
- *     with `lockHeldAtEnd` true so the seam can report a distinct `lock-held`
- *     outcome and remedy rather than telling the user to reinstall over a live
- *     writer.
- * Each poll's REAL elapsed interval (now() deltas) is attributed to the locked or
- * unlocked bucket by whether a fresh foreign lock was held when the interval
- * began, so a starved event loop only makes the wait coarser, never unbounded. A
+ *   - WRITER time — wall time observed under a fresh foreign lock, or while a
+ *     recorded foreign updater pid is alive and the tree has an in-flight signal
+ *     — is bounded SEPARATELY by `lockWaitMs` (default the lock contract's own
+ *     10-minute staleness window) and does NOT consume the settle budget. This
+ *     also covers a still-running updater whose lock became stale by age. When
+ *     that ceiling is reached, the result is unsettled; `lockHeldAtEnd` remains
+ *     reserved for a fresh lock held at the end.
+ * Each poll's REAL elapsed interval (now() deltas) is attributed to the writer or
+ * unlocked bucket by whether a fresh lock or qualifying live updater was observed
+ * when the interval began, so a starved event loop only makes the wait coarser,
+ * never unbounded. A
  * stale lock (dead pid, older than the staleness window, unparseable) or our own
- * pid never extends anything. The whole wait is bounded (≤ `deadlineMs +
+ * pid never extends anything by itself. The whole wait is bounded (≤ `deadlineMs +
  * lockWaitMs`), and the unchanged-tree path normally returns after the much
- * shorter `staleProbeMs` observation window.
+ * shorter `staleProbeMs` observation window unless a live updater pid is still
+ * present with an in-flight tree signal.
  */
 export async function waitForInstallTreeSettled(args) {
     const now = args.now ?? Date.now;
@@ -967,17 +992,21 @@ export async function waitForInstallTreeSettled(args) {
     let sawLock = false;
     let sawRetired = false;
     let lockedMs = 0;
+    let writerMs = 0;
     let unlockedMs = 0;
     let lockTool = "";
     let prevT = start;
     let prevForeignLockHeld = false;
+    let prevWriterHeld = false;
     let lockExtendedFired = false;
     for (;;) {
         const t = now();
-        // Attribute the interval that just elapsed [prevT, t) to the bucket for the
-        // lock state that held when it BEGAN (real now() deltas, never nominal pollMs).
+        // Attribute the interval that just elapsed [prevT, t) using the state that
+        // held when it BEGAN (real now() deltas, never nominal pollMs).
         if (prevForeignLockHeld)
             lockedMs += t - prevT;
+        if (prevWriterHeld)
+            writerMs += t - prevT;
         else
             unlockedMs += t - prevT;
         const lock = freshForeignLock(args.lockPath, t, isPidAlive, fs);
@@ -1015,7 +1044,10 @@ export async function waitForInstallTreeSettled(args) {
                 retiredCheckFailed = true;
             }
         }
-        let ready = !foreignLockHeld && installTargetPresent(args.target, fs);
+        const inFlightTree = sawLock || sawRetired || sawTreeChange;
+        const updaterPidHeld = inFlightTree && liveForeignUpdaterPid(args.lockPath, fs, isPidAlive);
+        const writerHeld = foreignLockHeld || updaterPidHeld;
+        let ready = !writerHeld && installTargetPresent(args.target, fs);
         if (ready && args.packageRoot) {
             try {
                 if (!packageRootHealthy(args.packageRoot, fs))
@@ -1055,6 +1087,7 @@ export async function waitForInstallTreeSettled(args) {
         }
         if (!ready &&
             !foreignLockHeld &&
+            !updaterPidHeld &&
             !retiredCheckFailed &&
             !sawLock &&
             !sawTreeChange &&
@@ -1078,14 +1111,13 @@ export async function waitForInstallTreeSettled(args) {
             };
         }
         // Give up when the TREE has had a full unlocked budget with no writer visible,
-        // OR a writer is STILL holding the lock and has held it past its own staleness
-        // ceiling. The lock ceiling is gated on a lock being held RIGHT NOW so that a
-        // ceiling of 0 (HQ_INSTALL_SETTLE_LOCK_TIMEOUT_MS=0, "do not extend under a
-        // lock") disables only the extension and does not collapse the ordinary
-        // deadlineMs settle when no lock exists — `lockedMs` is 0 ≥ 0 on every poll.
+        // OR a qualifying writer has exceeded the shared writer ceiling. The writer
+        // ceiling only extends while a fresh lock or in-flight live PID is present, so
+        // a ceiling of 0 disables only that extension and does not collapse the normal
+        // deadlineMs settle when no writer exists.
         // `deadlineMs` 0 makes the unlocked test fire on the first poll (evaluate-once),
         // matching the pre-lock-aware contract; `lockHeldAtEnd` distinguishes the causes.
-        if (unlockedMs >= deadlineMs || (foreignLockHeld && lockedMs >= lockWaitMs)) {
+        if (unlockedMs >= deadlineMs || (writerHeld && writerMs >= lockWaitMs)) {
             return {
                 settled: false,
                 waitedMs,
@@ -1102,15 +1134,15 @@ export async function waitForInstallTreeSettled(args) {
                 updaterPidAlive: updaterPidAlive(args.lockPath, fs, isPidAlive),
             };
         }
-        // The first poll at which the wait has reached `deadlineMs` while a lock is
-        // still held is exactly where the pre-lock-aware wait gave up — announce the
-        // extension once, and only when we are genuinely going to keep waiting.
-        if (!lockExtendedFired && foreignLockHeld && waitedMs >= deadlineMs) {
+        // Announce once when the deadline has passed and a qualifying writer is why
+        // the bounded wait continues.
+        if (!lockExtendedFired && writerHeld && waitedMs >= deadlineMs) {
             lockExtendedFired = true;
             args.onLockExtended?.();
         }
         prevT = t;
         prevForeignLockHeld = foreignLockHeld;
+        prevWriterHeld = writerHeld;
         await sleep(pollMs);
     }
 }

package/dist/utils/resident-package-preload.d.ts

@@ -1,4 +1,4 @@
-export type ResidentPackagePath = "agent-kit" | "agent-mcp" | "auth-login" | "agents-terminal" | "bot" | "bot-logs-follow" | "childWrapper" | "coreJobRun" | "login" | "mcp" | "daemon" | "daemon-logs-follow" | "mesh-daemon" | "lanes-watch" | "monitor-wait" | "monitor-run" | "agents-message-wait" | "integrations-oauth-wait" | "secrets-sandbox" | "pkg-update" | "pack-install";
+export type ResidentPackagePath = "agent-kit" | "agent-mcp" | "auth-login" | "agents-terminal" | "bot" | "bot-logs-follow" | "childWrapper" | "coreJobRun" | "daemon-call" | "login" | "mcp" | "daemon" | "daemon-logs-follow" | "mesh-daemon" | "lanes-watch" | "monitor-wait" | "monitor-run" | "agents-message-wait" | "integrations-oauth-wait" | "outpost-wait" | "secrets-sandbox" | "pkg-update" | "pack-install";
 /** Runtime modules that resident commands may need after a wait starts. */
 export declare const RESIDENT_PACKAGE_MODULES: Record<ResidentPackagePath, readonly string[]>;
 export declare class ResidentPackagePreloadError extends Error {