@indigoai-us/hq-cli 5.108.24 → 5.108.26

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

@@ -52,7 +52,6 @@
  * first-class skip), and {@link registerMcpServers} is the pack-install routing
  * seam over it.
  */
-import { type FlagReader } from '../lib/flag-registry.js';
 /** Base for every MCP-registration error; carries a stable machine-checkable `code`. */
 export declare abstract class McpRegistrationError extends Error {
     abstract readonly code: string;
@@ -596,10 +595,17 @@ export declare function registerServer(opts: RegisterServerOptions): RegisterSer
  * when neither a url nor a command is present.
  */
 export declare function manifestTarget(manifest: McpManifest): string;
-/** Resolve the gate once at the start of an MCP registration operation. */
-export declare function isMcpRegistrationEnabled(flagReader?: FlagReader): boolean;
-/** Freeze a registration decision so multi-server work cannot split on refresh. */
-export declare function captureMcpRegistrationDecision(flagReader?: FlagReader): FlagReader;
+/**
+ * Resolve the MCP registration kill switch from its env var alone.
+ *
+ * `HQ_DISABLE_MCP_REGISTRATION` is an operator's own machine-local opt-out, not
+ * a rollout flag, so it is read straight from the environment — no registry
+ * lookup. The polarity is inverted and the value match is asymmetric on
+ * purpose: ONLY the exact value "1" disables registration; unset and every
+ * other value (including "0" and "false") leave it enabled. Do not "tidy" this
+ * into a boolean parse — that would silently disable anyone who wrote "false".
+ */
+export declare function isMcpRegistrationEnabled(env?: Readonly<Record<string, string | undefined>>): boolean;
 /**
  * Register one pack's MCP servers into the shared agent configs (the public seam
  * `pack-install` routes `wire:'merge'` keys to). For each declared server name it
@@ -627,8 +633,12 @@ export declare function registerMcpServers(pkg: string, names: string[], options
     /** Lock tuning + backup stamp passthrough (tests). */
     lock?: AcquireLockOptions;
     stamp?: string;
-    /** Test seam: held registry snapshot reader. */
-    flagReader?: FlagReader;
+    /**
+     * Pre-resolved kill-switch decision, frozen once before a multi-server loop
+     * so an install writes either all of a pack's servers or none of them.
+     * Omitted → read `HQ_DISABLE_MCP_REGISTRATION` directly.
+     */
+    registrationEnabled?: boolean;
 }): RegisterServerResult[];
 /** smol-toml's value-table type (its `parse` return + `stringify` input). */
 type TomlTable = Record<string, unknown>;

package/dist/commands/mcp-registration.js

@@ -57,7 +57,6 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
-import { resolveFlagGate, resolveProcessFlagGate, } from '../lib/flag-registry.js';
 // ---------------------------------------------------------------------------
 // Named error classes (no bare catch-all anywhere in this module).
 //
@@ -1226,28 +1225,18 @@ export function manifestTarget(manifest) {
     }
     return manifest.url ?? '';
 }
-/** Registry vocabulary for the legacy MCP operator kill switch. */
-const MCP_REGISTRATION_LOOKUP = {
-    globalEnvVar: 'HQ_DISABLE_MCP_REGISTRATION',
-    globalValueSemantics: {
-        onValues: [],
-        offValues: ['1'],
-        unrecognizedValue: true,
-        unsetValue: true,
-    },
-    fallback: true,
-};
-const mcpRegistrationLegacyFallback = () => process.env.HQ_DISABLE_MCP_REGISTRATION !== '1';
-/** Resolve the gate once at the start of an MCP registration operation. */
-export function isMcpRegistrationEnabled(flagReader) {
-    return flagReader
-        ? resolveFlagGate(flagReader, 'cli.mcp-registration', MCP_REGISTRATION_LOOKUP, mcpRegistrationLegacyFallback)
-        : resolveProcessFlagGate('cli.mcp-registration', MCP_REGISTRATION_LOOKUP, mcpRegistrationLegacyFallback);
-}
-/** Freeze a registration decision so multi-server work cannot split on refresh. */
-export function captureMcpRegistrationDecision(flagReader) {
-    const enabled = isMcpRegistrationEnabled(flagReader);
-    return { isEnabled: () => enabled };
+/**
+ * Resolve the MCP registration kill switch from its env var alone.
+ *
+ * `HQ_DISABLE_MCP_REGISTRATION` is an operator's own machine-local opt-out, not
+ * a rollout flag, so it is read straight from the environment — no registry
+ * lookup. The polarity is inverted and the value match is asymmetric on
+ * purpose: ONLY the exact value "1" disables registration; unset and every
+ * other value (including "0" and "false") leave it enabled. Do not "tidy" this
+ * into a boolean parse — that would silently disable anyone who wrote "false".
+ */
+export function isMcpRegistrationEnabled(env = process.env) {
+    return env.HQ_DISABLE_MCP_REGISTRATION !== '1';
 }
 /**
  * Register one pack's MCP servers into the shared agent configs (the public seam
@@ -1275,14 +1264,14 @@ export function registerMcpServers(pkg, names, options) {
     // ORDERING: this is checked FIRST, BEFORE the loadManifest programmer-error guard
     // below. The kill-switch is a USER/OPERATOR condition; the missing-loadManifest
     // throw is a PROGRAMMER error. An operator who set the kill-switch must never hit a
-    // spurious McpManifestError, so the operator path wins. Its legacy environment
-    // predicate remains the outage fallback; `options.env` is the SafeWriteEnv
-    // home-path injector, not process env.
+    // spurious McpManifestError, so the operator path wins. The decision is read
+    // straight from `HQ_DISABLE_MCP_REGISTRATION`; `options.env` is the
+    // SafeWriteEnv home-path injector, not the process env this switch reads.
     //
     // Returns an empty RegisterServerResult[] (`[]`) — the correct "no servers
     // registered" semantic — so callers (pack-install) consume it gracefully. The skip
     // NOTICE is emitted exactly once per registerMcpServers call.
-    if (!isMcpRegistrationEnabled(options?.flagReader)) {
+    if (!(options?.registrationEnabled ?? isMcpRegistrationEnabled())) {
         process.stderr.write('MCP registration skipped (HQ_DISABLE_MCP_REGISTRATION=1)\n');
         return [];
     }

package/dist/commands/mesh.js

@@ -14,10 +14,17 @@ import { createCandidatesFetcher, createMigratePoster, createOrganizePoster, cre
 import { clearDefaultCompany, getDefaultCompany, readDeviceConfig, recordMigrationCapabilitySnapshot, setDefaultCompany, } from "../lib/work-context/config.js";
 import { DefaultCompanyLockedError, DefaultCompanyUnavailableError, } from "../lib/work-context/errors.js";
 import { isValidSessionId } from "../lib/mesh/live/session-identity.js";
-import { CLI_KIND_TO_SCHEMA, EnqueueValidationError, enqueueSessionEvent, } from "../lib/mesh/live/index.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";
+import { createEmitPoster, buildMeshEmitEvent } from "../lib/mesh/live/emit-client.js";
+import { emitEvents } 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 { workContextRoot } from "../lib/work-context/paths.js";
@@ -319,6 +326,9 @@ async function runContextBackfillHeld(opts) {
         workContextRoot: root,
         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,
         reconcile: (obs) => reconcileObservation(
         // Pass --company as a non-forcing hint (remoteOwnerSlug feeds
         // deterministic resolution BELOW the identity-file / device default,
@@ -725,9 +735,9 @@ function workMeshHomeRoot() {
     return workMeshRoot(os.homedir(), process.env);
 }
 async function runSessionEnqueue(cliKind, opts) {
-    if (!opts.enqueue) {
-        fail("`hq mesh session …` requires --enqueue (local spool append; no network).");
-    }
+    // `--enqueue` is retained for hook back-compat but now means "emit directly"
+    // (owner decision 2026-09-08: sessions POST events to the server over HTTPS;
+    // no local spool/daemon on the emit path).
     const kind = CLI_KIND_TO_SCHEMA[cliKind];
     if (!kind)
         fail(`Unknown session verb: ${cliKind}`);
@@ -741,57 +751,155 @@ async function runSessionEnqueue(cliKind, opts) {
     const seq = Number(opts.seq);
     if (!Number.isInteger(seq) || seq < 1)
         fail("--seq must be an integer >= 1");
-    let toolWrites;
-    if (opts.toolWrites !== undefined) {
-        toolWrites = Number(opts.toolWrites);
-        if (!Number.isInteger(toolWrites) || toolWrites < 0) {
-            fail("--tool-writes must be an integer >= 0");
+    const sessionId = resolveEnqueueSessionId(opts.sessionId, process.env);
+    if (!sessionId)
+        fail("sessionId required (--session-id or HQ_SESSION_ID)");
+    const evidence = buildEmitEvidence({
+        sessionId: sessionId,
+        hqRoot: opts.hqRoot,
+        cwd: opts.cwd,
+        touchedPaths: opts.touchedPath,
+        repoPath: opts.repoPath,
+        companySlug: opts.companySlug,
+        project: opts.project,
+        task: opts.task,
+    });
+    const event = buildMeshEmitEvent({
+        eventId: opts.eventId?.trim() || generateUlid(Date.now()),
+        kind: kind,
+        sessionId: sessionId,
+        harness,
+        adapterVersion,
+        at: opts.at?.trim() || new Date().toISOString(),
+        seq,
+        runtimeVersion: opts.runtimeVersion,
+        source: "hooks",
+        taskId: opts.taskId,
+        status: opts.status,
+        reason: opts.reason,
+        summary: opts.summary,
+        evidence,
+    });
+    const meshRoot = workMeshHomeRoot();
+    // 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;
+    try {
+        token = await requireToken();
+    }
+    catch {
+        token = null;
+    }
+    if (!token) {
+        const pending = readEmitRetry(meshRoot);
+        const { written } = writeEmitRetry(meshRoot, [...pending, event]);
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: true, action: "emit", kind, deferred: true, retryDepth: written }, null, 2));
+            return;
         }
+        console.error(`work-mesh: no token; deferred ${kind} (retryDepth=${written})`);
+        return;
     }
-    try {
-        const result = enqueueSessionEvent({
-            kind: kind,
-            sessionId: opts.sessionId,
-            harness,
-            adapterVersion,
-            runtimeVersion: opts.runtimeVersion,
-            seq,
-            eventId: opts.eventId,
-            at: opts.at,
-            taskId: opts.taskId,
-            status: opts.status,
-            reason: opts.reason,
-            summary: opts.summary,
-            cwd: opts.cwd,
-            hqRoot: opts.hqRoot,
-            companySlug: opts.companySlug,
-            project: opts.project,
-            task: opts.task,
-            toolWrites,
-            root: workMeshHomeRoot(),
-            env: process.env,
-        });
+    const poster = createEmitPoster({
+        token,
+        baseUrl: resolveVaultApiBase(process.env),
+    });
+    const summary = await emitEvents({
+        workMeshRoot: meshRoot,
+        poster,
+        newEvents: [event],
+    });
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, action: "emit", kind, ...summary }, null, 2));
+        return;
+    }
+    console.error(`work-mesh: emit ${kind} accepted=${summary.accepted}` +
+        ` unassigned=${summary.unassigned} rejected=${summary.rejected}` +
+        ` retryDepth=${summary.retryDepth}`);
+}
+async function runMeshMode(action, opts) {
+    const meshRoot = workMeshHomeRoot();
+    const act = (action ?? "get").toLowerCase();
+    if (act === "get") {
+        const mode = resolveMeshEmitMode({ env: process.env, meshRoot });
         if (opts.json) {
-            console.log(JSON.stringify({
-                ok: true,
-                action: "enqueue",
-                kind,
-                spoolPath: result.spoolPath,
-                eventId: result.event.eventId,
-            }, null, 2));
+            console.log(JSON.stringify({ ok: true, action: "mode", mode }, null, 2));
             return;
         }
-        // Quiet success for hooks/scripts — eventId on stderr only when not json.
-        console.error(`work-mesh: enqueued ${kind} ${result.event.eventId}`);
+        console.log(`mesh emit mode: ${mode}`);
+        return;
     }
-    catch (err) {
-        if (err instanceof EnqueueValidationError) {
-            console.error(chalk.red(`enqueue validation failed: ${err.message}`));
-            process.exitCode = 1;
+    if (act === "legacy" || act === "direct") {
+        writeMeshConfigMode(meshRoot, act);
+        const mode = resolveMeshEmitMode({ env: process.env, meshRoot });
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: true, action: "mode", set: act, effective: mode }, null, 2));
             return;
         }
-        throw err;
+        console.log(`mesh emit mode set to ${act}` +
+            (mode !== act
+                ? ` (note: HQ_MESH_MODE=${process.env.HQ_MESH_MODE} overrides → ${mode})`
+                : "") +
+            `. Restart the daemon (hq mesh daemon run) to apply.`);
+        return;
+    }
+    if (act === "check") {
+        // Probe the server route with an empty batch: 2xx/400 => route live,
+        // 404 => not deployed yet (safe to stay legacy).
+        let token;
+        try {
+            token = await requireToken();
+        }
+        catch (err) {
+            fail(err instanceof Error ? err.message : String(err));
+            return;
+        }
+        const poster = createEmitPoster({
+            token,
+            baseUrl: resolveVaultApiBase(process.env),
+        });
+        const res = await poster([]);
+        const ready = res.status === 200 || res.status === 400;
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: true, action: "mode", check: true, status: res.status, ready }, null, 2));
+            return;
+        }
+        console.log(`mesh route /v1/mesh/events: status=${res.status} ${ready ? "READY (safe to `hq mesh mode direct`)" : "not ready (stay legacy)"}`);
+        return;
+    }
+    fail(`Unknown mode action: ${act} (use get|legacy|direct|check)`);
+}
+async function runMeshEmit(opts) {
+    const token = await requireToken();
+    const meshRoot = workMeshHomeRoot();
+    const poster = createEmitPoster({
+        token,
+        baseUrl: resolveVaultApiBase(process.env),
+    });
+    let scanned = 0;
+    let skipped = 0;
+    let newEvents = [];
+    if (opts.replayLegacy) {
+        const backlog = readLegacyBacklog(meshRoot);
+        scanned = backlog.scanned;
+        skipped = backlog.skipped;
+        newEvents = backlog.events;
+    }
+    const summary = await emitEvents({ workMeshRoot: meshRoot, poster, newEvents });
+    const out = {
+        ok: true,
+        action: "emit",
+        ...(opts.replayLegacy ? { replayLegacy: true, legacyScanned: scanned, legacySkipped: skipped } : {}),
+        ...summary,
+    };
+    if (opts.json) {
+        console.log(JSON.stringify(out, null, 2));
+        return;
     }
+    console.log(`work-mesh emit: attempted=${summary.attempted} accepted=${summary.accepted}` +
+        ` unassigned=${summary.unassigned} rejected=${summary.rejected}` +
+        ` retryDepth=${summary.retryDepth}` +
+        (opts.replayLegacy ? ` (legacy scanned=${scanned} skipped=${skipped})` : ""));
 }
 async function runSessionFlush(opts) {
     const token = await requireToken();
@@ -829,10 +937,12 @@ function addSessionEnqueueFlags(cmd) {
         .option("--summary <text>", "Short summary (max 280)")
         .option("--cwd <path>", "Local-only working directory")
         .option("--hq-root <path>", "Local-only HQ tree root")
-        .option("--company-slug <slug>", "Local-only company slug hint")
-        .option("--project <name>", "Local-only project hint")
-        .option("--task <label>", "Local-only task label hint")
-        .option("--tool-writes <n>", "Local-only tool write count")
+        .option("--company-slug <slug>", "Attribution evidence: bound company slug")
+        .option("--project <name>", "Attribution evidence: project id/slug")
+        .option("--task <label>", "Attribution evidence: task id/label")
+        .option("--touched-path <path>", "Attribution evidence: a file path this tool call touched (repeatable)", collectRepeatable)
+        .option("--repo-path <path>", "Attribution evidence: enclosing repo path")
+        .option("--tool-writes <n>", "Local-only tool write count (unused on emit)")
         .option("--json", "Print machine-readable JSON");
 }
 function wrap(action) {
@@ -1012,6 +1122,20 @@ export function registerMeshCommand(program) {
         .description("Claim spool/held by rename, hold or drop by context state, POST batches of ≤100")
         .option("--json", "Print machine-readable JSON")
         .action((opts) => wrap(() => runSessionFlush(opts))());
+    mesh
+        .command("mode")
+        .description("Get/set the daemon emit mode (legacy = spool/flush; direct = receive-only). " +
+        "`check` probes whether the server route is live.")
+        .argument("[action]", "get | legacy | direct | check (default get)")
+        .option("--json", "Print machine-readable JSON")
+        .action((action, opts) => wrap(() => runMeshMode(action, opts))());
+    mesh
+        .command("emit")
+        .description("Direct-emit drain: POST any deferred events (retry file) to /v1/mesh/events; " +
+        "--replay-legacy also replays the legacy spool/held backlog through the new endpoint")
+        .option("--replay-legacy", "Also replay spool.jsonl + held.jsonl with their evidence")
+        .option("--json", "Print machine-readable JSON")
+        .action((opts) => wrap(() => runMeshEmit(opts))());
     session
         .command("status")
         .description("Print the company-wide live read (US-004) as a table or --json")

package/dist/commands/pack-install.js

@@ -52,7 +52,7 @@ import { safeExtractTarball } from './safe-extract.js';
 import { getCompanyUid, vaultApiFetch, vaultApiFetchPublic, } from '../utils/vault-api.js';
 import { ensureCognitoToken } from '../utils/cognito-session.js';
 import { formatApiKeyCapabilityDenial, peekHqApiKey, } from '../utils/resolve-vault-credential.js';
-import { redactSecrets, SECRET_REDACTION, captureMcpRegistrationDecision, registerMcpServers, McpManifestError, } from './mcp-registration.js';
+import { redactSecrets, SECRET_REDACTION, isMcpRegistrationEnabled, registerMcpServers, McpManifestError, } from './mcp-registration.js';
 import { listSecretCacheScopes } from '../utils/secrets-cache.js';
 import { loadRevealedSecrets } from './secrets.js';
 const PACK_UPDATE_CACHE_TTL_MS = 12 * 60 * 60 * 1000;
@@ -1492,9 +1492,9 @@ async function wireMcpServers(pkg, destDir, company) {
     const loadManifest = (name) => loadMcpManifestFrom(destDir, name);
     const registered = [];
     const skipped = [];
-    // A refresh may arrive while secret resolution awaits. Freeze the gate before
-    // the loop so an install never writes only an arbitrary prefix of a pack.
-    const flagReader = captureMcpRegistrationDecision();
+    // Resolve the kill-switch once and freeze it before the loop so an install
+    // never writes only an arbitrary prefix of a pack's servers.
+    const registrationEnabled = isMcpRegistrationEnabled();
     for (const name of pkg.contributes.mcp ?? []) {
         try {
             const resolveSecret = await makeInstallSecretResolver(collectManifestSecretNames(loadManifest(name)), company);
@@ -1503,7 +1503,7 @@ async function wireMcpServers(pkg, destDir, company) {
             const results = registerMcpServers(pkg.name, [name], {
                 loadManifest,
                 resolveSecret,
-                flagReader,
+                registrationEnabled,
             });
             if (results.length > 0)
                 registered.push(name);

package/dist/commands/secrets.d.ts

@@ -3,6 +3,13 @@ import { writeSync } from "node:fs";
 import { vaultApiFetch, getCompanyUid, getEntityUid } from "../utils/vault-api.js";
 export type { VaultApiOptions } from "../utils/vault-api.js";
 export { vaultApiFetch, getCompanyUid, getEntityUid };
+/**
+ * Mirrors `RESOURCE_SURFACES` in hq-pro
+ * `src/journey/limited-resource-telemetry.ts`. Keep this list in sync with
+ * the server so CLI telemetry cannot silently fall back to `api`.
+ */
+export declare const HQ_PRO_RESOURCE_SURFACES: readonly ["api", "bot_invite", "bot_join_now", "calendar_auto_schedule", "calendar_preferences", "cli_secrets_set", "console_secrets_form", "deploy_precheck", "external_connection", "factory_install", "integrations_connect", "oauth_callback", "plan_limit_check", "secrets_input_link", "web"];
+export declare const CLI_SECRETS_SET_SURFACE = "cli_secrets_set";
 export type SecretTier = "standard" | "sensitive" | "nuclear";
 export type SecretScriptLockMode = "off" | "enforced";
 export type SecretUsageChannel = "run" | "exec" | "env" | "sandbox" | "reveal" | "submit-link";

package/dist/commands/secrets.js

@@ -12,6 +12,29 @@ import { vaultApiFetch, getCompanyUid, getEntityUid, looksLikeCompanyUid, } from
 import { HQ_API_KEY_PREFIX, formatApiKeyCapabilityDenial, requireApiKeyCapability, resolveVaultCredentialForCapability, } from "../utils/resolve-vault-credential.js";
 import { SandboxRunnerClient, } from "../utils/sandbox-runner-client.js";
 export { vaultApiFetch, getCompanyUid, getEntityUid };
+/**
+ * Mirrors `RESOURCE_SURFACES` in hq-pro
+ * `src/journey/limited-resource-telemetry.ts`. Keep this list in sync with
+ * the server so CLI telemetry cannot silently fall back to `api`.
+ */
+export const HQ_PRO_RESOURCE_SURFACES = [
+    "api",
+    "bot_invite",
+    "bot_join_now",
+    "calendar_auto_schedule",
+    "calendar_preferences",
+    "cli_secrets_set",
+    "console_secrets_form",
+    "deploy_precheck",
+    "external_connection",
+    "factory_install",
+    "integrations_connect",
+    "oauth_callback",
+    "plan_limit_check",
+    "secrets_input_link",
+    "web",
+];
+export const CLI_SECRETS_SET_SURFACE = "cli_secrets_set";
 /**
  * Cognito session for secrets surfaces hq-pro serves on the JWT routes only —
  * the capability would apply, but there is no Bearer `hqk_` route (no HEAD
@@ -829,9 +852,10 @@ export function registerSecretsCommand(program) {
                 body: {
                     name,
                     value,
+                    surface: CLI_SECRETS_SET_SURFACE,
                     // Only present when --high-security was passed — an ordinary
-                    // `set` with no flags sends exactly `{ name, value }`, byte-for-
-                    // byte unchanged from before this story.
+                    // `set` with no flags sends only its name/value plus this additive
+                    // telemetry attribution field.
                     ...(opts.highSecurity ? { highSecurity: true } : {}),
                     ...(destinations ? { destinations } : {}),
                     ...(injection ? { injection } : {}),

package/dist/lib/mesh/live/backfill-held.d.ts

@@ -21,10 +21,28 @@
  */
 import type { ReconcileObservation, ReconcileOutcome } from "../../work-context/reconcile.js";
 import { type SessionStateFile } from "../../work-context/state.js";
-/** One distinct session discovered in held.jsonl, with its harness. */
+/**
+ * One distinct session discovered in held.jsonl, carrying the company evidence
+ * its held events recorded at enqueue time (cwd / hqRoot / companySlug /
+ * project / task). ENDED sessions never reconcile again, so this per-event
+ * evidence is the only company signal a backfill can use — the synthesized
+ * observation forwards it so the shared resolver (cwd → companies/{slug}/,
+ * meta.yaml company_slug via hqRoot, or the event's own bound companySlug)
+ * can attribute the backlog instead of holding it forever.
+ */
 export interface HeldSessionRef {
     sessionId: string;
     harness?: string;
+    /** Working directory the events were emitted from (deterministic company/project evidence). */
+    cwd?: string;
+    /** HQ root, so the resolver can read workspace/sessions/<sid>/meta.yaml. */
+    hqRoot?: string;
+    /** Company the session was bound to at emit time (enqueue --company-slug). */
+    companySlug?: string;
+    /** Project id carried on the event, if any. */
+    project?: string;
+    /** Task id carried on the event, if any. */
+    task?: string;
 }
 export interface BackfillHeldResult {
     /** Distinct sessions found in held.jsonl (before --limit). */
@@ -63,9 +81,32 @@ export interface BackfillHeldDeps {
      * `hq mesh context reconcile` handler.
      */
     reconcile: (obs: ReconcileObservation) => Promise<ReconcileOutcome>;
+    /**
+     * Non-forcing company hint (the `--company` flag). Fed to the resolver as
+     * deterministic remote-owner evidence (below identity / explicit / session
+     * meta) in BOTH the dry-run predictor and the write path, so the two agree.
+     */
+    remoteOwnerHint?: string;
+    /** Env passed to the dry-run resolver (tests). Default process.env. */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Read-only company predictor for --dry-run. MUST mirror what the write
+     * path's reconcile would resolve, so dry-run and write report the same
+     * counts (the earlier bug: dry-run counted every session as would-reconcile
+     * while the write path, given no evidence, resolved none). Default runs the
+     * shared `resolveCompany` over the same reconstructed evidence.
+     */
+    predictCompany?: (ref: HeldSessionRef) => boolean;
     /** Optional progress logger. */
     log?: (message: string) => void;
 }
+/**
+ * Build the reconcile observation for one held session, forwarding the company
+ * evidence its events recorded (cwd / hqRoot / bound companySlug / project /
+ * task). The event's own companySlug is trusted explicit — it is the company
+ * the session was bound to when the events were emitted on this box.
+ */
+export declare function observationFromHeldRef(ref: HeldSessionRef, contractVersion: number, clientOperationId: string): ReconcileObservation;
 /**
  * Read held.jsonl and return distinct sessions (first occurrence wins),
  * carrying the harness from whichever held event we saw first for that session.