@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/commands/mesh.js

@@ -5,37 +5,57 @@
  * require hq-pack-work-mesh on disk and does not start MQTT listen.
  * Distinct from `hq doctor` (hook guardrails).
  */
+import { resolve as resolvePath } from "node:path";
 import * as os from "node:os";
+import { readFileSync } from "node:fs";
+import { findHqRoot } from "../utils/manifest.js";
+import { CLI_VERSION } from "../cli-version.js";
 import chalk from "chalk";
-import { loadCachedTokens, isMachineIdentity } from "../utils/cognito-session.js";
+import { ensureCognitoToken, isExpiring, isMachineIdentity, loadCachedTokens, } from "../utils/cognito-session.js";
 import * as readline from "node:readline/promises";
-import { STORY_STATUSES, appendThreadEvent, callerLabelFromToken, ensureProjectThread, eventPayload, listActiveMembershipCompanies, listActiveThreads, patchStoryStatus, resolveActiveMembershipCompany, resolveMeshPrincipalUid, warmMeshConversationCache, } from "../lib/mesh/api.js";
+import { STORY_STATUSES, appendThreadEvent, ensureProjectThread, eventPayload, getProjectView, listActiveMembershipCompanies, listActiveThreads, patchStory, putProjectView, registerMeshProject, resolveActiveMembershipCompany, resolveMeshPrincipalUid, warmMeshConversationCache, } from "../lib/mesh/api.js";
+import { closeSupersededProjectThread, ensureMissingBoardStories, ensureProjectBoard, boardStoryStatus, formatStoryStatusChanges, mergeProjectStories, prdSyncEventsThatChangeBoard, } from "../lib/mesh/project-board.js";
+import { mapSourceStoryStatus } from "../lib/mesh/story-status.js";
+import { buildPreflightFixtures } from "../lib/work-context/preflight-contract.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";
+import { clearDefaultCompany, isDefaultCompanyDisabled, readDeviceConfig, recordMigrationCapabilitySnapshot, setRepairHeldWithDefault, setDefaultCompany, } from "../lib/work-context/config.js";
+import { ensureDefaultCompany } from "../lib/work-context/default-company.js";
+import { DefaultCompanyUnavailableError, } from "../lib/work-context/errors.js";
 import { isValidSessionId } from "../lib/mesh/live/session-identity.js";
 import { CLI_KIND_TO_SCHEMA, resolveEnqueueSessionId, } from "../lib/mesh/live/index.js";
 import { flushSessionEvents } from "../lib/mesh/live/flush.js";
 import { backfillHeldSessions } from "../lib/mesh/live/backfill-held.js";
 import { createSessionEventsPoster, resolveVaultApiBase, } from "../lib/mesh/live/session-events-client.js";
-import { buildEmitEvidence } from "../lib/mesh/live/emit-evidence.js";
+const ONLINE_MEMBERSHIP_VALIDATION_TIMEOUT_MS = 5_000;
+// Leave 500 ms of headroom inside SessionStart's 2 s process-group limit.
+const OFFLINE_MEMBERSHIP_VALIDATION_TIMEOUT_MS = 1_500;
+import { buildEmitEvidence, machineEmitDisposition } from "../lib/mesh/live/emit-evidence.js";
+import { appendHeldLine } from "../lib/mesh/live/spool.js";
 import { createEmitPoster, buildMeshEmitEvent } from "../lib/mesh/live/emit-client.js";
-import { emitEvents } from "../lib/mesh/live/emit.js";
+import { enrichSessionEndEvent } from "../lib/mesh/live/report-summary.js";
+import { emitEvents, formatEmitRejectionLines } from "../lib/mesh/live/emit.js";
 import { readEmitRetry, writeEmitRetry } from "../lib/mesh/live/emit-retry.js";
 import { generateUlid } from "../lib/mesh/live/ulid.js";
 import { readLegacyBacklog } from "../lib/mesh/live/emit-replay.js";
 import { resolveMeshEmitMode, writeMeshConfigMode, } from "../lib/mesh/live/daemon/mode.js";
 import { workMeshRoot } from "../lib/mesh/live/paths.js";
-import { buildInstallPaths, collectDaemonDoctor, daemonServiceStatus, detectPlatform, formatDaemonDoctor, installDaemonService, readDaemonState, runMeshDaemon, uninstallDaemonService, daemonDir, } from "../lib/mesh/live/daemon/index.js";
+import { buildInstallPaths, collectDaemonDoctor, daemonServiceIsLoaded, daemonServiceStatus, findAncestorHqRoot, resolveInstallHqRoot, detectPlatform, formatCliIdentityLines, formatDaemonDoctor, installDaemonIfStale, installDaemonService, readDaemonState, resolveAbsoluteNodeBinary, resolveRunningCliEntry, runMeshDaemon, uninstallDaemonService, } from "../lib/mesh/live/daemon/index.js";
+import { defaultRunCommand } from "../lib/service-manager/launchd.js";
 import { workContextRoot } from "../lib/work-context/paths.js";
 import { formatMigrateConfirmation, submitSessionMigration, } from "../lib/work-context/migrate.js";
 import { formatOrganizeList, prepareOrganizeDecision, settleOrganizeAskWithoutBind, submitOrganizeDecision, } from "../lib/work-context/organize.js";
-import { readSessionState } from "../lib/work-context/state.js";
+import { applyOperatorProjectBinding, readSessionState, updateSessionState, } from "../lib/work-context/state.js";
+import { findLocalPrd, listNeedsProjectSessions } from "../lib/work-context/bind-best.js";
+import { bindCallingSession, formatSessionBoundLine } from "../lib/work-context/bind-calling-session.js";
+import { rebindNeedsProjectOnPrompt } from "../lib/work-context/prompt-rebind.js";
+import { planPrdSync, rebindSessionToProject } from "../lib/work-context/prd-sync.js";
+import { reserveSessionSeq } from "../lib/mesh/live/session-seq.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";
+import { handOffInstallHere } from "../lib/daemon/handoff.js";
 export function formatCheckLines(threads, company, projectId) {
     if (threads.length === 0) {
         return ["Work mesh: no active project threads found."];
@@ -43,14 +63,22 @@ export function formatCheckLines(threads, company, projectId) {
     const scope = projectId
         ? `${company.companySlug || company.companyUid}/${projectId}`
         : company.companySlug || company.companyUid;
-    const lines = [`Work mesh: ${threads.length} active thread(s) for ${scope}`];
+    const lines = [`Work mesh: ${threads.length} thread(s) for ${scope}`];
     for (const thread of threads.slice(0, 8)) {
         const owner = thread.ownerUid ? ` owner=${thread.ownerUid}` : "";
         const summary = thread.progressSummary ||
             thread.sourceSignalSummary ||
             thread.blockedReason ||
             "";
-        lines.push(`- ${thread.threadStatus ?? "unknown"} ${thread.threadId ?? "?"}${owner}${summary ? `: ${summary}` : ""}`);
+        const lane = thread.kind === "lane" ? thread.lane : undefined;
+        const laneDetails = lane
+            ? ` lane=${lane.laneId} laneStatus=${thread.laneStatus ?? "unknown"}` +
+                ` story=${lane.storyId ?? "unknown"} profile=${lane.workerProfile ?? "unknown"}` +
+                ` model=${lane.model ?? "unknown"} account=${lane.account ?? "unknown"}` +
+                `${lane.parentLaneId ? ` parent=${lane.parentLaneId}` : ""}`
+            : "";
+        const machine = thread.senderMachineUid ? ` machine=${thread.senderMachineUid}` : "";
+        lines.push(`- ${thread.threadStatus ?? "unknown"} ${thread.threadId ?? "?"}${owner}${machine}${laneDetails}${summary ? `: ${summary}` : ""}`);
     }
     return lines;
 }
@@ -85,12 +113,20 @@ async function runCheck(opts) {
 async function runEvent(verb, opts) {
     const { token, company } = await withCompany(opts);
     const projectId = requireProject(opts);
+    const eventKind = verb === "start" ? "claim" : verb;
+    let claimant = "";
+    if (eventKind === "claim") {
+        const resolvedClaimant = await resolveMeshPrincipalUid(token, loadCachedTokens());
+        if (!resolvedClaimant) {
+            fail("Could not resolve the authenticated claimant. Sign in again and retry `hq mesh start`.");
+        }
+        claimant = resolvedClaimant;
+    }
     const ensured = await ensureProjectThread(token, company, projectId, {
         threadId: opts.threadId,
         summary: opts.summary,
     });
-    const eventKind = verb === "start" ? "claim" : verb;
-    const event = await appendThreadEvent(token, company.companyUid, ensured.threadId, eventKind, eventPayload(eventKind, opts, callerLabelFromToken(token)));
+    const event = await appendThreadEvent(token, company.companyUid, ensured.threadId, eventKind, eventPayload(eventKind, opts, claimant));
     if (opts.json) {
         console.log(JSON.stringify({
             ok: true,
@@ -109,33 +145,705 @@ async function runEvent(verb, opts) {
 async function runStory(opts) {
     const storyId = opts.story?.trim();
     const status = opts.status?.trim();
-    if (!storyId || !status || !STORY_STATUSES.has(status)) {
-        fail("story requires --story <id> and --status queued|in_progress|review|done");
+    const assignee = opts.assignee?.trim();
+    if (!storyId) {
+        fail("story requires --story <id>");
+    }
+    if (!status && !assignee) {
+        fail("story requires --status queued|in_progress|review|done or --assignee <uid|me|none>");
+    }
+    if (status && !STORY_STATUSES.has(status)) {
+        fail("story --status must be queued|in_progress|review|done");
     }
     const { token, company } = await withCompany(opts);
     const projectId = requireProject(opts);
-    const patched = await patchStoryStatus(token, company.companyUid, projectId, storyId, status);
+    let assigneeUid;
+    let clearAssignee = false;
+    if (assignee === "none") {
+        clearAssignee = true;
+    }
+    else if (assignee === "me") {
+        const resolved = await resolveMeshPrincipalUid(token, loadCachedTokens());
+        if (!resolved || resolved === "session") {
+            fail("`--assignee me` needs the signed-in person or agent. The synthetic session identity cannot be assigned. Sign in again and retry `hq mesh story`.");
+        }
+        assigneeUid = resolved;
+    }
+    else if (assignee) {
+        if (!/^(prs|agt)_/.test(assignee)) {
+            fail("`--assignee` must be a person or agent uid, `me`, or `none`.");
+        }
+        assigneeUid = assignee;
+    }
+    const patched = await patchStory(token, company.companyUid, projectId, storyId, {
+        ...(status ? { status } : {}),
+        ...(assigneeUid ? { assigneeUid } : {}),
+        ...(clearAssignee ? { clearAssignee: true } : {}),
+    });
     if (opts.json) {
         console.log(JSON.stringify({ ok: true, action: "story", company, ...patched, storyId }, null, 2));
         return;
     }
-    console.log(`Work mesh: story ${storyId} → ${patched.status} (v${patched.version ?? "?"})`);
+    const assignment = assignee === "none"
+        ? "assignee cleared"
+        : assignee
+            ? `assignee ${patched.assigneeUid ?? assigneeUid}`
+            : "";
+    const statusPart = status ? `${storyId} → ${patched.status}` : storyId;
+    console.log(`Work mesh: story ${statusPart}${assignment ? ` ${assignment}` : ""} (v${patched.version ?? "?"})`);
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function parseProjectRepoSpec(value, source) {
+    const raw = value.trim();
+    const separator = raw.lastIndexOf("@");
+    const path = (separator > 0 ? raw.slice(0, separator) : raw).trim();
+    const branch = (separator > 0 ? raw.slice(separator + 1) : "").trim();
+    if (!path)
+        fail(`${source} requires a non-empty repository path.`);
+    if (separator > 0 && !branch)
+        fail(`${source} has an empty branch after @.`);
+    return { path, branch };
+}
+function parseProjectRepos(value, source) {
+    if (!Array.isArray(value))
+        fail(`${source} must be a JSON repository array.`);
+    return value.map((raw, index) => {
+        if (typeof raw === "string")
+            return parseProjectRepoSpec(raw, `${source}[${index}]`);
+        const repo = record(raw);
+        const path = typeof repo?.path === "string"
+            ? repo.path.trim()
+            : typeof repo?.repoPath === "string"
+                ? repo.repoPath.trim()
+                : typeof repo?.repo === "string"
+                    ? repo.repo.trim()
+                    : "";
+        const branchValue = repo?.branch ?? repo?.branchName;
+        const branch = branchValue === undefined ? "" : typeof branchValue === "string" ? branchValue.trim() : null;
+        if (!repo || !path)
+            fail(`${source}[${index}].path requires a string.`);
+        if (branch === null)
+            fail(`${source}[${index}].branch requires a string.`);
+        return { path, branch };
+    });
+}
+function parseProjectReposJson(raw, source) {
+    try {
+        return parseProjectRepos(JSON.parse(raw), source);
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            fail(`${source} must contain valid JSON.`);
+        throw err;
+    }
+}
+function projectStoriesFromJson(value, source) {
+    const plan = Array.isArray(value) ? null : record(value);
+    const rawStories = Array.isArray(value)
+        ? value
+        : Array.isArray(plan?.userStories)
+            ? plan.userStories
+            : Array.isArray(plan?.stories)
+                ? plan.stories
+                : null;
+    if (!rawStories) {
+        fail(`${source} must be a JSON story array or an object with userStories.`);
+    }
+    const stories = rawStories.map((raw, index) => {
+        const story = record(raw);
+        const id = typeof story?.id === "string" ? story.id.trim() : "";
+        const title = typeof story?.title === "string" ? story.title.trim() : "";
+        if (!story || !id || !title) {
+            fail(`${source} userStories[${index}] requires string id and title.`);
+        }
+        const status = mapSourceStoryStatus(story, `${source} userStories[${index}]`);
+        const resolvedStatus = status || (story.passes === true ? "done" : undefined);
+        return {
+            id,
+            title,
+            ...(typeof story.description === "string" ? { description: story.description } : {}),
+            ...(Array.isArray(story.acceptanceCriteria)
+                ? {
+                    acceptanceCriteria: story.acceptanceCriteria.filter((item) => typeof item === "string"),
+                }
+                : {}),
+            ...(resolvedStatus ? { status: resolvedStatus } : {}),
+            // hq-pro makes passes mirror the Board status. A completed PRD story
+            // without an explicit status must therefore become done.
+            passes: resolvedStatus === "done",
+            ...(typeof story.priority === "number" && Number.isFinite(story.priority)
+                ? { priority: story.priority }
+                : {}),
+        };
+    });
+    const metadata = record(plan?.metadata);
+    const repos = metadata && Object.hasOwn(metadata, "repos")
+        ? parseProjectRepos(metadata.repos, `${source} metadata.repos`)
+        : undefined;
+    return {
+        ...(typeof plan?.name === "string" ? { name: plan.name } : {}),
+        ...(typeof plan?.description === "string" ? { description: plan.description } : {}),
+        stories,
+        ...(repos ? { repos } : {}),
+    };
+}
+function parseProjectPlan(raw, source) {
+    try {
+        return projectStoriesFromJson(JSON.parse(raw), source);
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            fail(`${source} must contain valid JSON.`);
+        throw err;
+    }
+}
+function httpStatus(err) {
+    if (err && typeof err === "object" && "status" in err && typeof err.status === "number") {
+        return err.status;
+    }
+    return undefined;
+}
+function mergeProjectRepos(current, planned) {
+    const plannedPaths = new Set(planned.map((repo) => repo.path));
+    return [...planned, ...current.filter((repo) => !plannedPaths.has(repo.path))];
+}
+async function runProjectSet(projectId, opts) {
+    if (opts.channel !== undefined && !opts.channel.trim()) {
+        fail("PROJECT_CHANNEL_INVALID: --channel must be a non-empty channel id.");
+    }
+    if (opts.storiesFile && opts.storiesJson) {
+        fail("Pass only one of --stories-file or --stories-json.");
+    }
+    if (opts.reposJson && opts.repo?.length) {
+        fail("Pass only one of --repos-json or --repo.");
+    }
+    const source = opts.storiesFile
+        ? parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile)
+        : opts.storiesJson
+            ? parseProjectPlan(opts.storiesJson, "--stories-json")
+            : undefined;
+    const explicitRepos = opts.reposJson
+        ? parseProjectReposJson(opts.reposJson, "--repos-json")
+        : opts.repo?.length
+            ? opts.repo.map((repo, index) => parseProjectRepoSpec(repo, `--repo[${index}]`))
+            : undefined;
+    const { token, company } = await withCompany(opts);
+    let current;
+    try {
+        current = await getProjectView(token, company.companyUid, projectId);
+    }
+    catch (err) {
+        if (httpStatus(err) === 404 && opts.create) {
+            if (!source && !opts.name?.trim()) {
+                fail("`--create` needs --name or a stories file when the Board view does not exist.");
+            }
+            current = undefined;
+        }
+        else {
+            throw err;
+        }
+    }
+    if (!current && !opts.create) {
+        fail(`Work mesh project ${projectId} has no Board view. Re-run with --create to add one.`);
+    }
+    const principalUid = await resolveMeshPrincipalUid(token, loadCachedTokens());
+    const PROJECT_CHANGED = "The Board changed while you were editing. Re-run to pick up the latest.";
+    let view;
+    let registration;
+    if (!current) {
+        const ensured = await ensureProjectBoard({
+            token,
+            company,
+            projectId,
+            name: opts.name?.trim() || source?.name || projectId,
+            description: opts.description !== undefined ? opts.description : source?.description ?? "",
+            stories: source?.stories ?? [],
+            repos: explicitRepos ?? source?.repos ?? [],
+            channelId: opts.channel,
+        });
+        view = ensured.view;
+        registration = ensured.registration;
+    }
+    else if (opts.name !== undefined || opts.description !== undefined || source !== undefined || explicitRepos !== undefined) {
+        const stories = source
+            ? mergeProjectStories(current.stories, source.stories, { resetStatus: Boolean(opts.resetStatus) })
+            : current.stories;
+        const statusChangeLine = source ? formatStoryStatusChanges(current.stories, stories) : undefined;
+        try {
+            view = await putProjectView(token, company.companyUid, projectId, {
+                name: opts.name?.trim() || source?.name || current.name,
+                ...(opts.description !== undefined
+                    ? { description: opts.description }
+                    : source?.description !== undefined
+                        ? { description: source.description }
+                        : { description: current.description }),
+                stories,
+                repos: explicitRepos ?? source?.repos ?? current.repos,
+                ...(current.version !== undefined ? { expectedVersion: current.version } : {}),
+            });
+        }
+        catch (err) {
+            const conflict = err;
+            if (conflict.status === 409 && conflict.code === "VERSION_CONFLICT") {
+                if (opts.json) {
+                    console.log(JSON.stringify({ ok: false, code: "VERSION_CONFLICT", error: PROJECT_CHANGED }));
+                }
+                fail(PROJECT_CHANGED);
+            }
+            throw err;
+        }
+        if (statusChangeLine) {
+            if (opts.json)
+                console.error(statusChangeLine);
+            else
+                console.log(statusChangeLine);
+        }
+    }
+    else {
+        view = current;
+    }
+    if (current && opts.channel !== undefined) {
+        registration = await registerMeshProject(token, company.companyUid, projectId, opts.channel);
+    }
+    if (!current && opts.create) {
+        noteCallingSessionBound(view.projectId, company);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({
+            ok: true,
+            action: "project.set",
+            principalUid,
+            ...view,
+            ...(registration ? { registration } : {}),
+        }, null, 2));
+        return;
+    }
+    console.log(`Work mesh: project ${view.projectId} set (${view.name}; ${view.stories.length} stories)`);
+}
+async function runProjectRegister(projectId, opts) {
+    if (opts.channel !== undefined && !opts.channel.trim()) {
+        fail("PROJECT_CHANNEL_INVALID: --channel must be a non-empty channel id.");
+    }
+    const { token, company } = await withCompany(opts);
+    const principalUid = await resolveMeshPrincipalUid(token, loadCachedTokens());
+    const companyRef = company.companySlug || company.companyUid;
+    try {
+        const board = await getProjectView(token, company.companyUid, projectId);
+        if (board.companyUid !== company.companyUid || board.projectId !== projectId) {
+            fail(`Work mesh project ${projectId} has no Board view in company ${companyRef}. Create the Board before registering it.`);
+        }
+    }
+    catch (err) {
+        if (httpStatus(err) === 404) {
+            fail(`Work mesh project ${projectId} has no Board view in company ${companyRef}. Create the Board before registering it.`);
+        }
+        throw err;
+    }
+    let registration;
+    try {
+        registration = await registerMeshProject(token, company.companyUid, projectId, opts.channel);
+    }
+    catch (err) {
+        const failure = err;
+        if (failure.status === 403 && failure.code === "PROJECT_NOT_IN_COMPANY") {
+            fail(`Work mesh project ${projectId} could not be registered in company ${companyRef}: the Board or its genesis thread is missing. Run "hq mesh project ensure ${projectId} --company ${companyRef} --stories-file <prd.json>" to create or restore them.`);
+        }
+        throw err;
+    }
+    const boardState = "registered";
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, action: "project.register", principalUid, boardState, ...registration }, null, 2));
+        return;
+    }
+    console.log(`Work mesh: project ${registration.projectId} registered (${boardState}; channel ${registration.channelId} ${registration.channelCreated ? "created" : "bound"})`);
+}
+async function runProjectEnsure(projectId, opts) {
+    if (!opts.storiesFile?.trim())
+        fail("`--stories-file <prd.json>` is required.");
+    const source = parseProjectPlan(readFileSync(opts.storiesFile, "utf8"), opts.storiesFile);
+    const { token, company } = await withCompany(opts);
+    let current;
+    try {
+        current = await getProjectView(token, company.companyUid, projectId);
+    }
+    catch (err) {
+        if (httpStatus(err) !== 404)
+            throw err;
+    }
+    if (opts.dryRun) {
+        if (current && (current.companyUid !== company.companyUid || current.projectId !== projectId)) {
+            fail("Work mesh project ensure dry-run: Board company or project id did not match the request.");
+        }
+        const stories = current ? mergeProjectStories(current.stories, source.stories) : source.stories;
+        const sourceStatuses = source.stories.map((story) => ({
+            id: story.id,
+            title: story.title,
+            status: boardStoryStatus(story),
+        }));
+        const boardStatuses = stories.map((story) => ({
+            id: story.id,
+            title: story.title,
+            status: boardStoryStatus(story),
+        }));
+        if (opts.json) {
+            console.log(JSON.stringify({
+                ok: true,
+                action: "project.ensure.dry-run",
+                projectId,
+                companyUid: company.companyUid,
+                sourceStatuses,
+                stories: boardStatuses,
+            }, null, 2));
+        }
+        else {
+            console.log(`Work mesh: project ${projectId} dry run (${sourceStatuses.length} source stories)`);
+            console.log("Source statuses:");
+            for (const story of sourceStatuses)
+                console.log(`${story.id}\t${story.status}`);
+            console.log("Merged Board statuses:");
+            for (const story of boardStatuses)
+                console.log(`${story.id}\t${story.status}`);
+        }
+        return;
+    }
+    // Genesis thread, then the view, then register. Register returns 403
+    // PROJECT_NOT_IN_COMPANY until both exist. A missing view uses that chain
+    // from ensureProjectBoard; an existing view is merged, then registered.
+    let registration;
+    let verified;
+    if (!current) {
+        const ensured = await ensureProjectBoard({
+            token,
+            company,
+            projectId,
+            name: source.name || projectId,
+            description: source.description ?? "",
+            stories: source.stories,
+            repos: source.repos ?? [],
+        });
+        registration = ensured.registration;
+        verified = ensured.view;
+    }
+    else {
+        const genesis = await ensureProjectThread(token, company, projectId, {
+            summary: source.name || projectId,
+        });
+        if (!genesis.threadId)
+            fail("Work mesh did not return a threadId.");
+        {
+            const stories = mergeProjectStories(current.stories, source.stories);
+            const repos = mergeProjectRepos(current.repos, source.repos ?? []);
+            const name = source.name || current.name;
+            const description = source.description !== undefined ? source.description : current.description;
+            const changed = name !== current.name ||
+                description !== current.description ||
+                JSON.stringify(stories) !== JSON.stringify(current.stories) ||
+                JSON.stringify(repos) !== JSON.stringify(current.repos);
+            if (changed) {
+                await putProjectView(token, company.companyUid, projectId, {
+                    name,
+                    description,
+                    stories,
+                    repos,
+                    ...(current.version !== undefined ? { expectedVersion: current.version } : {}),
+                });
+            }
+        }
+        registration = await registerMeshProject(token, company.companyUid, projectId);
+        await closeSupersededProjectThread({
+            token,
+            companyUid: company.companyUid,
+            openedThreadId: genesis.threadId,
+            canonicalThreadId: registration.threadId,
+            created: genesis.created,
+        });
+        if (!registration.threadId || !registration.channelId) {
+            fail("Work mesh registration did not return a threadId and channelId.");
+        }
+        verified = await getProjectView(token, company.companyUid, projectId);
+    }
+    if (verified.companyUid !== company.companyUid) {
+        fail(`Work mesh project ensure: company mismatch (expected ${company.companyUid}, got ${verified.companyUid}).`);
+    }
+    if (verified.projectId !== projectId) {
+        fail(`Work mesh project ensure: project id mismatch (expected ${projectId}, got ${verified.projectId}).`);
+    }
+    for (const story of source.stories) {
+        if (!verified.stories.some((row) => row.id === story.id)) {
+            fail(`Work mesh project ensure: missing story ${story.id}.`);
+        }
+    }
+    for (const repo of source.repos ?? []) {
+        if (!verified.repos.some((row) => row.path === repo.path)) {
+            fail(`Work mesh project ensure: missing repo ${repo.path}.`);
+        }
+    }
+    if (verified.version === undefined) {
+        fail("Work mesh project ensure: verified view has no version.");
+    }
+    const payload = {
+        projectId: verified.projectId,
+        threadId: registration.threadId,
+        channelId: registration.channelId,
+        version: verified.version,
+        stories: verified.stories,
+    };
+    noteCallingSessionBound(payload.projectId, company);
+    if (opts.json) {
+        console.log(JSON.stringify(payload));
+        return;
+    }
+    console.log(`Work mesh: project ${payload.projectId} ensured (thread ${payload.threadId}, channel ${payload.channelId}, ${payload.stories.length} stories)`);
+}
+async function runPrdSync(opts) {
+    const sessionId = opts.session.trim();
+    const file = opts.file.trim();
+    if (!sessionId || !file)
+        fail("Usage: hq mesh context prd-sync --session <sid> --file <prd.json>");
+    const root = workContextHomeRoot();
+    const plan = planPrdSync({ sessionId, file, root });
+    if (plan.rebindTo) {
+        rebindSessionToProject({ sessionId, root, projectId: plan.rebindTo });
+    }
+    if (!plan.changed) {
+        const payload = { ok: true, action: "context.prd-sync", changed: 0, ...(plan.skip ? { skip: plan.skip } : {}) };
+        if (opts.json)
+            console.log(JSON.stringify(payload));
+        else
+            console.log(plan.skip ? `Work mesh: prd-sync skipped (${plan.skip})` : "Work mesh: prd-sync unchanged");
+        return;
+    }
+    let token;
+    try {
+        token = await requireToken();
+    }
+    catch {
+        token = null;
+    }
+    if (!token) {
+        console.error("work-mesh: prd-sync has changes but no token; snapshot not advanced");
+        return;
+    }
+    // Attribution evidence: without company and project the server files these
+    // as unassigned and the Board never moves. After a same-company switch,
+    // this is the new project's id so ingest writes SESSION_STATE.projectId
+    // and bound-forward posts the channel line there.
+    const bound = readSessionState(sessionId, root);
+    const evidenceBase = {
+        ...(bound?.companySlug ? { companySlug: bound.companySlug } : {}),
+        ...(bound?.projectId ? { project: bound.projectId } : {}),
+        touchedPaths: [resolvePath(file)],
+    };
+    let toEmit = plan.events;
+    if (bound?.companyUid && bound.projectId) {
+        try {
+            const live = await getProjectView(token, bound.companyUid, bound.projectId);
+            toEmit = prdSyncEventsThatChangeBoard(plan.events, live.stories);
+        }
+        catch {
+            // Board unread — emit the snapshot diff; the server drops same-status.
+        }
+        if (toEmit.length === 0) {
+            plan.commit();
+            if (opts.json) {
+                console.log(JSON.stringify({ ok: true, action: "context.prd-sync", changed: 0 }));
+            }
+            else {
+                console.log("Work mesh: prd-sync unchanged");
+            }
+            return;
+        }
+        try {
+            const source = parseProjectPlan(readFileSync(file, "utf8"), file);
+            await ensureMissingBoardStories({
+                token,
+                company: {
+                    companyUid: bound.companyUid,
+                    companySlug: bound.companySlug || bound.companyUid,
+                },
+                projectId: bound.projectId,
+                name: source.name || bound.projectId,
+                description: source.description ?? "",
+                stories: source.stories,
+                repos: source.repos ?? [],
+                requiredIds: toEmit.map((event) => event.taskId),
+            });
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            console.error(`work-mesh: prd-sync ensure failed; emitting anyway (${reason.slice(0, 160)})`);
+        }
+    }
+    const alreadyOnBoard = plan.events
+        .filter((event) => !toEmit.some((row) => row.taskId === event.taskId))
+        .map((event) => event.taskId);
+    const meshRoot = workMeshHomeRoot();
+    const seqFirst = reserveSessionSeq(sessionId, toEmit.length);
+    const events = toEmit.map((event, index) => buildMeshEmitEvent({
+        eventId: generateUlid(Date.now() + index),
+        kind: "task_status",
+        sessionId,
+        harness: "hq-sessions",
+        adapterVersion: "1.0.0",
+        at: new Date().toISOString(),
+        seq: seqFirst + index,
+        source: "hooks",
+        taskId: event.taskId,
+        status: event.status,
+        summary: event.status === "done"
+            ? `${event.taskId} passes`
+            : event.status === "in_progress"
+                ? `${event.taskId} in progress`
+                : `${event.taskId} in review`,
+        evidence: { ...evidenceBase, task: event.taskId },
+    }));
+    const poster = createEmitPoster({ token, baseUrl: resolveVaultApiBase(process.env) });
+    const emitted = await emitEvents({
+        workMeshRoot: meshRoot,
+        poster,
+        newEvents: events,
+    });
+    if (emitted.unassigned > 0 || emitted.rejected > 0) {
+        console.error(`work-mesh: prd-sync sent ${events.length}; unassigned=${emitted.unassigned} rejected=${emitted.rejected}`);
+        for (const line of formatEmitRejectionLines(emitted.rejections))
+            console.error(line);
+    }
+    const blocked = new Set(emitted.rejections.map((row) => row.eventId));
+    for (const pending of readEmitRetry(meshRoot)) {
+        const id = typeof pending.eventId === "string" ? pending.eventId : "";
+        if (id)
+            blocked.add(id);
+    }
+    const advanced = events.flatMap((event) => (event.eventId && event.taskId && !blocked.has(event.eventId) ? [event.taskId] : []));
+    plan.commit([...alreadyOnBoard, ...advanced]);
+    if (plan.taskId && advanced.includes(plan.taskId)) {
+        updateSessionState(sessionId, root, (current) => {
+            if (!current)
+                return null;
+            return {
+                ...current,
+                taskId: plan.taskId,
+                contextStatus: current.projectId ? "bound" : current.contextStatus,
+                updatedAt: new Date().toISOString(),
+            };
+        });
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, action: "context.prd-sync", changed: toEmit.length, taskId: plan.taskId }));
+        return;
+    }
+    console.log(`Work mesh: prd-sync emitted ${toEmit.length} task_status`);
+}
+function noteCallingSessionBound(projectId, company) {
+    try {
+        const bound = bindCallingSession({
+            root: workContextHomeRoot(),
+            projectId,
+            company,
+        });
+        if (bound.bound)
+            console.error(formatSessionBoundLine(bound.sessionId, bound.projectId));
+    }
+    catch {
+        /* session bind is local and must not fail project ensure */
+    }
 }
 async function runDoctor(opts) {
     if (opts.apply) {
         fail("`hq mesh doctor --apply` (paced Board PUTs from local prd.json) is not in the CLI yet.\n" +
             "Omit --apply to warm the conversation cache (directory, inbox, pair DMs).");
     }
+    const identity = collectDaemonDoctor();
+    const identityLines = formatCliIdentityLines(identity);
+    if (!opts.json) {
+        for (const line of identityLines)
+            console.log(line);
+    }
     const token = await requireToken();
     const principalUid = await resolveMeshPrincipalUid(token, loadCachedTokens());
+    if (!principalUid) {
+        fail("Could not resolve the authenticated principal. Sign in again and retry `hq mesh doctor`.");
+    }
     const warmed = await warmMeshConversationCache(token, principalUid);
+    const needsProject = listNeedsProjectSessions(workContextHomeRoot());
     if (opts.json) {
-        console.log(JSON.stringify({ ok: true, action: "doctor", ...warmed }, null, 2));
+        console.log(JSON.stringify({
+            ok: true,
+            action: "doctor",
+            ...warmed,
+            needsProject,
+            cliMismatchLine: identity.cliMismatchLine ?? null,
+            hqOnPath: identity.hqOnPath,
+            multipleHqOnPath: identity.multipleHqOnPath,
+        }, null, 2));
         return;
     }
     console.log(`Work mesh cache warmed at ${warmed.cacheRoot}` +
         ` (directory=${warmed.directory} inbox=${warmed.inbox}` +
         ` contacts=${warmed.contacts} pair-threads=${warmed.threads})`);
+    if (needsProject.length === 0) {
+        console.log("needs_project sessions: none");
+        return;
+    }
+    console.log(`needs_project sessions: ${needsProject.length}`);
+    for (const row of needsProject) {
+        const choices = row.candidates.map((candidate) => candidate.projectId).join(", ") || "(none)";
+        console.log(`- ${row.sessionId}: ${row.reason ?? "no reason recorded"}; candidates: ${choices}`);
+    }
+}
+async function runBindProject(target, opts) {
+    const sessionId = opts.session.trim();
+    const root = workContextHomeRoot();
+    const current = readSessionState(sessionId, root);
+    if (!current)
+        fail(`No work-context state for session ${sessionId}.`);
+    let projectId = target.trim();
+    if (projectId === "new") {
+        const slug = opts.slug?.trim();
+        if (!slug)
+            fail("Usage: hq mesh context bind-project new <slug> --session <sid>");
+        const hqRoot = process.env.HQ_ROOT?.trim() || findHqRoot();
+        const prdPath = findLocalPrd(hqRoot, current.companySlug, slug);
+        if (!prdPath) {
+            fail(`No PRD for ${slug}. Run /prd before binding a new project.`);
+        }
+        if (!current.companyUid)
+            fail(`Session ${sessionId} has no company. Bind a company first.`);
+        const { token, company } = await withCompany({ company: opts.company ?? current.companySlug });
+        const plan = parseProjectPlan(readFileSync(prdPath, "utf8"), prdPath);
+        await ensureProjectBoard({
+            token,
+            company: {
+                companyUid: current.companyUid,
+                companySlug: current.companySlug || company.companySlug,
+            },
+            projectId: slug,
+            name: plan.name || slug,
+            description: plan.description ?? "",
+            stories: plan.stories,
+            repos: plan.repos ?? [],
+        });
+        projectId = slug;
+    }
+    else if (/^[1-9][0-9]*$/.test(projectId)) {
+        const index = Number(projectId) - 1;
+        const chosen = current.projectCandidates?.[index];
+        if (!chosen)
+            fail(`No candidate ${projectId} on session ${sessionId}.`);
+        projectId = chosen.projectId;
+    }
+    const updated = updateSessionState(sessionId, root, (state) => state ? applyOperatorProjectBinding(state, projectId) : null);
+    if (!updated)
+        fail(`No work-context state for session ${sessionId}.`);
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, action: "context.bind-project", sessionId, projectId, contextStatus: updated.contextStatus }));
+        return;
+    }
+    console.log(`Work mesh: session ${sessionId} bound to project ${projectId}`);
 }
 async function runContextReconcile(opts) {
     if (!opts.observationFile && !opts.observationJson) {
@@ -152,25 +860,92 @@ async function runContextReconcile(opts) {
     let fetchCandidates;
     let validateMembership;
     let offline = Boolean(opts.offline);
-    if (!offline) {
-        try {
-            const token = await requireToken();
-            deliver = createWorkSessionDeliverer({ token });
-            fetchCandidates = createCandidatesFetcher({ token });
+    let token;
+    try {
+        if (offline) {
+            if (isMachineIdentity()) {
+                token = await ensureCognitoToken({ tokenSource: "machine", interactive: false });
+            }
+            else {
+                const cached = loadCachedTokens();
+                if (cached && !isExpiring(cached, 120)) {
+                    token = cached.accessToken;
+                }
+            }
+        }
+        else {
+            token = await requireToken();
+        }
+        if (token) {
+            const sessionToken = token;
+            const membershipValidationTimeoutMs = offline
+                ? OFFLINE_MEMBERSHIP_VALIDATION_TIMEOUT_MS
+                : ONLINE_MEMBERSHIP_VALIDATION_TIMEOUT_MS;
             validateMembership = async (candidate) => {
-                const membership = await resolveActiveMembershipCompany(token, candidate);
-                if (!membership)
+                const membership = await new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => reject(new Error("membership validation timed out")), membershipValidationTimeoutMs);
+                    void resolveActiveMembershipCompany(sessionToken, candidate).then((value) => {
+                        clearTimeout(timer);
+                        resolve(value);
+                    }, (error) => {
+                        clearTimeout(timer);
+                        reject(error);
+                    });
+                });
+                if (!membership || typeof membership.companyUid !== "string" || !membership.companyUid) {
                     return false;
+                }
                 return { uid: membership.companyUid };
             };
+            if (!offline) {
+                deliver = createWorkSessionDeliverer({ token: sessionToken });
+                fetchCandidates = createCandidatesFetcher({ token: sessionToken });
+            }
         }
-        catch {
+    }
+    catch {
+        if (!offline) {
             offline = true;
             if (!opts.machine) {
                 console.error(chalk.yellow("No Cognito session; reconciling offline (outbox only)."));
             }
         }
     }
+    if (token) {
+        const activation = await ensureDefaultCompany({
+            root,
+            listMemberships: () => listActiveMembershipCompanies(token),
+            log: (message) => console.error(chalk.dim(message)),
+        });
+        if (activation.status === "needs_choice") {
+            const interactive = !offline &&
+                !opts.machine &&
+                Boolean(process.stdin.isTTY && process.stdout.isTTY) &&
+                !isMachineIdentity();
+            if (interactive) {
+                const choices = activation.memberships
+                    .map((membership, index) => `${index + 1}. ${membership.slug}`)
+                    .join("\n");
+                const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+                try {
+                    const answer = await rl.question(`Choose this device's default company:\n${choices}\nSelection: `);
+                    const selected = activation.memberships[Number.parseInt(answer, 10) - 1];
+                    if (selected) {
+                        await setDefaultCompany(selected.slug, {
+                            root,
+                            validateMembership: (candidate) => candidate === selected.slug ? { uid: selected.uid } : false,
+                        });
+                    }
+                }
+                finally {
+                    rl.close();
+                }
+            }
+            else if (!offline && !opts.machine) {
+                console.error(chalk.yellow("Multiple active memberships. Run `hq mesh context default set <slug>` to choose this device's default company."));
+            }
+        }
+    }
     const outcome = await reconcileObservation(obs, {
         root,
         env: process.env,
@@ -178,6 +953,20 @@ async function runContextReconcile(opts) {
         fetchCandidates,
         offline,
         validateMembership,
+        ensureProjectBoard: token
+            ? async ({ companyUid, projectId, prdPath }) => {
+                const plan = parseProjectPlan(readFileSync(prdPath, "utf8"), prdPath);
+                await ensureProjectBoard({
+                    token,
+                    company: { companyUid, companySlug: companyUid },
+                    projectId,
+                    name: plan.name || projectId,
+                    description: plan.description ?? "",
+                    stories: plan.stories,
+                    repos: plan.repos ?? [],
+                });
+            }
+            : undefined,
     });
     for (const line of outcome.diagnostics) {
         console.error(line);
@@ -294,19 +1083,21 @@ async function runContextBackfillHeld(opts) {
     const parsedLimit = opts.limit ? Number.parseInt(opts.limit, 10) : 0;
     const limit = Number.isFinite(parsedLimit) && parsedLimit > 0 ? parsedLimit : 0;
     const companyHint = opts.company?.trim() || undefined;
-    // Build the reconcile network seam exactly like `hq mesh context reconcile`.
-    // Not needed in --dry-run (reconcile is never invoked then). Explicit types
-    // because these are captured in the reconcile closure below (no control-flow
-    // narrowing, unlike the inline reconcile handler).
+    const useDeviceDefault = opts.useDeviceDefault === true || readDeviceConfig({ root }).repairHeldWithDefault === true;
+    // Build the membership seam for both modes; dry-run is read-only but must
+    // validate a locally resolved slug just as live reconciliation does.
+    // The remaining seams are captured in the reconcile closure below.
     let deliver;
     let fetchCandidates;
     let validateMembership;
     let offline = Boolean(opts.offline);
-    if (!dryRun && !offline) {
+    if (!offline) {
         try {
             const token = await requireToken();
-            deliver = createWorkSessionDeliverer({ token });
-            fetchCandidates = createCandidatesFetcher({ token });
+            if (!dryRun) {
+                deliver = createWorkSessionDeliverer({ token });
+                fetchCandidates = createCandidatesFetcher({ token });
+            }
             validateMembership = async (candidate) => {
                 const membership = await resolveActiveMembershipCompany(token, candidate);
                 if (!membership)
@@ -324,11 +1115,14 @@ async function runContextBackfillHeld(opts) {
     const result = await backfillHeldSessions({
         workMeshRoot: meshRoot,
         workContextRoot: root,
+        hqRoot: process.env.HQ_ROOT?.trim() || findHqRoot(),
         dryRun,
         limit,
         // Mirror the reconcile closure's non-forcing hint in the dry-run predictor
         // so `--dry-run` and the real run report the same counts.
         remoteOwnerHint: companyHint || undefined,
+        useDeviceDefault,
+        validateMembership,
         reconcile: (obs) => reconcileObservation(
         // Pass --company as a non-forcing hint (remoteOwnerSlug feeds
         // deterministic resolution BELOW the identity-file / device default,
@@ -340,6 +1134,8 @@ async function runContextBackfillHeld(opts) {
             fetchCandidates,
             offline,
             validateMembership,
+            allowDeviceDefault: useDeviceDefault,
+            deviceDefaultConfidence: useDeviceDefault,
         }),
     });
     if (opts.json) {
@@ -354,6 +1150,9 @@ async function runContextBackfillHeld(opts) {
         `${result.unresolved} unresolved, ` +
         `${result.errors} error(s).` +
         (dryRun ? " (dry-run: nothing written)" : ""));
+    for (const { sessionId, reason } of result.unresolvedReasons) {
+        console.log(`Unresolved ${sessionId}: ${reason}`);
+    }
     if (!dryRun && result.reconciled > 0) {
         console.log("Reconciled session state files were rewritten with a resolved company; " +
             "the mesh daemon's held retry will re-attribute and post those events.");
@@ -362,20 +1161,38 @@ async function runContextBackfillHeld(opts) {
 async function runContextDefaultGet(opts) {
     const root = workContextHomeRoot();
     const cfg = readDeviceConfig({ root });
-    const current = getDefaultCompany({ root });
+    const current = cfg.defaultCompany?.enabled && cfg.defaultCompany.slug
+        ? cfg.defaultCompany
+        : null;
+    const memberships = cfg.defaultCompanyMemberships?.memberships ?? [];
+    const disabled = isDefaultCompanyDisabled({ root });
+    const source = disabled ? "disabled" : current?.source ?? (current ? "chosen" : "unset");
     if (opts.json) {
-        console.log(JSON.stringify({ ok: true, config: cfg, defaultCompany: current }, null, 2));
+        console.log(JSON.stringify({
+            ok: true,
+            slug: current?.slug ?? null,
+            uid: current?.uid ?? null,
+            enabled: current?.enabled ?? false,
+            source,
+            needsChoice: !current && !disabled && memberships.length > 1,
+            memberships,
+            repairHeldWithDefault: cfg.repairHeldWithDefault === true,
+        }, null, 2));
+        return;
+    }
+    if (disabled) {
+        console.log("Default company disabled on this device.");
         return;
     }
     if (!current) {
         console.log("No device default company (default-company mode may be dark).");
         return;
     }
-    console.log(`Default company: ${current.slug}${current.uid ? ` (${current.uid})` : ""} enabled=${current.enabled}`);
+    console.log(`Default company: ${current.slug}${current.uid ? ` (${current.uid})` : ""} enabled=${current.enabled} source=${source}`);
 }
 async function runContextDefaultSet(slug, opts) {
     const root = workContextHomeRoot();
-    void opts.company; // retained for CLI compatibility; unlock is memberships-wide
+    void opts.company; // retained for CLI compatibility
     let token;
     try {
         token = await requireToken();
@@ -383,42 +1200,38 @@ async function runContextDefaultSet(slug, opts) {
     catch {
         token = undefined;
     }
-    // US-017B: unlock only when EVERY active membership advertises migration.
+    // Migration remains useful diagnostic context, but it must never prevent a
+    // verified member from choosing their own device-local preference.
     let migrationCapability = false;
+    let migrationWarning;
     if (token) {
         const probe = await probeMigrationCapabilityForMemberships(token);
         recordMigrationCapabilitySnapshot(probe, { root });
         migrationCapability = probe.unlocked;
-        if (probe.offline && !opts.allowWithoutMigration) {
-            console.error(chalk.red("DEFAULT_COMPANY_LOCKED: cannot probe migration capability (offline or not logged in)"));
-            process.exitCode = 1;
-            return;
+        if (probe.offline) {
+            migrationWarning =
+                "Warning: migration capability could not be checked; membership for the selected company will still be verified.";
         }
-        if (!probe.unlocked && !opts.allowWithoutMigration) {
+        else if (!probe.unlocked) {
             const detail = probe.companies.length === 0
                 ? "no active memberships"
                 : probe.companies
                     .filter((c) => !c.migration)
                     .map((c) => c.companySlug || c.companyUid)
                     .join(", ");
-            console.error(chalk.red(`DEFAULT_COMPANY_LOCKED: migration capability is not true for every company you belong to (${detail || "locked"})`));
-            process.exitCode = 1;
-            return;
+            migrationWarning =
+                `Warning: migration capability is mixed or unavailable for ${detail || "some memberships"}; ` +
+                    "the selected company can still be set because membership is verified directly.";
         }
     }
-    else if (!opts.allowWithoutMigration) {
-        console.error(chalk.red("DEFAULT_COMPANY_LOCKED: cannot probe migration capability (no Cognito session)"));
-        process.exitCode = 1;
-        return;
-    }
-    if (!migrationCapability && opts.allowWithoutMigration) {
-        console.error(chalk.yellow("Warning: --allow-without-migration bypasses DEFAULT_COMPANY_LOCKED; a wrong default is hard to correct until migration is available for every company you belong to."));
+    else {
+        migrationWarning =
+            "Warning: migration capability could not be checked without a Cognito session; membership for the selected company must still be verified.";
     }
     try {
         const cfg = await setDefaultCompany(slug, {
             root,
             migrationCapability,
-            allowWithoutMigration: opts.allowWithoutMigration,
             validateMembership: async (candidate) => {
                 if (!token) {
                     throw new DefaultCompanyUnavailableError(`Cannot verify membership for company "${candidate}" (no Cognito session; offline or not logged in)`);
@@ -436,16 +1249,20 @@ async function runContextDefaultSet(slug, opts) {
                 return { uid: membership.companyUid };
             },
         });
+        const configured = opts.repairHeldWithDefault
+            ? setRepairHeldWithDefault(true, { root })
+            : cfg;
         if (opts.json) {
-            console.log(JSON.stringify({ ok: true, config: cfg }, null, 2));
+            console.log(JSON.stringify({ ok: true, config: configured, migrationWarning }, null, 2));
             return;
         }
-        const stored = cfg.defaultCompany;
+        const stored = configured.defaultCompany;
         console.log(`Default company set to ${stored?.slug ?? slug}${stored?.uid ? ` (${stored.uid})` : ""}`);
+        if (migrationWarning)
+            console.error(chalk.yellow(migrationWarning));
     }
     catch (err) {
-        if (err instanceof DefaultCompanyLockedError ||
-            err instanceof DefaultCompanyUnavailableError) {
+        if (err instanceof DefaultCompanyUnavailableError) {
             console.error(chalk.red(`${err.code}: ${err.message}`));
             process.exitCode = 1;
             return;
@@ -715,13 +1532,16 @@ async function runSessionStatus(opts) {
     }
     const { token, company } = await withCompany({ company: opts.company });
     const live = await fetchCompanyLive(token, company.companyUid);
+    const unattributedEvents = collectDaemonDoctor().unattributedEvents;
     if (opts.json) {
-        console.log(JSON.stringify({ ok: true, action: "session-status", company, live }, null, 2));
+        console.log(JSON.stringify({ ok: true, action: "session-status", company, live, unattributedEvents }, null, 2));
         return;
     }
     for (const line of formatCompanyLiveTable(live, company.companySlug || company.companyUid)) {
         console.log(line);
     }
+    console.log(`unattributed events: ${unattributedEvents.total} ` +
+        `(spool=${unattributedEvents.spool} held=${unattributedEvents.held} dead-letter=${unattributedEvents.deadLetter})`);
 }
 const HARNESSES = new Set([
     "claude-code",
@@ -754,6 +1574,21 @@ async function runSessionEnqueue(cliKind, opts) {
     const sessionId = resolveEnqueueSessionId(opts.sessionId, process.env);
     if (!sessionId)
         fail("sessionId required (--session-id or HQ_SESSION_ID)");
+    if (kind === "turn_start") {
+        try {
+            rebindNeedsProjectOnPrompt({
+                sessionId,
+                root: workContextHomeRoot(),
+                hqRoot: opts.hqRoot?.trim() || process.env.HQ_ROOT,
+                cwd: opts.cwd,
+                companySlug: opts.companySlug,
+                env: process.env,
+            });
+        }
+        catch {
+            /* prompt rebind is fail-soft */
+        }
+    }
     const evidence = buildEmitEvidence({
         sessionId: sessionId,
         hqRoot: opts.hqRoot,
@@ -763,7 +1598,16 @@ async function runSessionEnqueue(cliKind, opts) {
         companySlug: opts.companySlug,
         project: opts.project,
         task: opts.task,
+        env: process.env,
     });
+    const reportFields = kind === "session_end"
+        ? enrichSessionEndEvent({
+            kind,
+            sessionId: sessionId,
+            cwd: opts.cwd,
+            summary: opts.summary,
+        })
+        : {};
     const event = buildMeshEmitEvent({
         eventId: opts.eventId?.trim() || generateUlid(Date.now()),
         kind: kind,
@@ -777,10 +1621,35 @@ async function runSessionEnqueue(cliKind, opts) {
         taskId: opts.taskId,
         status: opts.status,
         reason: opts.reason,
-        summary: opts.summary,
+        summary: opts.summary ||
+            (typeof reportFields.summary === "string" ? reportFields.summary : undefined),
+        repo: typeof reportFields.repo === "string" ? reportFields.repo : undefined,
+        gitBranch: typeof reportFields.gitBranch === "string"
+            ? reportFields.gitBranch
+            : undefined,
+        prUrls: Array.isArray(reportFields.prUrls)
+            ? reportFields.prUrls
+            : undefined,
         evidence,
     });
     const meshRoot = workMeshHomeRoot();
+    // A machine credential with no company must not be posted. The server files
+    // that as company NONE. Hold it and say why.
+    if (machineEmitDisposition({ machine: isMachineIdentity(), companySlug: evidence.companySlug }) === "hold") {
+        appendHeldLine(JSON.stringify({
+            event,
+            heldReason: "NEEDS_COMPANY",
+            heldAt: new Date().toISOString(),
+            reason: "machine session has no company; event was not sent",
+        }), meshRoot);
+        const heldMessage = `work-mesh: held ${kind}; needs_company (machine session has no company; not sent)`;
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: true, action: "emit", kind, held: true, reason: "needs_company" }, null, 2));
+            return;
+        }
+        console.error(heldMessage);
+        return;
+    }
     // Resolve a token non-interactively (same path as every CLI call). If the box
     // is not logged in, retain the event locally for the next invocation to drain.
     let token;
@@ -816,6 +1685,9 @@ async function runSessionEnqueue(cliKind, opts) {
     console.error(`work-mesh: emit ${kind} accepted=${summary.accepted}` +
         ` unassigned=${summary.unassigned} rejected=${summary.rejected}` +
         ` retryDepth=${summary.retryDepth}`);
+    for (const line of formatEmitRejectionLines(summary.rejections)) {
+        console.error(line);
+    }
 }
 async function runMeshMode(action, opts) {
     const meshRoot = workMeshHomeRoot();
@@ -900,6 +1772,9 @@ async function runMeshEmit(opts) {
         ` unassigned=${summary.unassigned} rejected=${summary.rejected}` +
         ` retryDepth=${summary.retryDepth}` +
         (opts.replayLegacy ? ` (legacy scanned=${scanned} skipped=${skipped})` : ""));
+    for (const line of formatEmitRejectionLines(summary.rejections)) {
+        console.log(line);
+    }
 }
 async function runSessionFlush(opts) {
     const token = await requireToken();
@@ -998,9 +1873,43 @@ export function registerMeshCommand(program) {
         .option("--summary <text>", "Note text")).action((opts) => wrap(() => runEvent("note", opts))());
     addSharedFlags(mesh
         .command("story")
-        .description("PATCH one Board story status")
+        .description("PATCH one Board story status and/or assignee")
         .requiredOption("--story <id>", "Story id, e.g. US-001")
-        .requiredOption("--status <status>", "queued|in_progress|review|done")).action((opts) => wrap(() => runStory(opts))());
+        .option("--status <status>", "queued|in_progress|review|done")
+        .option("--assignee <uid|me|none>", "Assign a person or agent uid, yourself, or clear")).action((opts) => wrap(() => runStory(opts))());
+    const project = mesh
+        .command("project")
+        .description("Set a project Board view or register its project channel");
+    project
+        .command("set <projectId>")
+        .description("PUT the project Board view from flags or a PRD JSON file")
+        .requiredOption("--company <slug|uid>", "Company slug or cloud uid")
+        .option("--name <name>", "Project name")
+        .option("--description <text>", "Project description")
+        .option("--stories-file <path>", "PRD JSON file with userStories")
+        .option("--stories-json <json>", "Story array or JSON object with userStories")
+        .option("--repos-json <json>", "Repository array, such as [{path,branch}]")
+        .option("--repo <path[@branch]>", "Repository binding (repeatable)", collectRepeatable)
+        .option("--channel <channelId>", "Bind the project to an existing company or project channel")
+        .option("--create", "Create the Board view when the GET is a 404")
+        .option("--reset-status", "Overwrite live story status from the PRD (prints a one-line summary of changes)")
+        .option("--json", "Print machine-readable JSON")
+        .action((projectId, opts) => wrap(() => runProjectSet(projectId, opts))());
+    project
+        .command("ensure <projectId>")
+        .description("Idempotently register a PRD on the Board and verify the view")
+        .requiredOption("--company <slug|uid>", "Company slug or cloud uid")
+        .requiredOption("--stories-file <path>", "PRD JSON file with userStories and metadata.repos")
+        .option("--dry-run", "Read the current Board and print computed story statuses without writing")
+        .option("--json", "Print {projectId, threadId, channelId, version, stories}")
+        .action((projectId, opts) => wrap(() => runProjectEnsure(projectId, opts))());
+    project
+        .command("register <projectId>")
+        .description("Register an existing Board and bind its project channel; use project ensure to create or repair a Board")
+        .requiredOption("--company <slug|uid>", "Company slug or cloud uid")
+        .option("--channel <channelId>", "Bind the project to an existing company or project channel")
+        .option("--json", "Print machine-readable JSON")
+        .action((projectId, opts) => wrap(() => runProjectRegister(projectId, opts))());
     mesh
         .command("doctor")
         .description("Warm ~/.hq/work-mesh/cache from hq-pro (directory, inbox, pair DMs). Not `hq doctor`.")
@@ -1030,12 +1939,29 @@ export function registerMeshCommand(program) {
     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)")
-        .option("--dry-run", "Report what would be reconciled; write nothing, no network")
+        .option("--dry-run", "Report what would be reconciled; write nothing or deliver events")
         .option("--offline", "Reconcile outbox-only (no candidates/register network)")
         .option("--limit <n>", "Cap sessions processed (default 0 = no cap)")
-        .option("--company <slug>", "Optional non-forcing company hint (resolver default still wins)")
+        .option("--company <slug>", "Optional non-forcing company hint")
+        .option("--use-device-default", "Opt in to historical repair using the device default (lower-confidence attribution)")
         .option("--json", "Print machine-readable JSON")
         .action((opts) => wrap(() => runContextBackfillHeld(opts))());
+    context
+        .command("bind-project")
+        .description("Bind this session to a project id, a numbered candidate, or new <slug>")
+        .argument("<target>", "Project id, candidate number, or new")
+        .argument("[slug]", "Project slug when target is new")
+        .requiredOption("--session <sid>", "Canonical session id")
+        .option("--company <slug|uid>", "Company override when creating a Board")
+        .option("--json", "Print machine-readable JSON")
+        .action((target, slug, opts) => wrap(() => runBindProject(target, { ...opts, slug }))());
+    context
+        .command("prd-sync")
+        .description("Emit task_status for PRD story passes/status changes on a bound session")
+        .requiredOption("--session <sid>", "Canonical session id")
+        .requiredOption("--file <path>", "prd.json written by the bound session")
+        .option("--json", "Print machine-readable JSON")
+        .action((opts) => wrap(() => runPrdSync(opts))());
     context
         .command("organize")
         .description("List or submit one-time project/task decisions (US-007B / US-005B)")
@@ -1085,10 +2011,11 @@ export function registerMeshCommand(program) {
         .action((opts) => wrap(() => runContextDefaultGet(opts))());
     def
         .command("set")
-        .description("Set the device default company slug (unlocked when migration is true for every membership)")
+        .description("Set the device default company slug after verifying membership")
         .argument("<slug>", "Company slug")
-        .option("--allow-without-migration", "Bypass DEFAULT_COMPANY_LOCKED with a warning")
-        .option("--company <slug|uid>", "Deprecated no-op; unlock probes every active membership")
+        .option("--allow-without-migration", "Deprecated compatibility no-op; selected-company membership is always verified")
+        .option("--repair-held-with-default", "Persist opt-in for lower-confidence historical held-session repair")
+        .option("--company <slug|uid>", "Deprecated no-op; the selected company is verified directly")
         .option("--json", "Print machine-readable JSON")
         .action((slug, opts) => wrap(() => runContextDefaultSet(slug, opts))());
     def
@@ -1102,6 +2029,19 @@ export function registerMeshCommand(program) {
         .argument("<sessionId>", "Canonical session id")
         .option("--machine", "Write exactly one ContextResult JSON line to stdout")
         .action((sessionId, opts) => wrap(() => runContextUntracked(sessionId, opts))());
+    const contract = mesh
+        .command("contract")
+        .description("Print versioned work-mesh contracts for other repositories");
+    contract
+        .command("preflight")
+        .description("Offline preflight ContextResult contract (contracts/preflight/v1)")
+        .option("--print-fixtures", "Write the fixture file JSON to stdout")
+        .action((opts) => wrap(async () => {
+        if (!opts.printFixtures) {
+            throw new Error("Pass --print-fixtures. The stable package path is contracts/preflight/v1/fixtures.json.");
+        }
+        process.stdout.write(`${JSON.stringify(buildPreflightFixtures(), null, 2)}\n`);
+    })());
     const session = mesh
         .command("session")
         .description("Local session-event spool: enqueue (printf-compatible), flush, and live status");
@@ -1148,11 +2088,14 @@ export function registerMeshCommand(program) {
     daemon
         .command("run")
         .description("Start the single-instance daemon (pid lock, spool watch, presence)")
-        .action(() => wrap(() => runDaemonRun())());
+        .option("--hq-root <path>", "HQ tree root (else HQ_ROOT / persisted trusted roots); the Windows task passes this explicitly")
+        .action((opts) => wrap(() => runDaemonRun(opts))());
     daemon
         .command("install")
-        .description("Install LaunchAgent (macOS) or systemd user unit (Linux)")
+        .description("Install LaunchAgent (macOS), systemd user unit (Linux), or Scheduled Task (Windows)")
         .option("--system-user <user>", "Write a root-owned unit template for agent boxes (e.g. ec2-user)")
+        .option("--hq-root <path>", "HQ root to record for the service (else HQ_ROOT, else the nearest HQ root above cwd)")
+        .option("--if-stale", "Reinstall and restart only when this CLI is newer than the daemon's recorded version")
         .option("--json", "Print machine-readable JSON")
         .action((opts) => wrap(() => runDaemonInstall(opts))());
     daemon
@@ -1171,18 +2114,65 @@ export function registerMeshCommand(program) {
         .option("--json", "Print machine-readable JSON")
         .action((opts) => wrap(() => runDaemonDoctorCmd(opts))());
 }
-async function runDaemonRun() {
-    const handle = await runMeshDaemon();
+async function runDaemonRun(opts = {}) {
+    const hqRoot = opts.hqRoot?.trim() || undefined;
+    const handle = await runMeshDaemon({
+        ...(hqRoot ? { hqRoot } : {}),
+        enableWorkCache: true,
+    });
     // Stay alive until signal handlers call stop + exit.
     await new Promise(() => {
         void handle;
     });
 }
 async function runDaemonInstall(opts) {
+    // `hq daemon` runs mesh on this machine: installing a second unit would run it twice.
+    // An explicit --hq-root is verified the same way as below and saved for the daemon.
+    const explicitRoot = opts.hqRoot ? resolveInstallHqRoot({ explicit: opts.hqRoot }).root : undefined;
+    const handedOff = opts.systemUser
+        ? null
+        : handOffInstallHere(["mesh"], process.env, { hqRoot: explicitRoot, ifStale: opts.ifStale });
+    if (handedOff) {
+        console.log(opts.json ? JSON.stringify({ ok: true, action: "hq-daemon", reinstalled: false, message: handedOff }) : handedOff);
+        return;
+    }
+    // Verified root only: a repo's own .claude/ must never become the daemon's
+    // HQ root (that path is persisted as trusted and used for attribution).
+    const hqRoot = resolveInstallHqRoot({ explicit: opts.hqRoot });
+    const paths = buildInstallPaths({
+        systemUser: opts.systemUser,
+        hqRoot: hqRoot.root,
+        hqRootSource: hqRoot.source,
+        hqBinary: resolveRunningCliEntry(),
+        nodeBinary: resolveAbsoluteNodeBinary(),
+    });
+    if (opts.ifStale) {
+        const stale = installDaemonIfStale({
+            currentVersion: CLI_VERSION,
+            platform: detectPlatform(),
+            paths,
+            systemUser: opts.systemUser,
+        });
+        if (opts.json) {
+            console.log(JSON.stringify({
+                ok: true,
+                action: stale.reinstalled ? "install" : "unchanged",
+                reinstalled: stale.reinstalled,
+                message: stale.message,
+                hqBinary: paths.hqBinary,
+                nodeBinary: paths.nodeBinary,
+                hqRoot: hqRoot.root,
+            }, null, 2));
+            return;
+        }
+        console.log(stale.message);
+        return;
+    }
     const result = installDaemonService({
         platform: detectPlatform(),
-        paths: buildInstallPaths({ systemUser: opts.systemUser }),
+        paths,
         systemUser: opts.systemUser,
+        run: defaultRunCommand,
     });
     if (opts.json) {
         console.log(JSON.stringify({
@@ -1191,10 +2181,15 @@ async function runDaemonInstall(opts) {
             platform: result.platform,
             dest: result.dest,
             message: result.message,
+            hqRoot: hqRoot.root,
+            hqRootSource: hqRoot.source,
+            ...(result.notice ? { notice: result.notice } : {}),
         }, null, 2));
         return;
     }
     console.log(result.message);
+    if (result.notice)
+        console.log(result.notice);
 }
 async function runDaemonUninstall(opts) {
     const result = uninstallDaemonService({
@@ -1213,12 +2208,14 @@ async function runDaemonUninstall(opts) {
     }
     console.log(result.message);
 }
-async function runDaemonStatus(opts) {
+export async function runDaemonStatus(opts, deps = {}) {
+    const paths = deps.paths ?? buildInstallPaths({});
     const result = daemonServiceStatus({
-        platform: detectPlatform(),
-        paths: buildInstallPaths({}),
+        platform: deps.platform ?? detectPlatform(),
+        paths,
+        isLoaded: daemonServiceIsLoaded(deps.run ?? defaultRunCommand, deps.uid),
     });
-    const state = readDaemonState(daemonDir());
+    const state = readDaemonState(paths.daemonDir);
     const presenceRefusal = state?.presenceRefusal ?? null;
     if (opts.json) {
         console.log(JSON.stringify({
@@ -1228,12 +2225,21 @@ async function runDaemonStatus(opts) {
             running: result.running ?? false,
             dest: result.dest,
             message: result.message,
+            ...(result.lastResult !== undefined ? { lastResult: result.lastResult } : {}),
+            ...(result.lastRunFailed !== undefined ? { lastRunFailed: result.lastRunFailed } : {}),
+            ...(result.recordedHqRoot !== undefined ? { hqRoot: result.recordedHqRoot } : {}),
+            ...(result.rootValid !== undefined ? { rootValid: result.rootValid } : {}),
+            ...(result.notice ? { notice: result.notice } : {}),
             mqttState: state?.mqttState,
             presenceRefusal,
         }, null, 2));
         return;
     }
     console.log(result.message);
+    if (result.recordedHqRoot)
+        console.log(`hq root: ${result.recordedHqRoot}`);
+    if (result.notice)
+        console.log(result.notice);
     if (presenceRefusal) {
         console.log(`presence refusal: ${presenceRefusal.code} (HTTP ${presenceRefusal.status}); next retry at ${presenceRefusal.nextRetryAt}`);
     }
@@ -1242,7 +2248,11 @@ async function runDaemonStatus(opts) {
     }
 }
 async function runDaemonDoctorCmd(opts) {
-    const report = collectDaemonDoctor();
+    // Same predicate as install: a repo's .claude/ is not an HQ root. Doctor
+    // only reads, so an unresolvable root is reported as absent, not fatal.
+    const report = collectDaemonDoctor({
+        hqRoot: process.env.HQ_ROOT?.trim() || findAncestorHqRoot(process.cwd()) || undefined,
+    });
     if (opts.json) {
         console.log(JSON.stringify({ ok: !report.unhealthy, ...report }, null, 2));
         return;