@cruxy/cli 0.26.0 → 0.27.0

package/dist/net/ip-guard.js

@@ -0,0 +1,229 @@
+import { lookup } from "node:dns";
+/** Default resolver: node's `dns.lookup` returning ALL addresses. */
+export const defaultResolveHost = (host) => new Promise((resolve, reject) => {
+    lookup(host, { all: true }, (err, addresses) => {
+        if (err)
+            reject(err);
+        else
+            resolve(addresses.map((a) => a.address));
+    });
+});
+/** Thrown when a URL/host is refused pre-dispatch; carries a human reason. */
+export class BlockedHostError extends Error {
+}
+/** Thrown when the host could not be resolved (a network failure, not a block). */
+export class HostUnresolvedError extends Error {
+}
+/** Parse a dotted-quad IPv4 string into its four octets, or null. */
+function parseIpv4(ip) {
+    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(ip);
+    if (!m)
+        return null;
+    const octets = m.slice(1, 5).map((s) => Number(s));
+    if (octets.some((o) => o > 255))
+        return null;
+    return octets;
+}
+/** True if an IPv4 address falls in a private/loopback/link-local/reserved range. */
+function isBlockedIpv4(ip) {
+    const octets = parseIpv4(ip);
+    if (!octets)
+        return false;
+    const [a, b] = octets;
+    if (a === 0)
+        return true; // 0.0.0.0/8 "this network" / unspecified
+    if (a === 10)
+        return true; // 10.0.0.0/8 private
+    if (a === 127)
+        return true; // 127.0.0.0/8 loopback
+    if (a === 169 && b === 254)
+        return true; // 169.254.0.0/16 link-local (incl. 169.254.169.254 metadata)
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // 172.16.0.0/12 private
+    if (a === 192 && b === 168)
+        return true; // 192.168.0.0/16 private
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // 100.64.0.0/10 CGNAT
+    if (a === 198 && (b === 18 || b === 19))
+        return true; // 198.18.0.0/15 benchmarking
+    if (a === 255 && b === 255)
+        return true; // broadcast-ish
+    return false;
+}
+/**
+ * Expand an IPv6 literal into its 8 sixteen-bit groups, or null if unparseable.
+ * Handles `::` compression and an embedded IPv4 tail (`::ffff:127.0.0.1`).
+ */
+function parseIpv6(input) {
+    let s = input;
+    const tail = [];
+    // Peel off a trailing dotted-quad (IPv4-mapped/-compatible forms).
+    const v4 = /(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(s);
+    if (v4) {
+        const o = parseIpv4(v4[1]);
+        if (!o)
+            return null;
+        tail.push((o[0] << 8) | o[1], (o[2] << 8) | o[3]);
+        s = s.slice(0, v4.index); // leaves a trailing ':' before the compression split
+    }
+    const halves = s.split("::");
+    if (halves.length > 2)
+        return null; // more than one "::" is illegal
+    const head = halves[0] ? halves[0].split(":").filter(Boolean) : [];
+    const rest = halves[1] ? halves[1].split(":").filter(Boolean) : [];
+    const toNums = (groups) => {
+        const out = [];
+        for (const g of groups) {
+            if (!/^[0-9a-f]{1,4}$/.test(g))
+                return null;
+            out.push(parseInt(g, 16));
+        }
+        return out;
+    };
+    const headNums = toNums(head);
+    const restNums = toNums(rest);
+    if (!headNums || !restNums)
+        return null;
+    let groups;
+    if (halves.length === 2) {
+        const fill = 8 - (headNums.length + restNums.length + tail.length);
+        if (fill < 0)
+            return null;
+        groups = [
+            ...headNums,
+            ...Array(fill).fill(0),
+            ...restNums,
+            ...tail,
+        ];
+    }
+    else {
+        groups = [...headNums, ...tail];
+    }
+    return groups.length === 8 ? groups : null;
+}
+/** The dotted-quad embedded in an IPv6 tail's last two groups. */
+function embeddedV4(g) {
+    return `${g[6] >> 8}.${g[6] & 0xff}.${g[7] >> 8}.${g[7] & 0xff}`;
+}
+/** True if an expanded IPv6 address is in a range that must never be reached. */
+function isBlockedIpv6(g) {
+    // IPv4-mapped (::ffff:a.b.c.d) and IPv4-compatible (::a.b.c.d): check the v4 part.
+    const firstFiveZero = g.slice(0, 5).every((x) => x === 0);
+    const firstSixZero = firstFiveZero && g[5] === 0;
+    const embedded = embeddedV4(g);
+    if (firstFiveZero && g[5] === 0xffff)
+        return isBlockedIpv4(embedded); // ::ffff:x
+    if (firstSixZero &&
+        !(g[6] === 0 && g[7] === 0) &&
+        !(g[6] === 0 && g[7] === 1))
+        return isBlockedIpv4(embedded); // ::x.y.z.w (IPv4-compatible, deprecated)
+    if (g.every((x) => x === 0))
+        return true; // :: unspecified
+    if (firstSixZero && g[6] === 0 && g[7] === 1)
+        return true; // ::1 loopback
+    if ((g[0] & 0xffc0) === 0xfe80)
+        return true; // fe80::/10 link-local (fe80–febf)
+    if ((g[0] & 0xfe00) === 0xfc00)
+        return true; // fc00::/7 unique-local (fc00–fdff)
+    if ((g[0] & 0xff00) === 0xff00)
+        return true; // ff00::/8 multicast
+    return false;
+}
+/** Strip brackets, lowercase, and drop an IPv6 scope/zone id from an address. */
+function normalizeAddress(addr) {
+    return addr
+        .trim()
+        .toLowerCase()
+        .replace(/^\[|\]$/g, "")
+        .split("%")[0];
+}
+/** True if an address (v4 or v6) is in a range that must never be reached. */
+export function isBlockedAddress(addr) {
+    const ip = normalizeAddress(addr);
+    if (ip.includes(":")) {
+        const groups = parseIpv6(ip);
+        if (!groups)
+            return true; // fail closed: an unparseable colon-address is refused
+        return isBlockedIpv6(groups);
+    }
+    return isBlockedIpv4(ip);
+}
+/**
+ * True if an address is a LOOPBACK address (127.0.0.0/8, ::1, or an IPv4-mapped
+ * loopback). This is the ONLY range the network MCP transport permits over plain
+ * `http` (loopback dev servers); everything else must be `https` to a public IP.
+ * An unparseable address is not loopback (fail closed — it won't get the http pass).
+ */
+export function isLoopbackAddress(addr) {
+    const ip = normalizeAddress(addr);
+    if (ip.includes(":")) {
+        const g = parseIpv6(ip);
+        if (!g)
+            return false;
+        const firstSixZero = g.slice(0, 6).every((x) => x === 0);
+        if (firstSixZero && g[6] === 0 && g[7] === 1)
+            return true; // ::1
+        // ::ffff:127.x and deprecated ::127.x embed a v4 loopback.
+        const firstFiveZero = g.slice(0, 5).every((x) => x === 0);
+        if (firstFiveZero && (g[5] === 0xffff || g[5] === 0)) {
+            const embedded = `${g[6] >> 8}.${g[6] & 0xff}.${g[7] >> 8}.${g[7] & 0xff}`;
+            const o = parseIpv4(embedded);
+            return o !== null && o[0] === 127;
+        }
+        return false;
+    }
+    const o = parseIpv4(ip);
+    return o !== null && o[0] === 127;
+}
+/**
+ * Resolve `host` and require that EVERY resolved address is public — the SSRF
+ * gate for any URL a caller did not fully control. Throws {@link BlockedHostError}
+ * if any address is private/loopback/link-local/reserved (a security refusal), or
+ * {@link HostUnresolvedError} if the host cannot be resolved (a network failure).
+ * Returns the validated addresses so the caller can PIN the connection to them.
+ */
+export async function assertAllPublic(host, resolve) {
+    const cleaned = host.replace(/^\[|\]$/g, "");
+    let addresses;
+    try {
+        addresses = await resolve(cleaned);
+    }
+    catch (err) {
+        throw new HostUnresolvedError(`could not resolve host "${cleaned}": ${err.message}`);
+    }
+    if (addresses.length === 0) {
+        throw new HostUnresolvedError(`host "${cleaned}" resolved to no addresses`);
+    }
+    for (const addr of addresses) {
+        if (isBlockedAddress(addr)) {
+            throw new BlockedHostError(`host "${cleaned}" resolves to ${addr}, a private/loopback/link-local address`);
+        }
+    }
+    return addresses;
+}
+/**
+ * A `dns.lookup`-compatible function that ignores the hostname and always hands
+ * back one of the pre-validated `addresses`. This is what pins a connection to the
+ * address the SSRF check already approved, defeating DNS rebinding: the socket can
+ * only reach a validated IP, never a value re-resolved at connect time. The Host
+ * header / TLS SNI still carry the original hostname (only the dialed IP is pinned).
+ */
+export function pinnedLookup(addresses) {
+    const resolved = addresses.map((address) => ({
+        address,
+        family: address.includes(":") ? 6 : 4,
+    }));
+    return (_hostname, options, callback) => {
+        const all = typeof options === "object" && options !== null && "all" in options
+            ? options.all
+            : false;
+        if (all)
+            callback(null, resolved);
+        else
+            callback(null, resolved[0].address, resolved[0].family);
+    };
+}
+/** Sort + dedupe an address set so equality checks are order-insensitive. */
+export function normalizeAddressSet(addresses) {
+    return [...new Set(addresses.map(normalizeAddress))].sort();
+}

package/dist/render/index.d.ts

@@ -4,6 +4,7 @@ export { detectCapabilities, detectReducedMotion, resolveColumns, DEFAULT_COLUMN
 export { attachResize, processResizeSignal, type ResizeSignal, } from "./resize.js";
 export { fit, fitMiddle, reflow, stripAnsi, visibleWidth, kvStack, MIN_VALUE_COLS, type KvRow, } from "./layout.js";
 export { composeStatusLine, describePhase, ELAPSED_AFTER_MS, fitStatusLine, formatElapsed, formatTokens, phaseIdentity, } from "./state.js";
+export { createFrameClock, inTransition, intervalFrameTimer, spinnerGlyph, FRAME_INTERVAL_MS, TRANSITION_TICKS, type FrameClock, type FrameTimer, } from "./motion.js";
 export { renderActionPreview, PREVIEW_MAX_LINES } from "./diff.js";
 export { createStreamHighlighter, defaultLineHighlighter, type HighlightCarry, type LineHighlighter, type StreamHighlighter, } from "./highlight.js";
 export { PlainRenderer } from "./plain-renderer.js";

package/dist/render/index.js

@@ -7,6 +7,7 @@ export { detectCapabilities, detectReducedMotion, resolveColumns, DEFAULT_COLUMN
 export { attachResize, processResizeSignal, } from "./resize.js";
 export { fit, fitMiddle, reflow, stripAnsi, visibleWidth, kvStack, MIN_VALUE_COLS, } from "./layout.js";
 export { composeStatusLine, describePhase, ELAPSED_AFTER_MS, fitStatusLine, formatElapsed, formatTokens, phaseIdentity, } from "./state.js";
+export { createFrameClock, inTransition, intervalFrameTimer, spinnerGlyph, FRAME_INTERVAL_MS, TRANSITION_TICKS, } from "./motion.js";
 export { renderActionPreview, PREVIEW_MAX_LINES } from "./diff.js";
 export { createStreamHighlighter, defaultLineHighlighter, } from "./highlight.js";
 export { PlainRenderer } from "./plain-renderer.js";

package/dist/render/motion.d.ts

@@ -0,0 +1,76 @@
+import type { ThemeGlyphs } from "../theme/index.js";
+/**
+ * Motion (U.10) — one frame clock drives every live animation on the render
+ * seam, and a tiny set of pure frame→glyph/style primitives express it. The
+ * design is the same honest-signal discipline as U.4 state: motion encodes real
+ * state (work is progressing, the activity changed, a result landed) and never
+ * decorates. It is a cosmetic overlay on the transient live region (U.2) — never
+ * in the content path, never touching committed bytes.
+ *
+ * The single gate is `caps.spinner` (`cursor && !reducedMotion`, from U.11):
+ * when motion is reduced the clock is *disabled* — it schedules nothing and
+ * never ticks, so every motion collapses to its static end-state, drawn once.
+ * There is exactly one clock per renderer (refcounted like the U.12 resize
+ * signal), not a timer per surface.
+ */
+/** The one frame cadence: 10 fps, the pre-U.10 spinner interval. Bounded by construction. */
+export declare const FRAME_INTERVAL_MS = 100;
+/**
+ * How many frames a phase-transition emphasis lasts before it settles — ~300ms
+ * at {@link FRAME_INTERVAL_MS}. Long enough for the eye to catch "the activity
+ * changed", short enough to never read as decoration.
+ */
+export declare const TRANSITION_TICKS = 3;
+/** Schedule/cancel a repeating tick; injectable so tests drive frames deterministically. */
+export interface FrameTimer {
+    schedule(callback: () => void, intervalMs: number): {
+        unref?: () => void;
+    };
+    cancel(handle: {
+        unref?: () => void;
+    }): void;
+}
+/** The real timer: a single unref'd interval that never holds the process open. */
+export declare const intervalFrameTimer: FrameTimer;
+/**
+ * The one clock that drives all live animation. Subscribers get a monotonic
+ * frame number on each tick; the underlying timer runs ONLY while at least one
+ * subscriber is attached (refcounted), and is torn down on the last unsubscribe
+ * — the same discipline that keeps the U.12 resize listener from leaking.
+ */
+export interface FrameClock {
+    /**
+     * Attach a per-frame callback. The first subscriber starts the single timer;
+     * the returned function detaches and, when it was the last subscriber, stops
+     * the timer. A no-op subscription (returns a no-op unsubscribe) when the clock
+     * is disabled — reduced motion never schedules anything.
+     */
+    subscribe(onFrame: (frame: number) => void): () => void;
+    /** The current monotonic frame counter. Stays 0 while disabled (no ticks). */
+    readonly frame: number;
+    /** Whether motion runs at all — false under reduced motion (`caps.spinner`). */
+    readonly enabled: boolean;
+}
+/**
+ * Build the frame clock. `enabled` is `caps.spinner`: when false the clock is
+ * inert — {@link FrameClock.subscribe} schedules nothing, never ticks, and
+ * `frame` never advances, so callers draw their static end-state once and stop.
+ */
+export declare function createFrameClock(enabled: boolean, timer?: FrameTimer, intervalMs?: number): FrameClock;
+/**
+ * The spinner glyph for a frame (U.10 progress motion): the animated braille
+ * (or single-column ASCII) cycle when the clock runs, the static marker
+ * otherwise. `animated=false` (reduced motion / no cursor) yields the static
+ * glyph with no reference to `frame` — the honest still form of "working".
+ */
+export declare function spinnerGlyph(frame: number, glyph: ThemeGlyphs, animated: boolean): string;
+/**
+ * Whether a phase-transition emphasis is still playing (U.10): true for the
+ * first {@link TRANSITION_TICKS} frames after the phase *identity* changed. The
+ * caller records the frame the identity began on and passes it here; when the
+ * clock is not advancing (reduced motion), `startFrame === frame` forever, so
+ * this is briefly true only if drawn on the very first frame — the renderer
+ * gates the whole emphasis behind `clock.enabled`, so a static draw always uses
+ * the settled end-state.
+ */
+export declare function inTransition(frame: number, startFrame: number): boolean;

package/dist/render/motion.js

@@ -0,0 +1,94 @@
+/**
+ * Motion (U.10) — one frame clock drives every live animation on the render
+ * seam, and a tiny set of pure frame→glyph/style primitives express it. The
+ * design is the same honest-signal discipline as U.4 state: motion encodes real
+ * state (work is progressing, the activity changed, a result landed) and never
+ * decorates. It is a cosmetic overlay on the transient live region (U.2) — never
+ * in the content path, never touching committed bytes.
+ *
+ * The single gate is `caps.spinner` (`cursor && !reducedMotion`, from U.11):
+ * when motion is reduced the clock is *disabled* — it schedules nothing and
+ * never ticks, so every motion collapses to its static end-state, drawn once.
+ * There is exactly one clock per renderer (refcounted like the U.12 resize
+ * signal), not a timer per surface.
+ */
+/** The one frame cadence: 10 fps, the pre-U.10 spinner interval. Bounded by construction. */
+export const FRAME_INTERVAL_MS = 100;
+/**
+ * How many frames a phase-transition emphasis lasts before it settles — ~300ms
+ * at {@link FRAME_INTERVAL_MS}. Long enough for the eye to catch "the activity
+ * changed", short enough to never read as decoration.
+ */
+export const TRANSITION_TICKS = 3;
+/** The real timer: a single unref'd interval that never holds the process open. */
+export const intervalFrameTimer = {
+    schedule(callback, intervalMs) {
+        const handle = setInterval(callback, intervalMs);
+        handle.unref?.();
+        return handle;
+    },
+    cancel(handle) {
+        clearInterval(handle);
+    },
+};
+/**
+ * Build the frame clock. `enabled` is `caps.spinner`: when false the clock is
+ * inert — {@link FrameClock.subscribe} schedules nothing, never ticks, and
+ * `frame` never advances, so callers draw their static end-state once and stop.
+ */
+export function createFrameClock(enabled, timer = intervalFrameTimer, intervalMs = FRAME_INTERVAL_MS) {
+    const subscribers = new Set();
+    let handle = null;
+    let frame = 0;
+    const tick = () => {
+        frame++;
+        for (const fn of [...subscribers])
+            fn(frame);
+    };
+    return {
+        get frame() {
+            return frame;
+        },
+        enabled,
+        subscribe(onFrame) {
+            // Reduced motion: register nothing, schedule nothing. The single absolute
+            // gate — no timer can ever start, so no frame can ever be emitted.
+            if (!enabled)
+                return () => { };
+            subscribers.add(onFrame);
+            if (handle === null)
+                handle = timer.schedule(tick, intervalMs);
+            return () => {
+                subscribers.delete(onFrame);
+                if (subscribers.size === 0 && handle !== null) {
+                    timer.cancel(handle);
+                    handle = null;
+                }
+            };
+        },
+    };
+}
+/**
+ * The spinner glyph for a frame (U.10 progress motion): the animated braille
+ * (or single-column ASCII) cycle when the clock runs, the static marker
+ * otherwise. `animated=false` (reduced motion / no cursor) yields the static
+ * glyph with no reference to `frame` — the honest still form of "working".
+ */
+export function spinnerGlyph(frame, glyph, animated) {
+    if (!animated)
+        return glyph.spinnerStatic;
+    const frames = glyph.spinnerFrames;
+    return frames[frame % frames.length];
+}
+/**
+ * Whether a phase-transition emphasis is still playing (U.10): true for the
+ * first {@link TRANSITION_TICKS} frames after the phase *identity* changed. The
+ * caller records the frame the identity began on and passes it here; when the
+ * clock is not advancing (reduced motion), `startFrame === frame` forever, so
+ * this is briefly true only if drawn on the very first frame — the renderer
+ * gates the whole emphasis behind `clock.enabled`, so a static draw always uses
+ * the settled end-state.
+ */
+export function inTransition(frame, startFrame) {
+    return frame - startFrame < TRANSITION_TICKS;
+}

package/dist/render/tty-renderer.d.ts

@@ -25,6 +25,15 @@ import type { ProgressState, RenderCapabilities, RenderPhase, RenderStream, Stre
  * A committed write still only *hides* the drawn line (registers survive);
  * the next state transition redraws. Nothing redraws per streamed delta, so
  * the U.2 first-chunk-immediate guarantee is untouched.
+ *
+ * U.10 puts every live animation on ONE frame clock (see motion.ts) instead of
+ * a private interval: the spinner glyph and the phase-transition emphasis draw
+ * off `clock.frame`, subscribed only while the line is visible and torn down on
+ * hide/close (no leaked timer). Reduced motion disables the clock — the line is
+ * drawn once in its static end-state. The result reveal is a one-time entrance
+ * emphasis on a committed tool note (never a redraw of committed bytes), so it
+ * needs no clock. Motion is a cosmetic overlay on the live region only; it never
+ * gates a committed write, so the latency guarantee holds with motion active.
  */
 export declare class TtyRenderer implements StreamRenderer {
     readonly caps: RenderCapabilities;
@@ -45,8 +54,12 @@ export declare class TtyRenderer implements StreamRenderer {
     private displaced;
     /** Whether the live line is currently drawn on screen. */
     private lineVisible;
-    private timer;
-    private frame;
+    /** The one frame clock driving live animation (U.10); disabled under reduced motion. */
+    private readonly clock;
+    /** Detach from the clock; null when the live line is hidden (no ticks wanted). */
+    private unsubscribeFrame;
+    /** Clock frame the current phase *identity* began on — drives the transition emphasis (U.10). */
+    private phaseStartFrame;
     private closed;
     /** Unsubscribe from the resize signal (U.12); null when the stream can't resize. */
     private unsubscribeResize;
@@ -67,7 +80,8 @@ export declare class TtyRenderer implements StreamRenderer {
      * zero-cost: no redraw-under per delta.)
      */
     private hideLine;
-    private stopTimer;
+    /** Detach from the frame clock — the timer stops once this is the last subscriber. */
+    private stopFrames;
     /**
      * The current live-line text, composed from the registers. `null` means the
      * line must be hidden: nothing to say, or an interactive prompt owns the

package/dist/render/tty-renderer.js

@@ -3,10 +3,10 @@ import { createStreamPrinter } from "../cli/stream-print.js";
 import { renderActionPreview } from "./diff.js";
 import { createStreamHighlighter, } from "./highlight.js";
 import { fit } from "./layout.js";
+import { createFrameClock, inTransition, spinnerGlyph, } from "./motion.js";
 import { ELAPSED_AFTER_MS, fitStatusLine, formatElapsed, phaseIdentity, } from "./state.js";
 /** Erase the current line and return the cursor to column 0. */
 const CLEAR_LINE = "\r\x1b[2K";
-const SPINNER_INTERVAL_MS = 100;
 /**
  * The interactive renderer: committed content is append-only; the one transient
  * thing on screen is a single managed status line, redrawn in place.
@@ -31,6 +31,15 @@ const SPINNER_INTERVAL_MS = 100;
  * A committed write still only *hides* the drawn line (registers survive);
  * the next state transition redraws. Nothing redraws per streamed delta, so
  * the U.2 first-chunk-immediate guarantee is untouched.
+ *
+ * U.10 puts every live animation on ONE frame clock (see motion.ts) instead of
+ * a private interval: the spinner glyph and the phase-transition emphasis draw
+ * off `clock.frame`, subscribed only while the line is visible and torn down on
+ * hide/close (no leaked timer). Reduced motion disables the clock — the line is
+ * drawn once in its static end-state. The result reveal is a one-time entrance
+ * emphasis on a committed tool note (never a redraw of committed bytes), so it
+ * needs no clock. Motion is a cosmetic overlay on the live region only; it never
+ * gates a committed write, so the latency guarantee holds with motion active.
  */
 export class TtyRenderer {
     caps;
@@ -51,8 +60,12 @@ export class TtyRenderer {
     displaced = null;
     /** Whether the live line is currently drawn on screen. */
     lineVisible = false;
-    timer = null;
-    frame = 0;
+    /** The one frame clock driving live animation (U.10); disabled under reduced motion. */
+    clock;
+    /** Detach from the clock; null when the live line is hidden (no ticks wanted). */
+    unsubscribeFrame = null;
+    /** Clock frame the current phase *identity* began on — drives the transition emphasis (U.10). */
+    phaseStartFrame = 0;
     closed = false;
     /** Unsubscribe from the resize signal (U.12); null when the stream can't resize. */
     unsubscribeResize = null;
@@ -62,6 +75,10 @@ export class TtyRenderer {
         this.theme = resolveTheme(caps);
         this.highlighter = createStreamHighlighter(this.theme);
         this.print = this.newPrinter();
+        // One clock for all live motion (U.10). Gated on `caps.spinner`
+        // (cursor && !reducedMotion), so reduced motion yields an inert clock that
+        // never schedules or ticks — the line is drawn once, statically.
+        this.clock = createFrameClock(caps.spinner);
         // Resize reactivity (U.12): only the live line reflows at the new width —
         // committed rows above are immutable and never rewritten.
         this.unsubscribeResize = caps.onResize?.(() => this.reflowLive()) ?? null;
@@ -107,13 +124,14 @@ export class TtyRenderer {
         if (!this.lineVisible)
             return;
         this.lineVisible = false;
-        this.stopTimer();
+        this.stopFrames();
         this.out.write(CLEAR_LINE);
     }
-    stopTimer() {
-        if (this.timer !== null) {
-            clearInterval(this.timer);
-            this.timer = null;
+    /** Detach from the frame clock — the timer stops once this is the last subscriber. */
+    stopFrames() {
+        if (this.unsubscribeFrame !== null) {
+            this.unsubscribeFrame();
+            this.unsubscribeFrame = null;
         }
     }
     /**
@@ -146,28 +164,36 @@ export class TtyRenderer {
             return;
         }
         this.drawLine(line);
-        if (this.caps.spinner && this.timer === null) {
-            this.timer = setInterval(() => {
-                this.frame++;
+        // Subscribe to the one clock while the line is live; the clock owns the
+        // single (unref'd) timer and only runs while something is subscribed. An
+        // inert clock (reduced motion) subscribes to nothing — the static draw
+        // above is the whole story, no frames follow.
+        if (this.clock.enabled && this.unsubscribeFrame === null) {
+            this.unsubscribeFrame = this.clock.subscribe(() => {
                 const current = this.currentLine();
                 if (current !== null)
                     this.drawLine(current);
-            }, SPINNER_INTERVAL_MS);
-            // Never hold the process open for a spinner.
-            this.timer.unref?.();
+            });
         }
     }
     drawLine(text) {
         this.lineVisible = true;
-        const frames = this.theme.glyph.spinnerFrames;
-        const glyph = this.caps.spinner
-            ? frames[this.frame % frames.length]
-            : this.theme.glyph.spinnerStatic;
+        const animated = this.caps.spinner;
+        const glyph = spinnerGlyph(this.clock.frame, this.theme.glyph, animated);
         // Reserve glyph + space; ANSI-aware fit so the live line can never
         // soft-wrap (currentLine already fits — this is defense in depth) (U.12).
         const room = Math.max(1, this.caps.width - 2);
         const line = fit(text, room, this.theme.glyph.ellipsis);
-        this.out.write(`${CLEAR_LINE}${this.theme.accent(glyph)} ${this.theme.muted(line)}`);
+        // Phase-transition emphasis (U.10): a newly-begun activity brightens for a
+        // few frames, then settles to muted. Purely a color role, so NO_COLOR and
+        // the static (reduced-motion) draw both collapse to the settled end-state —
+        // and it only ever plays on a live phase whose identity just changed.
+        const emphasized = animated &&
+            this.rawStatus === null &&
+            this.phase !== null &&
+            inTransition(this.clock.frame, this.phaseStartFrame);
+        const body = emphasized ? this.theme.accent(line) : this.theme.muted(line);
+        this.out.write(`${CLEAR_LINE}${this.theme.accent(glyph)} ${body}`);
     }
     beginTurn() {
         this.highlighter = createStreamHighlighter(this.theme);
@@ -230,8 +256,13 @@ export class TtyRenderer {
         }
         const before = phaseIdentity(this.phase);
         this.phase = phase;
-        if (phaseIdentity(phase) !== before)
+        if (phaseIdentity(phase) !== before) {
             this.phaseStartedAt = Date.now();
+            // A new activity: restart the transition emphasis from the current frame
+            // (U.10). Only a genuine identity change resets it — a thinking phase that
+            // merely gains token counts keeps drawing settled, no re-flourish.
+            this.phaseStartFrame = this.clock.frame;
+        }
         if (phase === null) {
             // A cleared phase means "nothing is happening" — hide rather than
             // redraw a bare progress prefix between turns.
@@ -263,7 +294,13 @@ export class TtyRenderer {
         const elapsed = started === null ? 0 : Date.now() - started.at;
         const suffix = elapsed >= ELAPSED_AFTER_MS ? ` (${formatElapsed(elapsed)})` : "";
         const mark = event.ok ? this.theme.glyph.success : this.theme.glyph.failure;
-        this.note(`${mark} ${event.label}${suffix}`);
+        // Result reveal (U.10): a freshly-landed result gets a one-time entrance
+        // emphasis on its mark when motion is active — written once into committed
+        // history and never redrawn (immutable). It gates on the same motion axis,
+        // so reduced motion shows the plain mark; under NO_COLOR `strong` is the
+        // identity, so the committed bytes are byte-for-byte unchanged either way.
+        const shownMark = this.caps.spinner ? this.theme.strong(mark) : mark;
+        this.note(`${shownMark} ${event.label}${suffix}`);
     }
     promptResolved() {
         if (this.closed)

package/dist/web/ssrf.d.ts

@@ -17,34 +17,20 @@ import type { HostResolver } from "./types.js";
  *
  * The check runs BEFORE any request is dispatched, and again on every redirect hop
  * (see fetch.ts). A block is a security refusal, distinct from a network failure.
+ *
+ * The IP range math, the pin shim, and the error types now live in the shared
+ * {@link ../net/ip-guard ip-guard} module (JC-A) — the ONE owner of "is this IP
+ * allowed"; this file keeps only the web-specific policy (scheme + the
+ * `allowPrivateHosts` escape hatch) and the web one-shot dispatcher.
  */
-/** Default resolver: node's `dns.lookup` returning ALL addresses. */
-export declare const defaultResolveHost: HostResolver;
-/** Thrown when a URL is refused pre-dispatch; carries a human reason. */
-export declare class BlockedHostError extends Error {
-}
-/** Thrown when the host could not be resolved (a network failure, not a block). */
-export declare class HostUnresolvedError extends Error {
-}
-/** True if an address (v4 or v6) is in a range `web_fetch` must never reach. */
-export declare function isBlockedAddress(addr: string): boolean;
-/**
- * A `dns.lookup`-compatible function that ignores the hostname and always hands
- * back one of the pre-validated `addresses`. This is what pins a connection to the
- * address the SSRF check already approved, defeating DNS rebinding: the socket can
- * only reach a validated IP, never a value re-resolved at connect time.
- */
-export declare function pinnedLookup(addresses: string[]): (_hostname: string, options: unknown, callback: (err: NodeJS.ErrnoException | null, address: string | {
-    address: string;
-    family: number;
-}[], family?: number) => void) => void;
+export { BlockedHostError, HostUnresolvedError, isBlockedAddress, defaultResolveHost, pinnedLookup, } from "../net/ip-guard.js";
 /** An undici dispatcher whose connections are pinned to `addresses`. */
 export declare function createPinnedDispatcher(addresses: string[]): Dispatcher;
 /**
  * Assert that `url` may be fetched and return the validated addresses to pin the
  * connection to. Throws {@link BlockedHostError} for a bad scheme or a host
- * resolving into a blocked range, or {@link HostUnresolvedError} if the host cannot
- * be resolved.
+ * resolving into a blocked range, or `HostUnresolvedError` if the host cannot be
+ * resolved.
  *
  * The returned list is the exact set of addresses the caller must restrict the
  * connection to (via {@link createPinnedDispatcher}). An empty list means "do not