@indigoai-us/hq-cli 5.108.23 → 5.108.25

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+## [5.108.25] — 2026-09-08
+
+## [5.108.24] — 2026-09-08
+
+### Added
+
+- `hq sync doctor --reconcile-conflicts [--yes]` folds legacy sibling
+  `.conflict-<ts>-<machine>` twins back into their live files (higher
+  frontmatter `version:` wins, else newer mtime), parks the losing side under
+  `.hq/conflict-backups/`, and surfaces undecidable pairs for manual review.
+  Dry-run by default; `--yes` applies.
+
+### Changed
+
+- Bump `@indigoai-us/hq-cloud` to 6.16.28: sync no longer writes sibling
+  `.conflict-*` twins on conflict and instead picks the higher `version:`
+  frontmatter side, parking the loser under `.hq/conflict-backups/`.
+
 ## [5.108.23] — 2026-09-08
 
 ### Added

package/dist/commands/cloud.d.ts

@@ -336,6 +336,16 @@ export interface PerCompanyPullResolveResult {
 }
 export declare function resolvePerCompanyPullPlan(client: PerCompanyPullResolveClient, targetCompany: string | undefined): Promise<PerCompanyPullResolveResult>;
 export declare function registerCloudCommands(program: Command): void;
+/**
+ * `hq sync doctor --reconcile-conflicts [--yes]`.
+ *
+ * Reconcile mode is purely local — the engine walks the HQ root for legacy
+ * sibling conflict twins and never touches the vault — but the engine's
+ * `SyncDoctorOptions` type still requires `entity` / `vaultConfig` for its
+ * skill-key dedupe mode. Placeholders are passed; the reconcile branch returns
+ * before either is read (verified against hq-cloud's `doctor.js`).
+ */
+export declare function runSyncDoctorReconcileConflicts(hqRoot: string, yes: boolean): Promise<void>;
 /** Exported for the US-003 sync-health exit-path regression test. */
 export declare function runPullPersonal(hqRoot: string, onConflict?: ConflictStrategy): Promise<void>;
 //# sourceMappingURL=cloud.d.ts.map

package/dist/commands/cloud.js

@@ -15,7 +15,7 @@
 import chalk from "chalk";
 import * as fs from "fs";
 import * as path from "path";
-import { share, sync, getStateDir, listJournals, loadCachedTokens, VaultClient, computePersonalVaultPaths, PERSONAL_VAULT_JOURNAL_SLUG, resolvePullScope, } from "@indigoai-us/hq-cloud";
+import { share, sync, getStateDir, listJournals, loadCachedTokens, VaultClient, computePersonalVaultPaths, PERSONAL_VAULT_JOURNAL_SLUG, resolvePullScope, syncDoctor, } from "@indigoai-us/hq-cloud";
 import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, } from "../utils/cognito-session.js";
 import { companyFolderExceedsThreshold, emitNarrowHint, isStrictRefusal, resolveBannerLevel, resolveNarrowHintPresentationLevel, resolveNarrowHintMinBytes, } from "../lib/narrow-hint-banner.js";
 import { beginSyncHealthReport, } from "../utils/client-health.js";
@@ -1098,6 +1098,81 @@ export function registerCloudCommands(program) {
             process.exit(1);
         }
     });
+    program
+        .command("doctor")
+        .description("Repair the local HQ tree. `--reconcile-conflicts` folds legacy " +
+        "sibling `.conflict-*` twins back into their live files (higher " +
+        "frontmatter `version:` wins; losers are parked under " +
+        ".hq/conflict-backups/). Dry-run unless --yes.")
+        .option("--hq-root <path>", `Local HQ tree root (default: ${DEFAULT_HQ_ROOT})`, DEFAULT_HQ_ROOT)
+        .option("--reconcile-conflicts", "Reconcile legacy sibling `.conflict-<ts>-<machine>` twins against " +
+        "their live files (purely local; no vault access).")
+        .option("--yes", "Apply the plan (default: dry-run, print only)")
+        .action(async (options) => {
+        try {
+            if (!options.reconcileConflicts) {
+                console.error(chalk.red("✗ hq sync doctor:"), "only `--reconcile-conflicts` mode is supported right now.");
+                console.error(chalk.dim("  Usage: hq sync doctor --reconcile-conflicts [--yes] [--hq-root <path>]"));
+                process.exit(1);
+                return;
+            }
+            await runSyncDoctorReconcileConflicts(options.hqRoot, options.yes === true);
+        }
+        catch (err) {
+            console.error(chalk.red("\n✗ Sync doctor failed:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}
+/**
+ * `hq sync doctor --reconcile-conflicts [--yes]`.
+ *
+ * Reconcile mode is purely local — the engine walks the HQ root for legacy
+ * sibling conflict twins and never touches the vault — but the engine's
+ * `SyncDoctorOptions` type still requires `entity` / `vaultConfig` for its
+ * skill-key dedupe mode. Placeholders are passed; the reconcile branch returns
+ * before either is read (verified against hq-cloud's `doctor.js`).
+ */
+export async function runSyncDoctorReconcileConflicts(hqRoot, yes) {
+    console.log(chalk.bold("\nHQ Sync — Doctor (reconcile conflicts)"));
+    console.log(`  HQ root: ${hqRoot}`);
+    console.log(`  Mode:    ${yes ? "apply (--yes)" : "dry-run (pass --yes to apply)"}`);
+    console.log("");
+    const result = await syncDoctor({
+        entity: "local",
+        vaultConfig: {},
+        hqRoot,
+        yes,
+        reconcileConflicts: true,
+    });
+    const twins = result.conflictTwins;
+    const backupsDir = path.join(hqRoot, ".hq", "conflict-backups");
+    console.log(chalk.bold(twins?.applied ? "\nReconcile — applied" : "\nReconcile — dry-run (nothing written)"));
+    console.log(`  Twins found:     ${twins?.plan.length ?? 0}`);
+    console.log(`  Promoted:        ${twins?.promoted ?? 0}`);
+    console.log(`  Kept live:       ${twins?.removed ?? 0}`);
+    console.log(`  Backed up:       ${twins?.backedUp ?? 0}`);
+    console.log(`  Orphans parked:  ${twins?.orphansParked ?? 0}`);
+    console.log(`  Index rows dropped: ${twins?.indexRowsDropped ?? 0}`);
+    if ((twins?.warnings ?? result.warnings) > 0) {
+        console.log(chalk.yellow(`  Warnings:        ${twins?.warnings ?? result.warnings}`));
+    }
+    const manual = twins?.manualReview ?? [];
+    if (manual.length > 0) {
+        console.log(chalk.yellow(`\n  Manual review (${manual.length}) — NOT auto-resolved:`));
+        for (const item of manual) {
+            console.log(`    • ${item.livePath}`);
+            console.log(chalk.dim(`        twin:   ${item.twinPath}`));
+            console.log(chalk.dim(`        reason: ${item.reason}`));
+            if (item.backupPath) {
+                console.log(chalk.dim(`        backup: ${item.backupPath}`));
+            }
+        }
+    }
+    console.log(chalk.dim(`\n  Backups live under: ${backupsDir}`));
+    if (!twins?.applied) {
+        console.log(chalk.dim("  Re-run with --yes to apply the plan above."));
+    }
 }
 async function runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal, forceScopeShrink) {
     console.log(chalk.bold("\nHQ Sync — Pull (all)"));

package/dist/commands/files.d.ts

@@ -89,6 +89,17 @@ export declare function stripRedundantCompanyScope(prefix: string): {
     prefix: string;
     strippedSlug: string;
 } | null;
+/**
+ * The company an anchored path names, or `undefined` for a relative/personal
+ * path.
+ *
+ * Discarding this slug is what makes retargeting possible: strip the anchor,
+ * then resolve the company from somewhere else, and the operation lands on a
+ * DIFFERENT company than the operator pasted. Callers pair this with
+ * `normalizeCompanyFilePrefix` so the anchor either MATCHES the explicit
+ * `--company` (or is refused), or BECOMES the company when none was given.
+ */
+export declare function companySlugFromAnchor(prefix: string, personal?: boolean): string | undefined;
 export declare function runFilesDelete(params: RunFilesDeleteParams, deps?: {
     confirm?: ConfirmFn;
 }): Promise<void>;

package/dist/commands/files.js

@@ -5,6 +5,8 @@ import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
 import { gateApiKeyCapabilities } from "../utils/api-key-command-gate.js";
 import { vaultApiFetch, getCompanyUid } from "./secrets.js";
 import { GROUP_ID_PATTERN, EMAIL_PATTERN, normalizeFilePrefix } from "./_patterns.js";
+import { looksLikeCompanyUid } from "../utils/vault-api.js";
+import { AuthError } from "../utils/auth-error.js";
 // ---------------------------------------------------------------------------
 // Pure helpers (exported for unit tests)
 // ---------------------------------------------------------------------------
@@ -157,8 +159,8 @@ export function registerFilesCommand(program) {
                 process.exit(1);
             }
             // Fork: --with present → existing direct-grant path. No --with →
-            // browser-launch share-session path. Per PRD, the direct-grant
-            // path is unchanged from US-001 and operates on a single prefix.
+            // browser-launch share-session path. The direct-grant path
+            // operates on a single prefix.
             if (opts.with !== undefined) {
                 if (paths.length !== 1) {
                     console.error(chalk.red("Direct grant (--with) takes exactly one prefix. Pass multiple paths only when minting a share-session URL."));
@@ -190,7 +192,15 @@ export function registerFilesCommand(program) {
         .requiredOption("--with <principal>", "Email address, group id, or '@all' to remove the company-wide grant")
         .action(async (prefix, opts) => {
         try {
-            const canonicalPrefix = normalizeFilePrefix(prefix);
+            // Unshare MUTATES access with no preview, and it resolves the target
+            // company from --company (not from the pasted anchor), so a mismatched
+            // anchor would revoke a real grant in the wrong company.
+            const canonicalPrefix = normalizeCompanyFilePrefix(prefix, {
+                mutating: true,
+                ...(files.opts().company !== undefined
+                    ? { companySlug: files.opts().company }
+                    : {}),
+            });
             const principal = opts.with;
             const isAll = principal === "@all";
             const isEmail = !isAll && EMAIL_PATTERN.test(principal);
@@ -264,10 +274,21 @@ export function registerFilesCommand(program) {
         .description("Show the ACL (access control list) for a file prefix")
         .action(async (prefix) => {
         try {
-            const canonicalPrefix = normalizeFilePrefix(prefix);
+            // Read-only, so stripping is safe — but a mismatched anchor would show
+            // a DIFFERENT company's ACL than the one the operator pasted.
+            const explicitCompany = files.opts().company;
+            const canonicalPrefix = normalizeCompanyFilePrefix(prefix, {
+                ...(explicitCompany !== undefined
+                    ? { companySlug: explicitCompany }
+                    : {}),
+            });
             const token = (await resolveVaultCredential()).token;
-            const companySlug = files.opts().company;
-            const companyUid = await getCompanyUid(token, companySlug);
+            // Resolve through the anchor so the answer describes the company the
+            // operator actually pasted, and never a different one.
+            const companyUid = await resolveCompanyUidForAnchoredPath(token, {
+                explicit: explicitCompany,
+                anchorSlug: companySlugFromAnchor(prefix),
+            });
             // `/acl/tree` carries the prefix's own row metadata (directRow) and the
             // caller's effectivePermission alongside direct/inherited/children, so
             // a single request returns everything the "files acl" view needs.
@@ -474,7 +495,13 @@ export function registerFilesCommand(program) {
     return files;
 }
 async function runDirectGrant(params) {
-    const canonicalPrefix = normalizeFilePrefix(params.prefix);
+    const canonicalPrefix = normalizeCompanyFilePrefix(params.prefix, {
+        mutating: true,
+        rootAdvice: "Use --full --with <principal> to share the entire vault, or pass a bounded path.",
+        ...(params.companySlug !== undefined
+            ? { companySlug: params.companySlug }
+            : {}),
+    });
     if (!params.permission) {
         console.error(chalk.red("--permission is required when --with is set (read | write)"));
         process.exit(1);
@@ -565,9 +592,15 @@ async function runDirectGrant(params) {
     }
 }
 async function runShareSession(params) {
-    // Normalize every path through the shared prefix helper so a trailing
-    // `/` becomes `/*` consistently with the direct-grant path.
-    const normalizedPaths = params.paths.map(normalizeFilePrefix);
+    // Validate every path before minting a session; an anchored path must never
+    // silently become a share of the corresponding company-relative objects.
+    const normalizedPaths = params.paths.map((prefix) => normalizeCompanyFilePrefix(prefix, {
+        mutating: true,
+        rootAdvice: "Use --full --with <principal> to share the entire vault, or pass a bounded path.",
+        ...(params.companySlug !== undefined
+            ? { companySlug: params.companySlug }
+            : {}),
+    }));
     let expiresInMs;
     if (params.expires !== undefined) {
         const parsed = parseDuration(params.expires);
@@ -723,36 +756,179 @@ export function stripRedundantCompanyScope(prefix) {
         return null;
     return { prefix: m[2] ?? "", strippedSlug: m[1] };
 }
+/**
+ * Resolve the company for a possibly-anchored path, refusing any retarget.
+ *
+ * The pure normalizer can only compare slug against slug. That left a hole: a
+ * UID-form `--company` was skipped by the string check, so
+ * `--company cmp_beta delete <alpha-anchored-path>` stripped the anchor,
+ * resolved beta, and previewed/deleted from beta. Comparing IDENTITIES rather
+ * than strings is the only way to close it, and that needs resolution.
+ *
+ * - no anchor            -> unchanged behaviour
+ * - anchor, no --company -> the anchor IS the company
+ * - UID anchor           -> compare with the selected company UID
+ * - slug + explicit UID  -> validate the selected entity's slug directly
+ * - slug + slug          -> resolve BOTH and require the same uid
+ *
+ * API keys can verify UID anchors through their company selector or keyed
+ * membership. Slug anchors still fail closed because keys cannot read entities.
+ */
+async function resolveCompanyUidForAnchoredPath(token, opts) {
+    if (opts.anchorSlug === undefined) {
+        return getCompanyUid(token, opts.explicit);
+    }
+    if (looksLikeCompanyUid(opts.anchorSlug)) {
+        const selectedUid = await getCompanyUid(token, opts.explicit ?? (token.startsWith("hqk_") ? undefined : opts.anchorSlug));
+        if (selectedUid !== opts.anchorSlug) {
+            throw new Error(`Refusing anchored path: it names company '${opts.anchorSlug}' ` +
+                `but this command targets '${selectedUid}'. Pass a matching company or path.`);
+        }
+        return selectedUid;
+    }
+    if (token.startsWith("hqk_")) {
+        throw new Error(`Refusing anchored path under an API key: the anchor names ` +
+            `'${opts.anchorSlug}', and an API key cannot resolve a slug to verify ` +
+            `that is the company it is bound to. Pass the bucket-relative path.`);
+    }
+    if (opts.explicit !== undefined && looksLikeCompanyUid(opts.explicit)) {
+        // An explicit UID disambiguates duplicate slugs. Resolving the slug first
+        // would fail before the caller's unambiguous selector could be considered.
+        const response = await vaultApiFetch({
+            token,
+            path: `/entity/${encodeURIComponent(opts.explicit)}`,
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (response.status === 401)
+            throw new AuthError();
+        if (!response.ok) {
+            throw new Error(`Failed to resolve company '${opts.explicit}' (HTTP ${response.status})`);
+        }
+        const data = (await response.json());
+        if (data.entity?.uid !== opts.explicit ||
+            data.entity.type !== "company" ||
+            data.entity.slug !== opts.anchorSlug) {
+            throw new Error(`Refusing anchored path: cannot verify that company '${opts.explicit}' ` +
+                `has the anchored slug '${opts.anchorSlug}'. Pass a matching company or path.`);
+        }
+        return opts.explicit;
+    }
+    const anchorUid = await getCompanyUid(token, opts.anchorSlug);
+    if (opts.explicit === undefined)
+        return anchorUid;
+    const explicitUid = await getCompanyUid(token, opts.explicit);
+    if (explicitUid !== anchorUid) {
+        throw new Error(`Refusing anchored path: it names company '${opts.anchorSlug}' ` +
+            `(${anchorUid}) but this command targets '${opts.explicit}' ` +
+            `(${explicitUid}). Re-run with --company ${opts.anchorSlug}, or pass ` +
+            `the bucket-relative path.`);
+    }
+    return anchorUid;
+}
+/**
+ * The company an anchored path names, or `undefined` for a relative/personal
+ * path.
+ *
+ * Discarding this slug is what makes retargeting possible: strip the anchor,
+ * then resolve the company from somewhere else, and the operation lands on a
+ * DIFFERENT company than the operator pasted. Callers pair this with
+ * `normalizeCompanyFilePrefix` so the anchor either MATCHES the explicit
+ * `--company` (or is refused), or BECOMES the company when none was given.
+ */
+export function companySlugFromAnchor(prefix, personal) {
+    if (personal)
+        return undefined;
+    return stripRedundantCompanyScope(prefix)?.strippedSlug;
+}
+/**
+ * Normalize company paths at the CLI boundary, preserving personal keys.
+ *
+ * `mutating` marks a route that CHANGES access and has no preview or
+ * confirmation step (grant, share, unshare). Those refuse an anchored path
+ * outright rather than guessing, because stripping the anchor changes which
+ * objects the operation reaches and there is nothing downstream to catch it.
+ *
+ * `companySlug` is the company the command is actually targeting. When the
+ * anchor names a DIFFERENT company we refuse in every mode: stripping would
+ * silently retarget the operation at the active company, so
+ * `--company beta unshare <alpha-anchored-path>` would revoke a real grant in
+ * beta while leaving alpha untouched.
+ */
+function normalizeCompanyFilePrefix(prefix, options = {}) {
+    const scope = options.personal ? null : stripRedundantCompanyScope(prefix);
+    if (!scope)
+        return normalizeFilePrefix(prefix);
+    // A `cmp_…` reference is a UID, not a slug, so it can only be compared to the
+    // anchor by RESOLVING it — which this pure helper cannot do. Comparing the
+    // strings would refuse `--company cmp_acme` against an `acme` anchor even
+    // though both name the same company, and `getCompanyUid`'s ambiguity error
+    // explicitly tells callers to retry with `--company <uid>`. Skip the check
+    // rather than break that recovery path; the UID is authoritative either way.
+    if (options.companySlug !== undefined &&
+        !looksLikeCompanyUid(options.companySlug) &&
+        !looksLikeCompanyUid(scope.strippedSlug) &&
+        options.companySlug !== scope.strippedSlug) {
+        throw new Error(`Refusing anchored path '${prefix}': it names company ` +
+            `'${scope.strippedSlug}' but this command targets ` +
+            `'${options.companySlug}'. Stripping the anchor would apply the ` +
+            `operation to '${options.companySlug}' instead. Re-run with ` +
+            `--company ${scope.strippedSlug}, or pass the bucket-relative path.`);
+    }
+    // A bare anchor strips to nothing. The ACL routes would ship that empty
+    // prefix to a server that answers 400, so fail here with a message that says
+    // what to do instead. `deferRootReject` is for callers that already have a
+    // root guard with better copy — `runFilesDelete` says "Refusing to delete the
+    // vault root", which beats anything this generic helper could write.
+    if (!scope.prefix && !options.deferRootReject) {
+        // Route-specific: `--full` exists ONLY on `files share`. Suggesting it for
+        // `unshare` fails with an unknown option and names the opposite operation.
+        const advice = options.rootAdvice ??
+            "Pass a bounded bucket-relative path (e.g. 'projects/foo').";
+        throw new Error(`Refusing anchored path '${prefix}': it resolves to the vault root. ` +
+            advice);
+    }
+    if (options.mutating) {
+        throw new Error(`Refusing anchored path '${prefix}': the vault is already ` +
+            `company-scoped, so removing 'companies/${scope.strippedSlug}/' would ` +
+            `change which objects this affects. Retry with the bucket-relative ` +
+            `path '${normalizeFilePrefix(scope.prefix)}' if that is what you intend.`);
+    }
+    console.error(chalk.yellow(`Note: stripped redundant 'companies/${scope.strippedSlug}/' — the vault ` +
+        `is already company-scoped; using bucket-relative '${scope.prefix}'.`));
+    return normalizeFilePrefix(scope.prefix);
+}
 export async function runFilesDelete(params, deps = {}) {
     const confirm = deps.confirm ?? realConfirm;
-    // The vault is already company-scoped — a `companies/<slug>/` prefix is the HQ
-    // LOCAL tree layout, not a vault key, and the server 400s it (HQ-8F). Strip it
-    // here so a pasted local path is gracefully normalized to bucket-relative
-    // BEFORE the dry-run/preview (so the operator still sees the exact keys and
-    // confirms the right target). If stripping empties the prefix, the root-reject
-    // below catches it with a clear message.
-    const scope = stripRedundantCompanyScope(params.prefix);
-    if (scope) {
-        console.error(chalk.yellow(`Note: stripped redundant 'companies/${scope.strippedSlug}/' — the vault ` +
-            `is already company-scoped; using bucket-relative ` +
-            `'${scope.prefix || "(root)"}'.`));
-    }
-    const rawPrefix = scope ? scope.prefix : params.prefix;
-    // Normalize exactly as the share/unshare/acl paths do (trailing `/` → `/*`),
-    // then reject the root/empty prefix CLIENT-side so a typo never reaches the
-    // server as a vault-wide delete. The server enforces this too (defense in
-    // depth), but failing fast here is clearer and avoids a wasted round-trip.
-    const normalized = normalizeFilePrefix(rawPrefix);
+    // Strip the local company anchor before preview/confirmation (HQ-8F/HQ-CA).
+    // Personal keys are already bucket-relative and must keep any such anchor.
+    // Normalize trailing `/` to `/*`, then reject the root/empty prefix before
+    // any network call, including when stripping a bare company anchor empties it.
+    // The anchor names a company. Compare it with --company (refusing a
+    // mismatch), and when --company was omitted ADOPT it rather than letting the
+    // membership fallback pick a different company to delete from.
+    const anchorSlug = companySlugFromAnchor(params.prefix, params.personal);
+    const normalized = normalizeCompanyFilePrefix(params.prefix, {
+        personal: params.personal,
+        deferRootReject: true,
+        ...(params.companySlug !== undefined
+            ? { companySlug: params.companySlug }
+            : {}),
+    });
     if (normalized === "" || normalized === "*" || normalized === "/*") {
         console.error(chalk.red("Refusing to delete the vault root. Pass a bounded prefix (e.g. 'projects/foo/' or 'projects/foo/*') or an exact key."));
         process.exit(1);
     }
     const token = (await resolveVaultCredential()).token;
     // Personal scope resolves the vault server-side from the caller's identity —
-    // no company to look up. Company scope resolves the companyUid as before.
+    // no company to look up. Company scope resolves the companyUid through the
+    // anchor-aware resolver so an anchored path can never delete from a company
+    // other than the one it names.
     const companyUid = params.personal
         ? undefined
-        : await getCompanyUid(token, params.companySlug);
+        : await resolveCompanyUidForAnchoredPath(token, {
+            explicit: params.companySlug,
+            anchorSlug,
+        });
     const scopeArgs = params.personal
         ? { personal: true }
         : { companyUid };

package/dist/commands/mesh.js

@@ -7,9 +7,9 @@
  */
 import * as os from "node:os";
 import chalk from "chalk";
-import { loadCachedTokens } from "../utils/cognito-session.js";
+import { loadCachedTokens, isMachineIdentity } from "../utils/cognito-session.js";
 import * as readline from "node:readline/promises";
-import { STORY_STATUSES, appendThreadEvent, callerLabelFromToken, ensureProjectThread, eventPayload, listActiveThreads, patchStoryStatus, resolveActiveMembershipCompany, resolveMeshPrincipalUid, warmMeshConversationCache, } from "../lib/mesh/api.js";
+import { STORY_STATUSES, appendThreadEvent, callerLabelFromToken, ensureProjectThread, eventPayload, listActiveMembershipCompanies, listActiveThreads, patchStoryStatus, resolveActiveMembershipCompany, resolveMeshPrincipalUid, warmMeshConversationCache, } from "../lib/mesh/api.js";
 import { createCandidatesFetcher, createMigratePoster, createOrganizePoster, createWorkSessionDeliverer, fetchCompanyLive, formatCompanyLiveTable, openMeshTransport, probeMigrationCapabilityForMemberships, requireToken, } from "../lib/mesh/client.js";
 import { clearDefaultCompany, getDefaultCompany, readDeviceConfig, recordMigrationCapabilitySnapshot, setDefaultCompany, } from "../lib/work-context/config.js";
 import { DefaultCompanyLockedError, DefaultCompanyUnavailableError, } from "../lib/work-context/errors.js";
@@ -25,6 +25,9 @@ import { formatMigrateConfirmation, submitSessionMigration, } from "../lib/work-
 import { formatOrganizeList, prepareOrganizeDecision, settleOrganizeAskWithoutBind, submitOrganizeDecision, } from "../lib/work-context/organize.js";
 import { readSessionState } from "../lib/work-context/state.js";
 import { loadObservationFromFile, markUntracked, parseObservationJson, reconcileObservation, } from "../lib/work-context/reconcile.js";
+import { resolveCompany } from "../lib/work-context/company.js";
+import { deriveRemoteOwnerSlug, deriveRepoIdentityKey, } from "../lib/work-context/repo-remote.js";
+import { promptRepoCompany, } from "../lib/work-context/repo-prompt.js";
 import { requeueQuarantinedOutbox } from "../lib/work-context/outbox.js";
 export function formatCheckLines(threads, company, projectId) {
     if (threads.length === 0) {
@@ -180,6 +183,103 @@ async function runContextReconcile(opts) {
     }
     process.exitCode = outcome.exitCode;
 }
+/**
+ * `hq mesh context resolve` — interactive per-repo company prompt (gap 4).
+ *
+ * Owner decision: "Always ask per repo". When a person session is unresolved
+ * (needs_company) and this is an interactive person TTY, ask ONCE which company
+ * this repo's work is filed under, then remember it (persisted repo→company
+ * map). Never prompts on machine / agent-box identities (they resolve from the
+ * identity file) or in non-interactive / --json / --machine contexts — those
+ * fall through to needs_company exactly as before.
+ */
+async function runContextResolve(opts) {
+    const sessionId = opts.session?.trim();
+    if (!sessionId || !isValidSessionId(sessionId)) {
+        fail("`--session <sid>` is required and must be a valid session id");
+    }
+    const root = workContextHomeRoot();
+    const cwd = opts.cwd?.trim() || process.cwd();
+    const hqRoot = opts.hqRoot?.trim() || undefined;
+    const jsonMode = Boolean(opts.json || opts.machine);
+    const emit = (payload) => {
+        if (jsonMode) {
+            console.log(JSON.stringify(payload, null, opts.machine ? 0 : 2));
+        }
+    };
+    // Only prompt when the deterministic resolver leaves the session unresolved.
+    const remoteOwnerSlug = deriveRemoteOwnerSlug({ cwd, hqRoot }) ?? undefined;
+    const repoIdentityKey = deriveRepoIdentityKey({ cwd });
+    const resolution = resolveCompany({
+        root,
+        sessionId,
+        env: process.env,
+        cwd,
+        hqRoot,
+        remoteOwnerSlug,
+        repoIdentityKey,
+    });
+    if (resolution.status === "resolved") {
+        const c = resolution.company;
+        if (!jsonMode) {
+            console.error(chalk.dim(`Company already resolved via ${c.source}: ${c.slug ?? c.uid}`));
+        }
+        emit({ ok: true, status: "resolved", already: true, company: c });
+        return;
+    }
+    if (resolution.status === "company_conflict") {
+        if (!jsonMode) {
+            console.error(chalk.yellow("Company conflict — resolve with `hq mesh context correct`, not the per-repo prompt."));
+        }
+        emit({ ok: false, ...resolution });
+        process.exitCode = 1;
+        return;
+    }
+    // needs_company → interactive per-repo prompt (gated inside promptRepoCompany).
+    const outcome = await promptRepoCompany({
+        root,
+        cwd,
+        isMachineIdentity: () => isMachineIdentity(),
+        isInteractive: () => Boolean(process.stdin.isTTY && process.stdout.isTTY) && !jsonMode,
+        listMemberships: async () => {
+            const token = await requireToken();
+            return listActiveMembershipCompanies(token);
+        },
+        ask: async (question) => {
+            const rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stderr,
+            });
+            try {
+                return await rl.question(question);
+            }
+            finally {
+                rl.close();
+            }
+        },
+    });
+    if (outcome.status === "resolved") {
+        if (!jsonMode) {
+            const verb = outcome.alreadyMapped ? "already filed under" : "filed under";
+            console.error(chalk.green(`This repo is ${verb} ${outcome.company.slug}` +
+                `${outcome.company.uid ? ` (${outcome.company.uid})` : ""}.`));
+        }
+        emit({ ok: true, ...outcome });
+        return;
+    }
+    // Skipped — fall through to needs_company exactly as today.
+    if (!jsonMode) {
+        const reasons = {
+            machine: "Machine/agent-box identity — company comes from the identity file.",
+            non_interactive: "Non-interactive context — no prompt; session stays needs_company.",
+            no_repo_key: "Not inside a git repo — nothing to remember; needs_company.",
+            no_memberships: "No active memberships to choose from; needs_company.",
+            cancelled: "No selection made; session stays needs_company.",
+        };
+        console.error(chalk.dim(reasons[outcome.reason] ?? "needs_company"));
+    }
+    emit({ ok: true, status: "needs_company", skipped: outcome.reason });
+}
 async function runContextBackfillHeld(opts) {
     const root = workContextHomeRoot();
     const meshRoot = workMeshRoot(undefined, process.env);
@@ -808,6 +908,15 @@ export function registerMeshCommand(program) {
         .option("--machine", "Write exactly one ContextResult JSON line to stdout")
         .option("--offline", "Skip network; leave register operations queued in the outbox")
         .action((opts) => wrap(() => runContextReconcile(opts))());
+    context
+        .command("resolve")
+        .description("Interactively ask (once per repo) which company this repo's work is filed under, and remember it (gap 4). Person TTYs only — never agent boxes / non-interactive.")
+        .requiredOption("--session <sid>", "Canonical session id")
+        .option("--cwd <path>", "Working directory to derive the repo identity (defaults to cwd)")
+        .option("--hq-root <path>", "HQ root for deterministic company evidence")
+        .option("--json", "Print machine-readable JSON (suppresses the prompt)")
+        .option("--machine", "Compact JSON on stdout (suppresses the prompt)")
+        .action((opts) => wrap(() => runContextResolve(opts))());
     context
         .command("backfill-held")
         .description("Reconcile ENDED sessions whose held events lack a company so the daemon re-attributes the backlog (explicit, opt-in; no fleet fan-out)")

package/dist/lib/mesh/live/daemon/transcript-watch.js

@@ -32,7 +32,7 @@ import { CLI_VERSION } from "../../../../cli-version.js";
 import { companySlugFromCwd, projectIdFromCwd, resolveCompany, } from "../../../work-context/company.js";
 import { WORK_CONTEXT_CONTRACT_VERSION } from "../../../work-context/contract.js";
 import { reconcileObservation, } from "../../../work-context/reconcile.js";
-import { deriveRemoteOwnerSlug } from "../../../work-context/repo-remote.js";
+import { deriveRemoteOwnerSlug, deriveRepoIdentityKey, } from "../../../work-context/repo-remote.js";
 import { isHookWrittenSessionState, readSessionState, writeSessionState, } from "../../../work-context/state.js";
 import { enqueueSessionEvent } from "../enqueue.js";
 import { isValidSessionId } from "../session-identity.js";
@@ -448,6 +448,10 @@ export function resolveTranscriptRegistration(input) {
     const remoteOwnerSlug = input.cwd
         ? deriveRemoteOwnerSlug({ cwd: input.cwd, hqRoot: input.hqRoot })
         : null;
+    // Detached transcript watch never prompts, but honours a persisted repo map.
+    const repoIdentityKey = input.cwd
+        ? deriveRepoIdentityKey({ cwd: input.cwd })
+        : null;
     const resolution = resolveCompany({
         root: input.workContextRoot,
         sessionId: input.sessionId,
@@ -455,6 +459,7 @@ export function resolveTranscriptRegistration(input) {
         cwd: input.cwd,
         hqRoot: input.hqRoot,
         remoteOwnerSlug,
+        repoIdentityKey,
     });
     const company = resolution.status === "resolved" ? resolution.company : undefined;
     const companySlug = company?.slug;

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

@@ -8,6 +8,9 @@
  *   4. agent-box identity file (HQ_AGENT_IDENTITY_FILE → companyUid; source
  *      trusted_explicit — never "default company mode"; below HQ_SPAWN_COMPANY,
  *      above device default)
+ *   4b. persisted per-repo company map (gap 4 — person "always ask per repo",
+ *      remembered by repoIdentityKey; above the git-remote heuristic + device
+ *      default, below the identity file so an agent box always wins)
  *   5. enabled device default
  *   6. exactly one deterministic mapping (cwd under companies/{slug}/ or repo remote)
  *
@@ -16,7 +19,7 @@
  */
 import type { TrustedExplicitContext } from "./contract.js";
 import { type SessionStateFile } from "./state.js";
-export type CompanyResolutionSource = "trusted_explicit" | "existing_scope" | "session_meta" | "device_default" | "deterministic_cwd" | "deterministic_remote";
+export type CompanyResolutionSource = "trusted_explicit" | "existing_scope" | "session_meta" | "repo_map" | "device_default" | "deterministic_cwd" | "deterministic_remote";
 export interface ResolvedCompany {
     slug?: string;
     uid?: string;
@@ -55,6 +58,13 @@ export interface CompanyResolveInput {
     metaCompanySlug?: string | null;
     /** Optional injected deterministic remote ownership slug. */
     remoteOwnerSlug?: string | null;
+    /**
+     * Normalised per-repo identity key (deriveRepoIdentityKey). When present, the
+     * resolver consults the persisted repo→company map (gap 4) — above the
+     * git-remote heuristic and device default, below identity file / explicit /
+     * session-meta. Omitted (or unmapped) → the ladder falls through unchanged.
+     */
+    repoIdentityKey?: string | null;
 }
 /** Env naming the on-box identity.json (fleet agent boxes). */
 export declare const HQ_AGENT_IDENTITY_FILE_ENV = "HQ_AGENT_IDENTITY_FILE";

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

@@ -8,6 +8,9 @@
  *   4. agent-box identity file (HQ_AGENT_IDENTITY_FILE → companyUid; source
  *      trusted_explicit — never "default company mode"; below HQ_SPAWN_COMPANY,
  *      above device default)
+ *   4b. persisted per-repo company map (gap 4 — person "always ask per repo",
+ *      remembered by repoIdentityKey; above the git-remote heuristic + device
+ *      default, below the identity file so an agent box always wins)
  *   5. enabled device default
  *   6. exactly one deterministic mapping (cwd under companies/{slug}/ or repo remote)
  *
@@ -16,7 +19,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { getDefaultCompany } from "./config.js";
+import { getDefaultCompany, getRepoCompany } from "./config.js";
 import { authoritativeCompanyFromState, readSessionState, } from "./state.js";
 /** Pointer to the US-017B correction client (never auto-switches). */
 export const COMPANY_CORRECTION_PATH_PREFIX = "hq mesh context correct --session";
@@ -247,6 +250,19 @@ export function resolveCompany(input) {
             company: { uid: identityUid, source: "trusted_explicit" },
         };
     }
+    // 4b. Persisted per-repo company map (gap 4). A person answered once for this
+    // repo; remember it. Above the git-remote heuristic + device default, below
+    // the identity file / explicit / session-meta so an agent box always wins.
+    const repoKey = input.repoIdentityKey?.trim();
+    if (repoKey) {
+        const mapped = getRepoCompany(repoKey, { root: input.root });
+        if (mapped?.slug) {
+            return {
+                status: "resolved",
+                company: { slug: mapped.slug, uid: mapped.uid, source: "repo_map" },
+            };
+        }
+    }
     // 5 + 6. Device default vs deterministic evidence.
     const deviceDefault = getDefaultCompany({ root: input.root });
     const deterministic = resolveDeterministicCompany({

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

@@ -20,12 +20,27 @@ export interface MigrationCapabilitySnapshot {
         migration: boolean;
     }>;
 }
+/**
+ * Persisted per-repo company mapping (gap 4 — person "always ask per repo").
+ * Keyed by the normalised repo identity from deriveRepoIdentityKey
+ * (`remote:owner/name` or `root:<abs work-tree>`). Written only after a person
+ * answers the one-time interactive prompt; consulted by the resolver so the
+ * same repo never re-asks.
+ */
+export interface RepoCompanyMapping {
+    slug: string;
+    uid?: string;
+    updatedAt: string;
+}
+export type RepoCompanyMap = Record<string, RepoCompanyMapping>;
 export interface WorkContextDeviceConfig {
     schemaVersion: typeof DEVICE_CONFIG_SCHEMA_VERSION;
     /** Explicit device default. Never copied from activeCompany. */
     defaultCompany?: DeviceDefaultCompany | null;
     /** Last-known migration capability across memberships (doctor reports this). */
     migrationCapability?: MigrationCapabilitySnapshot | null;
+    /** Per-repo company map (gap 4). Remembers each repo's filed-under company. */
+    repoCompanyMap?: RepoCompanyMap | null;
     updatedAt: string;
 }
 /** true / { uid } = member; false = not a member. */
@@ -50,6 +65,19 @@ export declare function setDefaultCompany(slug: string, deps: DeviceConfigDeps &
     allowWithoutMigration?: boolean;
 }): Promise<WorkContextDeviceConfig>;
 export declare function clearDefaultCompany(deps: DeviceConfigDeps): WorkContextDeviceConfig;
+/**
+ * Read the persisted company mapping for a repo identity key (gap 4).
+ * Returns null when unmapped. Never throws.
+ */
+export declare function getRepoCompany(key: string, deps: Pick<DeviceConfigDeps, "root">): RepoCompanyMapping | null;
+/**
+ * Persist (or overwrite) the company mapping for a repo identity key (gap 4).
+ * Called after a person answers the one-time interactive prompt.
+ */
+export declare function setRepoCompany(key: string, mapping: {
+    slug: string;
+    uid?: string;
+}, deps: Pick<DeviceConfigDeps, "root" | "now">): WorkContextDeviceConfig;
 /** Persist the last memberships-wide migration capability probe (US-017B). */
 export declare function recordMigrationCapabilitySnapshot(snapshot: MigrationCapabilitySnapshot, deps: Pick<DeviceConfigDeps, "root" | "now">): WorkContextDeviceConfig;
 /** Convenience: build deps from HOME / injectable root. */

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

@@ -15,9 +15,36 @@ function emptyConfig(now) {
         schemaVersion: DEVICE_CONFIG_SCHEMA_VERSION,
         defaultCompany: null,
         migrationCapability: null,
+        repoCompanyMap: null,
         updatedAt: now().toISOString(),
     };
 }
+/** Sanitize a raw repoCompanyMap from disk: drop malformed entries. */
+function sanitizeRepoCompanyMap(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!key.trim())
+            continue;
+        if (!value || typeof value !== "object")
+            continue;
+        const v = value;
+        const slug = typeof v.slug === "string" ? v.slug.trim() : "";
+        if (!slug)
+            continue;
+        const entry = {
+            slug,
+            updatedAt: typeof v.updatedAt === "string" && v.updatedAt.trim()
+                ? v.updatedAt
+                : new Date(0).toISOString(),
+        };
+        if (typeof v.uid === "string" && v.uid.trim())
+            entry.uid = v.uid.trim();
+        out[key] = entry;
+    }
+    return Object.keys(out).length > 0 ? out : null;
+}
 function assertSafeConfigPath(configPath) {
     const dir = path.dirname(configPath);
     try {
@@ -60,6 +87,7 @@ export function readDeviceConfig(deps) {
             schemaVersion: DEVICE_CONFIG_SCHEMA_VERSION,
             defaultCompany: raw.defaultCompany ?? null,
             migrationCapability: raw.migrationCapability ?? null,
+            repoCompanyMap: sanitizeRepoCompanyMap(raw.repoCompanyMap),
             updatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : new Date(0).toISOString(),
         };
         return cleaned;
@@ -122,6 +150,7 @@ export async function setDefaultCompany(slug, deps) {
         schemaVersion: DEVICE_CONFIG_SCHEMA_VERSION,
         defaultCompany,
         migrationCapability: prior.migrationCapability ?? null,
+        repoCompanyMap: prior.repoCompanyMap ?? null,
         updatedAt: now().toISOString(),
     };
     writeDeviceConfig(deps, next);
@@ -134,11 +163,56 @@ export function clearDefaultCompany(deps) {
         schemaVersion: DEVICE_CONFIG_SCHEMA_VERSION,
         defaultCompany: null,
         migrationCapability: prior.migrationCapability ?? null,
+        repoCompanyMap: prior.repoCompanyMap ?? null,
         updatedAt: now().toISOString(),
     };
     writeDeviceConfig(deps, next);
     return next;
 }
+/**
+ * Read the persisted company mapping for a repo identity key (gap 4).
+ * Returns null when unmapped. Never throws.
+ */
+export function getRepoCompany(key, deps) {
+    const trimmed = key?.trim();
+    if (!trimmed)
+        return null;
+    const cfg = readDeviceConfig(deps);
+    const entry = cfg.repoCompanyMap?.[trimmed];
+    if (!entry || !entry.slug?.trim())
+        return null;
+    return entry;
+}
+/**
+ * Persist (or overwrite) the company mapping for a repo identity key (gap 4).
+ * Called after a person answers the one-time interactive prompt.
+ */
+export function setRepoCompany(key, mapping, deps) {
+    const trimmed = key?.trim();
+    if (!trimmed) {
+        throw new WorkContextError("InvalidRepoKey", "Empty repo identity key");
+    }
+    const slug = mapping.slug?.trim();
+    if (!slug || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(slug)) {
+        throw new WorkContextError("InvalidCompanySlug", `Invalid company slug: ${mapping.slug}`);
+    }
+    const now = deps.now ?? (() => new Date());
+    const prior = readDeviceConfig({ root: deps.root });
+    const entry = { slug, updatedAt: now().toISOString() };
+    const uid = mapping.uid?.trim();
+    if (uid)
+        entry.uid = uid;
+    const nextMap = { ...(prior.repoCompanyMap ?? {}), [trimmed]: entry };
+    const next = {
+        schemaVersion: DEVICE_CONFIG_SCHEMA_VERSION,
+        defaultCompany: prior.defaultCompany ?? null,
+        migrationCapability: prior.migrationCapability ?? null,
+        repoCompanyMap: nextMap,
+        updatedAt: now().toISOString(),
+    };
+    writeDeviceConfig({ root: deps.root }, next);
+    return next;
+}
 /** Persist the last memberships-wide migration capability probe (US-017B). */
 export function recordMigrationCapabilitySnapshot(snapshot, deps) {
     const prior = readDeviceConfig(deps);
@@ -155,6 +229,7 @@ export function recordMigrationCapabilitySnapshot(snapshot, deps) {
                 migration: c.migration,
             })),
         },
+        repoCompanyMap: prior.repoCompanyMap ?? null,
         updatedAt: now().toISOString(),
     };
     writeDeviceConfig({ root: deps.root }, next);

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

@@ -17,7 +17,9 @@ export { decisionFromCandidates, digestOrganizePayload, formatOrganizeList, prep
 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 { deriveRemoteOwnerSlug, deriveRepoIdentityKey, findWorkTreeRoot, matchCompanySlugForRepo, normalizeRemoteOwnerName, } from "./repo-remote.js";
+export { matchMembershipAnswer, promptRepoCompany, } from "./repo-prompt.js";
+export type { RepoPromptCompany, RepoPromptDeps, RepoPromptOutcome, RepoPromptSkipReason, } from "./repo-prompt.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

@@ -15,6 +15,7 @@ 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 { deriveRemoteOwnerSlug, deriveRepoIdentityKey, findWorkTreeRoot, matchCompanySlugForRepo, normalizeRemoteOwnerName, } from "./repo-remote.js";
+export { matchMembershipAnswer, promptRepoCompany, } from "./repo-prompt.js";
 export { loadObservationFromFile, markUntracked, parseObservationJson, reconcileObservation, } from "./reconcile.js";
 //# sourceMappingURL=index.js.map

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

@@ -9,7 +9,7 @@ import { WORK_CONTEXT_CONTRACT_VERSION, normalizeTaskId, } from "./contract.js";
 import { EXIT_INVALID_IDENTITY, EXIT_NOT_TRACKING, EXIT_OK, InvalidDecisionOriginError, NotTrackingError, } from "./errors.js";
 import { decisionFromCandidates, } from "./organize.js";
 import { resolveProjectTask, shouldAskAfter } from "./project.js";
-import { deriveRemoteOwnerSlug } from "./repo-remote.js";
+import { deriveRemoteOwnerSlug, deriveRepoIdentityKey } from "./repo-remote.js";
 import { enqueueOutbox, markOutboxAcked, markOutboxQuarantined, markOutboxQueued, replayOutbox, } from "./outbox.js";
 import { mergeLocalSessionFields, readSessionState, writeSessionState, } from "./state.js";
 function resultOf(parts) {
@@ -210,6 +210,9 @@ export async function reconcileObservation(obs, deps) {
             cwd: cwd ?? process.cwd(),
             hqRoot,
         }) ?? undefined;
+    // Persisted per-repo company map key (gap 4). The detached reconcile path
+    // NEVER prompts, but it does honour a mapping a person already answered.
+    const repoIdentityKey = deriveRepoIdentityKey({ cwd: cwd ?? process.cwd() });
     const company = resolveCompany({
         root: deps.root,
         sessionId,
@@ -218,6 +221,7 @@ export async function reconcileObservation(obs, deps) {
         cwd,
         hqRoot,
         remoteOwnerSlug,
+        repoIdentityKey,
         existingState: prior,
     });
     const nowIso = nowFn().toISOString();

package/dist/lib/work-context/repo-prompt.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Interactive per-repo company prompt (Work Mesh Live gap 4 — person attribution).
+ *
+ * Owner decision ("Always ask per repo"): every person is asked ONCE PER REPO
+ * which company the work is filed under, then the answer is remembered for that
+ * repo (persisted repo→company map in the device config).
+ *
+ * Hard gates — the prompt NEVER fires:
+ *   - on machine / agent-box identities (isMachineIdentity) — those resolve from
+ *     the identity file, never a prompt;
+ *   - when stdin/stdout is not a TTY, or in --json / --machine / non-interactive
+ *     contexts;
+ *   - when cwd is not inside a git repo (no stable key to remember an answer);
+ *   - when the repo is already mapped (a second resolve is silent).
+ *
+ * There is NO auto-pick from a sole membership: even a caller with exactly one
+ * active membership is asked once. The core is dependency-injected so tests never
+ * need a real TTY, network, or identity file.
+ */
+import { type RepoCompanyMapping } from "./config.js";
+export interface RepoPromptCompany {
+    companyUid: string;
+    companySlug: string;
+}
+export interface RepoPromptDeps {
+    /** Work-context config root (~/.hq/work-context or injected tmp). */
+    root: string;
+    /** cwd used to derive the repo identity key. */
+    cwd?: string;
+    /** True when the caller is a machine / agent-box identity. */
+    isMachineIdentity: () => boolean;
+    /** True only for an interactive person TTY (not --json/--machine/piped). */
+    isInteractive: () => boolean;
+    /** Caller's active membership companies (reused across memberships). */
+    listMemberships: () => Promise<RepoPromptCompany[]>;
+    /** Ask a single plain question; returns the raw answer (trimmed by caller). */
+    ask: (question: string) => Promise<string>;
+    /** Injectable repo key derivation (defaults to deriveRepoIdentityKey). */
+    deriveKey?: (cwd?: string) => string | null;
+    /** Injectable persisted-map lookup (defaults to getRepoCompany). */
+    lookup?: (key: string, root: string) => RepoCompanyMapping | null;
+    /** Injectable persistence (defaults to setRepoCompany). */
+    persist?: (key: string, mapping: {
+        slug: string;
+        uid?: string;
+    }, root: string) => void;
+    now?: () => Date;
+}
+export type RepoPromptSkipReason = "machine" | "non_interactive" | "no_repo_key" | "no_memberships" | "cancelled";
+export type RepoPromptOutcome = {
+    status: "resolved";
+    repoKey: string;
+    company: {
+        slug: string;
+        uid?: string;
+    };
+    /** true when this call wrote the mapping; false when already remembered. */
+    persisted: boolean;
+    alreadyMapped: boolean;
+} | {
+    status: "skipped";
+    reason: RepoPromptSkipReason;
+    repoKey?: string;
+};
+/** Match a raw answer to a membership by 1-based number or slug/uid. */
+export declare function matchMembershipAnswer(answer: string, companies: RepoPromptCompany[]): RepoPromptCompany | null;
+/**
+ * Resolve a repo's company via the one-time interactive prompt (gap 4).
+ * Pure control flow over injected effects — no direct TTY/network/fs beyond the
+ * default config helpers. Callers must first confirm the session is unresolved
+ * (needs_company); this only decides whether/how to prompt and persist.
+ */
+export declare function promptRepoCompany(deps: RepoPromptDeps): Promise<RepoPromptOutcome>;
+//# sourceMappingURL=repo-prompt.d.ts.map

package/dist/lib/work-context/repo-prompt.js

@@ -0,0 +1,98 @@
+/**
+ * Interactive per-repo company prompt (Work Mesh Live gap 4 — person attribution).
+ *
+ * Owner decision ("Always ask per repo"): every person is asked ONCE PER REPO
+ * which company the work is filed under, then the answer is remembered for that
+ * repo (persisted repo→company map in the device config).
+ *
+ * Hard gates — the prompt NEVER fires:
+ *   - on machine / agent-box identities (isMachineIdentity) — those resolve from
+ *     the identity file, never a prompt;
+ *   - when stdin/stdout is not a TTY, or in --json / --machine / non-interactive
+ *     contexts;
+ *   - when cwd is not inside a git repo (no stable key to remember an answer);
+ *   - when the repo is already mapped (a second resolve is silent).
+ *
+ * There is NO auto-pick from a sole membership: even a caller with exactly one
+ * active membership is asked once. The core is dependency-injected so tests never
+ * need a real TTY, network, or identity file.
+ */
+import { setRepoCompany, getRepoCompany } from "./config.js";
+import { deriveRepoIdentityKey } from "./repo-remote.js";
+function buildQuestion(companies) {
+    const lines = companies.map((c, i) => `  ${i + 1}) ${c.companySlug}${c.companyUid ? ` (${c.companyUid})` : ""}`);
+    return [
+        "Which company is this repo's work filed under?",
+        ...lines,
+        "Enter a number (or company slug): ",
+    ].join("\n");
+}
+/** Match a raw answer to a membership by 1-based number or slug/uid. */
+export function matchMembershipAnswer(answer, companies) {
+    const trimmed = answer.trim();
+    if (!trimmed)
+        return null;
+    if (/^\d+$/.test(trimmed)) {
+        const idx = Number.parseInt(trimmed, 10) - 1;
+        return idx >= 0 && idx < companies.length ? companies[idx] : null;
+    }
+    const needle = trimmed.toLowerCase();
+    const matches = companies.filter((c) => c.companySlug.toLowerCase() === needle ||
+        c.companyUid.toLowerCase() === needle);
+    return matches.length === 1 ? matches[0] : null;
+}
+/**
+ * Resolve a repo's company via the one-time interactive prompt (gap 4).
+ * Pure control flow over injected effects — no direct TTY/network/fs beyond the
+ * default config helpers. Callers must first confirm the session is unresolved
+ * (needs_company); this only decides whether/how to prompt and persist.
+ */
+export async function promptRepoCompany(deps) {
+    // Gate 1: machine / agent-box identities never prompt.
+    if (deps.isMachineIdentity()) {
+        return { status: "skipped", reason: "machine" };
+    }
+    // Gate 2: only interactive person TTYs prompt.
+    if (!deps.isInteractive()) {
+        return { status: "skipped", reason: "non_interactive" };
+    }
+    const deriveKey = deps.deriveKey ?? ((cwd) => deriveRepoIdentityKey({ cwd }));
+    const repoKey = deriveKey(deps.cwd);
+    // Gate 3: no repo → nothing stable to remember; do not prompt.
+    if (!repoKey) {
+        return { status: "skipped", reason: "no_repo_key" };
+    }
+    // Already remembered → silent resolve (a second resolve never re-asks).
+    const lookup = deps.lookup ?? ((key, root) => getRepoCompany(key, { root }));
+    const existing = lookup(repoKey, deps.root);
+    if (existing?.slug) {
+        return {
+            status: "resolved",
+            repoKey,
+            company: { slug: existing.slug, uid: existing.uid },
+            persisted: false,
+            alreadyMapped: true,
+        };
+    }
+    const memberships = await deps.listMemberships();
+    if (!memberships || memberships.length === 0) {
+        return { status: "skipped", reason: "no_memberships", repoKey };
+    }
+    // Always ask — NO auto-pick, even for a sole membership.
+    const answer = await deps.ask(buildQuestion(memberships));
+    const chosen = matchMembershipAnswer(answer, memberships);
+    if (!chosen) {
+        return { status: "skipped", reason: "cancelled", repoKey };
+    }
+    const persist = deps.persist ??
+        ((key, mapping, root) => setRepoCompany(key, mapping, { root, now: deps.now }));
+    persist(repoKey, { slug: chosen.companySlug, uid: chosen.companyUid }, deps.root);
+    return {
+        status: "resolved",
+        repoKey,
+        company: { slug: chosen.companySlug, uid: chosen.companyUid },
+        persisted: true,
+        alreadyMapped: false,
+    };
+}
+//# sourceMappingURL=repo-prompt.js.map

package/dist/lib/work-context/repo-remote.d.ts

@@ -30,6 +30,23 @@ export declare function readOriginRemoteUrl(gitDir: string): string | null;
  */
 export declare function matchCompanySlugForRepo(ownerName: string, companies: CompaniesManifestMap): string | null;
 export declare function readCompaniesManifestMap(hqRoot: string): CompaniesManifestMap | null;
+/**
+ * Walk up from startDir to the working-tree root (the dir that *contains* a
+ * `.git` entry). Unlike findEnclosingGitDir this returns the work tree, not the
+ * gitdir, so it is a stable per-repo identity for the fallback repo key.
+ */
+export declare function findWorkTreeRoot(startDir: string): string | null;
+/**
+ * Stable per-repo identity key for the persisted repo→company map (gap 4).
+ *
+ * Prefers the normalised git-remote `remote:owner/name` (lower-cased) so a repo
+ * keeps one mapping across clones/worktrees; falls back to `root:<abs work-tree>`
+ * when there is no recognised origin. Returns null when cwd is not inside a repo.
+ * Never runs git; never throws.
+ */
+export declare function deriveRepoIdentityKey(opts: {
+    cwd?: string;
+}): string | null;
 /**
  * Derive the deterministic remote-owner company slug from cwd + HQ manifest.
  * Returns null when there is no unique match.

package/dist/lib/work-context/repo-remote.js

@@ -173,6 +173,51 @@ export function readCompaniesManifestMap(hqRoot) {
         return null;
     }
 }
+/**
+ * Walk up from startDir to the working-tree root (the dir that *contains* a
+ * `.git` entry). Unlike findEnclosingGitDir this returns the work tree, not the
+ * gitdir, so it is a stable per-repo identity for the fallback repo key.
+ */
+export function findWorkTreeRoot(startDir) {
+    let cur = path.resolve(startDir);
+    for (;;) {
+        try {
+            if (fs.existsSync(path.join(cur, ".git")))
+                return cur;
+        }
+        catch {
+            return null;
+        }
+        const parent = path.dirname(cur);
+        if (parent === cur)
+            return null;
+        cur = parent;
+    }
+}
+/**
+ * Stable per-repo identity key for the persisted repo→company map (gap 4).
+ *
+ * Prefers the normalised git-remote `remote:owner/name` (lower-cased) so a repo
+ * keeps one mapping across clones/worktrees; falls back to `root:<abs work-tree>`
+ * when there is no recognised origin. Returns null when cwd is not inside a repo.
+ * Never runs git; never throws.
+ */
+export function deriveRepoIdentityKey(opts) {
+    const cwd = opts.cwd?.trim() ? path.resolve(opts.cwd) : process.cwd();
+    const gitDir = findEnclosingGitDir(cwd);
+    if (gitDir) {
+        const origin = readOriginRemoteUrl(gitDir);
+        if (origin) {
+            const ownerName = normalizeRemoteOwnerName(origin);
+            if (ownerName)
+                return `remote:${ownerName.toLowerCase()}`;
+        }
+    }
+    const workTree = findWorkTreeRoot(cwd);
+    if (workTree)
+        return `root:${workTree}`;
+    return null;
+}
 /**
  * Derive the deterministic remote-owner company slug from cwd + HQ manifest.
  * Returns null when there is no unique match.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.108.23",
+  "version": "5.108.25",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -31,7 +31,7 @@
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
-    "@indigoai-us/hq-cloud": "~6.16.23",
+    "@indigoai-us/hq-cloud": "~6.16.28",
     "@indigoai-us/hq-flags-client": "^0.1.2",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",