@indigoai-us/hq-cli 5.108.1 → 5.108.2

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

@@ -0,0 +1,46 @@
+/**
+ * Typed Work Context errors (US-007A / resolver error map).
+ */
+export class WorkContextError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "WorkContextError";
+        this.code = code;
+    }
+}
+export class NotTrackingError extends WorkContextError {
+    constructor(message, code = "NOT_TRACKING") {
+        super(code, message);
+        this.name = "NotTrackingError";
+    }
+}
+export class DefaultCompanyLockedError extends WorkContextError {
+    constructor(message = "Default-company mode is locked until the server advertises migrationCapability") {
+        super("DEFAULT_COMPANY_LOCKED", message);
+        this.name = "DefaultCompanyLockedError";
+    }
+}
+export class DefaultCompanyUnavailableError extends WorkContextError {
+    constructor(message = "Cannot set default company: membership unavailable or caller is not a current member") {
+        super("DEFAULT_COMPANY_UNAVAILABLE", message);
+        this.name = "DefaultCompanyUnavailableError";
+    }
+}
+export class InvalidDecisionOriginError extends WorkContextError {
+    constructor(message = "Untracked origin must be user; model/agent origins are rejected") {
+        super("InvalidDecisionOriginError", message);
+        this.name = "InvalidDecisionOriginError";
+    }
+}
+export class UnsafeConfigPathError extends WorkContextError {
+    constructor(message) {
+        super("UnsafeConfigPathError", message);
+        this.name = "UnsafeConfigPathError";
+    }
+}
+/** Exit codes for `hq mesh context reconcile` machine mode. */
+export const EXIT_OK = 0;
+export const EXIT_INVALID_IDENTITY = 2;
+export const EXIT_NOT_TRACKING = 3;
+//# sourceMappingURL=errors.js.map

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

@@ -0,0 +1,23 @@
+/**
+ * Work Context reconciliation package (consumable by hq-cli).
+ * Contract (US-001) + reconcile / outbox / device default (US-007A)
+ * + organize / project resolution (US-007B)
+ * + cross-company correct / migrate (US-017B).
+ */
+export * from "./contract.js";
+export * from "./errors.js";
+export * from "./paths.js";
+export * from "./atomic.js";
+export * from "./config.js";
+export * from "./state.js";
+export * from "./outbox.js";
+export * from "./company.js";
+export * from "./project.js";
+export { decisionFromCandidates, digestOrganizePayload, formatOrganizeList, prepareOrganizeDecision, settleOrganizeAskWithoutBind, stableDecisionId, stableOrganizeOperationId, submitOrganizeDecision, } from "./organize.js";
+export type { CandidatesResponse, FetchCandidatesFn, OrganizeCandidate, OrganizeListResult, OrganizeReceipt, OrganizeSubmitDecision, OrganizeSubmitResult, PostOrganizeFn, } from "./organize.js";
+export { digestMigratePayload, formatMigrateConfirmation, stableMigrateOperationId, submitSessionMigration, } from "./migrate.js";
+export type { MigrateDestination, MigrateReceipt, MigrateSubmitResult, PostMigrateFn, } from "./migrate.js";
+export { deriveRemoteOwnerSlug, matchCompanySlugForRepo, normalizeRemoteOwnerName, } from "./repo-remote.js";
+export { loadObservationFromFile, markUntracked, parseObservationJson, reconcileObservation, } from "./reconcile.js";
+export type { ReconcileDeps, ReconcileObservation, ReconcileOutcome, } from "./reconcile.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,20 @@
+/**
+ * Work Context reconciliation package (consumable by hq-cli).
+ * Contract (US-001) + reconcile / outbox / device default (US-007A)
+ * + organize / project resolution (US-007B)
+ * + cross-company correct / migrate (US-017B).
+ */
+export * from "./contract.js";
+export * from "./errors.js";
+export * from "./paths.js";
+export * from "./atomic.js";
+export * from "./config.js";
+export * from "./state.js";
+export * from "./outbox.js";
+export * from "./company.js";
+export * from "./project.js";
+export { decisionFromCandidates, digestOrganizePayload, formatOrganizeList, prepareOrganizeDecision, settleOrganizeAskWithoutBind, stableDecisionId, stableOrganizeOperationId, submitOrganizeDecision, } from "./organize.js";
+export { digestMigratePayload, formatMigrateConfirmation, stableMigrateOperationId, submitSessionMigration, } from "./migrate.js";
+export { deriveRemoteOwnerSlug, matchCompanySlugForRepo, normalizeRemoteOwnerName, } from "./repo-remote.js";
+export { loadObservationFromFile, markUntracked, parseObservationJson, reconcileObservation, } from "./reconcile.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,84 @@
+/**
+ * Cross-company session correction (US-017B).
+ *
+ * Submits only a structured migrate request (operationId + digest), tracks the
+ * receipt via the outbox, and keeps the local state file at migration_pending
+ * until the destination receipt arrives. Never rebinds by any other path.
+ */
+import { type OutboxOperation } from "./outbox.js";
+import { type SessionStateFile } from "./state.js";
+export interface MigrateDestination {
+    projectId?: string;
+    taskId?: string;
+}
+export interface MigrateReceipt {
+    sessionId: string;
+    sourceCompanyUid: string;
+    destinationCompanyUid: string;
+    destination: MigrateDestination;
+    eventCount: number;
+    bindingCount: number;
+    receiptCount: number;
+    version: number;
+    migratedAt: string;
+    receipt: {
+        operationId: string;
+        digest: string;
+        status: "committed" | "replayed";
+    };
+}
+export interface MigrateSubmitResult {
+    ok: boolean;
+    /** True when confirmation was declined — nothing was sent. */
+    cancelled?: boolean;
+    pending?: boolean;
+    receipt?: MigrateReceipt;
+    outbox?: OutboxOperation;
+    state?: SessionStateFile;
+    confirmationSummary?: string;
+    errorCode?: string;
+    message?: string;
+}
+export type PostMigrateFn = (input: {
+    sessionId: string;
+    operationId: string;
+    digest: string;
+    sourceCompanyUid: string;
+    destinationCompanyUid: string;
+    destination: MigrateDestination;
+    expectedVersion: number;
+}) => Promise<MigrateReceipt>;
+/** Canonical digest material — mirrors hq-pro migrateDigestPayload + sha256. */
+export declare function digestMigratePayload(parts: {
+    sessionId: string;
+    sourceCompanyUid: string;
+    destinationCompanyUid: string;
+    destination: MigrateDestination;
+    expectedVersion: number;
+}): string;
+export declare function stableMigrateOperationId(sessionId: string, sourceCompanyUid: string, destinationCompanyUid: string): string;
+/** Human-readable summary printed before the confirmation gate. */
+export declare function formatMigrateConfirmation(input: {
+    sessionId: string;
+    sourceCompanySlug?: string;
+    sourceCompanyUid: string;
+    destinationCompanySlug: string;
+    destinationCompanyUid: string;
+    destination: MigrateDestination;
+}): string;
+/**
+ * Submit a cross-company correction after the caller has already confirmed.
+ * Writes migration_pending + outbox before any network I/O; on destination
+ * receipt, rewrites the state file to the destination company.
+ */
+export declare function submitSessionMigration(input: {
+    sessionId: string;
+    root: string;
+    destinationCompanyUid: string;
+    destinationCompanySlug: string;
+    destination?: MigrateDestination;
+    expectedVersion?: number;
+    now?: () => Date;
+    postMigrate: PostMigrateFn;
+}): Promise<MigrateSubmitResult>;
+//# sourceMappingURL=migrate.d.ts.map

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

@@ -0,0 +1,287 @@
+/**
+ * Cross-company session correction (US-017B).
+ *
+ * Submits only a structured migrate request (operationId + digest), tracks the
+ * receipt via the outbox, and keeps the local state file at migration_pending
+ * until the destination receipt arrives. Never rebinds by any other path.
+ */
+import * as crypto from "node:crypto";
+import { WORK_CONTEXT_CONTRACT_VERSION } from "./contract.js";
+import { NotTrackingError } from "./errors.js";
+import { enqueueOutbox, markOutboxAcked, markOutboxQuarantined, markOutboxQueued, } from "./outbox.js";
+import { mergeLocalSessionFields, readSessionState, writeSessionState, } from "./state.js";
+/** Canonical digest material — mirrors hq-pro migrateDigestPayload + sha256. */
+export function digestMigratePayload(parts) {
+    const canonical = JSON.stringify({
+        sessionId: parts.sessionId,
+        sourceCompanyUid: parts.sourceCompanyUid,
+        destinationCompanyUid: parts.destinationCompanyUid,
+        destination: {
+            ...(parts.destination.projectId
+                ? { projectId: parts.destination.projectId }
+                : {}),
+            ...(parts.destination.taskId ? { taskId: parts.destination.taskId } : {}),
+        },
+        expectedVersion: parts.expectedVersion,
+    });
+    return crypto.createHash("sha256").update(canonical).digest("hex");
+}
+export function stableMigrateOperationId(sessionId, sourceCompanyUid, destinationCompanyUid) {
+    const h = crypto
+        .createHash("sha256")
+        .update(`migrate:v1:${sessionId}:${sourceCompanyUid}:${destinationCompanyUid}`)
+        .digest("hex")
+        .slice(0, 32);
+    return `op_${h}`;
+}
+/** Human-readable summary printed before the confirmation gate. */
+export function formatMigrateConfirmation(input) {
+    const from = input.sourceCompanySlug && input.sourceCompanySlug !== input.sourceCompanyUid
+        ? `${input.sourceCompanySlug} (${input.sourceCompanyUid})`
+        : input.sourceCompanyUid;
+    const to = input.destinationCompanySlug !== input.destinationCompanyUid
+        ? `${input.destinationCompanySlug} (${input.destinationCompanyUid})`
+        : input.destinationCompanyUid;
+    const destBits = [];
+    if (input.destination.projectId) {
+        destBits.push(`project=${input.destination.projectId}`);
+    }
+    if (input.destination.taskId) {
+        destBits.push(`task=${input.destination.taskId}`);
+    }
+    const destExtra = destBits.length ? ` (${destBits.join(", ")})` : "";
+    return [
+        `Move session ${input.sessionId}`,
+        `  from company: ${from}`,
+        `  to company:   ${to}${destExtra}`,
+        "This freezes the source, copies history to the destination, and leaves a tombstone. It does not move any project or task.",
+    ].join("\n");
+}
+/**
+ * Submit a cross-company correction after the caller has already confirmed.
+ * Writes migration_pending + outbox before any network I/O; on destination
+ * receipt, rewrites the state file to the destination company.
+ */
+export async function submitSessionMigration(input) {
+    const state = readSessionState(input.sessionId, input.root);
+    if (!state) {
+        return {
+            ok: false,
+            errorCode: "NO_STATE",
+            message: `No work-context state for session ${input.sessionId}`,
+        };
+    }
+    if (!state.companyUid) {
+        return {
+            ok: false,
+            errorCode: "SOURCE_COMPANY_REQUIRED",
+            message: "Session has no verified source companyUid; cannot migrate across companies",
+        };
+    }
+    if (state.companyUid === input.destinationCompanyUid) {
+        return {
+            ok: false,
+            errorCode: "SAME_COMPANY",
+            message: "Destination company must differ from the session's current company",
+        };
+    }
+    if (state.contextStatus === "untracked") {
+        return {
+            ok: false,
+            errorCode: "UNTRACKED",
+            message: "Untracked sessions have no server history to migrate",
+        };
+    }
+    const destination = {};
+    if (input.destination?.projectId?.trim()) {
+        destination.projectId = input.destination.projectId.trim();
+    }
+    if (input.destination?.taskId?.trim()) {
+        destination.taskId = input.destination.taskId.trim();
+    }
+    if (destination.taskId && !destination.projectId) {
+        return {
+            ok: false,
+            errorCode: "PROJECT_REQUIRED",
+            message: "destination projectId is required when taskId is set",
+        };
+    }
+    const expectedVersion = typeof input.expectedVersion === "number" &&
+        Number.isInteger(input.expectedVersion) &&
+        input.expectedVersion >= 0
+        ? input.expectedVersion
+        : typeof state.version === "number"
+            ? state.version
+            : 0;
+    const operationId = stableMigrateOperationId(input.sessionId, state.companyUid, input.destinationCompanyUid);
+    const digest = digestMigratePayload({
+        sessionId: input.sessionId,
+        sourceCompanyUid: state.companyUid,
+        destinationCompanyUid: input.destinationCompanyUid,
+        destination,
+        expectedVersion,
+    });
+    const confirmationSummary = formatMigrateConfirmation({
+        sessionId: input.sessionId,
+        sourceCompanySlug: state.companySlug,
+        sourceCompanyUid: state.companyUid,
+        destinationCompanySlug: input.destinationCompanySlug,
+        destinationCompanyUid: input.destinationCompanyUid,
+        destination,
+    });
+    const nowFn = input.now ?? (() => new Date());
+    const nowIso = nowFn().toISOString();
+    let outbox;
+    try {
+        outbox = enqueueOutbox({
+            clientOperationId: operationId,
+            sessionId: input.sessionId,
+            companyUid: state.companyUid,
+            companySlug: state.companySlug,
+            projectId: destination.projectId,
+            taskId: destination.taskId,
+            kind: "migrate",
+            destinationCompanyUid: input.destinationCompanyUid,
+            destinationCompanySlug: input.destinationCompanySlug,
+            now: nowFn,
+        }, input.root);
+    }
+    catch (err) {
+        if (err instanceof NotTrackingError) {
+            return { ok: false, errorCode: "NOT_TRACKING", message: err.message };
+        }
+        throw err;
+    }
+    // Freeze local view before network I/O.
+    const pendingState = mergeLocalSessionFields({
+        contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
+        sessionId: input.sessionId,
+        companyUid: state.companyUid,
+        companySlug: state.companySlug,
+        contextStatus: "migration_pending",
+        ...(state.projectId ? { projectId: state.projectId } : {}),
+        ...(state.taskId ? { taskId: state.taskId } : {}),
+        ...(state.bindingEpisodeId
+            ? { bindingEpisodeId: state.bindingEpisodeId }
+            : {}),
+        ...(typeof state.version === "number" ? { version: state.version } : {}),
+        migration: {
+            operationId: outbox.operationId,
+            digest,
+            sourceCompanyUid: state.companyUid,
+            destinationCompanyUid: input.destinationCompanyUid,
+            destinationCompanySlug: input.destinationCompanySlug,
+            ...(Object.keys(destination).length ? { destination } : {}),
+            submittedAt: nowIso,
+        },
+        updatedAt: nowIso,
+    }, state);
+    try {
+        writeSessionState(pendingState, input.root);
+    }
+    catch (err) {
+        if (err instanceof NotTrackingError) {
+            return { ok: false, errorCode: "NOT_TRACKING", message: err.message };
+        }
+        throw err;
+    }
+    let receipt;
+    try {
+        receipt = await input.postMigrate({
+            sessionId: input.sessionId,
+            operationId: outbox.operationId,
+            digest,
+            sourceCompanyUid: state.companyUid,
+            destinationCompanyUid: input.destinationCompanyUid,
+            destination,
+            expectedVersion,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const retryable = /ECONN|ENOTFOUND|ETIMEDOUT|network|HTTP_5|429/i.test(message);
+        if (retryable) {
+            markOutboxQueued(outbox.operationId, input.root, "MIGRATE_RETRYABLE", nowFn);
+        }
+        else {
+            markOutboxQuarantined(outbox.operationId, input.root, "MIGRATE_FAILED", nowFn);
+        }
+        return {
+            ok: false,
+            pending: true,
+            outbox: outbox,
+            state: readSessionState(input.sessionId, input.root) ?? pendingState,
+            confirmationSummary,
+            errorCode: "MIGRATE_FAILED",
+            message,
+        };
+    }
+    if (!receipt?.receipt?.operationId ||
+        !receipt.destinationCompanyUid ||
+        !receipt.migratedAt) {
+        markOutboxQuarantined(outbox.operationId, input.root, "RECEIPT_INCOMPLETE", nowFn);
+        return {
+            ok: false,
+            pending: true,
+            outbox,
+            state: readSessionState(input.sessionId, input.root) ?? pendingState,
+            confirmationSummary,
+            errorCode: "RECEIPT_INCOMPLETE",
+            message: "Server response missing destination migrate receipt",
+        };
+    }
+    const acked = markOutboxAcked(outbox.operationId, input.root, receipt.receipt.operationId, nowFn) ?? outbox;
+    const appliedAt = nowFn().toISOString();
+    const destStatus = receipt.destination.projectId && receipt.destination.taskId
+        ? "bound"
+        : receipt.destination.projectId
+            ? "needs_task"
+            : "unresolved";
+    const applied = {
+        contractVersion: WORK_CONTEXT_CONTRACT_VERSION,
+        sessionId: input.sessionId,
+        companyUid: receipt.destinationCompanyUid,
+        companySlug: input.destinationCompanySlug,
+        contextStatus: destStatus,
+        ...(receipt.destination.projectId
+            ? { projectId: receipt.destination.projectId }
+            : {}),
+        ...(receipt.destination.taskId
+            ? { taskId: receipt.destination.taskId }
+            : {}),
+        version: receipt.version,
+        migration: {
+            operationId: receipt.receipt.operationId,
+            digest: receipt.receipt.digest || digest,
+            sourceCompanyUid: receipt.sourceCompanyUid,
+            destinationCompanyUid: receipt.destinationCompanyUid,
+            destinationCompanySlug: input.destinationCompanySlug,
+            ...(Object.keys(receipt.destination).length
+                ? { destination: receipt.destination }
+                : {}),
+            submittedAt: nowIso,
+            receiptId: receipt.receipt.operationId,
+            completedAt: receipt.migratedAt,
+        },
+        updatedAt: appliedAt,
+    };
+    // Preserve local-only counters; drop source project/task when destination
+    // did not name replacements (migration never moves a project/task).
+    const merged = mergeLocalSessionFields(applied, {
+        ...state,
+        projectId: undefined,
+        taskId: undefined,
+        bindingEpisodeId: undefined,
+        decision: undefined,
+    });
+    writeSessionState(merged, input.root);
+    return {
+        ok: true,
+        pending: false,
+        receipt,
+        outbox: acked,
+        state: merged,
+        confirmationSummary,
+    };
+}
+//# sourceMappingURL=migrate.js.map

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

@@ -0,0 +1,130 @@
+/**
+ * hq mesh context organize — one-time decisions and US-005B submit (US-007B).
+ *
+ * CLI only presents server candidates and submits structured decisions.
+ * Ranking is server-owned. Success is reported only from the server receipt.
+ * Cancel / timeout / incapable surface leaves the session unresolved; the CLI
+ * never invents a project or adhoc target and never repeats the ask.
+ */
+import { type SessionDecision, type SessionStateFile } from "./state.js";
+export interface OrganizeCandidate {
+    candidateId: string;
+    projectId: string;
+    taskId?: string;
+    title: string;
+    projectName: string;
+    updatedAt?: string;
+}
+export interface CandidatesResponse {
+    contractVersion: 1;
+    sessionId: string;
+    companyUid: string;
+    decisionExpiresAt: string;
+    candidates: OrganizeCandidate[];
+}
+export type OrganizeDecisionKind = "bind_existing" | "create_project" | "create_task";
+export interface OrganizeSubmitDecision {
+    kind: OrganizeDecisionKind;
+    projectId?: string;
+    taskId?: string;
+    title?: string;
+}
+export interface OrganizeReceipt {
+    sessionId: string;
+    companyUid: string;
+    projectId: string;
+    taskId?: string;
+    episodeId?: string;
+    bindingEpisodeId: string;
+    contextStatus: "bound";
+    version?: number;
+    openedAt?: string;
+    kind?: OrganizeDecisionKind;
+    receipt: {
+        operationId: string;
+        digest: string;
+        status: "committed" | "replayed";
+    };
+}
+export interface OrganizeListResult {
+    sessionId: string;
+    contextStatus: string;
+    pending: boolean;
+    decision: SessionDecision | null;
+    /** Why no ask is surfaced (threshold / already asked / bound / etc.). */
+    reason?: string;
+}
+export interface OrganizeSubmitResult {
+    ok: boolean;
+    receipt?: OrganizeReceipt;
+    localUntracked?: boolean;
+    errorCode?: string;
+    message?: string;
+}
+export type FetchCandidatesFn = (input: {
+    sessionId: string;
+    companyUid: string;
+}) => Promise<CandidatesResponse>;
+export type PostOrganizeFn = (input: {
+    sessionId: string;
+    companyUid: string;
+    operationId: string;
+    digest: string;
+    decision: OrganizeSubmitDecision;
+    expectedVersion: number;
+    decisionExpiresAt?: string;
+}) => Promise<OrganizeReceipt>;
+/** Stable decision id for a session + expiry window. */
+export declare function stableDecisionId(sessionId: string, decisionExpiresAt: string): string;
+export declare function digestOrganizePayload(parts: {
+    sessionId: string;
+    companyUid: string;
+    decision: OrganizeSubmitDecision;
+    expectedVersion: number;
+}): string;
+export declare function stableOrganizeOperationId(sessionId: string, decision: OrganizeSubmitDecision): string;
+/**
+ * Build a pending decision from server candidates. Soft evidence ranks on the
+ * server; the CLI never auto-binds from this list.
+ */
+export declare function decisionFromCandidates(sessionId: string, response: CandidatesResponse): SessionDecision;
+/**
+ * Evaluate work-signal threshold and, when crossed for the first time, attach
+ * a one-time decision (optionally from server candidates). Never invents a
+ * project. If a decision already exists, it is left untouched (ask-once).
+ */
+export declare function prepareOrganizeDecision(input: {
+    sessionId: string;
+    root: string;
+    now?: () => Date;
+    fetchCandidates?: FetchCandidatesFn;
+    /** Skip network; leave unresolved without candidates. */
+    offline?: boolean;
+}): Promise<OrganizeListResult>;
+export declare function formatOrganizeList(result: OrganizeListResult): string[];
+/**
+ * Mark that the ask was cancelled / timed out / surface incapable.
+ * Leaves the session unresolved and visible; clears askAfter so the CLI
+ * never repeats the ask; never invents a project.
+ */
+export declare function settleOrganizeAskWithoutBind(input: {
+    sessionId: string;
+    root: string;
+    now?: () => Date;
+    reason?: "cancelled" | "timeout" | "incapable";
+}): SessionStateFile | null;
+/**
+ * Submit an organize decision through US-005B. Success only from receipt.
+ */
+export declare function submitOrganizeDecision(input: {
+    sessionId: string;
+    root: string;
+    decisionId?: string;
+    optionId?: string;
+    createProjectTitle?: string;
+    createTaskTitle?: string;
+    untracked?: boolean;
+    now?: () => Date;
+    postOrganize?: PostOrganizeFn;
+}): Promise<OrganizeSubmitResult>;
+//# sourceMappingURL=organize.d.ts.map