@indigoai-us/hq-cli 5.273.0 → 5.274.1

package/dist/lib/first-sync-next-step.js

@@ -0,0 +1,189 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { resolveProcessFlagGate } from "./flag-registry.js";
+import { cognitoSubjectKey, isMachineIdentity, loadCachedTokens, } from "../utils/cognito-session.js";
+export const CLI_FIRST_SYNC_NEXT_STEP_FLAG = "cli.first-sync-next-step";
+export const FIRST_SYNC_NEXT_STEP_COPY = "Save a file in your HQ folder, then run `hq sync push`.";
+export const FIRST_SYNC_CONFIRMATION_COPY = "Your first work sync is complete.";
+const AUTOMATION_ENV_MARKERS = [
+    "CI",
+    "HQ_E2E",
+    "HQ_TEST",
+    "HQ_AUTOMATED",
+    "HQ_PROBE",
+    "HQ_AGENT_DIR",
+];
+const pendingOutcomes = [];
+export function shouldShowFirstSyncNextStep(input) {
+    return (input.flagEnabled &&
+        input.interactive &&
+        !input.alreadyShown &&
+        !input.alreadyCompleted);
+}
+export function shouldConfirmFirstWorkBearingSync(input) {
+    return (input.flagEnabled &&
+        input.interactive &&
+        !input.alreadyCompleted &&
+        input.workBearing);
+}
+export function isWorkBearingSyncResult(result) {
+    if (result.aborted === true)
+        return false;
+    return [
+        result.filesUploaded,
+        result.filesDownloaded,
+        result.sessionLogUploadedCount,
+        result.filesDeleted,
+        result.tombstonedCount,
+    ].some((count) => typeof count === "number" && Number.isFinite(count) && count > 0);
+}
+function isNonAutomatedHumanCliProcess(input) {
+    if (input.machineIdentity || input.env.NODE_ENV === "test")
+        return false;
+    return !AUTOMATION_ENV_MARKERS.some((name) => Boolean(input.env[name]?.trim()));
+}
+export function isHumanInteractiveCliSession(input) {
+    if (!input.stdoutIsTTY || !isNonAutomatedHumanCliProcess(input))
+        return false;
+    if (input.argv.some((arg) => ["--json", "--help", "-h", "--version", "-V"].includes(arg))) {
+        return false;
+    }
+    return true;
+}
+function markerDirectory(home) {
+    return path.join(home, ".hq", "first-sync-next-step");
+}
+export function firstSyncStepMarkerPaths(identity, home = process.env.HOME?.trim() || os.homedir()) {
+    const identityHash = createHash("sha256").update(identity).digest("hex");
+    const directory = markerDirectory(home);
+    return {
+        shown: path.join(directory, `${identityHash}.shown`),
+        completed: path.join(directory, `${identityHash}.completed`),
+    };
+}
+function reportMarkerError(action, err) {
+    const code = typeof err === "object" && err !== null && "code" in err
+        ? String(err.code)
+        : err instanceof Error
+            ? err.name
+            : "unknown error";
+    console.error(`hq: Could not ${action} first-sync state (${code}).`);
+}
+function firstSyncStepMarkerExists(kind, identity) {
+    try {
+        const paths = firstSyncStepMarkerPaths(identity);
+        return fs.existsSync(paths[kind]);
+    }
+    catch (err) {
+        reportMarkerError("read", err);
+        return false;
+    }
+}
+export function claimFirstSyncStepMarker(kind, identity, home = process.env.HOME?.trim() || os.homedir()) {
+    const paths = firstSyncStepMarkerPaths(identity, home);
+    const hqDirectory = path.join(home, ".hq");
+    try {
+        // Do not create ~/.hq on a signed-out machine. Authenticated CLI sessions
+        // already have it, and this state belongs only to the cached person.
+        if (!fs.existsSync(hqDirectory))
+            return false;
+        fs.mkdirSync(path.dirname(paths[kind]), { recursive: true, mode: 0o700 });
+        fs.writeFileSync(paths[kind], `${new Date().toISOString()}\n`, {
+            flag: "wx",
+            mode: 0o600,
+        });
+        return true;
+    }
+    catch (err) {
+        if (typeof err === "object" && err !== null && "code" in err && err.code === "EEXIST") {
+            return false;
+        }
+        reportMarkerError("write", err);
+        return false;
+    }
+}
+export function firstSyncStepTelemetryProperties(outcome) {
+    return {
+        step: "first_sync_next_step",
+        outcome,
+        flagKey: CLI_FIRST_SYNC_NEXT_STEP_FLAG,
+    };
+}
+export function isFirstSyncNextStepEnabled() {
+    return resolveProcessFlagGate(CLI_FIRST_SYNC_NEXT_STEP_FLAG, { fallback: false }, () => false);
+}
+function currentPersonIdentity() {
+    return cognitoSubjectKey(loadCachedTokens());
+}
+function isCurrentSessionEligible() {
+    return isHumanInteractiveCliSession({
+        stdoutIsTTY: Boolean(process.stdout.isTTY),
+        argv: process.argv,
+        env: process.env,
+        machineIdentity: isMachineIdentity(),
+    });
+}
+function queueOutcome(outcome) {
+    if (!pendingOutcomes.includes(outcome))
+        pendingOutcomes.push(outcome);
+}
+/** Called once after the first completed CLI action, before process finalization. */
+export function maybeShowFirstSyncNextStep() {
+    // Keep the cheap eligibility/gate checks ahead of identity and filesystem
+    // reads; neither an automated invocation nor a flag-off session needs state.
+    if (!isCurrentSessionEligible() || !isFirstSyncNextStepEnabled())
+        return false;
+    const identity = currentPersonIdentity();
+    if (!identity)
+        return false;
+    const shouldShow = shouldShowFirstSyncNextStep({
+        flagEnabled: true,
+        interactive: true,
+        alreadyShown: firstSyncStepMarkerExists("shown", identity),
+        alreadyCompleted: firstSyncStepMarkerExists("completed", identity),
+    });
+    if (!shouldShow || !claimFirstSyncStepMarker("shown", identity))
+        return false;
+    console.log(FIRST_SYNC_NEXT_STEP_COPY);
+    queueOutcome("shown");
+    return true;
+}
+/** Capture the first positive CLI sync result without changing transfer logic. */
+export function recordFirstWorkBearingSync(result) {
+    if (!isWorkBearingSyncResult(result))
+        return false;
+    if (!isNonAutomatedHumanCliProcess({
+        env: process.env,
+        machineIdentity: isMachineIdentity(),
+    }))
+        return false;
+    const identity = currentPersonIdentity();
+    if (!identity)
+        return false;
+    const alreadyCompleted = firstSyncStepMarkerExists("completed", identity);
+    if (alreadyCompleted || !claimFirstSyncStepMarker("completed", identity))
+        return false;
+    // Persist completion even while the rollout is off so enabling the flag later
+    // cannot prompt a person who already completed a work-bearing sync. JSON and
+    // other non-interactive human syncs count too; only the message is TTY-gated.
+    if (!isCurrentSessionEligible())
+        return false;
+    if (!shouldConfirmFirstWorkBearingSync({
+        flagEnabled: isFirstSyncNextStepEnabled(),
+        interactive: true,
+        alreadyCompleted: false,
+        workBearing: true,
+    }))
+        return false;
+    console.log(FIRST_SYNC_CONFIRMATION_COPY);
+    if (firstSyncStepMarkerExists("shown", identity))
+        queueOutcome("followed");
+    return true;
+}
+/** Drain outcomes once so each shown/followed event is sent at most once per run. */
+export function takeFirstSyncStepOutcomes() {
+    return pendingOutcomes.splice(0, pendingOutcomes.length);
+}
+//# sourceMappingURL=first-sync-next-step.js.map

package/dist/lib/lanes/hire-grant-dispatch.d.ts

@@ -16,9 +16,10 @@ export interface OutpostHireGrantContext {
     expected_senior: SeniorRef;
     hierarchy: HireGrantLaneSnapshot[];
     superseded_message_caller_id?: string;
+    superseded_message_session_id?: string;
 }
 /** Encode only the owner-relevant hierarchy from the primary's complete store. */
-export declare function createOutpostHireGrantContext(target: LaneRecord, lanes: readonly LaneRecord[], supersededMessageCallerId?: string): string;
+export declare function createOutpostHireGrantContext(target: LaneRecord, lanes: readonly LaneRecord[], supersededMessageCallerId?: string, supersededMessageSessionId?: string): string;
 /** Decode and validate an owner grant context, binding it to the target lane. */
 export declare function parseOutpostHireGrantContext(encoded: string, targetLaneId: string): OutpostHireGrantContext;
 export declare function sameHireGrantSenior(a: SeniorRef, b: SeniorRef): boolean;

package/dist/lib/lanes/hire-grant-dispatch.js

@@ -30,11 +30,18 @@ function snapshot(lane) {
     };
 }
 /** Encode only the owner-relevant hierarchy from the primary's complete store. */
-export function createOutpostHireGrantContext(target, lanes, supersededMessageCallerId) {
+export function createOutpostHireGrantContext(target, lanes, supersededMessageCallerId, supersededMessageSessionId) {
     const current = lanes.find((lane) => lane.lane_id === target.lane_id);
     if (!current || !sameSenior(current.senior, target.senior)) {
         throw new LanesError("hire_grant_hierarchy_unavailable", `Cannot build an authoritative hire-grant hierarchy for lane ${target.lane_id}`, { lane_id: target.lane_id });
     }
+    if (supersededMessageCallerId !== undefined && supersededMessageSessionId !== undefined) {
+        throw contextError("Outpost grant context cannot contain both lane and session message callers");
+    }
+    if (supersededMessageSessionId !== undefined &&
+        (current.senior.kind !== "session" || current.senior.id !== supersededMessageSessionId)) {
+        throw new LanesError("hire_grant_message_caller_invalid", `Cannot include an unverified session message caller in lane ${target.lane_id}'s Outpost context`, { lane_id: target.lane_id });
+    }
     const relevant = new Map();
     relevant.set(current.lane_id, current);
     if (current.senior.kind === "lane") {
@@ -65,6 +72,18 @@ export function createOutpostHireGrantContext(target, lanes, supersededMessageCa
             }
         }
     }
+    if (current.senior.kind === "session") {
+        const companyUid = current.company?.uid;
+        const projectId = current.project_id;
+        if (companyUid) {
+            for (const candidate of lanes) {
+                if (candidate.company?.uid === companyUid && ((current.worker_profile !== undefined && candidate.worker_profile === current.worker_profile) ||
+                    (projectId !== undefined && candidate.project_id === projectId && (candidate.hire_grant ?? 0) > 0))) {
+                    relevant.set(candidate.lane_id, candidate);
+                }
+            }
+        }
+    }
     const hierarchy = [...relevant.values()]
         .map(snapshot)
         .sort((a, b) => a.lane_id.localeCompare(b.lane_id));
@@ -79,6 +98,9 @@ export function createOutpostHireGrantContext(target, lanes, supersededMessageCa
         ...(supersededMessageCallerId === undefined
             ? {}
             : { superseded_message_caller_id: supersededMessageCallerId }),
+        ...(supersededMessageSessionId === undefined
+            ? {}
+            : { superseded_message_session_id: supersededMessageSessionId }),
     };
     const encoded = Buffer.from(JSON.stringify(context), "utf8").toString("base64url");
     if (Buffer.byteLength(encoded, "utf8") > MAX_CONTEXT_BYTES) {
@@ -183,7 +205,7 @@ export function parseOutpostHireGrantContext(encoded, targetLaneId) {
         throw contextError("Outpost grant context must be an object");
     }
     const record = raw;
-    if (Object.keys(record).some((key) => !["schema_version", "enforcement_enabled", "expected_senior", "hierarchy", "superseded_message_caller_id"].includes(key))) {
+    if (Object.keys(record).some((key) => !["schema_version", "enforcement_enabled", "expected_senior", "hierarchy", "superseded_message_caller_id", "superseded_message_session_id"].includes(key))) {
         throw contextError("Outpost grant context contains unknown fields");
     }
     if (record.schema_version !== HIRE_GRANT_CONTEXT_SCHEMA ||
@@ -194,10 +216,18 @@ export function parseOutpostHireGrantContext(encoded, targetLaneId) {
     }
     const expectedSenior = parseSenior(record.expected_senior);
     const messageCallerId = record.superseded_message_caller_id;
+    const messageSessionId = record.superseded_message_session_id;
     if (messageCallerId !== undefined &&
         (typeof messageCallerId !== "string" || !messageCallerId.trim() || messageCallerId.trim() !== messageCallerId)) {
         throw contextError("Outpost grant context contains an invalid superseded-message caller");
     }
+    if (messageSessionId !== undefined &&
+        (typeof messageSessionId !== "string" || !messageSessionId.trim() || messageSessionId.trim() !== messageSessionId)) {
+        throw contextError("Outpost grant context contains an invalid superseded-message session");
+    }
+    if (messageCallerId !== undefined && messageSessionId !== undefined) {
+        throw contextError("Outpost grant context cannot contain both lane and session message callers");
+    }
     const hierarchy = record.hierarchy.map(parseLaneSnapshot);
     if (!expectedSenior || hierarchy.some((lane) => lane === null)) {
         throw contextError("Outpost grant context contains an invalid senior or lane snapshot");
@@ -211,6 +241,10 @@ export function parseOutpostHireGrantContext(encoded, targetLaneId) {
     if (!target || !sameSenior(target.senior, expectedSenior)) {
         throw contextError("Outpost grant context does not match the target's expected senior");
     }
+    if (messageSessionId !== undefined &&
+        (expectedSenior.kind !== "session" || expectedSenior.id !== messageSessionId)) {
+        throw contextError("Outpost grant context session caller does not match the target's session senior");
+    }
     if (expectedSenior.kind === "lane" &&
         (!expectedSenior.id || !byId.has(expectedSenior.id))) {
         throw contextError("Outpost grant context is missing the target's senior lane");
@@ -232,6 +266,7 @@ export function parseOutpostHireGrantContext(encoded, targetLaneId) {
         expected_senior: expectedSenior,
         hierarchy: snapshots,
         ...(messageCallerId === undefined ? {} : { superseded_message_caller_id: messageCallerId }),
+        ...(messageSessionId === undefined ? {} : { superseded_message_session_id: messageSessionId }),
     };
 }
 export function sameHireGrantSenior(a, b) {

package/dist/lib/lanes/keep-alive.js

@@ -234,8 +234,8 @@ export function keepAliveSupersededBy(lane, lanes, lineageAware = LANE_SUPERSESS
         // Any descendant is part of this lead's work tree, not a replacement lead.
         if (laneAncestorsFrom(candidate.senior, lanesById, sessionOwners).has(lane.lane_id))
             return false;
-        const sameLaneSenior = lane.senior.kind === "lane" &&
-            candidate.senior.kind === "lane" &&
+        const sameLaneSenior = (lane.senior.kind === "lane" || lane.senior.kind === "session") &&
+            candidate.senior.kind === lane.senior.kind &&
             candidate.senior.id === lane.senior.id;
         const sameProfile = lane.worker_profile !== undefined &&
             candidate.worker_profile === lane.worker_profile &&

package/dist/main.js

@@ -43,7 +43,7 @@ import { enforceVersionGate, shouldSkipGate, } from "./utils/version-gate.js";
 import { autoUpdateAndReexec } from "./utils/self-update.js";
 import { CLI_VERSION } from "./cli-version.js";
 import { findLazyCommand, registerCommandCatalog } from "./lazy-commands.js";
-import { emitCliSessionStarted } from "./utils/cli-telemetry.js";
+import { emitCliFirstSyncNextStepOutcome, emitCliSessionStarted, takeFirstSyncStepOutcomes, maybeShowFirstSyncNextStep, } from "./utils/cli-telemetry.js";
 import { reportCliClientHealthInvocation } from "./utils/client-health.js";
 import { settleWithin } from "./utils/settle-with-timeout.js";
 import { emitPlanLimitNag } from "./lib/plan-limit-nag.js";
@@ -275,6 +275,7 @@ export async function runCli() {
             return;
         }
         await program.parseAsync();
+        maybeShowFirstSyncNextStep();
     }
     catch (err) {
         await handleTopLevelError(err);
@@ -292,9 +293,11 @@ export async function runCli() {
             // lifecycle boundary for this invocation. The budget reserves this 500 ms
             // slice even when the command itself was long-running.
             const releaseHealthTimeoutMs = foregroundNetworkBudget.timeoutFor(FINALIZATION_FOREGROUND_WAIT_MS);
+            const firstSyncOutcomeFlushes = takeFirstSyncStepOutcomes().map((outcome) => emitCliFirstSyncNextStepOutcome(outcome, releaseHealthTimeoutMs));
             await settleWithin([
                 refreshVersionCache({ timeoutMs: releaseHealthTimeoutMs }),
                 Sentry.flush(releaseHealthTimeoutMs),
+                ...firstSyncOutcomeFlushes,
             ], releaseHealthTimeoutMs);
         });
         // Last, so it wins over anything the (skipped) command path would have

package/dist/utils/cli-telemetry.d.ts

@@ -1,9 +1,13 @@
+import { type FirstSyncStepOutcome } from "../lib/first-sync-next-step.js";
+export { CLI_FIRST_SYNC_NEXT_STEP_FLAG, FIRST_SYNC_CONFIRMATION_COPY, FIRST_SYNC_NEXT_STEP_COPY, claimFirstSyncStepMarker, firstSyncStepMarkerPaths, firstSyncStepTelemetryProperties, isFirstSyncNextStepEnabled, isHumanInteractiveCliSession, isWorkBearingSyncResult, maybeShowFirstSyncNextStep, recordFirstWorkBearingSync, shouldConfirmFirstWorkBearingSync, shouldShowFirstSyncNextStep, takeFirstSyncStepOutcomes, type FirstSyncStepOutcome, } from "../lib/first-sync-next-step.js";
 export declare const TELEMETRY_TIMEOUT_MS = 1200;
 /**
  * Exact stderr line printed once on the first signed-in TTY run that is not
- * `--json`. Wording matches the event body: CLI version + timestamp only.
+ * `--json`. Keep this notice and its marker stable for the default telemetry
+ * path; first-sync fields have a separate opt-in disclosure below.
  */
 export declare const TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when you run a signed-in command (CLI version and a timestamp, never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.";
+export declare const FIRST_SYNC_TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when you run a signed-in command (CLI version and a timestamp; when enabled, first-sync guidance shown or followed and the flag key cli.first-sync-next-step; never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.";
 /**
  * `HQ_TELEMETRY=0` (also `false` and `off`, case-insensitive) disables every
  * CLI POST to `/v1/telemetry/events`. `HQ_TELEMETRY_TIMEOUT_MS` is unchanged.
@@ -25,4 +29,6 @@ export declare function maybeDiscloseCliTelemetry(stderr?: {
  * This deliberately never refreshes a session or opens a browser.
  */
 export declare function emitCliSessionStarted(timeoutMs?: number): Promise<void>;
+/** Emit one authenticated measurement for a first-sync prompt outcome. */
+export declare function emitCliFirstSyncNextStepOutcome(outcome: FirstSyncStepOutcome, timeoutMs?: number): Promise<void>;
 //# sourceMappingURL=cli-telemetry.d.ts.map

package/dist/utils/cli-telemetry.js

@@ -4,14 +4,19 @@ import * as path from "node:path";
 import { CLI_VERSION } from "../cli-version.js";
 import { isExpiring, isMachineIdentity, loadCachedTokens, } from "./cognito-session.js";
 import { vaultApiFetch } from "./vault-api.js";
+import { firstSyncStepTelemetryProperties, isFirstSyncNextStepEnabled, isHumanInteractiveCliSession, } from "../lib/first-sync-next-step.js";
+export { CLI_FIRST_SYNC_NEXT_STEP_FLAG, FIRST_SYNC_CONFIRMATION_COPY, FIRST_SYNC_NEXT_STEP_COPY, claimFirstSyncStepMarker, firstSyncStepMarkerPaths, firstSyncStepTelemetryProperties, isFirstSyncNextStepEnabled, isHumanInteractiveCliSession, isWorkBearingSyncResult, maybeShowFirstSyncNextStep, recordFirstWorkBearingSync, shouldConfirmFirstWorkBearingSync, shouldShowFirstSyncNextStep, takeFirstSyncStepOutcomes, } from "../lib/first-sync-next-step.js";
 export const TELEMETRY_TIMEOUT_MS = 1_200;
 /**
  * Exact stderr line printed once on the first signed-in TTY run that is not
- * `--json`. Wording matches the event body: CLI version + timestamp only.
+ * `--json`. Keep this notice and its marker stable for the default telemetry
+ * path; first-sync fields have a separate opt-in disclosure below.
  */
 export const TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when you run a signed-in command (CLI version and a timestamp, never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.";
+export const FIRST_SYNC_TELEMETRY_DISCLOSURE_LINE = "HQ sends a usage event when you run a signed-in command (CLI version and a timestamp; when enabled, first-sync guidance shown or followed and the flag key cli.first-sync-next-step; never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.";
 const TELEMETRY_DISABLED_VALUES = new Set(["0", "false", "off"]);
 const DISCLOSURE_MARKER = "cli-telemetry-disclosed";
+const FIRST_SYNC_DISCLOSURE_MARKER = "cli-telemetry-disclosed-first-sync-v1";
 let cliSessionStartedPromise;
 /**
  * `HQ_TELEMETRY=0` (also `false` and `off`, case-insensitive) disables every
@@ -30,27 +35,30 @@ function hqConfigDir() {
 export function telemetryDisclosureMarkerPath() {
     return path.join(hqConfigDir(), DISCLOSURE_MARKER);
 }
+function firstSyncTelemetryDisclosureMarkerPath() {
+    return path.join(hqConfigDir(), FIRST_SYNC_DISCLOSURE_MARKER);
+}
 function wantsJsonOutput(argv = process.argv) {
     return argv.includes("--json");
 }
 function canPrintDisclosure(stdout = process.stdout, argv = process.argv) {
     return Boolean(stdout.isTTY) && !wantsJsonOutput(argv);
 }
-function hasShownDisclosure() {
+function hasShownDisclosure(markerPath) {
     try {
-        return fs.existsSync(telemetryDisclosureMarkerPath());
+        return fs.existsSync(markerPath);
     }
     catch {
         return false;
     }
 }
-function recordDisclosureShown() {
+function recordDisclosureShown(markerPath) {
     try {
         const dir = hqConfigDir();
         // Do not create ~/.hq. Signed-in runs already have it (cached tokens).
         if (!fs.existsSync(dir))
             return;
-        fs.writeFileSync(telemetryDisclosureMarkerPath(), `${new Date().toISOString()}\n`);
+        fs.writeFileSync(markerPath, `${new Date().toISOString()}\n`);
     }
     catch {
         // Marker write is best effort; a repeat print is better than crashing.
@@ -62,17 +70,23 @@ function recordDisclosureShown() {
  * non-TTY stdout skip the print and do not record the marker.
  */
 export function maybeDiscloseCliTelemetry(stderr = process.stderr, stdout = process.stdout, argv = process.argv) {
-    if (hasShownDisclosure())
+    return maybeDiscloseTelemetry(TELEMETRY_DISCLOSURE_LINE, telemetryDisclosureMarkerPath(), stderr, stdout, argv);
+}
+function maybeDiscloseFirstSyncTelemetry() {
+    return maybeDiscloseTelemetry(FIRST_SYNC_TELEMETRY_DISCLOSURE_LINE, firstSyncTelemetryDisclosureMarkerPath());
+}
+function maybeDiscloseTelemetry(line, markerPath, stderr = process.stderr, stdout = process.stdout, argv = process.argv) {
+    if (hasShownDisclosure(markerPath))
         return true;
     if (!canPrintDisclosure(stdout, argv))
         return false;
     try {
-        stderr.write(`${TELEMETRY_DISCLOSURE_LINE}\n`);
+        stderr.write(`${line}\n`);
     }
     catch {
         return false;
     }
-    recordDisclosureShown();
+    recordDisclosureShown(markerPath);
     return true;
 }
 /**
@@ -131,4 +145,66 @@ async function emitCachedCliSessionStarted(timeoutMs) {
         // Cached-token reads are also best effort (for example, a malformed cache).
     }
 }
+/** Emit one authenticated measurement for a first-sync prompt outcome. */
+export async function emitCliFirstSyncNextStepOutcome(outcome, timeoutMs = TELEMETRY_TIMEOUT_MS) {
+    try {
+        if (isCliTelemetryDisabled())
+            return;
+        if (!isFirstSyncNextStepEnabled())
+            return;
+        const cached = loadCachedTokens();
+        const machineIdentity = isMachineIdentity();
+        if (!cached ||
+            isExpiring(cached, 120) ||
+            !isHumanInteractiveCliSession({
+                stdoutIsTTY: Boolean(process.stdout.isTTY),
+                argv: process.argv,
+                env: process.env,
+                machineIdentity,
+            }))
+            return;
+        const token = cached.accessToken;
+        if (!token)
+            return;
+        const consentBasis = maybeDiscloseFirstSyncTelemetry() ? "disclosed" : "no-consent";
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await vaultApiFetch({
+                token,
+                path: "/v1/telemetry/events",
+                method: "POST",
+                body: {
+                    events: [
+                        {
+                            eventName: "cli_session_started",
+                            app: "hq-cli",
+                            source: "cli",
+                            occurredAt: new Date().toISOString(),
+                            consentBasis,
+                            schemaVersion: 1,
+                            properties: {
+                                version: CLI_VERSION,
+                                ...firstSyncStepTelemetryProperties(outcome),
+                            },
+                        },
+                    ],
+                },
+                signal: controller.signal,
+            });
+            if (!response.ok)
+                return;
+        }
+        catch {
+            // Telemetry is best effort and must never affect or follow as an error
+            // after the completed CLI command.
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    catch {
+        // Cached-token reads are also best effort (for example, a malformed cache).
+    }
+}
 //# sourceMappingURL=cli-telemetry.js.map

package/dist/utils/contribution-table.d.ts

@@ -99,5 +99,5 @@ export declare const CONTRIBUTION_KEYS: ContributionKey[];
  */
 export declare function payloadFor(key: ContributionKey, item: string): string;
 /** Keys whose contributions are wired by a host symlink (skip `merge` rows). */
-export declare const SYMLINK_KEYS: ("workers" | "mcp" | "skills" | "knowledge" | "commands" | "hooks" | "policies" | "scripts")[];
+export declare const SYMLINK_KEYS: ("workers" | "mcp" | "commands" | "skills" | "knowledge" | "hooks" | "policies" | "scripts")[];
 //# sourceMappingURL=contribution-table.d.ts.map

package/dist/utils/scaffold-fast-import-guard.d.ts

@@ -0,0 +1,3 @@
+export declare function forbiddenFastPathModules(loadedModules: readonly string[], distDirectory: string): string[];
+export declare function assertFastPathStaysCommandGraphFree(loadedModules: readonly string[], distDirectory: string): void;
+//# sourceMappingURL=scaffold-fast-import-guard.d.ts.map

package/dist/utils/scaffold-fast-import-guard.js

@@ -0,0 +1,28 @@
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+export function forbiddenFastPathModules(loadedModules, distDirectory) {
+    const dist = path.resolve(distDirectory);
+    const main = path.join(dist, "main.js");
+    const commands = `${path.join(dist, "commands")}${path.sep}`;
+    return [...new Set(loadedModules.map((loaded) => {
+            if (loaded.startsWith("file:")) {
+                try {
+                    return fileURLToPath(loaded);
+                }
+                catch {
+                    return loaded;
+                }
+            }
+            return path.resolve(loaded);
+        }))]
+        .filter((loaded) => path.resolve(loaded) === main ||
+        path.resolve(loaded).startsWith(commands))
+        .sort();
+}
+export function assertFastPathStaysCommandGraphFree(loadedModules, distDirectory) {
+    const forbidden = forbiddenFastPathModules(loadedModules, distDirectory);
+    if (forbidden.length > 0) {
+        throw new Error(`fast core loaded forbidden command modules:\n${forbidden.join("\n")}`);
+    }
+}
+//# sourceMappingURL=scaffold-fast-import-guard.js.map

package/dist/utils/scaffold-packlist-guard.d.ts

@@ -0,0 +1,7 @@
+export type ScaffoldPacklistCheck = {
+    missingAssets: string[];
+    forbiddenTestData: string[];
+};
+export declare function checkScaffoldPacklist(listedAssets: readonly string[], packedPaths: ReadonlySet<string>, assetPrefix: string): ScaffoldPacklistCheck;
+export declare function assertScaffoldPacklist(listedAssets: readonly string[], packedPaths: ReadonlySet<string>, assetPrefix: string): void;
+//# sourceMappingURL=scaffold-packlist-guard.d.ts.map

package/dist/utils/scaffold-packlist-guard.js

@@ -0,0 +1,23 @@
+export function checkScaffoldPacklist(listedAssets, packedPaths, assetPrefix) {
+    const prefix = assetPrefix.replace(/\/$/, "");
+    const missingAssets = listedAssets
+        .map((asset) => `${prefix}/${asset}`)
+        .filter((assetPath) => !packedPaths.has(assetPath))
+        .sort();
+    const forbiddenTestData = [...packedPaths]
+        .filter((packedPath) => packedPath === "test/differential" ||
+        packedPath.startsWith("test/differential/") ||
+        packedPath.split("/").some((part) => /corpus/i.test(part)))
+        .sort();
+    return { missingAssets, forbiddenTestData };
+}
+export function assertScaffoldPacklist(listedAssets, packedPaths, assetPrefix) {
+    const check = checkScaffoldPacklist(listedAssets, packedPaths, assetPrefix);
+    const failures = [
+        ...check.missingAssets.map((asset) => `missing listed asset ${asset}`),
+        ...check.forbiddenTestData.map((file) => `test data leaked into packlist: ${file}`),
+    ];
+    if (failures.length > 0)
+        throw new Error(failures.join("\n"));
+}
+//# sourceMappingURL=scaffold-packlist-guard.js.map

package/dist/utils/scaffold-sibling-references.d.ts

@@ -0,0 +1,21 @@
+export type SiblingAssetReference = {
+    referringAsset: string;
+    targetAsset: string;
+};
+export type HqRootAssetReference = {
+    referringAsset: string;
+    reference: string;
+};
+export type ScaffoldReferenceScan = {
+    missing: SiblingAssetReference[];
+    allowedHqRoot: HqRootAssetReference[];
+};
+/**
+ * Scan every asset below assets/scaffold for local file loads. Node source is
+ * identified by extension or shebang; unknown text assets use shell scanning.
+ * `${HQ_ROOT}/...` paths stay rooted in the live HQ tree and are returned as
+ * allowed references for review instead of being mistaken for package assets.
+ */
+export declare function scanScaffoldSiblingReferences(scaffoldRoot: string): ScaffoldReferenceScan;
+export declare function assertNoMissingScaffoldSiblings(scan: ScaffoldReferenceScan): void;
+//# sourceMappingURL=scaffold-sibling-references.d.ts.map