phase-trace

state/lib/phase-trace.ts - pure in-memory accumulator. Pairs with the PhaseDisclosure shape registered in web/src/components/phase-disclosure.tsx (snappy-os). One trace per tick, many phases per trace, optional body per phase.

The disclosure pattern matches Claude Desktop's "Cowork" layout (cd-23 in the design references): a vertical stack of rows, each with a chevron, status dot, mono label, and a one-line summary. Click any row to expand the multi-paragraph body underneath.

Steps

1. Open a trace with optional title:

   import { startTrace } from "../lib/phase-trace.ts";
   const t = startTrace("Charlotte execute");

1. Add phases as the work progresses. Each .phase(label, opts) returns

a fluent handle:

   const p = t.phase("Loaded tools", { summary: "Probing connectors", status: "running" });
   p.body("Now let me probe the actual connector data shapes...");
   p.done();

1. When the tick finishes, emit() returns the canonical payload shape:

   const { phaseDisclosure } = t.emit();
   // → { phases: [{ label, summary, body?, status? }, ...], title? }

1. The dispatcher in state/bin/head-screen/server.ts wraps the payload

in a TOOL_CALL_* triple keyed PhaseDisclosure and the snappy-os surface renders the disclosure rows inline.

Status enum

pending | running | done | error. The renderer maps each to a colored status dot (text-tertiary / accent w/ glow / ok-green / danger-red).

Eval

Shape gate. The actor is startTrace().emit() and the auditor is the parser parsePhaseDisclosureArgs in web/src/tool-args.ts. A row passes if every phase has both label and summary strings and the status (when present) is in the four-value enum.

phase-trace - loader

Per-turn rules for the phase-trace skill. Full reference: state/skills/phase-trace/SKILL.md.

phase-trace is the builder API long-running snappy-os skills use to accumulate phase rows (label + summary + body + status) as they work, then emit one canonical PhaseDisclosure payload at end of tick. The snappy-os generative UI renders that payload inline as a vertical stack of collapsible disclosure rows - chevron + status dot + mono label + one-line summary, expanding to multi-paragraph body. Visual pattern matches Claude Desktop's "Cowork" layout (cd-23 in design references). Pure in-memory accumulator. Pairs with web/src/components/phase-disclosure.tsx in snappy-os. Lib: state/lib/phase-trace.ts.

Critical Rules

1. Status enum is pending|running|done|error exactly - parsePhaseDisclosureArgs in web/src/tool-args.ts kills any card with off-enum status.
2. Both label and summary are REQUIRED on every phase. body is optional; status is optional (defaults handled downstream).
3. emit() is one-shot. Call it at end of tick. Do NOT re-emit during streaming - the renderer expects one payload per trace.
4. Pure in-memory accumulator. Do NOT persist phase rows to disk; the eval row in state/log/evals.ndjson is the persistence record of record.
5. Phase ordering = insertion order. Sort upstream of t.phase() calls if you want a different display order.

Commands

| ui model | live composition via compose_inline, persisted as artifact lang_body, reopened with OpenArtifact | |invoke: import { startTrace } from "../lib/phase-trace.ts" |usage: const t = startTrace("Charlotte execute"); const p = t.phase("Loaded tools", {summary:"Probing connectors", status:"running"}); p.body("...long body..."); p.done(); ... t.emit() returns {phaseDisclosure: {phases: [...], title?}} |dispatcher: state/bin/head-screen/server.ts - regex matcher + emitTriple("PhaseDisclosure", payload.phaseDisclosure) |trigger phrases (matched in dispatcher regex, extended at L7029): running / currently-running / happening right now |eval log: state/log/evals.ndjson (skill: "phase-trace", eval_mode: shape) |tested: 2026-04-29 end-to-end with shape PhaseDisclosure paired against snappy-os renderer; parser roundtrip OK; dispatcher routing hooked

Status enum

Trigger phrases

• running
• currently running / currently-running
• happening right now

(Dispatcher regex extended at L7029 in state/bin/head-screen/server.ts to route these to PhaseDisclosure.)

Known Pitfalls

• A phase missing summary fails the parser shape gate and the card is dropped silently. Always set summary, even a one-word placeholder.
• body strings can be long (multi-paragraph) - the renderer truncates inside the closed disclosure row; full text appears on expand. Don't pre-truncate upstream.
• status:"error" paints a red dot. Reserve it for actual failures; using it for "warning" or "skipped" misleads the cockpit reader.

Self-Test

An agent reading this should correctly:

1. [ ] Confirm emit() output shape matches parsePhaseDisclosureArgs (label + summary required, status enum exact)
2. [ ] Confirm phase ordering is insertion order
3. [ ] Confirm status enum is strictly pending|running|done|error
4. [ ] Confirm emit() is called once per tick, not per phase
5. [ ] Confirm trigger phrases running / currently running / happening right now route to PhaseDisclosure via the dispatcher regex

Found a gap? Edit this file. <!-- footer-injection-point -->