@indigoai-us/hq-cli 5.345.147 → 5.345.149

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

@@ -0,0 +1,275 @@
+/**
+ * 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. The supported install adds that
+ * folder to the user PATH (HKCU only) and broadcasts the change. It never
+ * edits the machine PATH. When the add fails, doctor prints the exact command.
+ *
+ * Windows PowerShell 5.1 and reg.exe print piped output in the console code
+ * page, so a Path holding `C:\Users\José` comes back garbled when read as
+ * UTF-8. Reads therefore return the value as base64 of its UTF-16LE bytes, and
+ * the append is one PowerShell script that reads, checks, and writes the value
+ * without it ever leaving PowerShell.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+/** The longest user Path HQ will write. Longer values break `setx` and some installers. */
+export const MAX_USER_PATH_LENGTH = 2047;
+const REPLACEMENT_CHAR = "\uFFFD";
+/**
+ * Tests on Windows point the scripts at a scratch key with this variable. The
+ * scripts accept only keys under HKCU:\Software\HQTest\ and skip the
+ * broadcast for them.
+ */
+export const USER_PATH_TEST_KEY_ENV = "HQ_USER_PATH_TEST_KEY";
+/** 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;
+    });
+}
+const SELECT_USER_KEY = [
+    "$key = 'HKCU:\\Environment'",
+    `$test = $env:${USER_PATH_TEST_KEY_ENV}`,
+    "if ($test) { if (-not $test.StartsWith('HKCU:\\Software\\HQTest\\', [StringComparison]::OrdinalIgnoreCase)) { exit 2 }; $key = $test }",
+];
+/**
+ * Prints `U:<base64>` for the unexpanded user Path and `M:<base64>` for the
+ * machine Path, base64 of the UTF-16LE bytes, or `U-` / `M-` when a value
+ * cannot be read. Base64 is ASCII, so the console code page cannot change it.
+ */
+export const READ_PATHS_SCRIPT = [
+    "$ErrorActionPreference = 'Stop'",
+    ...SELECT_USER_KEY,
+    "function Emit($tag, $k) { $i = Get-Item -LiteralPath $k -ErrorAction SilentlyContinue; if ($null -eq $i) { return $tag + '-' }; $v = $i.GetValue('Path', $null, 'DoNotExpandEnvironmentNames'); if ($v -isnot [string]) { return $tag + '-' }; return $tag + ':' + [Convert]::ToBase64String([Text.Encoding]::Unicode.GetBytes($v)) }",
+    "Write-Output (Emit 'U' $key)",
+    "Write-Output (Emit 'M' 'HKLM:\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment')",
+].join("\n");
+/** Decode READ_PATHS_SCRIPT output. Null for a value that could not be read. */
+export function parseReadPathsOutput(stdout) {
+    const out = { user: null, machine: null };
+    for (const line of stdout.split(/\r?\n/)) {
+        const match = /^([UM]):([A-Za-z0-9+/=]*)$/.exec(line.trim());
+        if (!match)
+            continue;
+        const value = Buffer.from(match[2], "base64").toString("utf16le");
+        if (match[1] === "U")
+            out.user = value;
+        else
+            out.machine = value;
+    }
+    return out;
+}
+/**
+ * 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) {
+    let values = [];
+    try {
+        const result = run(READ_PATHS_SCRIPT, {});
+        if (result.status === 0) {
+            const read = parseReadPathsOutput(result.stdout);
+            values = [read.user, read.machine].filter((v) => v !== null);
+        }
+    }
+    catch {
+        // PowerShell missing or refused: treat as unreadable.
+    }
+    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);
+}
+/** Runs a script through Windows PowerShell. The script travels as -EncodedCommand (UTF-16LE), so quoting cannot change it. */
+function defaultPowerShell(script, extraEnv) {
+    const encoded = Buffer.from(script, "utf16le").toString("base64");
+    const result = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-EncodedCommand", encoded], {
+        encoding: "utf8",
+        windowsHide: true,
+        timeout: 15_000,
+        env: { ...process.env, ...extraEnv },
+    });
+    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.powerShell ?? defaultPowerShell, 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.`,
+        "HQ could not add it automatically. To add it for your user, run this in PowerShell, then open a new terminal:",
+        `  ${pathFixCommand(check.shimDir)}`,
+    ];
+}
+/**
+ * Decide the new unexpanded user Path. Membership is decided on the expanded
+ * value so `%APPDATA%\npm` counts. The stored text keeps `%VARS%`. A value
+ * that already holds U+FFFD was garbled by an earlier decode and is never
+ * written back. The ensure script applies the same rules inside PowerShell.
+ */
+export function planUserPathAppend(current, dir, env) {
+    if (isDirOnPath(dir, expandWindowsEnv(current, env)))
+        return { action: "skip", reason: "present" };
+    if (current.includes(REPLACEMENT_CHAR) || dir.includes(REPLACEMENT_CHAR) || dir.includes(";")) {
+        return { action: "skip", reason: "unsafe-value" };
+    }
+    const trimmed = current.trim().replace(/;+$/g, "");
+    const value = trimmed ? `${trimmed};${dir}` : dir;
+    if (value.length > MAX_USER_PATH_LENGTH)
+        return { action: "skip", reason: "too-long" };
+    return { action: "write", value };
+}
+/** Exit codes of ENSURE_USER_PATH_SCRIPT. */
+export const ENSURE_EXIT = {
+    written: 0,
+    badInput: 2,
+    unreadable: 3,
+    unsafeValue: 4,
+    tooLong: 5,
+    writtenNoBroadcast: 6,
+    present: 10,
+};
+/**
+ * Appends $env:HQ_SHIM_DIR to the HKCU Path as REG_EXPAND_SZ, then broadcasts
+ * the change. The value is read, checked, and written inside this script, so
+ * no console encoding touches it. Mirrors planUserPathAppend.
+ */
+export const ENSURE_USER_PATH_SCRIPT = [
+    "$ErrorActionPreference = 'Stop'",
+    "$dir = $env:HQ_SHIM_DIR",
+    `if ([string]::IsNullOrWhiteSpace($dir) -or $dir.Contains(';') -or $dir.Contains([string][char]0xFFFD)) { exit ${ENSURE_EXIT.badInput} }`,
+    ...SELECT_USER_KEY,
+    "$item = Get-Item -LiteralPath $key -ErrorAction SilentlyContinue",
+    `if ($null -eq $item) { exit ${ENSURE_EXIT.unreadable} }`,
+    "$p = $item.GetValue('Path', '', 'DoNotExpandEnvironmentNames')",
+    `if ($p -isnot [string]) { exit ${ENSURE_EXIT.unsafeValue} }`,
+    // Same comparison as normalizeDir: unquote, use backslashes, collapse repeated
+    // separators (keeping a UNC prefix), drop trailing ones, ignore case.
+    "function Norm($s) { $t = $s.Trim(); if ($t.Length -ge 2 -and $t.StartsWith([string][char]34) -and $t.EndsWith([string][char]34)) { $t = $t.Substring(1, $t.Length - 2).Trim() }; $t = $t.Replace([char]47, [char]92); $bs = [string][char]92; $lead = ''; if ($t.StartsWith($bs + $bs)) { $lead = $bs + $bs; $t = $t.Substring(2) }; $t = $lead + [regex]::Replace($t, ($bs + $bs + '+'), $bs); return $t.TrimEnd([char]92).ToLowerInvariant() }",
+    "$want = Norm $dir",
+    `foreach ($e in [Environment]::ExpandEnvironmentVariables($p).Split(';')) { if ((Norm $e) -eq $want) { exit ${ENSURE_EXIT.present} } }`,
+    `if ($p.Contains([string][char]0xFFFD)) { exit ${ENSURE_EXIT.unsafeValue} }`,
+    "$t = $p.Trim().TrimEnd(';')",
+    "if ($t) { $new = $t + ';' + $dir } else { $new = $dir }",
+    `if ($new.Length -gt ${MAX_USER_PATH_LENGTH}) { exit ${ENSURE_EXIT.tooLong} }`,
+    "New-ItemProperty -LiteralPath $key -Name Path -PropertyType ExpandString -Force -Value $new | Out-Null",
+    `if (-not $test) { try { [Environment]::SetEnvironmentVariable('${PATH_REFRESH_VAR}','1','User'); [Environment]::SetEnvironmentVariable('${PATH_REFRESH_VAR}',$null,'User') } catch { exit ${ENSURE_EXIT.writtenNoBroadcast} } }`,
+    `exit ${ENSURE_EXIT.written}`,
+].join("\n");
+export function ensureExitReason(status) {
+    switch (status) {
+        case ENSURE_EXIT.written:
+        case ENSURE_EXIT.writtenNoBroadcast:
+            return { written: true, reason: "written" };
+        case ENSURE_EXIT.present:
+            return { written: false, reason: "present" };
+        case ENSURE_EXIT.unreadable:
+            return { written: false, reason: "unreadable" };
+        case ENSURE_EXIT.unsafeValue:
+        case ENSURE_EXIT.badInput:
+            return { written: false, reason: "unsafe-value" };
+        case ENSURE_EXIT.tooLong:
+            return { written: false, reason: "too-long" };
+        default:
+            return { written: false, reason: "write-failed" };
+    }
+}
+export function powershellUserPathStore(run = defaultPowerShell, extraEnv = {}) {
+    return {
+        appendUserPath(dir) {
+            try {
+                return ensureExitReason(run(ENSURE_USER_PATH_SCRIPT, { ...extraEnv, HQ_SHIM_DIR: dir }).status);
+            }
+            catch {
+                return { written: false, reason: "write-failed" };
+            }
+        },
+    };
+}
+let cachedOnPathDir = null;
+export function resetUserPathEnsureCacheForTests() {
+    cachedOnPathDir = null;
+}
+/**
+ * Add the npm shim folder to HKCU Path when it is missing. Null off Windows
+ * or when this process is not an npm global install. A failed read does not
+ * write. Machine Path is never written.
+ */
+export function ensureShimOnUserPath(deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    if (platform !== "win32")
+        return null;
+    const cacheable = deps.store === undefined && deps.powerShell === undefined && deps.platform === undefined;
+    if (cacheable && cachedOnPathDir) {
+        return { shimDir: cachedOnPathDir, written: false, onPath: true, source: "registry", reason: "present" };
+    }
+    const check = checkShimOnPath(deps);
+    if (!check)
+        return null;
+    if (check.onPath) {
+        if (cacheable)
+            cachedOnPathDir = check.shimDir;
+        return { shimDir: check.shimDir, written: false, onPath: true, source: check.source, reason: "present" };
+    }
+    const store = deps.store ?? powershellUserPathStore(deps.powerShell);
+    const applied = store.appendUserPath(check.shimDir);
+    const onPath = applied.written || applied.reason === "present";
+    if (onPath && cacheable)
+        cachedOnPathDir = check.shimDir;
+    return { shimDir: check.shimDir, written: applied.written, onPath, source: check.source, reason: applied.reason };
+}
+//# 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