@indigoai-us/hq-cli 5.155.0 → 5.157.0

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 ## [Unreleased]
 
+## [5.157.0] — 2026-09-24
+
+### Fixed
+
+- Local bots (`hq bot run`) now receive HQ chat attachments. The runner reads
+  `attachments` on each inbox item, downloads every file with the bot's own
+  machine identity through the same checks `hq_attachment_fetch` uses (chat
+  attachment path only, DM must include the bot, company must be one of the
+  bot's own, 26 MiB cap), and saves it under `~/.hq/bots/<name>/attachments/`
+  (dir 0700, files 0600). The turn text lists each file's name, type, size and
+  local path, with small text files inlined; a file that could not be fetched
+  gets a one-line reason, which is also logged. A message that is only an
+  attachment is answered instead of being acked and dropped. Claude turns get
+  `--add-dir` for the attachments folder so gated permission modes can read it.
+  The MIME type is also read from the server's `kind` field.
+
+## [5.156.0] — 2026-09-24
+
+### Fixed
+
+- Project-thread lookup treats an omitted server `kind` as the project thread,
+  preventing duplicate project threads when a newer lane thread is present.
+- Lane admission reservations are refreshed after Work Mesh lane-thread
+  registration so slow registration cannot age the reservation before spawn.
+
+### Added
+
+- `hq mesh project register --channel` and `project set --channel` can bind an
+  existing channel to project events. `hq mesh check --project` shows lane
+  identity and status, including terminal lane threads.
+- Lane mesh threads keep a stable lane id across resume and account moves.
+  Events include the worker profile, model, account, parent lane, and senior
+  owner. Stop and dead-host recovery events close terminal threads.
+
+### Tests
+
+- Cover server-shaped project-thread results and reservation timing after
+  lane-thread registration.
+
 ## [5.155.0] — 2026-09-24
 
 ### Fixed

package/dist/command-catalog.generated.d.ts

@@ -5708,6 +5708,9 @@ export declare const COMMAND_CATALOG: readonly [{
             }, {
                 readonly flags: "--repo <path[@branch]>";
                 readonly description: "Repository binding (repeatable)";
+            }, {
+                readonly flags: "--channel <channelId>";
+                readonly description: "Bind the project to an existing company or project channel";
             }, {
                 readonly flags: "--create";
                 readonly description: "Create the Board view when the GET is a 404";
@@ -5754,7 +5757,7 @@ export declare const COMMAND_CATALOG: readonly [{
                 readonly description: "Company slug or cloud uid";
             }, {
                 readonly flags: "--channel <channelId>";
-                readonly description: "Reserved: the current server chooses the project channel";
+                readonly description: "Bind the project to an existing company or project channel";
             }, {
                 readonly flags: "--json";
                 readonly description: "Print machine-readable JSON";

package/dist/command-catalog.generated.js

@@ -7367,6 +7367,10 @@ export const COMMAND_CATALOG = [
                                 "flags": "--repo <path[@branch]>",
                                 "description": "Repository binding (repeatable)"
                             },
+                            {
+                                "flags": "--channel <channelId>",
+                                "description": "Bind the project to an existing company or project channel"
+                            },
                             {
                                 "flags": "--create",
                                 "description": "Create the Board view when the GET is a 404"
@@ -7427,7 +7431,7 @@ export const COMMAND_CATALOG = [
                             },
                             {
                                 "flags": "--channel <channelId>",
-                                "description": "Reserved: the current server chooses the project channel"
+                                "description": "Bind the project to an existing company or project channel"
                             },
                             {
                                 "flags": "--json",

package/dist/commands/agent-mcp.d.ts

@@ -9,18 +9,16 @@
  * hq binary with the machine-identity env pinned.
  */
 import { Command } from "commander";
-import type { Readable } from "node:stream";
 import { McpServer } from "../lib/agent-kit/mcp/jsonrpc.js";
 import { type HqRunResult, type McpToolClients } from "../lib/agent-kit/mcp/tools.js";
 import { type AgentKitPaths } from "../lib/agent-kit/paths.js";
 import type { ExternalMachineCreds } from "../lib/agent-kit/creds.js";
+export { readBounded } from "../lib/agent-kit/attachment-download.js";
 export declare const AGENT_MCP_SERVER_NAME = "hq-agent";
 export declare const AGENT_MCP_INSTRUCTIONS: string;
 export declare const HQ_SUBPROCESS_TIMEOUT_MS = 120000;
 export declare function defaultRunHq(nodeBinary: string, hqBinary: string, env: NodeJS.ProcessEnv): (args: string[]) => Promise<HqRunResult>;
 export declare function defaultMcpClients(creds: ExternalMachineCreds, credsPath: string, paths?: Pick<AgentKitPaths, "inboxDir" | "attachmentsDir">): McpToolClients;
-/** Drain a stream into memory, refusing past `max` bytes. */
-export declare function readBounded(body: Readable, max: number): Promise<Buffer>;
 export declare function createAgentMcpServer(clients: McpToolClients): McpServer;
 export declare function registerAgentMcpCommand(agent: Command): void;
 //# sourceMappingURL=agent-mcp.d.ts.map

package/dist/commands/agent-mcp.js

@@ -12,15 +12,15 @@ import { spawn } from "node:child_process";
 import * as os from "node:os";
 import { CLI_VERSION } from "../cli-version.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
-import { GetObjectCommand } from "@aws-sdk/client-s3";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
-import { createCompanyPresignClient } from "./files-browse.js";
-import { MAX_ATTACHMENT_BYTES } from "../lib/agent-kit/mcp/attachments.js";
 import { McpServer } from "../lib/agent-kit/mcp/jsonrpc.js";
+import { createVaultObjectDownloader } from "../lib/agent-kit/attachment-download.js";
 import { buildAgentMcpTools } from "../lib/agent-kit/mcp/tools.js";
 import { readKitConfig } from "../lib/agent-kit/kit-config.js";
 import { agentKitPaths } from "../lib/agent-kit/paths.js";
 import { requireExternalCreds } from "./agent-kit.js";
+// Re-exported for callers that imported it from here before it moved.
+export { readBounded } from "../lib/agent-kit/attachment-download.js";
 export const AGENT_MCP_SERVER_NAME = "hq-agent";
 export const AGENT_MCP_INSTRUCTIONS = "You are acting inside HQ as an enrolled external agent. Tools run as that machine identity: " +
     "hq_whoami (identity), hq_search / hq_files_list / hq_files_read (company vault), " +
@@ -78,14 +78,8 @@ export function defaultMcpClients(creds, credsPath, paths = agentKitPaths(os.hom
                 throw err;
             }
         },
-        downloadVaultObject: async (scopeUid, key) => {
-            // Same presign path `hq files cat` uses; the vault API's per-key ACL decides.
-            const client = createCompanyPresignClient({ token: await getToken(), companyUid: scopeUid, baseUrl: creds.apiBaseUrl });
-            const res = await client.send(new GetObjectCommand({ Bucket: scopeUid, Key: key }));
-            if (!res.Body)
-                throw new Error(`no body returned for '${key}'`);
-            return readBounded(res.Body, MAX_ATTACHMENT_BYTES);
-        },
+        // Same presign path `hq files cat` uses; the vault API's per-key ACL decides.
+        downloadVaultObject: createVaultObjectDownloader({ getToken, baseUrl: creds.apiBaseUrl }),
         apiJson: async (token, path, init) => {
             const res = await vaultApiFetch({
                 token,
@@ -100,21 +94,6 @@ export function defaultMcpClients(creds, credsPath, paths = agentKitPaths(os.hom
         },
     };
 }
-/** Drain a stream into memory, refusing past `max` bytes. */
-export async function readBounded(body, max) {
-    const chunks = [];
-    let total = 0;
-    for await (const chunk of body) {
-        const b = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        total += b.length;
-        if (total > max) {
-            body.destroy();
-            throw new Error(`object exceeds the ${max}-byte attachment limit`);
-        }
-        chunks.push(b);
-    }
-    return Buffer.concat(chunks);
-}
 export function createAgentMcpServer(clients) {
     return new McpServer({
         name: AGENT_MCP_SERVER_NAME,

package/dist/commands/bot.js

@@ -25,6 +25,7 @@ import { hasPromotionHold, promotionHoldSummary } from "../lib/bot/promotion-hol
  * list (online flag), and rm. Secrets are never printed.
  */
 import { promoteLocalBot } from "../lib/bot/promote.js";
+import { createVaultObjectDownloader } from "../lib/agent-kit/attachment-download.js";
 import { addBotToCompanies, describeCompanyFailures, removeBotFromCompanies } from "./bot-companies.js";
 import { registerBotContinuityCommand } from "./bot-continuity.js";
 import { registerBotJobsCommand } from "./bot-jobs.js";
@@ -680,9 +681,19 @@ async function runBotResident(nameArg) {
             console.log(orphanBotRunMessage(name, outcome));
         return;
     }
-    const api = new BotApi({ token: botTokenSupplier(dir) });
+    const token = botTokenSupplier(dir);
+    const api = new BotApi({ token });
     const owner = new OwnerContextCache(() => lookupOwnerContext(config.ownerUid), Date.now, undefined, config.ownerUid);
-    const handle = await runBot({ dir, config, api, runtime: runtimeFor(config.runtime), ownerContext: () => owner.get() });
+    const handle = await runBot({
+        dir,
+        config,
+        api,
+        runtime: runtimeFor(config.runtime),
+        ownerContext: () => owner.get(),
+        // Chat attachments are fetched with the bot's own machine identity against
+        // the same API its inbox and posts use (BotApi has no baseUrl override either).
+        downloadAttachment: createVaultObjectDownloader({ getToken: token }),
+    });
     await handle.done;
     void name;
 }

package/dist/commands/lanes.js

@@ -18,7 +18,7 @@ import { buildOutpostLaneCommand, buildOutpostPickupCommand, createOutpostsClien
 import { parseUserYaml } from "../utils/user-yaml-error.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
 import { openMeshTransport } from "../lib/mesh/client.js";
-import { createLaneMesh, emitLaneDecisionEvents, } from "../lib/lanes/mesh-events.js";
+import { createLaneMesh, emitLaneDecisionEvents, emitLaneTerminalStateEvent, laneMeshEventIdentity, } from "../lib/lanes/mesh-events.js";
 import { sessionIdFromEnv } from "../lib/mesh/live/session-identity.js";
 import { AccountResolutionError, compareLaneQueueOrder, coveredLaneIds, DEFAULT_ACCOUNT_HOMES, LANE_PROVIDERS, LANE_STATES, PROVIDER_HOME_ENV, QUESTION_STATUSES, SENIOR_KINDS, accountStatus, appendCappedHistory, canonicalizeHome, createLane, decideAdmission, defaultLivenessDeps, defaultSystemdUserDir, defaultThrottleDeps, installDrainHook, installReconcileTimer, providerPathEnv, probeDrainHookRegistration, isLanesError, isLaneVersionConflict, isTerminalLaneState, listAccountStatuses, listLaneIds, listQuestionIds, listSessionLiveness, loadLanesConfig, laneRunsHere, MAX_LANE_DEPTH, MONITOR_ERROR_EXIT_CODE, MONITOR_ENGINES, MONITOR_MAX_TIMEOUT_MS, MONITOR_UNCOVERED_EXIT_CODE, MAX_WATCHED_LANES, monitorReminderText, readLiveMonitorEvidence, resolveMachineIdentity as lookupMachineIdentity, loadLivenessIndex, parseLaneProvider, parseLaneState, parseLivenessState, parseQuestionStatus, parseSeniorKind, readDaemonPresenceConnected, readLane, retryUpdateLane, readQuestion, resolveAccount, resolveLaneWorker, ignoredWorkerProfileFields, loadWorkerProfile, runReconcilePass, runLaneWatch, sessionLiveness, tryReadLane, uninstallReconcileTimer, updateLane, updateQuestion, writeLanesConfig, appendDropboxMessage, answerDropboxMessage, deliveryRefusalReason, resumeCommandRefusal, dropboxDir, dropboxInboxPath, laneAcceptsDropboxDelivery, laneAcceptsOperatorMessage, laneDeliveryMechanism, hasActiveAdmissionReservation, hasActivePendingResume, hasRecordedSessionId, hasEarlierEligibleQueuedLane, laneAdmissionCapReason, providerSupportsSessionResume, withLaneAdmissionLock, laneIdForAnswerDelivery, operatorMessageRefusalReason, raiseLaneQuestion, sha256Text, writeQuestionBody, } from "../lib/lanes/index.js";
 import { activeLaneStories, laneStories, laneStory, storyWarning, } from "../lib/lanes/stories.js";
@@ -1150,18 +1150,45 @@ function askDeliveryFailedPath(hqRoot, laneId) {
     return path.join(runDir(hqRoot, laneId), "ask_delivery_failed.json");
 }
 async function emitLaneMeshEvent(ctx, company, threadId, event, payload) {
-    if (!threadId || !company)
+    if (!company)
+        return;
+    let targetThreadId = threadId;
+    let eventPayload = payload;
+    const laneId = typeof payload.lane_id === "string" ? payload.lane_id.trim() : "";
+    if (laneId && ctx.mesh.ensureLaneThread) {
+        const lane = readLane(ctx.hqRoot(), laneId);
+        const ready = await ensureLaneThreadRecord(ctx, lane, lane.project_id, lane.story_id, "running");
+        targetThreadId = ready.thread_id;
+        eventPayload = { ...laneMeshEventIdentity(ready), ...payload };
+    }
+    if (!targetThreadId)
         return;
-    await ctx.mesh.appendThreadEvent(company, threadId, event, payload);
+    await ctx.mesh.appendThreadEvent(company, targetThreadId, event, eventPayload);
+}
+async function emitLaneTerminalStateSoft(ctx, lane) {
+    if (lane.state !== "failed" && lane.state !== "interrupted" &&
+        lane.state !== "cancelled" && lane.state !== "killed")
+        return;
+    try {
+        await emitLaneTerminalStateEvent(ctx.mesh, lane, lane.state, lane.terminal_reason, AbortSignal.timeout(10_000));
+    }
+    catch (err) {
+        process.stderr.write(`hq lanes: terminal mesh update failed for ${lane.lane_id}: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
 }
 async function emitLaneStartedForStories(ctx, company, lane, threadId) {
-    if (!threadId)
+    const ready = ctx.mesh.ensureLaneThread
+        ? await ensureLaneThreadRecord(ctx, lane, lane.project_id, lane.story_id, "running")
+        : lane;
+    const stableThreadId = ready.thread_id ?? threadId;
+    if (!stableThreadId)
         return;
     const failures = [];
-    for (const story of laneStories(lane)) {
+    for (const story of laneStories(ready)) {
         try {
-            await emitLaneMeshEvent(ctx, company, threadId, "lane_started", {
-                lane_id: lane.lane_id,
+            await emitLaneMeshEvent(ctx, company, stableThreadId, "lane_started", {
+                ...laneMeshEventIdentity(ready),
+                lane_id: ready.lane_id,
                 project_id: story.project_id,
                 story_id: story.story_id,
             });
@@ -1630,9 +1657,8 @@ async function runCreate(ctx, opts) {
                     (profileAccounts === undefined || profileAccounts.includes(id)))
                     .map(([id]) => id))]
         : undefined;
-    const threadId = meshCompany
-        ? await ctx.mesh.ensureProjectThread(meshCompany, project)
-        : undefined;
+    // The lane id is created in `persist`; its Work Mesh thread is ensured
+    // immediately afterward from that stable identity.
     const persist = async () => {
         let admission;
         let validation;
@@ -1712,7 +1738,6 @@ async function runCreate(ctx, opts) {
                 added_at: createdAt,
                 updated_at: createdAt,
             })),
-            thread_id: threadId,
             depth: laneDepth,
             senior,
             senior_history: [],
@@ -1765,7 +1790,35 @@ async function runCreate(ctx, opts) {
     else {
         persisted = await withLaneAdmissionLock(hqRoot, provider, persist, ctx.sleep);
     }
-    const { lane, admission, validation } = persisted;
+    let lane = persisted.lane;
+    const { admission, validation } = persisted;
+    if (meshCompany) {
+        try {
+            lane = await ensureLaneThreadRecord(ctx, lane);
+        }
+        catch {
+            try {
+                lane = casUpdateLane(ctx.hqRoot(), lane.lane_id, (current) => ({
+                    ...current,
+                    state: "failed",
+                    queued_reason: undefined,
+                    terminal_reason: "mesh_thread_registration_failed",
+                }));
+            }
+            catch {
+                throw new LanesError("mesh_thread_registration_failed", `Work Mesh lane registration failed for ${lane.lane_id}, and its local record could not be marked terminal.`, { lane_id: lane.lane_id });
+            }
+            throw new LanesError("mesh_thread_registration_failed", `Work Mesh lane registration failed; lane ${lane.lane_id} was marked failed.`, { lane_id: lane.lane_id, state: lane.state });
+        }
+    }
+    // Thread registration runs after persistence; anchor the reservation after
+    // its network work so a slow response cannot age the slot before spawn.
+    if (meshCompany && admission.action === "start" && lane.admission_reserved_at) {
+        lane = casUpdateLane(ctx.hqRoot(), lane.lane_id, (current) => ({
+            ...current,
+            admission_reserved_at: ctx.now().toISOString(),
+        }));
+    }
     const dest = runDir(hqRoot, lane.lane_id);
     ensureDir(path.join(dest, "logs"));
     ensureDir(path.join(dest, "envelopes"));
@@ -1802,7 +1855,7 @@ async function runCreate(ctx, opts) {
             locateTranscript: ctx.locateTranscript,
         });
         if (meshCompany)
-            await emitLaneStartedForStories(ctx, meshCompany, started, threadId);
+            await emitLaneStartedForStories(ctx, meshCompany, started, started.thread_id);
     }
     else if (outpostId) {
         started = await dispatchCreatedOutpostLane(ctx, {
@@ -1864,13 +1917,15 @@ async function dispatchCreatedOutpostLane(ctx, input) {
         const dispatched = await ctx.dispatchOutpostExec({ outpostId, command });
         const remote = parseRemotePickupJson(dispatched.stdout);
         if (remote?.error === "outpost_self_target") {
-            return casUpdateLane(hqRoot, lane.lane_id, (current) => ({
+            const cancelled = casUpdateLane(hqRoot, lane.lane_id, (current) => ({
                 ...current,
                 state: "cancelled",
                 queued_reason: undefined,
                 terminal_reason: "outpost_self_target",
                 outpost_command_id: dispatched.commandId,
             }));
+            await emitLaneTerminalStateSoft(ctx, cancelled);
+            return cancelled;
         }
         const stdoutTrimmed = dispatched.stdout.trim();
         if (remote === null && stdoutTrimmed !== "" && dispatched.status !== "Success") {
@@ -1882,6 +1937,7 @@ async function dispatchCreatedOutpostLane(ctx, input) {
                 stderr: dispatched.stderr.slice(0, 2000),
                 parse_error: "unparseable_pickup_stdout",
             });
+            await emitLaneTerminalStateSoft(ctx, failed);
             throw new LanesError(DISPATCH_TERMINAL_REASON, "Outpost pickup command failed", {
                 outpost_id: outpostId,
                 lane_id: failed.lane_id,
@@ -1899,6 +1955,7 @@ async function dispatchCreatedOutpostLane(ctx, input) {
                 status: dispatched.status,
                 stderr: dispatched.stderr.slice(0, 2000),
             });
+            await emitLaneTerminalStateSoft(ctx, failed);
             throw new LanesError(DISPATCH_TERMINAL_REASON, "Outpost pickup command failed", {
                 outpost_id: outpostId,
                 lane_id: failed.lane_id,
@@ -1923,6 +1980,7 @@ async function dispatchCreatedOutpostLane(ctx, input) {
             outpost_id: outpostId,
             message,
         });
+        await emitLaneTerminalStateSoft(ctx, failed);
         throw new LanesError(DISPATCH_TERMINAL_REASON, `Failed to dispatch lane to Outpost ${outpostId}: ${message}`, {
             outpost_id: outpostId,
             lane_id: failed.lane_id,
@@ -2126,6 +2184,7 @@ async function runPickup(ctx, opts) {
         env: ctx.env,
     });
     if (isTerminalLaneState(afterAccount.state)) {
+        await emitLaneTerminalStateSoft(ctx, afterAccount);
         printJson({
             ok: true,
             action: "pickup",
@@ -3150,17 +3209,32 @@ function callerMayVerifyStory(ctx, lane) {
         return false;
     return sessionIdFromEnv(ctx.env) === lane.senior.id;
 }
-async function ensureStoryThread(ctx, lane, projectId) {
+async function ensureStoryThread(ctx, lane, projectId, storyId = lane.story_id) {
+    const company = lane.mesh_company ?? lane.company;
+    if (!company)
+        return lane;
+    return ensureLaneThreadRecord(ctx, lane, projectId, storyId);
+}
+async function ensureLaneThreadRecord(ctx, lane, projectId = lane.project_id, storyId = lane.story_id, laneStatus = lane.state) {
     const company = lane.mesh_company ?? lane.company;
     if (!company)
         return lane;
-    const threadId = await ctx.mesh.ensureProjectThread(company, projectId);
-    if (threadId === lane.thread_id)
+    const descriptorLane = { ...lane, project_id: projectId, story_id: storyId };
+    const threadId = ctx.mesh.ensureLaneThread
+        ? await ctx.mesh.ensureLaneThread(company, descriptorLane, laneStatus)
+        : await ctx.mesh.ensureProjectThread(company, projectId);
+    if (threadId === lane.thread_id && !lane.thread_id.startsWith("proj-"))
         return lane;
-    return casUpdateLane(ctx.hqRoot(), lane.lane_id, (current) => ({
+    const updated = casUpdateLane(ctx.hqRoot(), lane.lane_id, (current) => ({
         ...current,
         thread_id: threadId,
     }));
+    // The CAS changes the lane version. Refresh once so the server descriptor
+    // and the durable local record converge before the worker starts.
+    if (ctx.mesh.ensureLaneThread) {
+        await ctx.mesh.ensureLaneThread(company, { ...updated, project_id: projectId, story_id: storyId }, laneStatus);
+    }
+    return updated;
 }
 async function emitStoryTransition(ctx, lane, projectId, storyId, event, status, payload = {}) {
     const company = lane.mesh_company ?? lane.company;
@@ -3174,6 +3248,7 @@ async function emitStoryTransition(ctx, lane, projectId, storyId, event, status,
         project_id: projectId,
         story_id: storyId,
         ...payload,
+        lane_status: lane.state,
     });
     await ctx.mesh.patchStoryStatus(company, projectId, storyId, status === "blocked" ? "in_progress" : status);
 }
@@ -3514,6 +3589,7 @@ async function runStop(ctx, laneId) {
             sleepMs: ctx.stopSleepMs,
         });
     }
+    await emitLaneTerminalStateSoft(ctx, updated);
     const cancelled = cancelPendingQuestionsForLane(hqRoot, laneId, at);
     printJson({
         ok: true,

package/dist/commands/mesh.js

@@ -59,14 +59,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;
 }
@@ -320,6 +328,9 @@ function mergeProjectRepos(current, planned) {
     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.");
     }
@@ -358,6 +369,7 @@ async function runProjectSet(projectId, opts) {
     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,
@@ -367,10 +379,12 @@ async function runProjectSet(projectId, opts) {
             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 {
+    else if (opts.name !== undefined || opts.description !== undefined || source !== undefined || explicitRepos !== undefined) {
         try {
             view = await putProjectView(token, company.companyUid, projectId, {
                 name: opts.name?.trim() || source?.name || current.name,
@@ -395,18 +409,30 @@ async function runProjectSet(projectId, opts) {
             throw err;
         }
     }
+    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 }, null, 2));
+        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?.trim()) {
-        fail("--channel is not supported by the current Work Mesh registration API; omit it to let the server create or bind the project channel.");
+    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());
@@ -425,7 +451,7 @@ async function runProjectRegister(projectId, opts) {
     }
     let registration;
     try {
-        registration = await registerMeshProject(token, company.companyUid, projectId);
+        registration = await registerMeshProject(token, company.companyUid, projectId, opts.channel);
     }
     catch (err) {
         const failure = err;
@@ -1787,6 +1813,7 @@ export function registerMeshCommand(program) {
         .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("--json", "Print machine-readable JSON")
         .action((projectId, opts) => wrap(() => runProjectSet(projectId, opts))());
@@ -1801,7 +1828,7 @@ export function registerMeshCommand(program) {
         .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>", "Reserved: the current server chooses the project channel")
+        .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

package/dist/lib/agent-kit/attachment-download.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Vault object download for chat attachments, shared by `hq agent mcp`
+ * (hq_attachment_fetch) and the local bot runner (`hq bot run`).
+ *
+ * Bytes come through the same vault presign path `hq files cat` uses
+ * (`createCompanyPresignClient` → POST /v1/files/presign) with the caller's own
+ * machine token, so the server's per-key ACL stays the authority. The body is
+ * read with a hard byte cap so a crafted key cannot pull a large object into
+ * memory.
+ */
+import type { Readable } from "node:stream";
+export type VaultObjectDownloader = (scopeUid: string, key: string) => Promise<Buffer>;
+/** Drain a stream into memory, refusing past `max` bytes. */
+export declare function readBounded(body: Readable, max: number): Promise<Buffer>;
+/**
+ * A downloader bound to one identity. `baseUrl` pins the API the token is sent
+ * to (an enrolled agent passes its own `apiBaseUrl`; undefined = the default
+ * vault API, the same one the caller's other API calls use).
+ */
+export declare function createVaultObjectDownloader(opts: {
+    getToken: () => Promise<string>;
+    baseUrl?: string;
+}): VaultObjectDownloader;
+//# sourceMappingURL=attachment-download.d.ts.map

package/dist/lib/agent-kit/attachment-download.js

@@ -0,0 +1,47 @@
+/**
+ * Vault object download for chat attachments, shared by `hq agent mcp`
+ * (hq_attachment_fetch) and the local bot runner (`hq bot run`).
+ *
+ * Bytes come through the same vault presign path `hq files cat` uses
+ * (`createCompanyPresignClient` → POST /v1/files/presign) with the caller's own
+ * machine token, so the server's per-key ACL stays the authority. The body is
+ * read with a hard byte cap so a crafted key cannot pull a large object into
+ * memory.
+ */
+import { GetObjectCommand } from "@aws-sdk/client-s3";
+import { createCompanyPresignClient } from "../../commands/files-browse.js";
+import { MAX_ATTACHMENT_BYTES } from "./mcp/attachments.js";
+/** Drain a stream into memory, refusing past `max` bytes. */
+export async function readBounded(body, max) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of body) {
+        const b = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += b.length;
+        if (total > max) {
+            body.destroy();
+            throw new Error(`object exceeds the ${max}-byte attachment limit`);
+        }
+        chunks.push(b);
+    }
+    return Buffer.concat(chunks);
+}
+/**
+ * A downloader bound to one identity. `baseUrl` pins the API the token is sent
+ * to (an enrolled agent passes its own `apiBaseUrl`; undefined = the default
+ * vault API, the same one the caller's other API calls use).
+ */
+export function createVaultObjectDownloader(opts) {
+    return async (scopeUid, key) => {
+        const client = createCompanyPresignClient({
+            token: await opts.getToken(),
+            companyUid: scopeUid,
+            ...(opts.baseUrl ? { baseUrl: opts.baseUrl } : {}),
+        });
+        const res = await client.send(new GetObjectCommand({ Bucket: scopeUid, Key: key }));
+        if (!res.Body)
+            throw new Error(`no body returned for '${key}'`);
+        return readBounded(res.Body, MAX_ATTACHMENT_BYTES);
+    };
+}
+//# sourceMappingURL=attachment-download.js.map

package/dist/lib/agent-kit/inbox-state.d.ts

@@ -30,11 +30,15 @@ export interface InboxAttachment {
     companyUid?: string;
 }
 /**
- * The file references on an inbox entry, plural `attachments[]` first and the
+ * The file references on an inbox entry (a mirrored kit entry or a bot
+ * runner's raw inbox item), plural `attachments[]` first and the
  * legacy singular `attachment` as a fallback. Entries without a `vaultPath` are
  * dropped: a reference the bot cannot fetch is worse than none. Pure.
  */
-export declare function inboxEntryAttachments(e: MirroredInboxEntry): InboxAttachment[];
+export declare function inboxEntryAttachments(e: MirroredInboxEntry | {
+    attachments?: unknown;
+    attachment?: unknown;
+}): InboxAttachment[];
 /**
  * Compact view for bots: who, when, which channel, the text, and any attached
  * files. The attachments belong here because this summary IS the message as far