@indigoai-us/hq-cli 5.345.146 → 5.345.148

package/dist/lib/windows/user-path.d.ts

@@ -0,0 +1,48 @@
+export type RegRun = (cmd: string, args: string[]) => {
+    status: number | null;
+    stdout: string;
+};
+export interface ShimPathCheck {
+    /** The folder holding `hq.cmd`. */
+    shimDir: string;
+    onPath: boolean;
+    /** Where the PATH came from: the persisted registry values, or this process's PATH when those could not be read. */
+    source: "registry" | "process";
+}
+export interface ShimPathDeps {
+    platform?: NodeJS.Platform;
+    /** The running CLI entry script (process.argv[1]). */
+    entry?: string;
+    exists?: (p: string) => boolean;
+    run?: RegRun;
+    env?: NodeJS.ProcessEnv;
+}
+/** The npm prefix folder above the package's `node_modules`, when `hq.cmd` is there. */
+export declare function npmShimDir(entry: string | undefined, exists: (p: string) => boolean): string | null;
+/** Expand `%NAME%` references the way Windows does, matching names case-insensitively. */
+export declare function expandWindowsEnv(value: string, env: NodeJS.ProcessEnv): string;
+/**
+ * The PATH a new terminal will get: the user Path then the machine Path, as
+ * stored in the registry. Falls back to this process's PATH when neither can
+ * be read.
+ */
+export declare function readPersistedPath(run: RegRun, env: NodeJS.ProcessEnv): {
+    value: string;
+    source: "registry" | "process";
+};
+export declare function isDirOnPath(dir: string, pathValue: string): boolean;
+/** Null when not on Windows or when hq was not installed as an npm global shim. */
+export declare function checkShimOnPath(deps?: ShimPathDeps): ShimPathCheck | null;
+/** Dummy user variable set and cleared so Windows tells running programs that the environment changed. */
+export declare const PATH_REFRESH_VAR = "HQ_PATH_REFRESH";
+/**
+ * A PowerShell command that appends `dir` to the user Path, keeping the value
+ * as REG_EXPAND_SZ so existing `%VAR%` entries still expand. Writing the
+ * registry alone does not notify Explorer, so terminals it opens would keep the
+ * old PATH until the next sign-in. Setting and clearing a dummy user variable
+ * through [Environment]::SetEnvironmentVariable broadcasts WM_SETTINGCHANGE.
+ */
+export declare function pathFixCommand(dir: string): string;
+/** Lines to print when the shim folder is missing from PATH; empty when it is present. */
+export declare function shimPathWarning(check: ShimPathCheck): string[];
+//# sourceMappingURL=user-path.d.ts.map

package/dist/lib/windows/user-path.js

@@ -0,0 +1,114 @@
+/**
+ * Is the npm global shim folder (where `hq.cmd` lives) on the Windows PATH?
+ *
+ * npm writes `hq.cmd` directly under its prefix (never `<prefix>\bin`). When
+ * that folder is not on the user or machine Path, a new terminal cannot find
+ * `hq` even though the install succeeded. HQ detects this and prints the exact
+ * fix; it never edits PATH itself.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+const USER_ENV_KEY = "HKCU\\Environment";
+const MACHINE_ENV_KEY = "HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment";
+/** The npm prefix folder above the package's `node_modules`, when `hq.cmd` is there. */
+export function npmShimDir(entry, exists) {
+    if (!entry)
+        return null;
+    const parts = path.win32.normalize(entry).split("\\");
+    const nm = parts.map((p) => p.toLowerCase()).lastIndexOf("node_modules");
+    if (nm <= 0)
+        return null;
+    const dir = parts.slice(0, nm).join("\\");
+    return exists(path.win32.join(dir, "hq.cmd")) ? dir : null;
+}
+/** Expand `%NAME%` references the way Windows does, matching names case-insensitively. */
+export function expandWindowsEnv(value, env) {
+    return value.replace(/%([^%;]+)%/g, (whole, name) => {
+        const key = Object.keys(env).find((k) => k.toLowerCase() === name.toLowerCase());
+        const found = key === undefined ? undefined : env[key];
+        return found === undefined ? whole : found;
+    });
+}
+function regPath(run, key) {
+    try {
+        const result = run("reg.exe", ["query", key, "/v", "Path"]);
+        if (result.status !== 0)
+            return null;
+        for (const line of result.stdout.split(/\r?\n/)) {
+            // An empty value prints no text after the type, which is an empty Path,
+            // not an unreadable one.
+            const match = /^\s+Path\s+REG_(?:EXPAND_)?SZ(?:\s+(.*))?$/i.exec(line);
+            if (match)
+                return (match[1] ?? "").trim();
+        }
+    }
+    catch {
+        // reg.exe missing or refused: treat as unreadable.
+    }
+    return null;
+}
+/**
+ * The PATH a new terminal will get: the user Path then the machine Path, as
+ * stored in the registry. Falls back to this process's PATH when neither can
+ * be read.
+ */
+export function readPersistedPath(run, env) {
+    const values = [regPath(run, USER_ENV_KEY), regPath(run, MACHINE_ENV_KEY)].filter((v) => v !== null);
+    if (values.length === 0)
+        return { value: env.PATH ?? env.Path ?? "", source: "process" };
+    return { value: values.map((v) => expandWindowsEnv(v, env)).join(";"), source: "registry" };
+}
+function normalizeDir(dir) {
+    const unquoted = dir.trim().replace(/^"(.*)"$/, "$1").trim();
+    if (!unquoted)
+        return "";
+    return path.win32.normalize(unquoted).replace(/[\\/]+$/, "").toLowerCase();
+}
+export function isDirOnPath(dir, pathValue) {
+    const want = normalizeDir(dir);
+    return pathValue.split(";").some((entry) => normalizeDir(entry) === want);
+}
+function defaultRun(cmd, args) {
+    const result = spawnSync(cmd, args, { encoding: "utf8", windowsHide: true, timeout: 5000 });
+    return { status: result.status, stdout: result.stdout ?? "" };
+}
+/** Null when not on Windows or when hq was not installed as an npm global shim. */
+export function checkShimOnPath(deps = {}) {
+    if ((deps.platform ?? process.platform) !== "win32")
+        return null;
+    const shimDir = npmShimDir(deps.entry ?? process.argv[1], deps.exists ?? fs.existsSync);
+    if (!shimDir)
+        return null;
+    const persisted = readPersistedPath(deps.run ?? defaultRun, deps.env ?? process.env);
+    return { shimDir, onPath: isDirOnPath(shimDir, persisted.value), source: persisted.source };
+}
+/** Dummy user variable set and cleared so Windows tells running programs that the environment changed. */
+export const PATH_REFRESH_VAR = "HQ_PATH_REFRESH";
+/**
+ * A PowerShell command that appends `dir` to the user Path, keeping the value
+ * as REG_EXPAND_SZ so existing `%VAR%` entries still expand. Writing the
+ * registry alone does not notify Explorer, so terminals it opens would keep the
+ * old PATH until the next sign-in. Setting and clearing a dummy user variable
+ * through [Environment]::SetEnvironmentVariable broadcasts WM_SETTINGCHANGE.
+ */
+export function pathFixCommand(dir) {
+    const quoted = dir.replace(/'/g, "''");
+    return ("$p = (Get-Item HKCU:\\Environment).GetValue('Path','','DoNotExpandEnvironmentNames'); " +
+        "New-ItemProperty -Path HKCU:\\Environment -Name Path -PropertyType ExpandString -Force " +
+        `-Value (($p.TrimEnd(';') + ';${quoted}').TrimStart(';')); ` +
+        `[Environment]::SetEnvironmentVariable('${PATH_REFRESH_VAR}','1','User'); ` +
+        `[Environment]::SetEnvironmentVariable('${PATH_REFRESH_VAR}',$null,'User')`);
+}
+/** Lines to print when the shim folder is missing from PATH; empty when it is present. */
+export function shimPathWarning(check) {
+    if (check.onPath)
+        return [];
+    return [
+        `The folder that holds the hq command (${check.shimDir}) is not on your Windows PATH, so a new terminal will not find hq.`,
+        "To add it for your user, run this in PowerShell, then open a new terminal:",
+        `  ${pathFixCommand(check.shimDir)}`,
+        "HQ does not change PATH for you.",
+    ];
+}
+//# sourceMappingURL=user-path.js.map

package/dist/lib/work-context/auto-bind.d.ts

@@ -32,7 +32,7 @@ export type AutoBindDecision = {
     candidates: AutoBindCandidate[];
 } | {
     action: "skip";
-    reason: "no_git" | "no_company" | "no_match" | "ambiguous";
+    reason: "no_git" | "no_company" | "no_match" | "ambiguous" | "foreign_lane";
     candidates: AutoBindCandidate[];
 };
 /** Find the git checkout for cwd and its current branch without spawning git. */

package/dist/lib/work-context/auto-bind.js

@@ -10,6 +10,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { foreignSessionOwnsLane } from "./lane-bind.js";
 function readText(file) {
     try {
         return fs.readFileSync(file, "utf8");
@@ -223,17 +224,35 @@ export function decideAutoBind(input) {
         identities,
         branch: git.branch,
     });
-    if (prior)
+    const ownedByOtherSession = (projectId) => foreignSessionOwnsLane({
+        hqRoot: input.hqRoot,
+        projectId,
+        sessionId: state.sessionId,
+        companySlug,
+    });
+    if (prior) {
+        if (ownedByOtherSession(prior)) {
+            return { action: "skip", reason: "foreign_lane", candidates, ...extra };
+        }
         return { action: "bind", projectId: prior, source: "history", candidates, ...extra };
+    }
     const branchMatches = candidates.filter((c) => c.matchedBranch);
     if (branchMatches.length === 1) {
-        return { action: "bind", projectId: branchMatches[0].projectId, source: "repo_branch", candidates, ...extra };
+        const projectId = branchMatches[0].projectId;
+        if (ownedByOtherSession(projectId)) {
+            return { action: "skip", reason: "foreign_lane", candidates, ...extra };
+        }
+        return { action: "bind", projectId, source: "repo_branch", candidates, ...extra };
     }
     if (branchMatches.length > 1) {
         return { action: "skip", reason: "ambiguous", candidates: branchMatches, ...extra };
     }
     if (candidates.length === 1) {
-        return { action: "bind", projectId: candidates[0].projectId, source: "repo_only", candidates, ...extra };
+        const projectId = candidates[0].projectId;
+        if (ownedByOtherSession(projectId)) {
+            return { action: "skip", reason: "foreign_lane", candidates, ...extra };
+        }
+        return { action: "bind", projectId, source: "repo_only", candidates, ...extra };
     }
     return {
         action: "skip",

package/dist/lib/work-context/lane-bind.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Lane ownership for automatic project attachment.
+ *
+ * A session may attach to a project when it is the senior, the provider
+ * session, or the creator of an active lane for that project. It must not
+ * attach just because a lane exists, the cwd matches, or a binding is recent.
+ * Terminal lanes do not count. A missing lane directory does not block.
+ */
+export interface ForeignLaneInput {
+    hqRoot?: string;
+    projectId?: string;
+    sessionId?: string;
+    /**
+     * Company the bind is for. A lane matches only when its company slug
+     * matches too. Missing company, or a lane with no company, does not match.
+     */
+    companySlug?: string;
+    /**
+     * Lane records already read during this reconcile, keyed by lane directory.
+     * Pass the same map to every check in one reconcile so the lane files are
+     * read once.
+     */
+    laneCache?: LaneRecordCache;
+}
+export type LaneRecordCache = Map<string, Record<string, unknown>[] | null>;
+/**
+ * True when an active lane for this company and project is owned by a
+ * different session and this session does not own or create one.
+ */
+export declare function foreignSessionOwnsLane(input: ForeignLaneInput): boolean;
+//# sourceMappingURL=lane-bind.d.ts.map

package/dist/lib/work-context/lane-bind.js

@@ -0,0 +1,101 @@
+/**
+ * Lane ownership for automatic project attachment.
+ *
+ * A session may attach to a project when it is the senior, the provider
+ * session, or the creator of an active lane for that project. It must not
+ * attach just because a lane exists, the cwd matches, or a binding is recent.
+ * Terminal lanes do not count. A missing lane directory does not block.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { TERMINAL_LANE_STATES } from "../lanes/types.js";
+const TERMINAL = new Set(TERMINAL_LANE_STATES);
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function sessionOwnsLane(lane, sessionId) {
+    const senior = asRecord(lane.senior);
+    if (senior?.kind === "session" && senior.id === sessionId)
+        return true;
+    if (lane.provider_session_id === sessionId)
+        return true;
+    if (lane.created_by_session === sessionId)
+        return true;
+    if (lane.created_by === sessionId)
+        return true;
+    return false;
+}
+function foreignSessionSenior(lane, sessionId) {
+    const senior = asRecord(lane.senior);
+    return senior?.kind === "session"
+        && typeof senior.id === "string"
+        && senior.id.length > 0
+        && senior.id !== sessionId;
+}
+/** Personal lanes and lanes with no company do not match a company-scoped bind. */
+function laneCompanyMatches(lane, companySlug) {
+    const company = asRecord(lane.company);
+    const slug = company && typeof company.slug === "string" ? company.slug.trim() : "";
+    if (!slug)
+        return false;
+    return slug.toLowerCase() === companySlug.toLowerCase();
+}
+/**
+ * True when an active lane for this company and project is owned by a
+ * different session and this session does not own or create one.
+ */
+export function foreignSessionOwnsLane(input) {
+    const hqRoot = input.hqRoot?.trim();
+    const projectId = input.projectId?.trim();
+    const sessionId = input.sessionId?.trim();
+    const companySlug = input.companySlug?.trim();
+    if (!hqRoot || !projectId || !sessionId || !companySlug)
+        return false;
+    const dir = path.join(hqRoot, "workspace", "lanes", "lanes");
+    const lanes = readLaneRecords(dir, input.laneCache);
+    if (!lanes)
+        return false;
+    let foreign = false;
+    let mine = false;
+    for (const parsed of lanes) {
+        if (parsed.project_id !== projectId)
+            continue;
+        if (!laneCompanyMatches(parsed, companySlug))
+            continue;
+        if (typeof parsed.state === "string" && TERMINAL.has(parsed.state))
+            continue;
+        if (sessionOwnsLane(parsed, sessionId))
+            mine = true;
+        else if (foreignSessionSenior(parsed, sessionId))
+            foreign = true;
+    }
+    return foreign && !mine;
+}
+function readLaneRecords(dir, cache) {
+    if (cache?.has(dir))
+        return cache.get(dir) ?? null;
+    let records;
+    try {
+        records = [];
+        for (const name of fs.readdirSync(dir)) {
+            if (!name.endsWith(".json"))
+                continue;
+            try {
+                const parsed = asRecord(JSON.parse(fs.readFileSync(path.join(dir, name), "utf8")));
+                if (parsed)
+                    records.push(parsed);
+            }
+            catch {
+                // An unreadable lane file does not block.
+            }
+        }
+    }
+    catch {
+        records = null;
+    }
+    cache?.set(dir, records);
+    return records;
+}
+//# sourceMappingURL=lane-bind.js.map

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

@@ -451,6 +451,7 @@ export async function submitOrganizeDecision(input) {
             projectId: receipt.projectId,
             ...(receipt.taskId ? { taskId: receipt.taskId } : {}),
             bindingEpisodeId: receipt.bindingEpisodeId,
+            projectBindAuthority: "trusted",
             updatedAt: now,
             // Clear ask — decision resolved.
             decision: undefined,

package/dist/lib/work-context/prd-sync.js

@@ -56,6 +56,9 @@ export function rebindSessionToProject(input) {
             return null;
         if (current.projectId === input.projectId)
             return current;
+        // An explicit trusted bind stays until the session rebinds explicitly.
+        if (current.projectBindAuthority === "trusted")
+            return current;
         return {
             ...current,
             projectId: input.projectId,
@@ -64,6 +67,7 @@ export function rebindSessionToProject(input) {
                 ? "needs_task"
                 : current.contextStatus,
             projectBindReason: `prd-sync project switch to ${input.projectId}`,
+            projectBindAuthority: undefined,
             updatedAt: nowIso,
         };
     });
@@ -117,6 +121,9 @@ export function planPrdSync(input) {
         return empty("different_project");
     }
     const targetProjectId = identity.projectId;
+    if (state.projectBindAuthority === "trusted" && state.projectId !== targetProjectId) {
+        return empty("different_project");
+    }
     const rebindTo = state.projectId !== targetProjectId ? targetProjectId : undefined;
     let stories;
     try {

package/dist/lib/work-context/project.d.ts

@@ -2,13 +2,21 @@
  * Project/task resolution for work-context (US-007B).
  *
  * Order:
- *   1. existing active binding (state bound / needs_task with projectId)
- *   2. trusted explicit (HQ_SPAWN_PROJECT/HQ_SPAWN_TASK, observation, meta.yaml)
- *   3. exactly one deterministic mapping (cwd under companies/{slug}/projects/{project}/
- *      or a registry resource that names exactly one project for the repo)
+ *   1. explicit trusted bind (observation authority "trusted"; shell alias
+ *      `project` / `task`). Beats an existing automatic binding and is not
+ *      refused because another session owns a lane. Refused when the project
+ *      directory is not under the resolved company.
+ *   2. existing active binding (state bound / needs_task with projectId).
+ *      Ambient HQ_SPAWN_PROJECT and meta.yaml do not override it.
+ *   3. trusted explicit (HQ_SPAWN_PROJECT/HQ_SPAWN_TASK, observation projectId,
+ *      meta.yaml). Meta and the bare `project` alias are refused when another
+ *      session owns an active lane for that project. Spawn is not.
+ *   4. exactly one deterministic mapping (cwd or registry), refused when
+ *      another session owns an active lane for that project.
  * Soft evidence never auto-binds — candidates are server-owned (GET .../candidates).
  */
 import { type TrustedExplicitContext } from "./contract.js";
+import { type LaneRecordCache } from "./lane-bind.js";
 import type { SessionStateFile } from "./state.js";
 export type ProjectResolutionSource = "existing_binding" | "trusted_explicit" | "deterministic_cwd" | "deterministic_registry";
 export interface ResolvedProjectTask {
@@ -17,16 +25,25 @@ export interface ResolvedProjectTask {
     source: ProjectResolutionSource;
     /** True when project+task are both present (trusted or existing bound). */
     complete: boolean;
+    /**
+     * Set when the operator or trusted-bind command explicitly chose this
+     * project. Later automatic sources must not replace it.
+     */
+    authority?: "trusted";
 }
+type TrustedProjectInput = TrustedExplicitContext & {
+    companySlug?: string;
+    /** Shell and native trusted bind write `project`, not `projectId`. */
+    project?: string;
+    /** Shell and native trusted bind write `task`, not `taskId`. */
+    task?: string;
+    /** "trusted" is an explicit bind and beats an existing automatic binding. */
+    authority?: string;
+};
 export interface ProjectResolveInput {
     sessionId: string;
     env?: NodeJS.ProcessEnv;
-    trusted?: TrustedExplicitContext & {
-        companySlug?: string;
-        projectId?: string;
-        taskId?: string;
-        storyId?: string;
-    };
+    trusted?: TrustedProjectInput;
     cwd?: string;
     hqRoot?: string;
     existingState?: SessionStateFile | null;
@@ -35,6 +52,14 @@ export interface ProjectResolveInput {
     metaTaskId?: string | null;
     /** Injectable registry project id (tests). */
     registryProjectId?: string | null;
+    /**
+     * Company reconcile already resolved. A trusted project is pinned only when
+     * that company's project directory exists. Missing company or root refuses
+     * the pin.
+     */
+    resolvedCompanySlug?: string;
+    /** Lane records shared across the lane checks of one reconcile. */
+    laneCache?: LaneRecordCache;
 }
 /**
  * Read project / task from workspace/sessions/<sid>/meta.yaml (best-effort).
@@ -75,4 +100,5 @@ export declare function shouldAskAfter(input: {
     hasTurn?: boolean;
     now?: Date;
 }): boolean;
+export {};
 //# sourceMappingURL=project.d.ts.map