@indigoai-us/hq-cli 5.108.18 → 5.108.20

package/dist/lib/doctor/checks/sync-health.d.ts

@@ -50,16 +50,61 @@ export interface SyncVersionInfo {
     core: string | null;
     desktop: string | null;
 }
+/**
+ * Per-scope manifest upload state, as `hq doctor` reads it. Structurally the
+ * subset of hq-cloud's `ManifestUploadStatus` this family reports, restated so
+ * the check is injectable without a state dir.
+ */
+export interface SyncManifestUploadStatus {
+    scopeKey: string;
+    lastUploadAt: string | null;
+    snapshotId: string | null;
+    sequence: number;
+    baseUsable: boolean;
+}
 /** Injectable dependencies — defaults are the real collectors. */
 export interface SyncHealthDeps {
     versions: (hqRoot: string) => SyncVersionInfo;
     journals: () => readonly SyncJournalSummary[];
     now: () => Date;
+    /**
+     * Per-scope manifest upload state (sync-reconciliation-audit US-004).
+     *
+     * Takes the ALREADY-ENUMERATED journals so the scope list the manifest check
+     * reports is exactly the scope list the staleness checks report — deriving it
+     * a second way is how the two halves of this family would end up disagreeing
+     * about which companies exist on the machine.
+     */
+    manifestStatuses?: (journals: readonly SyncJournalSummary[]) => readonly SyncManifestUploadStatus[];
+    /**
+     * Whether the installed hq-cloud exposes the manifest exports at all.
+     * Optional; defaults to feature detection. When false the family emits a
+     * single NA row instead of failing — an older hq-cloud is a missing
+     * capability, not a broken install.
+     */
+    manifestAvailable?: () => boolean;
+    /**
+     * Scopes that appear as journal shards but cannot be turned into a manifest
+     * scope key locally (company shards, whose `companyUid` the journal listing
+     * does not carry). Reported explicitly as UNTESTED rather than silently
+     * dropped — a scope missing from the output is indistinguishable from a
+     * scope that is fine.
+     */
+    unresolvedScopes?: (journals: readonly SyncJournalSummary[]) => readonly string[];
 }
 /** The versions/sync check family. Registered in `createDefaultRegistry`. */
 export declare const syncHealthFamily: CheckFamily;
 /** Run every versions/sync check. A thrown check degrades to UNKNOWN. */
-export declare function checkSyncHealth(context: CheckContext, deps?: SyncHealthDeps): CheckResult[];
+export declare function checkSyncHealth(context: CheckContext, rawDeps?: SyncHealthDeps): CheckResult[];
 /** True when `a` > `b` for plain X.Y.Z versions. Non-numeric parts compare 0. */
 export declare function semverGt(a: string, b: string): boolean;
+/**
+ * A scope whose last manifest upload is older than this is reported stale.
+ *
+ * The upload pass throttles itself to one pass per scope per 24h, so anything
+ * under two days is simply "the throttle is working". Three days means at
+ * least two scheduled passes were missed, which is a corroborated signal that
+ * something — the daemon, the network, the kill switch — is not running.
+ */
+export declare const STALE_MANIFEST_THRESHOLD_MS: number;
 //# sourceMappingURL=sync-health.d.ts.map

package/dist/lib/doctor/checks/sync-health.js

@@ -25,7 +25,12 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { listJournals } from "@indigoai-us/hq-cloud";
+// Namespace import, deliberately: hq-cloud is an ESM package, so a static
+// NAMED import of an export the installed version lacks is a link-time
+// SyntaxError that would stop `hq doctor` from starting at all. See
+// ../../hq-cloud-manifest.js.
+import * as hqCloud from "@indigoai-us/hq-cloud";
+import { loadManifestExports, MANIFEST_UNAVAILABLE_REASON, } from "../../hq-cloud-manifest.js";
 import { CLI_VERSION } from "../../../cli-version.js";
 import { readSyncVersion } from "../../../utils/feedback-versions.js";
 import { readHqVersion } from "../../../utils/pack-contributions.js";
@@ -41,6 +46,25 @@ export const SYNC_FAMILY_TITLE = "Versions & sync";
 export const STALE_JOURNAL_THRESHOLD_MS = 7 * 24 * 60 * 60 * 1000;
 /** The offline update cache written by the check-hq-update SessionStart hook. */
 export const UPDATE_CACHE_RELPATH = path.join("workspace", ".hq-update-check", "last-check.json");
+/** Fill in the optional dependencies so call sites never branch on undefined. */
+function withDefaults(deps) {
+    return {
+        ...deps,
+        manifestStatuses: deps.manifestStatuses ?? defaultManifestStatuses,
+        manifestAvailable: deps.manifestAvailable ?? (() => loadManifestExports() !== null),
+        unresolvedScopes: deps.unresolvedScopes ?? defaultUnresolvedScopes,
+    };
+}
+/**
+ * Company journal shards are unresolvable by the default collector: the
+ * snapshot store keys company scopes by `companyUid`, which `listJournals()`
+ * does not carry. Naming them here keeps them visible.
+ */
+function defaultUnresolvedScopes(journals) {
+    return journals
+        .filter((entry) => !NON_COMPANY_JOURNAL_SLUGS.has(entry.slug))
+        .map((entry) => entry.slug);
+}
 function defaultVersions(hqRoot) {
     return {
         cli: CLI_VERSION,
@@ -70,9 +94,58 @@ const DEFAULT_DEPS = {
     // surface as UNKNOWN in `journalResults`, never be collapsed into the
     // empty-list (NA, "cloud sync not in use") case. False healthy is worse
     // than no check.
-    journals: () => listJournals(),
+    journals: () => hqCloud.listJournals(),
     now: () => new Date(),
+    manifestStatuses: defaultManifestStatuses,
 };
+/**
+ * Map the machine's journal shards onto the manifest scopes hq-cloud keys its
+ * snapshot store by, then read each one's last upload.
+ *
+ * The journal slug `personal` is the personal tree; every other slug is a
+ * company. Note the snapshot store keys company scopes by `companyUid`, which
+ * the journal listing does not carry — so a company whose uid we cannot name
+ * is simply not reported here rather than reported wrongly. That is the honest
+ * outcome: this check exists to tell an operator when a manifest STOPPED being
+ * uploaded, and inventing a scope key would make it lie in both directions.
+ */
+function defaultManifestStatuses(journals) {
+    // Both the legacy `personal` shard and the current personal-vault
+    // pseudo-slug name the SAME personal tree; a machine mid-migration has both
+    // on disk, so collapse them to a single personal scope rather than asking
+    // hq-cloud for the same scope twice.
+    const scopes = journals.some((entry) => NON_COMPANY_JOURNAL_SLUGS.has(entry.slug))
+        ? [{ kind: "personal" }]
+        : [];
+    if (scopes.length === 0)
+        return [];
+    // Absent on an older hq-cloud; the NA row is emitted by `manifestResults`
+    // before this ever runs, so returning empty here is belt-and-braces.
+    const exports = loadManifestExports();
+    if (!exports)
+        return [];
+    return exports.readManifestUploadStatus(exports.getStateDir(), scopes);
+}
+/** The legacy journal slug that named the personal (non-company) tree. */
+const PERSONAL_SCOPE_SLUG = "personal";
+/**
+ * hq-cloud's personal-vault pseudo-slug (`PERSONAL_VAULT_JOURNAL_SLUG`). It is
+ * a sentinel, not a company: the entity service never mints a slug with
+ * leading underscores. Inlined rather than imported so this module keeps its
+ * link-safety story (see `hq-cloud-manifest.ts`).
+ */
+const PERSONAL_VAULT_SCOPE_SLUG = "__hq_personal_vault__";
+/**
+ * Journal slugs that do NOT name a company. Every one of these is already
+ * covered by the `sync.manifest.personal` row, so listing them as unresolved
+ * company scopes would be doubly wrong: it invents a company that does not
+ * exist and tells the operator to run `hq sync manifest --scope
+ * __hq_personal_vault__`, which is not a scope the CLI accepts.
+ */
+const NON_COMPANY_JOURNAL_SLUGS = new Set([
+    PERSONAL_SCOPE_SLUG,
+    PERSONAL_VAULT_SCOPE_SLUG,
+]);
 /** The versions/sync check family. Registered in `createDefaultRegistry`. */
 export const syncHealthFamily = {
     id: SYNC_FAMILY_ID,
@@ -80,12 +153,13 @@ export const syncHealthFamily = {
     run: (context) => Promise.resolve(checkSyncHealth(context)),
 };
 /** Run every versions/sync check. A thrown check degrades to UNKNOWN. */
-export function checkSyncHealth(context, deps = DEFAULT_DEPS) {
+export function checkSyncHealth(context, rawDeps = DEFAULT_DEPS) {
+    const deps = withDefaults(rawDeps);
     try {
         return [
             ...versionResults(context, deps),
             ...updateAvailabilityResult(context, deps),
-            ...journalResults(deps),
+            ...journalAndManifestResults(deps),
         ];
     }
     catch (error) {
@@ -204,7 +278,16 @@ export function semverGt(a, b) {
     return false;
 }
 // ─── Per-journal staleness ───────────────────────────────────────────────────
-function journalResults(deps) {
+/**
+ * Enumerate the journals ONCE, then run both the staleness checks and the
+ * manifest-upload checks off that single list.
+ *
+ * Sharing the enumeration is not just an optimisation: an enumeration failure
+ * must produce exactly one UNKNOWN, and the two checks must never disagree
+ * about which scopes exist because they asked the store at two different
+ * moments.
+ */
+function journalAndManifestResults(deps) {
     // Enumeration failure (throw / IO error) is UNKNOWN — which FAILS per the
     // doctor's exit-code contract — never NA: a broken or unreadable journal
     // store must not read as "cloud sync not in use" (a false healthy). Only a
@@ -235,6 +318,9 @@ function journalResults(deps) {
             },
         ];
     }
+    return [...journalResults(deps, journals), ...manifestResults(deps, journals)];
+}
+function journalResults(deps, journals) {
     const nowMs = deps.now().getTime();
     return journals.map((entry) => {
         const lastSync = entry.journal?.lastSync;
@@ -276,4 +362,125 @@ function journalResults(deps) {
         };
     });
 }
+// ─── Manifest upload freshness (sync-reconciliation-audit US-004) ────────────
+/**
+ * A scope whose last manifest upload is older than this is reported stale.
+ *
+ * The upload pass throttles itself to one pass per scope per 24h, so anything
+ * under two days is simply "the throttle is working". Three days means at
+ * least two scheduled passes were missed, which is a corroborated signal that
+ * something — the daemon, the network, the kill switch — is not running.
+ */
+export const STALE_MANIFEST_THRESHOLD_MS = 3 * 24 * 60 * 60 * 1000;
+/**
+ * Report the last manifest upload per scope.
+ *
+ * NEVER-UPLOADED IS INFORMATIONAL, NOT A FAILURE. The audit rolls out to a
+ * fleet that has never run a pass, and every one of those machines is working
+ * exactly as designed until the first pass is due. Reporting UNTESTED (wired
+ * but not yet exercised) rather than WARN is the whole reason the doctor's
+ * status vocabulary has that value — collapsing it into WARN would turn the
+ * first day of the rollout into a fleet-wide false alarm.
+ */
+function manifestResults(deps, journals) {
+    // An hq-cloud that predates the manifest exports is a MISSING CAPABILITY,
+    // not a fault: one NA row, and the rest of `hq doctor` runs untouched.
+    if (!deps.manifestAvailable()) {
+        return [
+            {
+                status: "NA",
+                checkId: "sync.manifest",
+                message: `${MANIFEST_UNAVAILABLE_REASON} — upgrade hq-cloud to audit manifest uploads.`,
+            },
+        ];
+    }
+    let statuses;
+    try {
+        statuses = deps.manifestStatuses(journals);
+    }
+    catch (error) {
+        return [
+            {
+                status: "UNKNOWN",
+                checkId: "sync.manifest",
+                message: `Manifest upload state could not be read: ${error instanceof Error ? error.message : String(error)}`,
+                remediation: "Check that the HQ state directory is readable, then re-run `hq doctor`.",
+            },
+        ];
+    }
+    const unresolved = unresolvedResults(deps, journals);
+    if (statuses.length === 0) {
+        if (unresolved.length > 0)
+            return unresolved;
+        return [
+            {
+                status: "NA",
+                checkId: "sync.manifest",
+                message: "No manifest-auditable sync scopes on this machine — nothing to reconcile.",
+            },
+        ];
+    }
+    const nowMs = deps.now().getTime();
+    const reported = statuses.map((entry) => {
+        const checkId = `sync.manifest.${entry.scopeKey}`;
+        if (!entry.lastUploadAt) {
+            return {
+                status: "UNTESTED",
+                checkId,
+                message: `Scope '${entry.scopeKey}' has never uploaded a sync manifest — expected until the first pass runs.`,
+                remediation: "Run `hq sync manifest` to upload one now.",
+            };
+        }
+        const parsed = Date.parse(entry.lastUploadAt);
+        if (!Number.isFinite(parsed)) {
+            return {
+                status: "UNKNOWN",
+                checkId,
+                message: `Scope '${entry.scopeKey}' has an unparseable last manifest upload time (${entry.lastUploadAt}).`,
+            };
+        }
+        const ageMs = nowMs - parsed;
+        const baseNote = entry.baseUsable
+            ? `delta base ${entry.snapshotId ?? "?"}`
+            : "next pass will send a full manifest";
+        if (ageMs > STALE_MANIFEST_THRESHOLD_MS) {
+            const days = Math.floor(ageMs / 86_400_000);
+            return {
+                status: "WARN",
+                checkId,
+                message: `Scope '${entry.scopeKey}' last uploaded a sync manifest ${days} day${days === 1 ? "" : "s"} ago (${entry.lastUploadAt}) — the daily audit pass is not running.`,
+                remediation: "Run `hq sync manifest` and check HQ_SYNC_MANIFEST_DISABLED and the sync runner.",
+            };
+        }
+        return {
+            status: "PASS",
+            checkId,
+            message: `Scope '${entry.scopeKey}' uploaded a sync manifest at ${entry.lastUploadAt} (sequence ${entry.sequence}, ${baseNote}).`,
+        };
+    });
+    return [...reported, ...unresolved];
+}
+/**
+ * One explicit row per scope we could NOT resolve to a manifest scope key.
+ *
+ * UNTESTED, not NA and certainly not silence: the scope exists on this machine
+ * and is genuinely un-audited, so an operator must be able to see that the
+ * doctor did not check it. Silently skipping is how a company stops being
+ * reconciled without anyone noticing.
+ */
+function unresolvedResults(deps, journals) {
+    let slugs;
+    try {
+        slugs = deps.unresolvedScopes(journals);
+    }
+    catch {
+        return [];
+    }
+    return slugs.map((slug) => ({
+        status: "UNTESTED",
+        checkId: `sync.manifest.unresolved.${slug}`,
+        message: `Company scope '${slug}' has a sync journal but its companyUid could not be resolved locally — its manifest uploads were not checked.`,
+        remediation: `Run \`hq sync manifest --scope ${slug}\` to audit it explicitly.`,
+    }));
+}
 //# sourceMappingURL=sync-health.js.map

package/dist/lib/hq-cloud-manifest.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Feature detection for the hq-cloud manifest exports.
+ *
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * `runManifestUploadPass` / `readManifestUploadStatus` were added in the
+ * hq-cloud sync-reconciliation-audit branch and are NOT in the currently
+ * published `~6.16.6` line that this CLI pins. hq-cloud is an ES module, so a
+ * static named import of an export that does not exist is a LINK-TIME
+ * SyntaxError: the importing module never evaluates, and every command that
+ * transitively imports it dies at startup. `hq doctor` is one of those
+ * commands, and it is one of the most widely used in the CLI — a doctor that
+ * cannot start is strictly worse than a doctor missing one row.
+ *
+ * So nothing imports those symbols by name. We import the module NAMESPACE
+ * (always link-safe, regardless of which exports exist) and feature-detect the
+ * functions on it. Callers that need them ask for them and degrade when they
+ * are absent:
+ *   - `hq doctor` emits a single NA row ("manifest status unavailable");
+ *   - `hq sync manifest` prints the version requirement and exits non-zero.
+ *
+ * Once the hq-cloud release carrying these exports lands and the pin is bumped,
+ * this module keeps working unchanged — detection simply always succeeds.
+ */
+/**
+ * The first hq-cloud release that carries the manifest upload exports.
+ *
+ * 6.16.23 is the release that actually ships `runManifestUploadPass` /
+ * `readManifestUploadStatus`, and is the version this package pins.
+ *
+ * Used only for the human-facing "you need at least X" message; the actual
+ * gate is capability detection, never a version comparison — a version string
+ * can lie about what a build contains, a function reference cannot. So a stale
+ * value here misinforms, but never misgates.
+ */
+export declare const MANIFEST_MIN_HQ_CLOUD_VERSION = "6.16.23";
+/** One-line explanation shared by every degradation path. */
+export declare const MANIFEST_UNAVAILABLE_REASON: string;
+/** The subset of hq-cloud the manifest paths need, once proven present. */
+export interface ManifestExports {
+    runManifestUploadPass: (options: never) => unknown;
+    readManifestUploadStatus: (...args: never[]) => unknown;
+    getStateDir: () => string;
+}
+/** Thrown by {@link requireManifestExports}. Carries a user-ready message. */
+export declare class ManifestUnsupportedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Resolve the manifest exports, or null when the installed hq-cloud predates
+ * them.
+ *
+ * The module object is injectable so the absent-export path is testable
+ * without mocking the package (and so the test cannot accidentally pass merely
+ * because the local `link:` override happens to be new enough).
+ */
+export declare function loadManifestExports(mod?: Record<string, unknown>): ManifestExports | null;
+/** True when the installed hq-cloud can do manifest passes at all. */
+export declare function manifestExportsAvailable(mod?: Record<string, unknown>): boolean;
+/** Like {@link loadManifestExports}, but throws instead of returning null. */
+export declare function requireManifestExports(mod?: Record<string, unknown>): ManifestExports;
+//# sourceMappingURL=hq-cloud-manifest.d.ts.map

package/dist/lib/hq-cloud-manifest.js

@@ -0,0 +1,83 @@
+/**
+ * Feature detection for the hq-cloud manifest exports.
+ *
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * `runManifestUploadPass` / `readManifestUploadStatus` were added in the
+ * hq-cloud sync-reconciliation-audit branch and are NOT in the currently
+ * published `~6.16.6` line that this CLI pins. hq-cloud is an ES module, so a
+ * static named import of an export that does not exist is a LINK-TIME
+ * SyntaxError: the importing module never evaluates, and every command that
+ * transitively imports it dies at startup. `hq doctor` is one of those
+ * commands, and it is one of the most widely used in the CLI — a doctor that
+ * cannot start is strictly worse than a doctor missing one row.
+ *
+ * So nothing imports those symbols by name. We import the module NAMESPACE
+ * (always link-safe, regardless of which exports exist) and feature-detect the
+ * functions on it. Callers that need them ask for them and degrade when they
+ * are absent:
+ *   - `hq doctor` emits a single NA row ("manifest status unavailable");
+ *   - `hq sync manifest` prints the version requirement and exits non-zero.
+ *
+ * Once the hq-cloud release carrying these exports lands and the pin is bumped,
+ * this module keeps working unchanged — detection simply always succeeds.
+ */
+import * as hqCloud from "@indigoai-us/hq-cloud";
+/**
+ * The first hq-cloud release that carries the manifest upload exports.
+ *
+ * 6.16.23 is the release that actually ships `runManifestUploadPass` /
+ * `readManifestUploadStatus`, and is the version this package pins.
+ *
+ * Used only for the human-facing "you need at least X" message; the actual
+ * gate is capability detection, never a version comparison — a version string
+ * can lie about what a build contains, a function reference cannot. So a stale
+ * value here misinforms, but never misgates.
+ */
+export const MANIFEST_MIN_HQ_CLOUD_VERSION = "6.16.23";
+/** One-line explanation shared by every degradation path. */
+export const MANIFEST_UNAVAILABLE_REASON = `manifest status unavailable: hq-cloud too old ` +
+    `(requires an hq-cloud release with manifest support ` +
+    `(>= ${MANIFEST_MIN_HQ_CLOUD_VERSION}))`;
+/** Thrown by {@link requireManifestExports}. Carries a user-ready message. */
+export class ManifestUnsupportedError extends Error {
+    constructor(message = MANIFEST_UNAVAILABLE_REASON) {
+        super(message);
+        this.name = "ManifestUnsupportedError";
+    }
+}
+/**
+ * Resolve the manifest exports, or null when the installed hq-cloud predates
+ * them.
+ *
+ * The module object is injectable so the absent-export path is testable
+ * without mocking the package (and so the test cannot accidentally pass merely
+ * because the local `link:` override happens to be new enough).
+ */
+export function loadManifestExports(mod = hqCloud) {
+    const runManifestUploadPass = mod.runManifestUploadPass;
+    const readManifestUploadStatus = mod.readManifestUploadStatus;
+    const getStateDir = mod.getStateDir;
+    if (typeof runManifestUploadPass !== "function" ||
+        typeof readManifestUploadStatus !== "function" ||
+        typeof getStateDir !== "function") {
+        return null;
+    }
+    return {
+        runManifestUploadPass,
+        readManifestUploadStatus,
+        getStateDir,
+    };
+}
+/** True when the installed hq-cloud can do manifest passes at all. */
+export function manifestExportsAvailable(mod) {
+    return loadManifestExports(mod) !== null;
+}
+/** Like {@link loadManifestExports}, but throws instead of returning null. */
+export function requireManifestExports(mod) {
+    const exports = loadManifestExports(mod);
+    if (!exports)
+        throw new ManifestUnsupportedError();
+    return exports;
+}
+//# sourceMappingURL=hq-cloud-manifest.js.map

package/dist/lib/mesh/live/session-event.schema.json

@@ -0,0 +1,144 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hq.getindigo.ai/schemas/work-mesh-live/session-event.schema.json",
+  "title": "Work Mesh Live Session Event",
+  "description": "Metadata-only spool / batch-ingest session event (contractVersion 1). Local-only fields are permitted on the spool line and MUST be stripped by the daemon before any network call. There is no free-text intent field and no prompt-derived content.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "v",
+    "eventId",
+    "kind",
+    "sessionId",
+    "harness",
+    "adapterVersion",
+    "at",
+    "seq"
+  ],
+  "properties": {
+    "v": {
+      "type": "integer",
+      "const": 1,
+      "description": "Schema version. Always 1 for this contract."
+    },
+    "eventId": {
+      "type": "string",
+      "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
+      "description": "ULID (Crockford base32, 26 chars). Idempotency key for batch ingest."
+    },
+    "kind": {
+      "type": "string",
+      "enum": [
+        "session_start",
+        "turn_start",
+        "turn_end",
+        "session_end",
+        "task_status",
+        "blocked",
+        "note"
+      ]
+    },
+    "sessionId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "Stable runtime session identifier."
+    },
+    "harness": {
+      "type": "string",
+      "enum": [
+        "claude-code",
+        "claude-desktop",
+        "codex",
+        "grok",
+        "hq-sessions",
+        "agent-box"
+      ]
+    },
+    "adapterVersion": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "Hook / adapter package version that emitted the event."
+    },
+    "runtimeVersion": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "Optional host runtime version (claude, codex, etc.)."
+    },
+    "source": {
+      "type": "string",
+      "enum": ["hooks", "transcript"],
+      "description": "Origin of the event stream: hooks (default) or the transcript-watch fallback (US-018)."
+    },
+    "at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?(?:Z|[+-]\\d{2}:\\d{2})$",
+      "description": "ISO-8601 timestamp when the event occurred."
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Monotonic per-session sequence number, starting at 1."
+    },
+    "taskId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "Canonical task identifier. storyId is an ingress alias normalized to taskId by the resolver; it is never a field on this schema."
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "queued",
+        "in_progress",
+        "review",
+        "done"
+      ],
+      "description": "Task status; used with kind=task_status."
+    },
+    "reason": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 500,
+      "description": "Blocked reason or similar short machine-safe note. Never prompt text."
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 280,
+      "description": "Optional short summary allowed only on note, blocked, and task_status. Never prompt-derived content."
+    },
+    "cwd": {
+      "type": "string",
+      "maxLength": 1024,
+      "description": "LOCAL-ONLY. Working directory at emit time. Stripped by the daemon before any network call."
+    },
+    "hqRoot": {
+      "type": "string",
+      "maxLength": 1024,
+      "description": "LOCAL-ONLY. Absolute path to the HQ tree root. Stripped before network."
+    },
+    "companySlug": {
+      "type": "string",
+      "maxLength": 128,
+      "description": "LOCAL-ONLY. Hint slug from local context. Never used as tenant authority. Stripped before network."
+    },
+    "project": {
+      "type": "string",
+      "maxLength": 256,
+      "description": "LOCAL-ONLY. Local project name/path hint. Stripped before network."
+    },
+    "task": {
+      "type": "string",
+      "maxLength": 256,
+      "description": "LOCAL-ONLY. Local task label hint. Stripped before network. Distinct from canonical taskId."
+    },
+    "toolWrites": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "LOCAL-ONLY. Count of tool file writes observed this session. Stripped before network."
+    }
+  }
+}