@cleocode/contracts 2026.5.104 → 2026.5.106

package/dist/render/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../src/render/tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAEhE;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACtB,SAAS,GACT,aAAa,GACb,MAAM,GACN,SAAS,GACT,WAAW,GACX,UAAU,CAAC;AAEf;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9C,0FAA0F;IAC1F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,wCAAwC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IAC7C,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAAC,CAAC,CAAC,CAS1E"}

package/dist/render/tree.js

@@ -0,0 +1,30 @@
+/**
+ * Typed render contracts — tree (flattened hierarchy).
+ *
+ * Part of the Human Render Contract (Epic T10114, ADR-077). The flat-tree shape
+ * is the canonical wire format for hierarchical task / saga / epic listings —
+ * presenters re-materialise the parent/child structure from `parentId` + `depth`.
+ *
+ * @epic T10114
+ * @task T10138
+ */
+/**
+ * Runtime type guard for `TreeResponse<T>`.
+ *
+ * Verifies the envelope shape without inspecting node payloads — the generic
+ * `T` cannot be checked at runtime, so callers must layer per-node validation
+ * separately if they need stronger guarantees.
+ *
+ * @param value — candidate value to inspect.
+ * @returns `true` iff `value` matches the `TreeResponse<T>` envelope shape.
+ */
+export function isTreeResponse(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return (Array.isArray(v.tree) &&
+        typeof v.root === 'string' &&
+        typeof v.totalNodes === 'number' &&
+        typeof v.maxDepth === 'number');
+}
+//# sourceMappingURL=tree.js.map

package/dist/render/tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../../src/render/tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAqFH;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAI,KAAc;IAC9C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,CAAC,GAAG,KAAgC,CAAC;IAC3C,OAAO,CACL,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;QACrB,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ;QAC1B,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ;QAChC,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAC/B,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/contracts",
-  "version": "2026.5.104",
+  "version": "v2026.5.106",
   "description": "Domain types, interfaces, and contracts for the CLEO ecosystem",
   "type": "module",
   "main": "./dist/index.js",
@@ -138,7 +138,7 @@
   "dependencies": {
     "zod": "^4.3.6",
     "zod-to-json-schema": "^3.25.2",
-    "@cleocode/lafs": "2026.5.104"
+    "@cleocode/lafs": "v2026.5.106"
   },
   "scripts": {
     "build": "tsc -b --force && node scripts/emit-schemas.mjs",

package/src/boundary.ts

@@ -318,9 +318,9 @@ export const BOUNDARY_REGISTRY: readonly BoundaryEntry[] = [
       'Verified-dead code: 531 LOC Rust crate referenced ONLY by packages/core/src/llm/rust/__tests__/. Production transports (chat-completions/gemini/openai) import StreamingThinkScrubber from the TS think-scrubber.js path. CLEO_USE_RUST gate is never set in any workflow. Scheduled for deletion in T10205; see ADR-078 implementation tasks.',
   },
   {
-    module: 'conduit-core',
+    module: 'cleo-conduit-core',
     intent: 'data-manifest',
-    rustCore: 'crates/conduit-core',
+    rustCore: 'crates/cleo-conduit-core',
     canonicalHome: 'cleocode',
     perfBudget: {
       latency_p50_ms: 10,
@@ -331,7 +331,7 @@ export const BOUNDARY_REGISTRY: readonly BoundaryEntry[] = [
     },
     amendments: [],
     rationale:
-      'Conduit serde-types crate (681 LOC) — stable contract surface consumed by cant-core, signaldock-protocol, signaldock-core, integration-tests, AND external /mnt/projects/signaldock-core + /mnt/projects/signaldock/backend via git deps. Mirrors @cleocode/contracts/conduit.ts. Forced KEEP+publish=true: deleting breaks production, and signaldock-protocol publish requires it.',
+      'Conduit serde-types crate (681 LOC) — renamed from conduit-core to cleo-conduit-core (T10185, saga T10180) because conduit-core is squatted on crates.io. Stable contract surface consumed by cant-core, signaldock-protocol, signaldock-core, integration-tests, AND external /mnt/projects/signaldock-core + /mnt/projects/signaldock/backend via git deps. Mirrors @cleocode/contracts/conduit.ts. Forced KEEP+publish=true: deleting breaks production, and signaldock-protocol publish requires it.',
   },
   {
     module: 'integration-tests',
@@ -348,7 +348,7 @@ export const BOUNDARY_REGISTRY: readonly BoundaryEntry[] = [
     },
     amendments: [],
     rationale:
-      'Internal Rust test harness (241 LOC) over lafs-core/conduit-core/cant-core/cant-router/signaldock-core. publish=false intentional — test code never ships.',
+      'Internal Rust test harness (241 LOC) over lafs-core/cleo-conduit-core/cant-core/cant-router/signaldock-core. publish=false intentional — test code never ships.',
   },
   {
     module: 'lafs-core',
@@ -366,7 +366,7 @@ export const BOUNDARY_REGISTRY: readonly BoundaryEntry[] = [
     },
     amendments: [],
     rationale:
-      'LAFS envelope serialization core (1,432 LOC) consumed by conduit-core, signaldock-protocol, lafs-napi, integration-tests. Mirrors @cleocode/lafs/src/envelope.ts. Flip publish=true to expose canonical envelope spec as a Rust library.',
+      'LAFS envelope serialization core (1,432 LOC) consumed by cleo-conduit-core, signaldock-protocol, lafs-napi, integration-tests. Mirrors @cleocode/lafs/src/envelope.ts. Flip publish=true to expose canonical envelope spec as a Rust library.',
   },
   {
     module: 'lafs-napi',

package/src/errors.ts

@@ -519,3 +519,74 @@ export function isErrorResult(result: {
 }): result is { success: false; error: string } {
   return !result.success;
 }
+
+/**
+ * Structured details payload attached to {@link ChangesetYamlInvalidError}.
+ *
+ * Carries the offending file path, the 1-based line number where the YAML
+ * parser bailed (when determinable), and an optional snippet of the parsed
+ * region to surface in CLI output and CI logs.
+ *
+ * @task T10105
+ * @epic E-RELEASE-PLAN-CHANGELOG
+ */
+export interface ChangesetYamlInvalidDetails {
+  /** Absolute or process-relative path to the offending `.md` file. */
+  file: string;
+  /** 1-based line number reported by the YAML parser; `null` when unknown. */
+  line: number | null;
+  /** Optional short excerpt around the failure (≤ 120 chars). */
+  snippet?: string;
+  /** Underlying parser message, propagated verbatim for diagnostics. */
+  parserMessage: string;
+}
+
+/**
+ * Thrown when `cleo release plan` (or the lint script) encounters a `.changeset/*.md`
+ * file whose YAML frontmatter cannot be parsed.
+ *
+ * Replaces the pre-T10105 silent-skip behaviour where a single malformed
+ * file (e.g. an unquoted colon in `summary:`) caused the aggregator to
+ * silently drop ALL changeset entries for that release. The v2026.5.100
+ * ship lost the v5.100/v5.101/v5.103 CHANGELOG entries to exactly this
+ * vector — see Saga T10099 SG-RELEASE-AUDIT-V2.
+ *
+ * @remarks
+ * Carries `exitCode` aligned with {@link ExitCode.VALIDATION_ERROR} (6) so
+ * the CLI surfaces a deterministic non-zero exit when invoked from CI.
+ *
+ * @example
+ * ```typescript
+ * throw new ChangesetYamlInvalidError({
+ *   file: '.changeset/bad.md',
+ *   line: 4,
+ *   parserMessage: 'Nested mappings are not allowed in compact mappings',
+ * });
+ * ```
+ *
+ * @task T10105
+ * @epic E-RELEASE-PLAN-CHANGELOG
+ * @saga T10099
+ */
+export class ChangesetYamlInvalidError extends Error {
+  /** Stable LAFS error code string for envelope emission. */
+  readonly code = 'E_CHANGESET_YAML_INVALID';
+  /** Numeric exit code aligned with {@link ExitCode.VALIDATION_ERROR} (6). */
+  readonly exitCode: ExitCode = ExitCode.VALIDATION_ERROR;
+  /** Structured payload describing the offending file + location. */
+  readonly details: ChangesetYamlInvalidDetails;
+
+  /**
+   * @param details - Structured failure context including file path and
+   *   line number. The constructor builds a deterministic human-readable
+   *   message of the form `<file>:<line> invalid YAML frontmatter: <msg>`.
+   */
+  constructor(details: ChangesetYamlInvalidDetails) {
+    const linePart = details.line !== null ? `:${details.line}` : '';
+    super(
+      `E_CHANGESET_YAML_INVALID: ${details.file}${linePart} invalid YAML frontmatter: ${details.parserMessage}`,
+    );
+    this.name = 'ChangesetYamlInvalidError';
+    this.details = details;
+  }
+}

package/src/exit-codes.ts

@@ -266,6 +266,19 @@ export const E_EVIDENCE_INSUFFICIENT = 'E_EVIDENCE_INSUFFICIENT' as const;
 export const E_PLAN_NOT_FOUND = 'E_PLAN_NOT_FOUND' as const;
 /** Generic release-plan validation failure (e.g. schema). Exit code 6. */
 export const E_RELEASE_PLAN_INVALID = 'E_RELEASE_PLAN_INVALID' as const;
+/**
+ * `cleo release plan` (or the lint script) encountered a `.changeset/*.md`
+ * file whose YAML frontmatter cannot be parsed. Exit code 6 (VALIDATION_ERROR).
+ *
+ * Replaces the pre-T10105 silent-skip that caused the v2026.5.100 ship to
+ * lose v5.100/v5.101/v5.103 CHANGELOG entries when a single changeset had
+ * an unquoted colon in `summary:`.
+ *
+ * @task T10105
+ * @epic E-RELEASE-PLAN-CHANGELOG
+ * @saga T10099
+ */
+export const E_CHANGESET_YAML_INVALID = 'E_CHANGESET_YAML_INVALID' as const;
 /**
  * Release row exists but is not in the status FSM state required by the
  * caller (R-051 — `cleo release open` requires status='planned'). Exit code 6.

package/src/index.ts

@@ -349,9 +349,10 @@ export {
   TASK_SEVERITIES,
   TASK_SIZES,
 } from './enums.js';
-export type { SagaInvariantErrorCode } from './errors.js';
+export type { ChangesetYamlInvalidDetails, SagaInvariantErrorCode } from './errors.js';
 // === Error Utilities ===
 export {
+  ChangesetYamlInvalidError,
   ClassifierUnregisteredAgentError,
   createErrorResult,
   createSuccessResult,
@@ -397,6 +398,8 @@ export {
 } from './evidence-record-schema.js';
 // === Exit Codes ===
 export {
+  // T10105 / Saga T10099 — fail-loud changeset parse
+  E_CHANGESET_YAML_INVALID,
   // SPEC-T9345 release pipeline v2 error code names (T9525)
   E_CHANNEL_MISMATCH,
   E_DIRTY_TREE,
@@ -1480,6 +1483,15 @@ export {
   TASK_KIND,
   TaskKindSchema,
 } from './release/plan.js';
+// === Release ship-e2e-smoke (T10103) ===
+export type {
+  ShipE2eSmokeFinalState,
+  ShipE2eSmokeParams,
+  ShipE2eSmokeResult,
+  ShipE2eSmokeStep,
+  ShipE2eSmokeStepName,
+  ShipE2eSmokeStepStatus,
+} from './release/ship-e2e-smoke.js';
 // === Release Version Bump ===
 export type {
   BumpResult,
@@ -1490,6 +1502,8 @@ export type {
   VersionBumpTarget,
   VersionBumpTargetSource,
 } from './release/version-bump.js';
+// === Human Render Contract (Epic T10114, ADR-077) ===
+export * from './render/index.js';
 // === Result Types (Dashboard, Stats, Log, Context, Sequence, Analysis, Deps) ===
 export type {
   BottleneckTask,

package/src/release/ship-e2e-smoke.ts

@@ -0,0 +1,113 @@
+/**
+ * Ship E2E Smoke contracts — types for the `cleo release ship-e2e-smoke`
+ * one-shot walker that exercises the full release lifecycle end-to-end.
+ *
+ * The smoke runs `plan` → `open` → wait-for-PR-merge → wait-for-tag →
+ * verify-npm-published. Each step records its status, duration, and any
+ * side-effect identifier (PR number, tag SHA, npm version) for downstream
+ * inspection. The aggregate envelope reports the final lifecycle state
+ * reached so failures can be resumed.
+ *
+ * Dry-run is the default; `--execute` flips the runner to perform real
+ * mutations. Both modes return the same envelope shape so consumers can
+ * diff a dry-run preview against a real run.
+ *
+ * @task T10103
+ * @epic E-CLEO-RELEASE-VERBS
+ * @saga T10099
+ */
+
+/**
+ * The discrete steps the smoke walker executes, in order. The aggregate
+ * envelope records one entry per step with status + duration.
+ */
+export type ShipE2eSmokeStepName =
+  | 'plan'
+  | 'open'
+  | 'wait-for-pr'
+  | 'wait-for-tag'
+  | 'verify-npm-published';
+
+/** Outcome of a single smoke step. */
+export type ShipE2eSmokeStepStatus =
+  /** Step completed successfully (or, in dry-run, would have run). */
+  | 'ok'
+  /** Step was skipped — e.g. dry-run mode shortcuts post-plan. */
+  | 'skipped'
+  /** Step failed; the smoke envelope's success flag will be false. */
+  | 'failed';
+
+/** Per-step result attached to the smoke envelope. */
+export interface ShipE2eSmokeStep {
+  /** The step name. */
+  name: ShipE2eSmokeStepName;
+  /** Outcome. */
+  status: ShipE2eSmokeStepStatus;
+  /** Wall-clock duration in milliseconds. */
+  durationMs: number;
+  /**
+   * Optional human-readable detail string captured at step completion
+   * (e.g. "plan written to .cleo/release/v2026.5.104.plan.json",
+   * "PR #524 merged", "tag v2026.5.104 found", "npm @cleocode/cleo@…
+   * published").
+   */
+  detail?: string;
+  /**
+   * Optional error message when `status === 'failed'`. Single-line so
+   * the envelope stays compact for CLI consumers.
+   */
+  error?: string;
+}
+
+/**
+ * Final lifecycle state the smoke reached. Mirrors the `releases.status`
+ * column values plus a synthetic `npm-published` terminal state captured
+ * by the verify step.
+ */
+export type ShipE2eSmokeFinalState =
+  | 'not-started'
+  | 'planned'
+  | 'pr-opened'
+  | 'pr-merged'
+  | 'tag-pushed'
+  | 'npm-published';
+
+/** Parameters accepted by the smoke walker. */
+export interface ShipE2eSmokeParams {
+  /** Candidate release version (e.g. "v2026.6.0" or "2026.6.0"). */
+  version: string;
+  /** Epic task ID that scopes the release (forwarded to `release plan`). */
+  epicId: string;
+  /**
+   * When false (default), no side effects — every step reports what it
+   * WOULD do. When true, each step performs its real mutation.
+   */
+  execute: boolean;
+  /**
+   * Total wall-clock budget across all polling waits, in milliseconds.
+   * Default 30 minutes when omitted. Per-step waits MUST respect this
+   * shared budget so a stuck PR doesn't hang the whole smoke.
+   */
+  totalTimeoutMs?: number;
+  /**
+   * Poll interval for wait-* steps, in milliseconds. Default 5_000.
+   * Lowered in tests via DI to keep the suite fast.
+   */
+  pollIntervalMs?: number;
+}
+
+/** Top-level envelope returned by the smoke walker. */
+export interface ShipE2eSmokeResult {
+  /** True when every step completed (or was intentionally skipped). */
+  success: boolean;
+  /** Echo of the version under smoke. */
+  version: string;
+  /** True when --execute was passed; false for dry-run preview. */
+  executed: boolean;
+  /** Ordered step log. */
+  steps: ShipE2eSmokeStep[];
+  /** Lifecycle state at smoke termination. */
+  finalState: ShipE2eSmokeFinalState;
+  /** Total wall-clock duration across all steps, in milliseconds. */
+  totalDurationMs: number;
+}

package/src/render/__tests__/envelope.test.ts

@@ -0,0 +1,194 @@
+/**
+ * Compile-time + runtime narrowing tests for `RenderableEnvelope<T>` and the
+ * per-kind type guards.
+ *
+ * Each test constructs a valid envelope of a single `kind` and asserts that
+ * the matching guard narrows it correctly while every other guard returns
+ * `false`. This catches both schema drift and accidental short-circuits in
+ * the guards.
+ *
+ * @epic T10114
+ * @task T10141
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  isGenericEnvelope,
+  isGroupedListEnvelope,
+  isListEnvelope,
+  isSectionEnvelope,
+  isSingleEnvelope,
+  isTableEnvelope,
+  isTreeEnvelope,
+  type RenderableEnvelope,
+} from '../envelope.js';
+import { isGroupedListResponse, isListResponse } from '../list.js';
+import { isTableResponse } from '../table.js';
+import { isTreeResponse } from '../tree.js';
+
+interface Sample {
+  readonly x: number;
+}
+
+describe('RenderableEnvelope<T> discriminated-union narrowing', () => {
+  it('narrows the tree variant and rejects all others', () => {
+    const env: RenderableEnvelope<Sample> = {
+      kind: 'tree',
+      data: { tree: [], root: 'T1', totalNodes: 0, maxDepth: 0 },
+    };
+    expect(isTreeEnvelope(env)).toBe(true);
+    expect(isTableEnvelope(env)).toBe(false);
+    expect(isListEnvelope(env)).toBe(false);
+    expect(isGroupedListEnvelope(env)).toBe(false);
+    expect(isSectionEnvelope(env)).toBe(false);
+    expect(isSingleEnvelope(env)).toBe(false);
+    expect(isGenericEnvelope(env)).toBe(false);
+    if (isTreeEnvelope(env)) {
+      expect(env.data.root).toBe('T1');
+    } else {
+      throw new Error('expected tree narrowing');
+    }
+  });
+
+  it('narrows the table variant and rejects all others', () => {
+    const env: RenderableEnvelope<Sample> = {
+      kind: 'table',
+      data: {
+        rows: [{ x: 1 }],
+        schema: { columns: [{ key: 'x', header: 'X' }] },
+        total: 1,
+      },
+    };
+    expect(isTableEnvelope(env)).toBe(true);
+    expect(isTreeEnvelope(env)).toBe(false);
+    if (isTableEnvelope(env)) {
+      expect(env.data.rows[0]?.x).toBe(1);
+    } else {
+      throw new Error('expected table narrowing');
+    }
+  });
+
+  it('narrows the flat list variant', () => {
+    const env: RenderableEnvelope<Sample> = {
+      kind: 'list',
+      data: { items: [{ x: 7 }], total: 1, renderItem: 'kv' },
+    };
+    expect(isListEnvelope(env)).toBe(true);
+    expect(isGroupedListEnvelope(env)).toBe(false);
+    if (isListEnvelope(env)) {
+      expect(env.data.items[0]?.x).toBe(7);
+      expect(env.data.renderItem).toBe('kv');
+    } else {
+      throw new Error('expected list narrowing');
+    }
+  });
+
+  it('narrows the grouped-list variant', () => {
+    const env: RenderableEnvelope<Sample> = {
+      kind: 'grouped-list',
+      data: {
+        groups: [{ key: 'a', label: 'A', items: [{ x: 2 }] }],
+        total: 1,
+      },
+    };
+    expect(isGroupedListEnvelope(env)).toBe(true);
+    expect(isListEnvelope(env)).toBe(false);
+    if (isGroupedListEnvelope(env)) {
+      expect(env.data.groups[0]?.items[0]?.x).toBe(2);
+    } else {
+      throw new Error('expected grouped-list narrowing');
+    }
+  });
+
+  it('narrows the section variant', () => {
+    const env: RenderableEnvelope<Sample> = {
+      kind: 'section',
+      data: { header: 'Summary', icon: 'i', items: ['a', 'b'] },
+    };
+    expect(isSectionEnvelope(env)).toBe(true);
+    if (isSectionEnvelope(env)) {
+      expect(env.data.items).toEqual(['a', 'b']);
+    } else {
+      throw new Error('expected section narrowing');
+    }
+  });
+
+  it('narrows the single variant', () => {
+    const env: RenderableEnvelope<Sample> = {
+      kind: 'single',
+      data: { x: 42 },
+    };
+    expect(isSingleEnvelope(env)).toBe(true);
+    if (isSingleEnvelope(env)) {
+      expect(env.data.x).toBe(42);
+    } else {
+      throw new Error('expected single narrowing');
+    }
+  });
+
+  it('narrows the generic variant', () => {
+    const env: RenderableEnvelope<Sample> = {
+      kind: 'generic',
+      data: { foo: 'bar', count: 3 },
+    };
+    expect(isGenericEnvelope(env)).toBe(true);
+    if (isGenericEnvelope(env)) {
+      expect(env.data.foo).toBe('bar');
+    } else {
+      throw new Error('expected generic narrowing');
+    }
+  });
+
+  it('exhaustively switches on kind without falling through', () => {
+    const envelopes: Array<RenderableEnvelope<Sample>> = [
+      { kind: 'tree', data: { tree: [], root: 'r', totalNodes: 0, maxDepth: 0 } },
+      {
+        kind: 'table',
+        data: { rows: [], schema: { columns: [] }, total: 0 },
+      },
+      { kind: 'list', data: { items: [], total: 0 } },
+      { kind: 'grouped-list', data: { groups: [], total: 0 } },
+      { kind: 'section', data: { header: 'h', items: [] } },
+      { kind: 'single', data: { x: 0 } },
+      { kind: 'generic', data: {} },
+    ];
+    const seen = new Set<RenderableEnvelope<Sample>['kind']>();
+    for (const env of envelopes) {
+      switch (env.kind) {
+        case 'tree':
+        case 'table':
+        case 'list':
+        case 'grouped-list':
+        case 'section':
+        case 'single':
+        case 'generic':
+          seen.add(env.kind);
+          break;
+        default: {
+          const _exhaustive: never = env;
+          throw new Error(`unreachable: ${JSON.stringify(_exhaustive)}`);
+        }
+      }
+    }
+    expect(seen.size).toBe(7);
+  });
+});
+
+describe('per-response type guards', () => {
+  it('accepts valid response shapes', () => {
+    expect(isTreeResponse({ tree: [], root: 'r', totalNodes: 0, maxDepth: 0 })).toBe(true);
+    expect(isTableResponse({ rows: [], schema: { columns: [] }, total: 0 })).toBe(true);
+    expect(isListResponse({ items: [], total: 0 })).toBe(true);
+    expect(isGroupedListResponse({ groups: [], total: 0 })).toBe(true);
+  });
+
+  it('rejects invalid response shapes', () => {
+    expect(isTreeResponse(null)).toBe(false);
+    expect(isTreeResponse({})).toBe(false);
+    expect(isTreeResponse({ tree: 'nope', root: 'r', totalNodes: 0, maxDepth: 0 })).toBe(false);
+    expect(isTableResponse({ rows: [], total: 0 })).toBe(false);
+    expect(isTableResponse({ rows: [], schema: 'nope', total: 0 })).toBe(false);
+    expect(isListResponse({ items: 'nope', total: 0 })).toBe(false);
+    expect(isGroupedListResponse({ groups: 'nope', total: 0 })).toBe(false);
+  });
+});

package/src/render/__tests__/icon.test.ts

@@ -0,0 +1,138 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ascii, BadgeIcon, KindIcon, pickIcon, RelationIcon, StatusIcon } from '../icon.js';
+
+describe('icon enums', () => {
+  it('StatusIcon emoji values match ADR-077', () => {
+    expect(StatusIcon.PENDING).toBe('⏳');
+    expect(StatusIcon.ACTIVE).toBe('🚧');
+    expect(StatusIcon.DONE).toBe('✅');
+    expect(StatusIcon.BLOCKED).toBe('🚪');
+    expect(StatusIcon.ARCHIVED).toBe('🗄');
+    expect(StatusIcon.CANCELLED).toBe('✗');
+  });
+
+  it('KindIcon emoji values match ADR-077', () => {
+    expect(KindIcon.SAGA).toBe('🌲');
+    expect(KindIcon.EPIC).toBe('📋');
+    expect(KindIcon.TASK).toBe('•');
+    expect(KindIcon.SUBTASK).toBe('◦');
+    expect(KindIcon.RESEARCH).toBe('📖');
+    expect(KindIcon.BUG).toBe('🐛');
+    expect(KindIcon.RELEASE).toBe('🚀');
+  });
+
+  it('BadgeIcon emoji values match ADR-077 (ORPHAN amended in T10137)', () => {
+    expect(BadgeIcon.EMPTY).toBe('🪦');
+    // ADR-077 §2 originally specified '🚪' for ORPHAN — identical to
+    // StatusIcon.BLOCKED. String enums share runtime values so ascii() cannot
+    // disambiguate. Amended to '👻' (abandoned/lonely). T10137 (B12) updates
+    // the ADR text to match.
+    expect(BadgeIcon.ORPHAN).toBe('👻');
+    expect(BadgeIcon.NESTED).toBe('🔁');
+    expect(BadgeIcon.CAUTION).toBe('⚠');
+    expect(BadgeIcon.NEW).toBe('★');
+  });
+
+  it('RelationIcon emoji values match ADR-077', () => {
+    expect(RelationIcon.GROUPS).toBe('⊂');
+    expect(RelationIcon.PARENT).toBe('⤴');
+    expect(RelationIcon.DEPENDS).toBe('⇨');
+    expect(RelationIcon.BLOCKS).toBe('⊘');
+  });
+
+  it('no two enum members share the same runtime string value', () => {
+    const all = [
+      ...Object.values(StatusIcon),
+      ...Object.values(KindIcon),
+      ...Object.values(BadgeIcon),
+      ...Object.values(RelationIcon),
+    ];
+    const unique = new Set(all);
+    expect(unique.size).toBe(all.length);
+  });
+});
+
+describe('ascii()', () => {
+  it('returns NO_COLOR fallback for every StatusIcon', () => {
+    expect(ascii(StatusIcon.PENDING)).toBe('[ ]');
+    expect(ascii(StatusIcon.ACTIVE)).toBe('[~]');
+    expect(ascii(StatusIcon.DONE)).toBe('[x]');
+    expect(ascii(StatusIcon.BLOCKED)).toBe('[!]');
+    expect(ascii(StatusIcon.ARCHIVED)).toBe('[#]');
+    expect(ascii(StatusIcon.CANCELLED)).toBe('[-]');
+  });
+
+  it('returns NO_COLOR fallback for every KindIcon', () => {
+    expect(ascii(KindIcon.SAGA)).toBe('SG');
+    expect(ascii(KindIcon.EPIC)).toBe('E');
+    expect(ascii(KindIcon.TASK)).toBe('-');
+    expect(ascii(KindIcon.SUBTASK)).toBe('.');
+    expect(ascii(KindIcon.RESEARCH)).toBe('R');
+    expect(ascii(KindIcon.BUG)).toBe('B');
+    expect(ascii(KindIcon.RELEASE)).toBe('>');
+  });
+
+  it('returns NO_COLOR fallback for every BadgeIcon', () => {
+    expect(ascii(BadgeIcon.EMPTY)).toBe('(empty)');
+    expect(ascii(BadgeIcon.ORPHAN)).toBe('(orphan)');
+    expect(ascii(BadgeIcon.NESTED)).toBe('(nested)');
+    expect(ascii(BadgeIcon.CAUTION)).toBe('(!)');
+    expect(ascii(BadgeIcon.NEW)).toBe('(new)');
+  });
+
+  it('returns NO_COLOR fallback for every RelationIcon', () => {
+    expect(ascii(RelationIcon.GROUPS)).toBe('in');
+    expect(ascii(RelationIcon.PARENT)).toBe('^');
+    expect(ascii(RelationIcon.DEPENDS)).toBe('->');
+    expect(ascii(RelationIcon.BLOCKS)).toBe('!>');
+  });
+});
+
+describe('pickIcon()', () => {
+  const originalNoColor = process.env['NO_COLOR'];
+  const originalTerm = process.env['TERM'];
+
+  beforeEach(() => {
+    delete process.env['NO_COLOR'];
+    delete process.env['TERM'];
+  });
+
+  afterEach(() => {
+    if (originalNoColor === undefined) {
+      delete process.env['NO_COLOR'];
+    } else {
+      process.env['NO_COLOR'] = originalNoColor;
+    }
+    if (originalTerm === undefined) {
+      delete process.env['TERM'];
+    } else {
+      process.env['TERM'] = originalTerm;
+    }
+  });
+
+  it('returns the emoji when noColor is explicitly false', () => {
+    expect(pickIcon(KindIcon.SAGA, { noColor: false })).toBe('🌲');
+    expect(pickIcon(StatusIcon.DONE, { noColor: false })).toBe('✅');
+  });
+
+  it('returns the ASCII form when noColor is explicitly true', () => {
+    expect(pickIcon(KindIcon.SAGA, { noColor: true })).toBe('SG');
+    expect(pickIcon(StatusIcon.DONE, { noColor: true })).toBe('[x]');
+  });
+
+  it('falls back to NO_COLOR=1 from process.env', () => {
+    process.env['NO_COLOR'] = '1';
+    expect(pickIcon(KindIcon.EPIC)).toBe('E');
+    expect(pickIcon(BadgeIcon.ORPHAN)).toBe('(orphan)');
+  });
+
+  it('falls back to TERM=dumb from process.env', () => {
+    process.env['TERM'] = 'dumb';
+    expect(pickIcon(RelationIcon.GROUPS)).toBe('in');
+  });
+
+  it('returns the emoji when no NO_COLOR signals are present', () => {
+    expect(pickIcon(KindIcon.TASK)).toBe('•');
+    expect(pickIcon(StatusIcon.ACTIVE)).toBe('🚧');
+  });
+});