@indigoai-us/hq-cli 5.314.0 → 5.316.0

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

@@ -4,7 +4,7 @@
  */
 import type { ClassificationState } from "./contract.js";
 import { WORK_CONTEXT_CONTRACT_VERSION } from "./contract.js";
-export type DecisionOptionKind = "bind_existing" | "create_project" | "create_task" | "untracked" | "keep_default" | "override_evidence";
+type DecisionOptionKind = "bind_existing" | "create_project" | "create_task" | "untracked" | "keep_default" | "override_evidence";
 export interface SessionDecisionOption {
     optionId: string;
     label?: string;
@@ -27,9 +27,9 @@ export interface SessionDecision {
 /** Local-only origin of the session state writer (never sent on the wire). */
 export type SessionEventSource = "hook" | "transcript";
 /** Local-only harness label when network schema cannot carry it (US-018). */
-export type LocalHarnessLabel = "claude-desktop" | "codex";
+type LocalHarnessLabel = "claude-desktop" | "codex";
 /** Local tracking for an in-flight or completed cross-company migrate (US-017B). */
-export interface SessionMigrationRecord {
+interface SessionMigrationRecord {
     operationId: string;
     digest: string;
     sourceCompanyUid: string;
@@ -89,19 +89,93 @@ export interface SessionStateFile {
      * before SESSION_STATE sync (kept after AMEND-001).
      */
     transcriptMarker?: "from transcript";
+    /** Historical repair under device-default evidence is intentionally weak. */
+    companyConfidence?: "device_default";
+    /** Why the current project was chosen, or why the session is asking. */
+    projectBindReason?: string;
+    /** Ranked alternatives when the session is waiting for a project choice. */
+    projectCandidates?: Array<{
+        projectId: string;
+        title?: string;
+        score?: number;
+    }>;
+    /**
+     * When set, flush holds events instead of posting them.
+     * `choose` — the match was unclear. `missing_board` — the server 404'd the project.
+     */
+    projectGate?: "choose" | "missing_board";
+    /** Slug the session was trying to bind. Re-checked on the next prompt. */
+    projectHint?: string;
+    /**
+     * LOCAL-ONLY. Pending session_end against a company this session just left
+     * (US-047). Flush posts it to that companyUid, then clears the field.
+     */
+    presenceLeave?: {
+        companyUid: string;
+        companySlug?: string;
+        projectId?: string;
+        taskId?: string;
+        bindingEpisodeId?: string;
+    };
     updatedAt: string;
 }
-/** Allowlisted keys that may appear in the durable state projection. */
-export declare const SESSION_STATE_ALLOWLIST: Set<string>;
+/**
+ * Metadata from a register operation that the control plane has acknowledged.
+ * Kept structural here so the state projection does not need a runtime
+ * dependency on the outbox implementation.
+ */
+export interface AcknowledgedRegisterBinding {
+    kind: "register";
+    sessionId: string;
+    companyUid?: string;
+    companySlug?: string;
+    projectId?: string;
+    taskId?: string;
+    receiptId: string;
+}
 export declare function readSessionState(sessionId: string, root: string): SessionStateFile | null;
 export declare function writeSessionState(state: SessionStateFile, root: string): string;
-/** Strip any non-allowlisted fields before durable write. */
-export declare function projectSessionState(state: SessionStateFile): SessionStateFile;
 /**
- * Merge prior local-only counters into a new state write so PostToolUse bumps
- * and reconcile updates do not clobber each other.
+ * Commit a state change only after inspecting the latest value under the same
+ * lock used by ordinary session writers. Returning null declines the write.
+ */
+export declare function updateSessionState(sessionId: string, root: string, update: (current: SessionStateFile | null) => SessionStateFile | null): SessionStateFile | null;
+/**
+ * Merge prior local fields into a new state write so PostToolUse bumps and
+ * reconcile updates do not clobber an acknowledged company binding.
+ */
+export declare function mergeLocalSessionFields(next: SessionStateFile, prior: SessionStateFile | null, options?: {
+    preserveBindingEpisode?: boolean;
+    preserveCompanyBinding?: boolean;
+}): SessionStateFile;
+/**
+ * True when a stored bindingEpisodeId is a register receipt, not an episode.
+ *
+ * The server mints binding episodes as UUIDs, and only on bind / organize. A
+ * register response carries no episode: its receipt is the operation id the
+ * client generated (`op_...`). An id is treated as a receipt when it has that
+ * shape or when it equals a receipt the caller knows about. A UUID is never
+ * treated as a receipt by shape.
  */
-export declare function mergeLocalSessionFields(next: SessionStateFile, prior: SessionStateFile | null): SessionStateFile;
+export declare function isRegisterReceiptEpisodeId(id: string | undefined, knownReceiptIds?: Iterable<string | undefined>): boolean;
+/**
+ * Clear register receipts stored as a binding episode, on the session itself
+ * and on its pending presenceLeave. Returns the same object when nothing
+ * changed, so callers can detect a repair by identity.
+ */
+export declare function stripRegisterReceiptEpisodes(state: SessionStateFile, knownReceiptIds?: Iterable<string | undefined>): SessionStateFile;
+/**
+ * Upgrade the local projection after the server acknowledges a register.
+ *
+ * A receipt makes the operation's company authoritative, but it must never
+ * erase an explicit untracked choice, a conflicting existing company, or a
+ * more specific binding for the same company. This is also used to repair
+ * state files created by older clients before this write-back existed.
+ *
+ * The read and the write happen under the session state lock, so a concurrent
+ * writer (for example bind-project) is never overwritten from a stale snapshot.
+ */
+export declare function writeAcknowledgedRegisterBinding(binding: AcknowledgedRegisterBinding, root: string, now?: () => Date): SessionStateFile | null;
 /** True when a durable state file was written by the hook / reconcile path. */
 export declare function isHookWrittenSessionState(state: SessionStateFile | null): boolean;
 /** Authoritative prior scope usable for company precedence. */
@@ -109,4 +183,13 @@ export declare function authoritativeCompanyFromState(state: SessionStateFile |
     slug?: string;
     uid?: string;
 } | null;
+/**
+ * Apply `hq mesh context bind-project`: an operator's local project choice.
+ *
+ * The server issues no binding episode for this local choice, so any prior
+ * bindingEpisodeId (older clients stored a register receipt there) is cleared.
+ * Carrying it forward makes the server drop every later session-event batch.
+ */
+export declare function applyOperatorProjectBinding(state: SessionStateFile, projectId: string, now?: () => Date): SessionStateFile;
+export {};
 //# sourceMappingURL=state.d.ts.map

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

@@ -3,32 +3,118 @@
  * Written only by hq mesh context. Owner 0600. Metadata-only — never prompts/tokens.
  */
 import * as fs from "node:fs";
+import * as path from "node:path";
 import { WORK_CONTEXT_CONTRACT_VERSION } from "./contract.js";
-import { atomicWriteJson, ensureOwnerDir } from "./atomic.js";
-import { NotTrackingError } from "./errors.js";
+import { atomicWriteJson, ensureOwnerDir, resolveRealTarget } from "./atomic.js";
+import { NotTrackingError, UnsafeConfigPathError } from "./errors.js";
 import { isSafeWorkContextSegment, workContextSessionPath, workContextSessionsDir, } from "./paths.js";
-/** Allowlisted keys that may appear in the durable state projection. */
-export const SESSION_STATE_ALLOWLIST = new Set([
-    "contractVersion",
-    "sessionId",
-    "companyUid",
-    "companySlug",
-    "contextStatus",
-    "projectId",
-    "taskId",
-    "bindingEpisodeId",
-    "version",
-    "decision",
-    "migration",
-    "untrackedReceipt",
-    "toolWrites",
-    "startedAt",
-    "hasTurn",
-    "source",
-    "localHarness",
-    "transcriptMarker",
-    "updatedAt",
-]);
+const SESSION_STATE_LOCK_TIMEOUT_MS = 5_000;
+const SESSION_STATE_LOCK_RETRY_MS = 10;
+function waitForSessionStateLock(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function asPersistenceFailure(err) {
+    if (err instanceof NotTrackingError || err instanceof UnsafeConfigPathError)
+        throw err;
+    const message = err instanceof Error ? err.message : String(err);
+    throw new NotTrackingError(`Failed to persist session state: ${message}`, "NOT_TRACKING");
+}
+function reclaimStaleSessionStateLock(lockPath) {
+    const claim = `${lockPath}.reclaim.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}`;
+    try {
+        fs.renameSync(lockPath, claim);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+    try {
+        return true;
+    }
+    finally {
+        try {
+            fs.unlinkSync(claim);
+        }
+        catch { /* private claim cannot block writers */ }
+    }
+}
+/**
+ * Serialize a session-state read/modify/write with every state writer. Atomic
+ * rename protects readers from torn files, but only this shared lock protects
+ * a writer that has to verify the current binding before changing it.
+ */
+function withSessionStateLock(sessionId, root, fn) {
+    if (!isSafeWorkContextSegment(sessionId)) {
+        throw new NotTrackingError(`Unsafe session id for state file: ${sessionId}`, "NOT_TRACKING");
+    }
+    try {
+        ensureOwnerDir(workContextSessionsDir(root));
+    }
+    catch (err) {
+        asPersistenceFailure(err);
+    }
+    const statePath = resolveRealTarget(workContextSessionPath(sessionId, root));
+    const lockPath = `${statePath}.lock`;
+    const token = `${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}`;
+    const deadline = Date.now() + SESSION_STATE_LOCK_TIMEOUT_MS;
+    let fd;
+    while (fd === undefined) {
+        try {
+            fd = fs.openSync(lockPath, "wx", 0o600);
+            fs.writeSync(fd, JSON.stringify({ pid: process.pid, token }));
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                asPersistenceFailure(err);
+            let ownerPid = 0;
+            try {
+                const raw = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+                ownerPid = typeof raw.pid === "number" && Number.isInteger(raw.pid) ? raw.pid : 0;
+            }
+            catch {
+                // A malformed lock cannot safely protect the state.
+            }
+            let ownerAlive = false;
+            if (ownerPid > 0) {
+                try {
+                    process.kill(ownerPid, 0);
+                    ownerAlive = true;
+                }
+                catch {
+                    // Dead owners do not retain the lock.
+                }
+            }
+            if (!ownerAlive) {
+                try {
+                    reclaimStaleSessionStateLock(lockPath);
+                }
+                catch (err) {
+                    asPersistenceFailure(err);
+                }
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                throw new NotTrackingError(`Timed out waiting for session state lock: ${path.basename(statePath)}`, "NOT_TRACKING");
+            }
+            waitForSessionStateLock(SESSION_STATE_LOCK_RETRY_MS);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        fs.closeSync(fd);
+        try {
+            const current = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+            if (current.token === token)
+                fs.unlinkSync(lockPath);
+        }
+        catch {
+            // A stale-lock reclaimer or replacement owner has already retired it.
+        }
+    }
+}
 export function readSessionState(sessionId, root) {
     if (!isSafeWorkContextSegment(sessionId))
         return null;
@@ -49,6 +135,9 @@ export function writeSessionState(state, root) {
     if (!isSafeWorkContextSegment(state.sessionId)) {
         throw new NotTrackingError(`Unsafe session id for state file: ${state.sessionId}`, "NOT_TRACKING");
     }
+    return withSessionStateLock(state.sessionId, root, () => writeSessionStateUnlocked(state, root));
+}
+function writeSessionStateUnlocked(state, root) {
     const projected = projectSessionState(state);
     try {
         ensureOwnerDir(workContextSessionsDir(root));
@@ -60,8 +149,22 @@ export function writeSessionState(state, root) {
         throw new NotTrackingError(`Failed to persist session state: ${err instanceof Error ? err.message : String(err)}`, "NOT_TRACKING");
     }
 }
+/**
+ * Commit a state change only after inspecting the latest value under the same
+ * lock used by ordinary session writers. Returning null declines the write.
+ */
+export function updateSessionState(sessionId, root, update) {
+    return withSessionStateLock(sessionId, root, () => {
+        const current = readSessionState(sessionId, root);
+        const next = update(current);
+        if (!next)
+            return null;
+        writeSessionStateUnlocked(next, root);
+        return next;
+    });
+}
 /** Strip any non-allowlisted fields before durable write. */
-export function projectSessionState(state) {
+function projectSessionState(state) {
     const out = {
         contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
         sessionId: state.sessionId,
@@ -100,16 +203,48 @@ export function projectSessionState(state) {
         out.localHarness = state.localHarness;
     if (state.transcriptMarker)
         out.transcriptMarker = state.transcriptMarker;
+    if (state.companyConfidence)
+        out.companyConfidence = state.companyConfidence;
+    if (state.projectBindReason)
+        out.projectBindReason = state.projectBindReason;
+    if (state.projectCandidates?.length)
+        out.projectCandidates = state.projectCandidates;
+    if (state.projectGate)
+        out.projectGate = state.projectGate;
+    if (state.projectHint && !state.projectId)
+        out.projectHint = state.projectHint;
+    if (state.presenceLeave?.companyUid)
+        out.presenceLeave = state.presenceLeave;
     return out;
 }
 /**
- * Merge prior local-only counters into a new state write so PostToolUse bumps
- * and reconcile updates do not clobber each other.
+ * Merge prior local fields into a new state write so PostToolUse bumps and
+ * reconcile updates do not clobber an acknowledged company binding.
  */
-export function mergeLocalSessionFields(next, prior) {
+export function mergeLocalSessionFields(next, prior, options = {}) {
     if (!prior)
         return next;
     const out = { ...next };
+    // Hook observations commonly carry only tool-write/session metadata. Those
+    // writes must not erase a company that an acknowledged register already
+    // projected locally; losing it causes held events and repeat registrations.
+    // A caller that carries either company field is intentionally changing the
+    // binding and remains authoritative.
+    if (options.preserveCompanyBinding !== false &&
+        !out.companyUid &&
+        !out.companySlug &&
+        (prior.companyUid || prior.companySlug)) {
+        out.companyUid = prior.companyUid;
+        out.companySlug = prior.companySlug;
+        out.contextStatus = prior.contextStatus;
+        if (!out.projectId && prior.projectId)
+            out.projectId = prior.projectId;
+        if (!out.taskId && prior.taskId)
+            out.taskId = prior.taskId;
+        if (out.version === undefined && prior.version !== undefined) {
+            out.version = prior.version;
+        }
+    }
     if (out.toolWrites === undefined && typeof prior.toolWrites === "number") {
         out.toolWrites = prior.toolWrites;
     }
@@ -131,11 +266,165 @@ export function mergeLocalSessionFields(next, prior) {
     if (!out.transcriptMarker && prior.transcriptMarker) {
         out.transcriptMarker = prior.transcriptMarker;
     }
-    if (!out.bindingEpisodeId && prior.bindingEpisodeId) {
+    const sameCompanyBinding = Boolean(prior.companyUid && out.companyUid && prior.companyUid === out.companyUid) ||
+        Boolean(prior.companySlug &&
+            out.companySlug &&
+            prior.companySlug.toLowerCase() === out.companySlug.toLowerCase());
+    if (!out.companyConfidence && prior.companyConfidence && sameCompanyBinding) {
+        out.companyConfidence = prior.companyConfidence;
+    }
+    if (!out.projectId &&
+        !out.projectHint &&
+        prior.projectHint &&
+        sameCompanyBinding) {
+        out.projectHint = prior.projectHint;
+    }
+    if (!out.presenceLeave && prior.presenceLeave) {
+        out.presenceLeave = prior.presenceLeave;
+    }
+    if (out.projectId)
+        out.projectHint = undefined;
+    const sameBinding = prior.companyUid === out.companyUid &&
+        prior.companySlug === out.companySlug &&
+        prior.projectId === out.projectId &&
+        prior.taskId === out.taskId;
+    if (options.preserveBindingEpisode !== false &&
+        !out.bindingEpisodeId &&
+        prior.bindingEpisodeId &&
+        sameBinding) {
         out.bindingEpisodeId = prior.bindingEpisodeId;
     }
     return out;
 }
+function acknowledgedStatus(binding) {
+    if (!binding.companyUid)
+        return null;
+    if (binding.projectId && binding.taskId)
+        return "bound";
+    if (binding.projectId)
+        return "needs_task";
+    return "needs_project";
+}
+function bindingStrength(state) {
+    if (state.contextStatus === "bound" && state.projectId && state.taskId)
+        return 3;
+    if (state.contextStatus === "needs_task" && state.projectId)
+        return 2;
+    if (state.contextStatus === "needs_project")
+        return 1;
+    return 0;
+}
+const SERVER_EPISODE_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * True when a stored bindingEpisodeId is a register receipt, not an episode.
+ *
+ * The server mints binding episodes as UUIDs, and only on bind / organize. A
+ * register response carries no episode: its receipt is the operation id the
+ * client generated (`op_...`). An id is treated as a receipt when it has that
+ * shape or when it equals a receipt the caller knows about. A UUID is never
+ * treated as a receipt by shape.
+ */
+export function isRegisterReceiptEpisodeId(id, knownReceiptIds = []) {
+    if (!id)
+        return false;
+    for (const receiptId of knownReceiptIds) {
+        if (receiptId && receiptId === id)
+            return true;
+    }
+    if (SERVER_EPISODE_SHAPE.test(id))
+        return false;
+    return id.startsWith("op_");
+}
+/**
+ * Clear register receipts stored as a binding episode, on the session itself
+ * and on its pending presenceLeave. Returns the same object when nothing
+ * changed, so callers can detect a repair by identity.
+ */
+export function stripRegisterReceiptEpisodes(state, knownReceiptIds = []) {
+    const known = [...knownReceiptIds];
+    const ownIsReceipt = isRegisterReceiptEpisodeId(state.bindingEpisodeId, known);
+    const leaveIsReceipt = isRegisterReceiptEpisodeId(state.presenceLeave?.bindingEpisodeId, known);
+    if (!ownIsReceipt && !leaveIsReceipt)
+        return state;
+    const out = { ...state };
+    if (ownIsReceipt)
+        out.bindingEpisodeId = undefined;
+    if (leaveIsReceipt && state.presenceLeave) {
+        const { bindingEpisodeId: _receipt, ...leave } = state.presenceLeave;
+        out.presenceLeave = leave;
+    }
+    return out;
+}
+/**
+ * Upgrade the local projection after the server acknowledges a register.
+ *
+ * A receipt makes the operation's company authoritative, but it must never
+ * erase an explicit untracked choice, a conflicting existing company, or a
+ * more specific binding for the same company. This is also used to repair
+ * state files created by older clients before this write-back existed.
+ *
+ * The read and the write happen under the session state lock, so a concurrent
+ * writer (for example bind-project) is never overwritten from a stale snapshot.
+ */
+export function writeAcknowledgedRegisterBinding(binding, root, now = () => new Date()) {
+    const acknowledged = acknowledgedStatus(binding);
+    if (!acknowledged || !isSafeWorkContextSegment(binding.sessionId))
+        return null;
+    let result = null;
+    updateSessionState(binding.sessionId, root, (current) => {
+        // Reconcile always writes the local projection before network delivery. Do
+        // not manufacture session files when replay sees an orphaned legacy outbox
+        // record with no corresponding tracked session.
+        if (!current)
+            return null;
+        // A register response never carries a server episode, bound or not. The
+        // server mints episodes only on bind / organize, and drops session-event
+        // batches whose episode it does not recognise. Older clients stored the
+        // register receipt as the episode, so clear it wherever it is found. This
+        // repair is independent of the binding decision below and therefore also
+        // applies to untracked and different-company states.
+        const prior = stripRegisterReceiptEpisodes(current, [binding.receiptId]);
+        const repaired = prior !== current;
+        if (prior.contextStatus === "untracked" ||
+            (prior.companyUid && prior.companyUid !== binding.companyUid)) {
+            result = prior;
+            return repaired ? prior : null;
+        }
+        const acknowledgementStrength = acknowledged === "bound" ? 3 : acknowledged === "needs_task" ? 2 : 1;
+        const priorStrength = bindingStrength(prior);
+        const preservePriorBinding = Boolean(prior.companyUid === binding.companyUid && priorStrength > acknowledgementStrength);
+        const sameBindingAsPrior = prior.companyUid === binding.companyUid &&
+            prior.projectId === binding.projectId &&
+            prior.taskId === binding.taskId;
+        const next = mergeLocalSessionFields({
+            contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
+            sessionId: binding.sessionId,
+            companyUid: binding.companyUid,
+            companySlug: binding.companySlug ?? prior.companySlug,
+            contextStatus: preservePriorBinding ? prior.contextStatus : acknowledged,
+            projectId: preservePriorBinding ? prior.projectId : binding.projectId,
+            taskId: preservePriorBinding ? prior.taskId : binding.taskId,
+            // Keep a server-issued episode only while the binding it was issued
+            // for is unchanged. Never derive one from the receipt.
+            bindingEpisodeId: preservePriorBinding || sameBindingAsPrior
+                ? prior.bindingEpisodeId
+                : undefined,
+            updatedAt: now().toISOString(),
+        }, prior, { preserveBindingEpisode: false });
+        if (prior.companyUid === next.companyUid &&
+            prior.companySlug === next.companySlug &&
+            prior.contextStatus === next.contextStatus &&
+            prior.projectId === next.projectId &&
+            prior.taskId === next.taskId &&
+            prior.bindingEpisodeId === next.bindingEpisodeId) {
+            result = prior;
+            return repaired ? prior : null;
+        }
+        result = next;
+        return next;
+    });
+    return result;
+}
 /** True when a durable state file was written by the hook / reconcile path. */
 export function isHookWrittenSessionState(state) {
     if (!state)
@@ -146,6 +435,10 @@ export function isHookWrittenSessionState(state) {
 export function authoritativeCompanyFromState(state) {
     if (!state)
         return null;
+    // A binding created only from the device default is deliberately weak. A
+    // later /startwork meta designation or remembered repo choice may replace it.
+    if (state.companyConfidence === "device_default")
+        return null;
     const writable = new Set([
         "unresolved",
         "needs_project",
@@ -159,4 +452,24 @@ export function authoritativeCompanyFromState(state) {
         return null;
     return { slug: state.companySlug, uid: state.companyUid };
 }
+/**
+ * Apply `hq mesh context bind-project`: an operator's local project choice.
+ *
+ * The server issues no binding episode for this local choice, so any prior
+ * bindingEpisodeId (older clients stored a register receipt there) is cleared.
+ * Carrying it forward makes the server drop every later session-event batch.
+ */
+export function applyOperatorProjectBinding(state, projectId, now = () => new Date()) {
+    return {
+        ...state,
+        contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
+        contextStatus: state.taskId ? "bound" : "needs_task",
+        projectId,
+        bindingEpisodeId: undefined,
+        projectGate: undefined,
+        projectCandidates: undefined,
+        projectBindReason: `operator selected ${projectId}`,
+        updatedAt: now().toISOString(),
+    };
+}
 //# sourceMappingURL=state.js.map