@groeponline/pi-wishcraft 1.12.0 → 1.13.0

package/AGENTS.md

@@ -115,9 +115,11 @@ scripts/github-release.sh
 
 CI workflows (`.github/workflows/`):
 - `test.yml` — Node 24, typecheck, test, circular, verify:package, npm audit
-- `release.yml` — reuses test.yml, prepares release-candidate branch
+- `release.yml` — reuses test.yml, prepares release-candidate branch, publishes on tag, attaches `npm pack` + `SHA256SUMS`
 - `promote-release-candidate.yml` — promotes verified SHA to main, tags, dispatches publish
 
+Tag `vX.Y.Z` must equal `package.json` and sit on `origin/main`. Identity: `src/product-identity.ts --version` / `/signal version`. See [`docs/release.md`](docs/release.md).
+
 Release behavior:
 - **Every main merge with `[Unreleased]` CHANGELOG notes cuts a release automatically** (verify → candidate → promote → tag → npm). Notes-less merges skip candidate creation entirely — no more empty versions.
 - Notes live under `## [Unreleased]` in CHANGELOG.md; the release commit rolls them into the new version heading.

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [1.13.0] - 2026-09-25
+
+### Added
+- `budget` segment (daily token budget): renders `budget NN%` with a fill bar when `wishcraft.tokenBudget.daily.limit` is set; wired into the `chef`, `full`, and `nerd` presets.
+- Resting animation has a real clock: while idle at full motion, the signal rail leases the scheduler's `ambient` channel and breathes from that tick. `reduced`/`off` motion still renders a stable dim marker with no scheduler consumer.
+
 ## [1.12.0] - 2026-09-25
 
 ### Added
@@ -38,18 +44,6 @@
 - Bash forward-mode privacy notice (issue #71): the first keystroke forwarded to a running command raises an info notice that typed input may echo into the transcript; documented in `docs/bash-mode.md`.
 - Managed PTY suite is now script-gated (issue #73): PTY-core tests skip when `script(1)` is missing instead of silently passing in degraded pipe mode, the basic run asserts a real PTY transport, and the explicit pipe-mode tests still cover the fallback.
 
-### Changed
-- Signal rail is now a compact single-line state surface. `ready` is stable and costs no animation frames; thinking, streaming, tools, and compaction use a bounded directional trail without expanding the footer to three rows.
-- Chef preset now includes session age, generated-token throughput, and cache-read information when present. The port counter names its protocol (`tcp` or `tcp+udp`) instead of displaying an ambiguous bare count.
-
-### Fixed
-- Bash paste-while-running (issue #72): a bracketed paste performed while a command runs is stripped of its markers and forwarded to the child stdin — including split delivery across input chunks — instead of silently queuing in the editor buffer behind the command.
-- PTY/transcript memory bounds (from jan `fix/runtime-pty-bounds`): a single unterminated output line is capped at a 64 KiB UTF-8 tail with a one-time notice, the partial-escape tail is bounded, and the active transcript command trims head lines/bytes within limits instead of growing unbounded.
-- Segment-options spread hygiene (CodeFactor #86–89): `normalizeSegmentOptions` assigns fields imperatively instead of spreading conditional empty objects.
-- Motion frames that contain multiple terminal columns no longer expand a rail cell and shift the footer layout while they animate.
-- Idle rail no longer samples `Date.now()` without a corresponding repaint clock, eliminating stale or apparently random idle frames.
-- TPS now reports `--` until a live two-sample rate exists, rather than falsely presenting idle telemetry as `0`; the existing `both`/`out`/`in` setting is validated and honored.
-
 ## [1.4.16] - 2026-09-05
 
 ### Fixed

package/build-stamp.json

@@ -0,0 +1 @@
+{"source_sha":"394402d958799308f24ffc284a240b878588a931"}

package/docs/commands.md

@@ -86,7 +86,7 @@ You can also set it in the agent settings file (`~/.pi/agent/settings.json` by d
 | `full` | Everything: hostname, model, path (abbreviated), full git incl commit + ↑/↓, totals, context total, elapsed + clock |
 | `nerd` | Maximum detail for Nerd Font users: qualified model, full tokens + cache, commit, totals, seconds clock |
 | `ascii` | Safe for any terminal: branch + short commit + ↑/↓, tokens, cost, context% (no Nerd glyphs) |
-| `chef` | Fork default: muted colors, slash separators, compact live state rail, session age, TPS in/out, protocol-labelled open ports, generated tokens, cache, subagent cost |
+| `chef` | Fork default: muted colors, slash separators, breathing state rail, session age, TPS in/out, protocol-labelled open ports, generated tokens, cache, budget, subagent cost |
 
 **Environment:** `POWERLINE_NERD_FONTS=1` to force Nerd Fonts, `=0` for ASCII.
 
@@ -99,7 +99,8 @@ Pi core renders the footer as static text, so live click is not possible; action
 - `/tps`: overlay of the live 1s window (same ring as the segment). `/tps <value>` sets `POWERLINE_TPS`
 - `/usage`: session / today / week overlay from `~/.pi/agent/wishcraft-usage.json`
 - `/open-ports`: list listening ports and pick one
-- `/powerline doctor`: diagnostics overlay — settings file validity, unknown presets, Nerd Font detection, git polling, bash-mode status, and queue file health
+- `/powerline doctor`: diagnostics overlay — settings file validity, unknown presets, Nerd Font detection, git polling, bash-mode status, queue file health, and `package.identity`
+- `/powerline version`: `{ version, source_sha }` from `package.json` (SHA only when release-stamped). See [release.md](./release.md).
 - `/powerline export`: export the current preset + effective layout + labels as a JSON snippet (Enter copies it to the clipboard)
 - `alt+p`: **Wishcraft Deck** — operator overlay (Home, Signal, Skills, Ideas, Guardrails, Appearance, …). `g` then a jump key (`h` home, `s` signal, `a` appearance). Escape closes. `/signal menu` still opens Navigate / Configure / Status.
 - `alt+i`: **powerline info**: full open-ports list

package/docs/index.md

@@ -11,6 +11,7 @@ This package is a Pi.dev extension, not a standalone website. The README is the
 - [Skill manager](./skill-manager.md) — browsing, inserting, `/skills doctor`, and `/skills new` templates.
 - [Working vibes](./working-vibes.md) — themed loading messages, modes, and configuration.
 - [Segments & theming](./segments.md) — segment reference, separators, thinking/path/git options, and theme overrides.
+- [Release route](./release.md) — tag == package version, GitHub Release artifacts, and identity.
 
 ## Design System & vNext Specifications
 

package/docs/release.md

@@ -0,0 +1,16 @@
+# Release route
+
+Declared version source: `package.json` `version`. Product tag `vX.Y.Z` must equal that value at the tagged commit, and the commit must be an ancestor of `origin/main`.
+
+Existing flow is unchanged: main pushes with `[Unreleased]` notes still prepare a candidate; promotion still tags protected main and dispatches publish. `scripts/npm-publish.sh` remains the npm publish target.
+
+This route adds GitHub Release evidence on top of that:
+
+1. `.github/workflows/release.yml` re-checks tag == `package.json` and ancestry on `origin/main`.
+2. It writes `build-stamp.json` / `PI_WISHCRAFT_BUILD_SHA` from the tag commit only (never a fake such as `0.0.0`).
+3. It runs `npm pack`, writes `SHA256SUMS`, and attaches those assets to the GitHub Release.
+4. Visible identity: `node --experimental-strip-types src/product-identity.ts --version` prints `{ version, source_sha }`. `/signal version` and `/signal doctor` (`package.identity`) show the same values. Missing stamp/env is `null`, never invented.
+
+`workflow_dispatch` input `tag` backfills the same checks at an existing tag (for example `v1.10.0`) and uploads artifacts. It does not publish to npm. Do not run the backfill from a contract PR.
+
+This document does not create a tag or GitHub Release.

package/docs/segments.md

@@ -6,6 +6,7 @@
 
 - `tps`: live tokens/sec over a rolling 1-second window (EMA-free, no spikes), reporting **output and input** rates separately (`⇡out ⇣in`) so you can see generation speed and incoming prompt tokens at a glance. It shows `--` until two live samples exist, rather than pretending an idle session runs at zero. Set `segmentOptions.tps.mode` to `both`, `out`, or `in`; override with `POWERLINE_TPS` when needed.
 - `open_ports`: count of unique **TCP** listening ports (`ss` → `netstat` → `/proc/net` fallback, dedupes IPv4/IPv6) rendered as `21 tcp`. Set `segmentOptions.openPorts.includeUdp: true` to include noisy UDP (mDNS/DHCP/ephemeral), rendered as `tcp+udp`.
+- `budget`: daily token-budget usage (`budget 62% ▓▓▓▓░░░░`) when `wishcraft.tokenBudget.daily.limit` is configured. Warns through the same threshold colors as the cost segment.
 
 ### Open-port process owners
 
@@ -101,7 +102,7 @@ The `minimal` and `compact` presets keep these off to stay lean; set `showCommit
 
 ## Segments
 
-`model` · `shell_mode` · `path` · `git` · `subagents` · `queue` · `token_in` · `token_out` · `token_total` · `cost` · `context_pct` · `context_total` · `time_spent` · `time` · `session` · `hostname` · `cache_read` · `cache_write` · `thinking` · `tps` · `open_ports` · `extension_statuses`
+`model` · `shell_mode` · `path` · `git` · `subagents` · `queue` · `token_in` · `token_out` · `token_total` · `cost` · `budget` · `context_pct` · `context_total` · `time_spent` · `time` · `session` · `hostname` · `cache_read` · `cache_write` · `thinking` · `tps` · `open_ports` · `extension_statuses`
 
 ## Separators
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groeponline/pi-wishcraft",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Operator cockpit for Pi: live powerline status, searchable skills, idea queue, sticky Bash, hooks, policy controls, and session UX.",
   "type": "module",
   "files": [

package/src/config/presets.ts

@@ -251,6 +251,7 @@ export const PRESETS: Record<StatusLinePreset, PresetDef> = {
       "cost",
       "context_pct",
       "context_total",
+      "budget",
       "time_spent",
       "time",
       "extension_statuses",
@@ -299,6 +300,7 @@ export const PRESETS: Record<StatusLinePreset, PresetDef> = {
       "cost",
       "context_pct",
       "context_total",
+      "budget",
       "time_spent",
       "time",
       "extension_statuses",
@@ -369,6 +371,7 @@ export const PRESETS: Record<StatusLinePreset, PresetDef> = {
       "subagents",
       "cost",
       "context_pct",
+      "budget",
       "time",
     ],
     separator: "slash",

package/src/config/types.ts

@@ -213,6 +213,7 @@ export const BUILTIN_STATUS_LINE_SEGMENT_IDS = [
   "cost",
   "context_pct",
   "context_total",
+  "budget",
   "time_spent",
   "time",
   "session",

package/src/extension/commands/commands.ts

@@ -35,6 +35,7 @@ import { config, normalizePreset } from "../core/state.ts";
 import type { RuntimeState } from "../core/types.ts";
 import { getPowerlineArgumentCompletions } from "./powerline-completions.ts";
 import { settleSignal } from "../../signal/integration.ts";
+import { formatProductIdentity, readProductIdentity } from "../../product-identity.ts";
 
 export function registerCommands(pi: ExtensionAPI, rt: RuntimeState): void {
   registerCdCommand(pi, () => rt.currentCtx?.cwd ?? process.cwd());
@@ -110,6 +111,10 @@ export function registerCommands(pi: ExtensionAPI, rt: RuntimeState): void {
         await runPowerlineDoctor(rt, ctx);
         return;
       }
+      if (normalizedArgs === "version") {
+        ctx.ui.notify(formatProductIdentity(readProductIdentity()).trimEnd(), "info");
+        return;
+      }
       if (normalizedArgs === "export") {
         await runPowerlineExport(ctx);
         return;

package/src/extension/commands/powerline-completions.ts

@@ -11,6 +11,10 @@ export const POWERLINE_SUBCOMMANDS: ReadonlyArray<{
     value: "doctor",
     description: "Run environment and settings diagnostics",
   },
+  {
+    value: "version",
+    description: "Print package version and stamped source SHA",
+  },
   {
     value: "export",
     description: "Export the current status-line configuration",

package/src/extension/commands/powerline-doctor.ts

@@ -13,6 +13,7 @@ import { hasNerdFonts } from "../../theme/icons.ts";
 import { config } from "../core/state.ts";
 import type { RuntimeState } from "../core/types.ts";
 import { showSelectOverlay } from "../ui/menu-views.ts";
+import { readProductIdentity } from "../../product-identity.ts";
 
 export type DoctorStatus = "ok" | "warn" | "fail";
 
@@ -51,6 +52,15 @@ export function buildDoctorReport(
   const cwd = ctx.cwd ?? process.cwd();
   const checks: DoctorCheck[] = [];
 
+  const identity = readProductIdentity();
+  checks.push({
+    status: "ok",
+    name: "package.identity",
+    detail: identity.source_sha
+      ? `${identity.version} source_sha=${identity.source_sha}`
+      : `${identity.version} source_sha=null`,
+  });
+
   // ── Settings ─────────────────────────────────────────────────────────────
   const globalPath = getSettingsPath();
   const projectPath = getProjectSettingsPath(cwd);

package/src/product-identity.ts

@@ -0,0 +1,86 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const BUILD_SHA_ENV = "PI_WISHCRAFT_BUILD_SHA";
+export const BUILD_STAMP_FILE = "build-stamp.json";
+const SHA_RE = /^[0-9a-f]{40}$/;
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+export type ProductIdentity = {
+  version: string;
+  source_sha: string | null;
+};
+
+function readJson(relativePath: string, rootDir = root): unknown {
+  return JSON.parse(readFileSync(path.join(rootDir, relativePath), "utf8"));
+}
+
+export function readPackageVersion(rootDir = root): string {
+  const pkg = readJson("package.json", rootDir);
+  if (typeof pkg !== "object" || pkg === null) {
+    throw new Error("package.json is not an object");
+  }
+  const version = (pkg as { version?: unknown }).version;
+  if (typeof version !== "string" || !version.trim()) {
+    throw new Error("package.json version is missing");
+  }
+  return version.trim();
+}
+
+function parseSha(raw: string, label: string): string {
+  const sha = raw.trim();
+  if (!SHA_RE.test(sha)) {
+    throw new Error(`${label} must be a 40-character lowercase hex SHA, or unset`);
+  }
+  return sha;
+}
+
+export function readStampSha(rootDir = root): string | null {
+  const stampPath = path.join(rootDir, BUILD_STAMP_FILE);
+  if (!existsSync(stampPath)) return null;
+  const stamp = JSON.parse(readFileSync(stampPath, "utf8")) as {
+    source_sha?: unknown;
+    sha?: unknown;
+  };
+  const raw = stamp.source_sha ?? stamp.sha;
+  if (raw == null || raw === "") return null;
+  if (typeof raw !== "string") {
+    throw new Error(`${BUILD_STAMP_FILE} source_sha must be a string or omitted`);
+  }
+  return parseSha(raw, BUILD_STAMP_FILE);
+}
+
+export function readBuildSha(
+  env: NodeJS.ProcessEnv = process.env,
+  name = BUILD_SHA_ENV,
+  rootDir = root,
+): string | null {
+  const raw = String(env[name] ?? "").trim();
+  if (raw) return parseSha(raw, name);
+  return readStampSha(rootDir);
+}
+
+export function readProductIdentity(
+  env: NodeJS.ProcessEnv = process.env,
+  rootDir = root,
+): ProductIdentity {
+  return {
+    version: readPackageVersion(rootDir),
+    source_sha: readBuildSha(env, BUILD_SHA_ENV, rootDir),
+  };
+}
+
+export function formatProductIdentity(identity: ProductIdentity): string {
+  return `${JSON.stringify(identity)}\n`;
+}
+
+function isDirectEntrypoint(): boolean {
+  if (!process.argv[1]) return false;
+  return fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+}
+
+if (isDirectEntrypoint() && process.argv.includes("--version")) {
+  process.stdout.write(formatProductIdentity(readProductIdentity()));
+}

package/src/render/motion-rail.ts

@@ -1,11 +1,13 @@
 /**
  * Compact Signal rail. It is deliberately a single terminal row: the rail
  * reports agent state, it never displaces the footer while a response streams.
- * Idle has no scheduler consumer; active work leases the shared scheduler.
+ * Full-motion idle leases the scheduler's ambient channel and breathes from
+ * that tick. Reduced and off motion stay a static marker with no consumer.
+ * Active work leases the signal channel.
  */
 
-import { getMotion } from "../motion/catalog.ts";
-import { frameAt, lanternGlow, sweepPhase, sweepReturning, trailGlyph } from "../motion/frames.ts";
+import { defaultMotionFor, getMotion } from "../motion/catalog.ts";
+import { frameAt, framesOf, lanternGlow, sweepPhase, sweepReturning, trailGlyph } from "../motion/frames.ts";
 import { fatBand } from "./motion-candidates.ts";
 import type { SignalRuntime } from "../signal/controller.ts";
 import type { SignalSpec } from "../config/types.ts";
@@ -55,6 +57,21 @@ function railCellColor(distance: number, p: RailPalette): string {
   return fgGradientCode("accent", "sep", Math.min(distance, p.trailDepth + 1) / (p.trailDepth + 1));
 }
 
+function clamp01(value: number): number {
+  return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+
+/** Map a scheduler tick to a repeating phase in the half-open range [0, 1). */
+function scene(duration: number, tick: number): number {
+  return (((tick % duration) + duration) % duration) / duration;
+}
+
+/**
+ * Render the one-line Signal rail and its activity label.
+ *
+ * `width` is the available status-line width used to size the rail. ASCII mode
+ * uses single-column fallback glyphs and a static marker while idle.
+ */
 export function renderActivity(
   runtime: SignalRuntime,
   spec: SignalSpec,
@@ -99,7 +116,9 @@ export function renderActivity(
 
   let rail: string;
   if (!runtime.active) {
-    rail = renderIdleRail(railWidth, ascii, track, dim);
+    rail = runtime.idleAnimated && !ascii
+      ? renderBreathingRail(runtime.tick, railWidth, dim, model, hot)
+      : renderIdleRail(railWidth, ascii, track, dim);
   } else if (runtime.event === "compact") {
     rail = renderCompactRail(runtime.tick, railWidth, ascii, headGlyph, cellColor);
   } else if (runtime.motionId === "fat-band") {
@@ -114,10 +133,41 @@ export function renderActivity(
   return `${paint(left, edge)}${rail}${paint(right, edge)} ${paint(label, runtime.active ? hot : dim)}`;
 }
 
-/** Idle rail. Do not derive idle state from Date.now(): there is
- * intentionally no idle animation clock, so a clock-derived rail otherwise
- * changes only when an unrelated repaint happens. The center marker makes
- * ready glanceable. */
+/**
+ * Resting rail on the ambient tick. A warm radial glow breathes and
+ * shimmers per cell. The same tick always paints the same rail, so tests
+ * can advance `runtime.tick` without sampling the wall clock.
+ */
+function renderBreathingRail(
+  tick: number,
+  width: number,
+  dim: string,
+  model: string,
+  hot: string,
+): string {
+  const idleDef = getMotion(defaultMotionFor("idle"));
+  const idleFrames = idleDef ? framesOf(idleDef) : ["◌", "◎", "◈", "⬡", "◈", "◎"];
+  const phase = scene(96, tick);
+  const center = (width - 1) / 2;
+  const built: string[] = [];
+  for (let i = 0; i < width; i++) {
+    const radial = Math.cos(((i - center) / Math.max(1, center)) * Math.PI * 0.5);
+    const shimmer = 0.22 * Math.sin(phase * Math.PI * 2 + i * 0.9);
+    const level = clamp01(radial * 0.9 + 0.1 + shimmer);
+    if (level <= 0.45) {
+      built.push(paint("─", dim));
+      continue;
+    }
+    const frameIdx = Math.floor(level * (idleFrames.length - 1)) % idleFrames.length;
+    const glyph = cellGlyph(idleFrames[frameIdx] ?? "", "·");
+    const color = level > 0.72 ? hot : model;
+    built.push(paint(glyph, color));
+  }
+  return built.join("");
+}
+
+/** Static idle rail. Reduced and off motion never lease a consumer, so the
+ * marker must not change between unrelated repaints. */
 function renderIdleRail(
   width: number,
   ascii: boolean,

package/src/segments/registry.ts

@@ -21,6 +21,7 @@ import {
   tokenOutSegment,
   tokenTotalSegment,
   costSegment,
+  budgetSegment,
   contextPctSegment,
   contextTotalSegment,
   cacheReadSegment,
@@ -152,6 +153,7 @@ export const SEGMENTS: Record<BuiltinStatusLineSegmentId, StatusLineSegment> = {
   cost: costSegment,
   context_pct: contextPctSegment,
   context_total: contextTotalSegment,
+  budget: budgetSegment,
   time_spent: timeSpentSegment,
   time: timeSegment,
   session: sessionSegment,

package/src/segments/usage.ts

@@ -139,10 +139,6 @@ function contextFillBar(
   percent: number,
   colorFn: (semantic: "context" | "contextWarn" | "contextError") => string,
 ): string {
-  const CELLS = 8;
-  // Clamp to the bar's cell count: percentages above 100 must not grow the
-  // status line, and negative percentages must not underflow the empty run.
-  const filled = Math.max(0, Math.min(CELLS, Math.round((percent / 100) * CELLS)));
   let semantic: "context" | "contextWarn" | "contextError";
   if (percent > 90) {
     semantic = "contextError";
@@ -151,8 +147,25 @@ function contextFillBar(
   } else {
     semantic = "context";
   }
+  return fillBar(percent, semantic, colorFn);
+}
+
+/**
+ * Draw the 8-cell bar for an already-resolved semantic color. Thresholds are
+ * the caller's contract: the budget segment uses its own (80/100) so the bar
+ * never disagrees with the label color next to it.
+ */
+function fillBar(
+  percent: number,
+  semantic: "context" | "contextWarn" | "contextError",
+  colorFn: (semantic: "context" | "contextWarn" | "contextError") => string,
+): string {
+  const CELLS = 8;
+  // Clamp to the bar's cell count: percentages above 100 must not grow the
+  // status line, and negative percentages must not underflow the empty run.
+  const filled = Math.max(0, Math.min(CELLS, Math.round((percent / 100) * CELLS)));
   // Filled cells are left-aligned, so we can emit them as one colored run,
-  // then the empty cells as another — just two color codes total, not one per cell.
+  // then the empty cells as another: just two color codes total, not one per cell.
   const filledColor = colorFn(semantic);
   const emptyColor = colorFn("context");
   const reset = colorEnabled() ? ansi.reset : "";
@@ -161,6 +174,28 @@ function contextFillBar(
   return `${filledRun}${emptyRun}`;
 }
 
+export const budgetSegment: StatusLineSegment = {
+  id: "budget",
+  /** Render daily token use, or hide the segment when no positive limit exists. */
+  render(ctx) {
+    const budget = ctx.tokenBudget;
+    if (!budget || !budget.dailyLimit || budget.dailyLimit <= 0) {
+      return { content: "", visible: false };
+    }
+    const percent = Math.max(0, Math.min(100, (budget.dailyUsed / budget.dailyLimit) * 100));
+    const level = tokenBudgetLevel(budget.dailyUsed, budget.dailyLimit);
+    // The bar must follow the same threshold contract as the label
+    // (costColorForBudget via tokenBudgetLevel: warning from 80%, error only
+    // at 100%): reusing the context bar's 70/90 thresholds would color the
+    // bar error while the label next to it still reads warning.
+    const semantic: "context" | "contextWarn" | "contextError" =
+      level.level >= 100 ? "contextError" : level.level >= 80 ? "contextWarn" : "context";
+    const bar = fillBar(percent, semantic, (s) => color(ctx, s, ""));
+    const text = `budget ${Math.round(percent)}%`;
+    return { content: `${color(ctx, costColorForBudget(level.level), text)} ${bar}`, visible: true };
+  },
+};
+
 export const contextTotalSegment: StatusLineSegment = {
   id: "context_total",
   render(ctx) {

package/src/signal/controller.ts

@@ -21,9 +21,12 @@ export interface SignalRuntime {
   startedAt: number;
   activity: string;
   active: boolean;
+  /** Idle leases an ambient consumer so the breathing rail has a real clock. */
+  idleAnimated: boolean;
   release: (() => void) | null;
 }
 
+/** Create an idle Signal runtime with no active scheduler lease. */
 export function createSignalRuntime(now = Date.now()): SignalRuntime {
   return {
     event: "idle",
@@ -32,6 +35,7 @@ export function createSignalRuntime(now = Date.now()): SignalRuntime {
     startedAt: now,
     activity: "ready",
     active: false,
+    idleAnimated: false,
     release: null,
   };
 }
@@ -47,6 +51,11 @@ export interface SetSignalEventOptions {
   settleOnDone?: boolean;
 }
 
+/**
+ * Update the Signal state for an event and replace its current scheduler lease.
+ * Active events lease the signal channel when policy permits; idle leases the
+ * ambient channel for its breathing rail. Otherwise, the runtime stays static.
+ */
 export function setSignalEvent(
   runtime: SignalRuntime,
   scheduler: MotionScheduler,
@@ -71,7 +80,41 @@ export function setSignalEvent(
   // filters both paths identically via `channelsForMotion`.
   runtime.active =
     def !== undefined && channelsForMotion(def, policy).includes("signal");
-  if (!runtime.active) return;
+  runtime.idleAnimated = false;
+  if (!runtime.active) {
+    // Rest is not static: while nothing runs, lease the ambient channel so
+    // the rail breathes on the shared clock instead of sampling Date.now()
+    // with no repaint of its own. The idle motion is always the catalog's
+    // ambient candidate (wisp) regardless of the active lane's signature.
+    const ambientDef = getMotion(defaultMotionFor("idle"));
+    if (
+      event === "idle" &&
+      ambientDef !== undefined &&
+      channelsForMotion(ambientDef, policy).includes("ambient")
+    ) {
+      runtime.idleAnimated = true;
+      let ambientRelease: (() => void) | null = null;
+      try {
+        ambientRelease = scheduler.subscribe({
+          id: "signal-ambient",
+          channel: "ambient",
+          intervalMs: ambientDef.generator?.intervalMs,
+          onTick(tick) {
+            runtime.tick = tick;
+          },
+          onDone() {
+            runtime.release = null;
+            runtime.idleAnimated = false;
+          },
+        });
+      } catch {
+        runtime.idleAnimated = false;
+        return;
+      }
+      runtime.release = ambientRelease;
+    }
+    return;
+  }
   // Wrap subscribe so a throw doesn't leave runtime.active=true with
   // release=null (a leaked state that would survive stopSignal).
   let release: (() => void) | null = null;