@openparachute/agent 0.2.2 → 0.2.3-rc.10

package/src/step-up.ts

@@ -0,0 +1,316 @@
+/**
+ * Step-up auth (PIN) for high-privilege agent-admin actions (agent#80).
+ *
+ * ## The risk this closes
+ *
+ * A single authenticated `agent:admin` session (the operator's hub cookie traded
+ * for an `agent:admin` Bearer) can today do ANYTHING dangerous with no re-confirm:
+ *   - set/rotate credentials (the Claude OAuth token + the generic env store)
+ *     → exfiltrate vault / channel / Claude tokens,
+ *   - open a TERMINAL → a raw host shell,
+ *   - spawn a `filesystem: full` (unsandboxed) agent → read the whole disk.
+ * "One session = total control over the operator's vault + tokens."
+ *
+ * ## The design (mirrors hub's admin-lock PIN, design `2026-06-17-admin-ui-lock.md`)
+ *
+ * A SECOND factor on top of `agent:admin`: an operator-set PIN, exchanged for a
+ * short-lived **step-up token**. The dangerous endpoints require BOTH a valid
+ * `agent:admin` Bearer AND a valid step-up token; everything else stays
+ * frictionless.
+ *
+ *   1. **PIN, set once by the operator** (`setStepUpPin`). Stored HASHED + SALTED
+ *      (`Bun.password.hash`, argon2id — salt is embedded in the PHC string) in
+ *      `~/.parachute/agent/step-up.json`, mode 0600. NEVER plaintext, NEVER logged,
+ *      NEVER returned. Setting/changing it requires the current `agent:admin`
+ *      session and, if a PIN already exists, the current PIN.
+ *   2. **Step-up exchange** (`mintStepUpToken` after `verifyStepUpPin`): an opaque
+ *      256-bit CSPRNG nonce, TTL ~5min, held server-side in a TTL'd map. REUSABLE
+ *      within its window (unlike the single-use SSE ticket) — one PIN entry buys a
+ *      short working window across several gated actions.
+ *   3. **Gate** (`requireStepUp` in `auth.ts`): the dangerous endpoints assert a
+ *      valid step-up token (header `X-Step-Up-Token`, or `?step_up=` for the
+ *      terminal WebSocket which can't set a header) in addition to `agent:admin`.
+ *      A missing/expired token → `403 { error: "step_up_required" }`, distinct from
+ *      a plain 401 (no/invalid Bearer), so the UI knows to PROMPT vs RE-AUTH.
+ *
+ * ## Security properties (all load-bearing)
+ *
+ *   - PIN hashed + salted (argon2id); never logged / returned. The hash never
+ *     leaves this module — the only readers are `verifyStepUpPin` + `setStepUpPin`.
+ *   - Rate-limited with LOCKOUT ({@link stepUpLimiter}): a compromised `agent:admin`
+ *     session can't brute-force the PIN. 5 wrong PINs / 5 min, mirroring hub's
+ *     `unlockLimiter`.
+ *   - Step-up token: opaque (256-bit nonce), short TTL, SERVER-SIDE only. It NEVER
+ *     widens scope — it's a second factor ON TOP of `agent:admin`, never a
+ *     substitute. A request still needs its own valid `agent:admin` Bearer.
+ *   - No secret in any log: neither the PIN nor the hash nor the token is ever
+ *     written to a log line.
+ *
+ * Process-local in-memory token state by design (mirrors `ui-ticket.ts` + the
+ * daemon's other in-process registries). The daemon is single-instance per
+ * machine; tokens live ≤5min and are cheap to lose on restart (the UI re-prompts).
+ */
+
+import { readFileSync, writeFileSync, existsSync, chmodSync, mkdirSync } from "fs";
+import { join } from "path";
+import { defaultStateDir } from "./registry.ts";
+
+// ---------------------------------------------------------------------------
+// PIN storage (argon2id hash in step-up.json, mode 0600)
+// ---------------------------------------------------------------------------
+
+/**
+ * PIN format: 4–12 digits. A numeric PIN is the phone-lock affordance (mirrors
+ * hub's `ADMIN_LOCK_PIN_RE`). The real defense is the rate-limiter + the fact the
+ * session is already `agent:admin`-authenticated — this is a second, convenience-
+ * grade re-confirm gate, not a high-entropy secret.
+ */
+export const STEP_UP_PIN_RE = /^[0-9]{4,12}$/;
+
+/** Whether a candidate string is a well-formed PIN (format check only). */
+export function isValidPinFormat(pin: unknown): pin is string {
+  return typeof pin === "string" && STEP_UP_PIN_RE.test(pin);
+}
+
+/** The on-disk `step-up.json` shape. Namespaced so a future field can coexist. */
+interface StepUpFile {
+  /** argon2id PHC hash of the operator PIN (salt embedded). Never plaintext. */
+  pinHash?: string;
+}
+
+/** Absolute path to the step-up.json store in a state dir. */
+export function stepUpFilePath(stateDir?: string): string {
+  return join(stateDir ?? defaultStateDir(), "step-up.json");
+}
+
+/** Read `step-up.json`. Returns `{}` when absent. */
+function readStepUpFile(stateDir?: string): StepUpFile {
+  const file = stepUpFilePath(stateDir);
+  if (!existsSync(file)) return {};
+  const parsed = JSON.parse(readFileSync(file, "utf8")) as StepUpFile;
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error(`step-up: ${file} must be a JSON object`);
+  }
+  return parsed;
+}
+
+/**
+ * Persist `step-up.json` 0600 — it holds the PIN hash. Creates the state dir if
+ * needed; `chmod`s 0600 unconditionally (writeFileSync's `mode` only applies on
+ * CREATE, so an existing file under a looser umask is tightened on every write) —
+ * the exact discipline `credentials.ts` / `registry.ts` keep for secrets.
+ */
+function writeStepUpFile(file: StepUpFile, stateDir?: string): void {
+  const dir = stateDir ?? defaultStateDir();
+  mkdirSync(dir, { recursive: true });
+  const path = stepUpFilePath(dir);
+  writeFileSync(path, JSON.stringify(file, null, 2) + "\n", { mode: 0o600 });
+  chmodSync(path, 0o600);
+}
+
+/** True iff a step-up PIN is configured (the feature is set up for this install). */
+export function isStepUpConfigured(stateDir?: string): boolean {
+  const h = readStepUpFile(stateDir).pinHash;
+  return typeof h === "string" && h.length > 0;
+}
+
+/** Thrown by {@link setStepUpPin} when the PIN format is rejected. */
+export class StepUpPinFormatError extends Error {
+  constructor() {
+    super("PIN must be 4–12 digits");
+    this.name = "StepUpPinFormatError";
+  }
+}
+
+/**
+ * Set (first-time) or rotate the step-up PIN. Hashes with argon2id
+ * (`Bun.password.hash` — salted, salt embedded in the PHC string). The CALLER
+ * must enforce that:
+ *   - the request is `agent:admin`-authenticated, and
+ *   - if a PIN ALREADY exists, the current PIN was verified first
+ *     ({@link verifyStepUpPin}) — rotating a PIN needs the old one.
+ * This function trusts that gating; it only validates format + writes the hash.
+ *
+ * Returns nothing. Throws {@link StepUpPinFormatError} on a malformed PIN.
+ */
+export async function setStepUpPin(newPin: string, stateDir?: string): Promise<void> {
+  if (!isValidPinFormat(newPin)) throw new StepUpPinFormatError();
+  const hash = await Bun.password.hash(newPin, "argon2id");
+  const file = readStepUpFile(stateDir);
+  file.pinHash = hash;
+  writeStepUpFile(file, stateDir);
+}
+
+/**
+ * Verify a submitted PIN against the stored hash. Returns false when no PIN is
+ * configured (defensive — callers gate on {@link isStepUpConfigured} first) or the
+ * hash is malformed. The CALLER must run the rate-limiter BEFORE this (a wrong PIN
+ * must count toward the lockout). The PIN is never logged.
+ */
+export async function verifyStepUpPin(pin: string, stateDir?: string): Promise<boolean> {
+  if (typeof pin !== "string" || pin.length === 0) return false;
+  const hash = readStepUpFile(stateDir).pinHash;
+  if (typeof hash !== "string" || hash.length === 0) return false;
+  try {
+    return await Bun.password.verify(pin, hash);
+  } catch {
+    // Corrupt / unparseable hash — fail closed.
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Step-up token store — opaque nonce, TTL'd, REUSABLE within its window
+// ---------------------------------------------------------------------------
+
+/**
+ * Default step-up token lifetime — 5 min (the issue's ~5min). Long enough for an
+ * operator to set a credential / open a terminal / spawn after one PIN entry,
+ * short enough that a stolen token (or a walk-away) is bounded.
+ */
+export const STEP_UP_TOKEN_TTL_MS = 5 * 60 * 1000;
+
+/** Nonce entropy: 32 bytes = 256 bits, matching the SSE ticket's floor. */
+const STEP_UP_TOKEN_BYTES = 32;
+
+/** A minted step-up token's server-side record. Never leaves the process. */
+interface StepUpTokenRecord {
+  /** Epoch ms after which the token is expired (treated as absent). */
+  expiresAt: number;
+}
+
+/** The process-local step-up token store. nonce → record. */
+const stepUpTokens = new Map<string, StepUpTokenRecord>();
+
+/** base64url-encode bytes (no padding) — URL-safe, no `+`/`/`/`=`. */
+function base64url(bytes: Uint8Array): string {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function pruneExpiredStepUpTokens(now = Date.now()): void {
+  for (const [k, rec] of stepUpTokens) {
+    if (now >= rec.expiresAt) stepUpTokens.delete(k);
+  }
+}
+
+/**
+ * Mint a step-up token valid for `ttlMs` (default {@link STEP_UP_TOKEN_TTL_MS}).
+ * The CALLER must have already verified the PIN — this never authenticates. The
+ * token is opaque (no scope/claims rides in it); it is purely a "the PIN was
+ * entered recently" capability checked alongside the `agent:admin` Bearer.
+ * Returns the nonce + its absolute expiry.
+ */
+export function mintStepUpToken(ttlMs = STEP_UP_TOKEN_TTL_MS): {
+  token: string;
+  expiresAt: number;
+} {
+  pruneExpiredStepUpTokens();
+  const bytes = new Uint8Array(STEP_UP_TOKEN_BYTES);
+  crypto.getRandomValues(bytes);
+  const token = base64url(bytes);
+  const expiresAt = Date.now() + ttlMs;
+  stepUpTokens.set(token, { expiresAt });
+  return { token, expiresAt };
+}
+
+/**
+ * Whether a step-up token is currently valid. REUSABLE within its window (does NOT
+ * delete on read — unlike the single-use SSE ticket), so one PIN entry buys a short
+ * window across several gated actions. An absent / expired token returns false (and
+ * an expired one is lazily pruned). Pure in-memory lookup — no I/O, no secret log.
+ */
+export function isStepUpTokenValid(token: string | null | undefined, now = Date.now()): boolean {
+  if (!token) return false;
+  const rec = stepUpTokens.get(token);
+  if (!rec) return false;
+  if (now >= rec.expiresAt) {
+    stepUpTokens.delete(token);
+    return false;
+  }
+  return true;
+}
+
+/** Explicitly revoke a step-up token ("lock now"). Idempotent. */
+export function revokeStepUpToken(token: string | null | undefined): void {
+  if (token) stepUpTokens.delete(token);
+}
+
+/** Test seam: clear the in-memory token store. */
+export function _resetStepUpTokensForTest(): void {
+  stepUpTokens.clear();
+}
+
+/** Test seam: the live step-up token count. */
+export function _stepUpTokenCountForTest(): number {
+  return stepUpTokens.size;
+}
+
+// ---------------------------------------------------------------------------
+// PIN brute-force limiter (lockout) — mirrors hub's admin-lock unlockLimiter
+// ---------------------------------------------------------------------------
+
+/**
+ * 5 wrong PINs / 5-min sliding window before lockout. The step-up exchange is
+ * already `agent:admin`-gated, so the threat is a COMPROMISED session (stolen
+ * cookie → minted Bearer) grinding argon2id PIN verifications without bound. Keyed
+ * per-session (the validated token's subject) so an attacker can't get a fresh
+ * bucket by rotating something cheap. Same floor + posture as hub's `unlockLimiter`.
+ */
+export const STEP_UP_MAX_ATTEMPTS = 5;
+export const STEP_UP_WINDOW_MS = 5 * 60 * 1000;
+
+export interface RateLimitResult {
+  /** True if the attempt is admitted; the caller proceeds to the PIN check. */
+  allowed: boolean;
+  /** Seconds until the bucket frees up (only set when denied). Always >= 1. */
+  retryAfterSeconds?: number;
+}
+
+/**
+ * A small sliding-window rate limiter (the shape mirrors hub's `RateLimiter`,
+ * inlined here to keep the agent module dependency-free). Each key keeps the last
+ * N admitted attempt timestamps; on a new attempt we prune anything older than the
+ * window, count what remains, and allow/deny. `now` is injectable for tests.
+ */
+export class StepUpRateLimiter {
+  private readonly buckets = new Map<string, number[]>();
+
+  constructor(
+    private readonly maxAttempts: number,
+    private readonly windowMs: number,
+  ) {}
+
+  /**
+   * Record an attempt and return whether it's admitted. A DENIED attempt is NOT
+   * recorded (so a flood of denials can't push the reset further out). `now` is
+   * epoch ms (injectable).
+   */
+  checkAndRecord(key: string, now = Date.now()): RateLimitResult {
+    const cutoff = now - this.windowMs;
+    const pruned = (this.buckets.get(key) ?? []).filter((t) => t > cutoff);
+    if (pruned.length >= this.maxAttempts) {
+      const resetAtMs = (pruned[0] ?? now) + this.windowMs;
+      const retryAfterSeconds = Math.max(1, Math.ceil((resetAtMs - now) / 1000));
+      this.buckets.set(key, pruned);
+      return { allowed: false, retryAfterSeconds };
+    }
+    pruned.push(now);
+    this.buckets.set(key, pruned);
+    return { allowed: true };
+  }
+
+  /** Clear a key's bucket (called on a SUCCESSFUL PIN entry so it resets). */
+  clear(key: string): void {
+    this.buckets.delete(key);
+  }
+
+  /** Test seam: wipe all buckets. */
+  reset(): void {
+    this.buckets.clear();
+  }
+}
+
+/** The singleton PIN-attempt limiter (all step-up exchanges share one bucket map). */
+export const stepUpLimiter = new StepUpRateLimiter(STEP_UP_MAX_ATTEMPTS, STEP_UP_WINDOW_MS);

package/src/terminal-ui.ts

@@ -164,6 +164,65 @@ ${SHELL_JS}
     });
   }
 
+  // --- step-up PIN (agent#80) --------------------------------------------
+  // A terminal is a raw host shell — the most dangerous capability — so the WS
+  // upgrade requires a STEP-UP TOKEN on top of the agent:admin Bearer. The WS
+  // can't set a header, so we present it as a step_up query param. We fetch the step-up
+  // status, prompt for the PIN (or set one first), exchange it for a short-TTL
+  // token, and cache it on window.__stepUp. Re-prompt on expiry / WS auth-fail.
+  // This page is server-rendered (no React) so the prompt is a native dialog.
+  function authedJson(suffix, init) {
+    init = init || {};
+    var headers = init.headers || {};
+    headers["accept"] = "application/json";
+    if (window.__token) headers["authorization"] = "Bearer " + window.__token;
+    init.headers = headers;
+    return fetch(MOUNT + "/api" + suffix, init);
+  }
+  function ensureStepUp() {
+    if (window.__stepUp && window.__stepUpExp && Date.now() < window.__stepUpExp - 5000) {
+      return Promise.resolve(window.__stepUp);
+    }
+    return authedJson("/step-up").then(function (r) {
+      return r.json();
+    }).then(function (s) {
+      if (!s.configured) {
+        var np = window.prompt("Set a step-up PIN (4-12 digits) — required to open a terminal:");
+        if (!np) return null;
+        var confirm = window.prompt("Confirm the PIN:");
+        if (confirm !== np) { showNotice("The PINs didn't match — try again.", true); return null; }
+        return authedJson("/step-up/pin", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ newPin: np }),
+        }).then(function (r) {
+          if (!r.ok) { showNotice("Could not set the PIN (must be 4-12 digits).", true); return null; }
+          return exchangePin(np);
+        });
+      }
+      var pin = window.prompt("Enter your step-up PIN to open a terminal:");
+      if (!pin) return null;
+      return exchangePin(pin);
+    });
+  }
+  function exchangePin(pin) {
+    return authedJson("/step-up", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ pin: pin }),
+    }).then(function (r) {
+      if (r.status === 401) { showNotice("Incorrect PIN.", true); return null; }
+      if (r.status === 429) { showNotice("Too many PIN attempts — wait a minute.", true); return null; }
+      if (!r.ok) { showNotice("Step-up failed (" + r.status + ").", true); return null; }
+      return r.json();
+    }).then(function (body) {
+      if (!body || !body.stepUpToken) return null;
+      window.__stepUp = body.stepUpToken;
+      window.__stepUpExp = body.expires_at ? new Date(body.expires_at).getTime() : Date.now() + 5 * 60000;
+      return window.__stepUp;
+    });
+  }
+
   // --- WebSocket relay ----------------------------------------------------
   // The path segment is the AGENT name — the daemon attaches to that agent's tmux
   // session (<name>-agent). NOT a channel.
@@ -172,6 +231,7 @@ ${SHELL_JS}
     var dims = "cols=" + term.cols + "&rows=" + term.rows;
     var u = proto + "//" + location.host + MOUNT + "/terminal/" + encodeURIComponent(agent) + "?" + dims;
     if (window.__token) u += "&token=" + encodeURIComponent(window.__token);
+    if (window.__stepUp) u += "&step_up=" + encodeURIComponent(window.__stepUp);
     return u;
   }
 
@@ -181,6 +241,19 @@ ${SHELL_JS}
     if (ws) { manualClose = true; try { ws.close(); } catch (_e) {} ws = null; }
     manualClose = false;
     clearNotice();
+    // Step-up FIRST — a terminal needs the PIN-minted token (agent#80). Only open
+    // the socket once we hold one; a cancelled prompt leaves the page idle.
+    setStatus("step-up…");
+    ensureStepUp().then(function (tok) {
+      if (!tok) { setStatus("step-up required", "err"); return; }
+      openSocket(agent);
+    }).catch(function () {
+      setStatus("step-up failed", "err");
+      showNotice("Could not complete step-up. Reload and try again.", true);
+    });
+  }
+
+  function openSocket(agent) {
     setStatus("connecting…");
     doFit();
     var socket = new WebSocket(wsUrl(agent));

package/src/transports/http-ui.ts

@@ -16,8 +16,9 @@
  *    to them (mirroring the daemon's `/events` SSE pattern for bridges).
  *
  * It owns two HTTP surfaces via `ingestHttp` (scoped to ITS OWN channel name):
- *   1. POST /api/channels/<name>/send   — body {text} → ctx.emit(...) → {ok:true}
- *   2. GET  /ui/events?channel=<name>    — SSE stream the browser subscribes to
+ *   1. POST /api/channels/<name>/send         — body {text} → ctx.emit(...) → {ok:true}
+ *   2. GET  /ui/events?channel=<name>&ticket=  — SSE stream the browser subscribes to
+ *      (one-time ticket auth — agent#25; the JWT never rides in this URL)
  * The static `/ui` chat page itself is global and served by the daemon, since
  * it's a channel picker across all http-ui channels.
  */
@@ -30,7 +31,7 @@ import type {
   PermissionArgs,
 } from "../transport.ts";
 import { sseFrame } from "../routing.ts";
-import { requireScope, json, SCOPE_SEND, SCOPE_READ } from "../auth.ts";
+import { requireScope, requireSseTicket, json, SCOPE_SEND, SCOPE_READ } from "../auth.ts";
 
 /** A connected browser SSE client (one per open chat page on this channel). */
 interface UiClient {
@@ -168,11 +169,12 @@ export class HttpUiTransport implements Transport {
       url.pathname === "/ui/events" &&
       url.searchParams.get("channel") === channel
     ) {
-      // Layer 2: gate on `agent:read`. EventSource can't set headers, so the
-      // token rides in as a `?token=` query param — the ONLY endpoint that opts
-      // into the query-param fallback (allowQueryParam: true). No-token → 401
-      // before the stream opens.
-      const denied = await requireScope(req, url, SCOPE_READ, true);
+      // Layer 2: EventSource can't set headers, so this gates on a one-time
+      // `?ticket=<nonce>` (agent#25) — minted by POST /api/ui/sse-ticket
+      // (Bearer-gated) and consumed single-use here, carrying `agent:read`. The
+      // hub JWT never appears in this URL (the leak the ticket closes). Absent /
+      // expired / already-used ticket → 401 before the stream opens.
+      const denied = requireSseTicket(url, SCOPE_READ);
       if (denied) return denied;
       const clientId = crypto.randomUUID();
       const clients = this.uiClients;

package/src/transports/vault.ts

@@ -96,6 +96,17 @@ export interface VaultTransportConfig {
   webhookSecret?: string;
   /** Optional path prefix for written notes. Default `channel`. */
   notePathPrefix?: string;
+  /**
+   * Whether `start()` fires the best-effort `ensureSchema()` tag-schema upsert
+   * against the connected vault. Default `true` (back-compat — the daemon always
+   * declares the module's tag inheritance on connect). Tests that construct a
+   * transport with a fake token set this `false` so `start()` does NOT hit the
+   * live vault on 127.0.0.1:1940 (which 401s the fake token → ~one `console.warn`
+   * per schema entry of benign noise). The "tag both parent + child" write floor
+   * means a channel works regardless, so skipping the declaration is safe; it's
+   * only a setup optimization, not a runtime contract. See #32.
+   */
+  declareSchemaOnStart?: boolean;
 }
 
 /** The note shape the daemon hands `ingestInbound` (a subset of the trigger payload). */
@@ -261,11 +272,11 @@ export class InboundClaimConflictError extends Error {
 /** Parent tag (NEW, namespaced) — carried LITERALLY on every note WE write; query
  *  this + metadata.channel to see BOTH directions of a channel (the slash children
  *  are namespace, not inheritance). */
-const AGENT_MESSAGE_TAG = "#agent/message";
+const AGENT_MESSAGE_TAG = "agent/message";
 /** Inbound child (NEW) — the vault trigger fires on this exact tag (never matches outbound → no loop). */
-const AGENT_MESSAGE_INBOUND_TAG = "#agent/message/inbound";
+const AGENT_MESSAGE_INBOUND_TAG = "agent/message/inbound";
 /** Outbound child (NEW) — replies carry this; the trigger's exact-match predicate excludes it. */
-const AGENT_MESSAGE_OUTBOUND_TAG = "#agent/message/outbound";
+const AGENT_MESSAGE_OUTBOUND_TAG = "agent/message/outbound";
 
 /** Metadata key carrying the channel-queue claim status (design 2026-06-18). */
 const STATUS_META_KEY = "status";
@@ -369,7 +380,7 @@ function buildThreadSummaryBody(t: {
  * (it always queries the exact leaf tag); it exists for the nice human rollup, per
  * the design's namespacing decision.
  */
-export const AGENT_ROOT_TAG = "#agent";
+export const AGENT_ROOT_TAG = "agent";
 
 /**
  * Agent-definition tag — a vault-native agent IS a `#agent/definition` note (design
@@ -377,7 +388,7 @@ export const AGENT_ROOT_TAG = "#agent";
  * METADATA is the config (name, backend, workspace, isolation, the def-vault binding).
  * The module reads these notes from a def-vault and instantiates each as a live agent.
  */
-export const AGENT_DEFINITION_TAG = "#agent/definition";
+export const AGENT_DEFINITION_TAG = "agent/definition";
 
 /**
  * Scheduled-job tag — the runner's vault-native job store (design
@@ -386,7 +397,7 @@ export const AGENT_DEFINITION_TAG = "#agent/definition";
  * `#agent/message`. Introduced in Phase 2 as the flat `#agent-job`; moved into the
  * `#agent/*` namespace (`#agent/job`) by the vault-native-agents work (Phase 4a).
  */
-export const AGENT_JOB_TAG = "#agent/job";
+export const AGENT_JOB_TAG = "agent/job";
 /** Default path prefix under which job notes are written: `Channels/<ch>/jobs/<id>`. */
 const JOB_PATH_PREFIX = "Channels";
 
@@ -413,7 +424,7 @@ const JOB_PATH_PREFIX = "Channels";
  * The note carries `['#agent/thread']` EXACTLY — NOT a message tag, NOT the inbound
  * child — so it can never wake a session (no loop).
  */
-export const AGENT_THREAD_TAG = "#agent/thread";
+export const AGENT_THREAD_TAG = "agent/thread";
 /** Default path prefix under which thread notes are written: `Threads/<ch>/<leaf>`. */
 const THREAD_PATH_PREFIX = "Threads";
 
@@ -557,7 +568,7 @@ export const AGENT_VAULT_TRIGGER_TEMPLATE = {
   name: "channel_inbound_<channel>", // hub substitutes the channel name
   events: ["created"],
   when: {
-    tags: ["#agent/message/inbound"],
+    tags: ["agent/message/inbound"],
     has_metadata: ["agent"],
     missing_metadata: ["channel_inbound_rendered_at"],
   },
@@ -581,7 +592,7 @@ export const AGENT_DEF_VAULT_TRIGGER_TEMPLATE = {
   name: "agent_def_reload",
   events: ["created", "updated", "deleted"],
   when: {
-    tags: ["#agent/definition"],
+    tags: ["agent/definition"],
   },
   action: {
     webhook: "<hub-origin>/agent/api/vault/agent-def", // hub fills origin + the auth.bearer
@@ -605,6 +616,8 @@ export class VaultTransport implements Transport {
    */
   readonly webhookSecret?: string;
   private readonly pathPrefix: string;
+  /** See `VaultTransportConfig.declareSchemaOnStart`. Default `true`. */
+  private readonly declareSchemaOnStart: boolean;
 
   constructor(config: VaultTransportConfig) {
     if (!config.vault) {
@@ -621,6 +634,7 @@ export class VaultTransport implements Transport {
     this.token = config.token;
     this.webhookSecret = config.webhookSecret;
     this.pathPrefix = (config.notePathPrefix ?? DEFAULT_PATH_PREFIX).replace(/\/$/, "");
+    this.declareSchemaOnStart = config.declareSchemaOnStart ?? true;
   }
 
   /**
@@ -642,7 +656,11 @@ export class VaultTransport implements Transport {
     // "tag both parent + child" floor in the note writes is the fail-safe, so the
     // channel works even if this declaration never lands. Fire-and-forget — no
     // reason to delay the channel coming up on a schema upsert.
-    void this.ensureSchema();
+    //
+    // Suppressible via `declareSchemaOnStart: false` — tests with a fake token
+    // set this so `start()` doesn't 401 against the live vault (benign warn noise,
+    // #32). The write floor makes the declaration optional anyway.
+    if (this.declareSchemaOnStart) void this.ensureSchema();
   }
 
   // -------------------------------------------------------------------------
@@ -657,11 +675,11 @@ export class VaultTransport implements Transport {
    * `decodeURIComponent`'d (parachute-vault `src/routes.ts` handleTags, the
    * "Routes with tag name" block + `routing.ts` `apiPath.startsWith("/tags")`).
    * Because the route matches a SINGLE path segment (`[^/]+`, no literal slash)
-   * and decodes it, the tag name — which contains BOTH `#` and `/`
-   * (`#agent/message/inbound`) — must be `encodeURIComponent`'d so the `#`
-   * becomes `%23` and the `/` becomes `%2F`; the route then decodes that back to
-   * the literal name. A bare `/` in the URL would fail the `[^/]+` match → 404,
-   * silently dropping the declaration. The PUT body is `{ description?, parent_names? }`.
+   * and decodes it, the tag name — which contains a `/`
+   * (`agent/message/inbound`) — must be `encodeURIComponent`'d so the `/` becomes
+   * `%2F`; the route then decodes that back to the literal name. A bare `/` in the
+   * URL would fail the `[^/]+` match → 404, silently dropping the declaration. The
+   * PUT body is `{ description?, parent_names? }`.
    *
    * Best-effort + non-fatal by contract: every failure is caught and `console.warn`'d,
    * never thrown — the tag-both write floor is the fallback.
@@ -669,8 +687,8 @@ export class VaultTransport implements Transport {
   async ensureSchema(): Promise<void> {
     for (const entry of AGENT_VAULT_TAG_SCHEMA) {
       try {
-        // Single-segment, percent-encoded name: `#agent/message/inbound` →
-        // `%23agent%2Fmessage%2Finbound`. The vault decodes it back to the literal.
+        // Single-segment, percent-encoded name: `agent/message/inbound` →
+        // `agent%2Fmessage%2Finbound`. The vault decodes it back to the literal.
         const url = `${this.vaultUrl}/vault/${this.vault}/api/tags/${encodeURIComponent(entry.name)}`;
         const body: {
           description?: string;
@@ -1099,7 +1117,7 @@ export class VaultTransport implements Transport {
    * namespace, not query inheritance, so we never key off them here.
    *
    *   GET <vaultUrl>/vault/<vault>/api/notes
-   *       ?tag=%23agent%2Fmessage             (the `#` + `/` MUST be percent-encoded)
+   *       ?tag=agent%2Fmessage             (the `/` MUST be percent-encoded)
    *       &include_content=true               (we need the bodies)
    *       &limit=<n>                          (default 200)
    *
@@ -1138,7 +1156,7 @@ export class VaultTransport implements Transport {
     // empty transcript).
     const fetchByTag = async (tag: string): Promise<RawNote[]> => {
       const params = new URLSearchParams();
-      params.set("tag", tag); // URLSearchParams encodes `#` → `%23`
+      params.set("tag", tag); // URLSearchParams encodes `/` → `%2F`
       params.set("include_content", "true");
       params.set("limit", String(fetchLimit));
       const url = `${this.vaultUrl}/vault/${this.vault}/api/notes?${params.toString()}`;
@@ -1380,7 +1398,7 @@ export class VaultTransport implements Transport {
     // Overfetch (the tag query spans all channels) then keep this channel's items.
     const fetchLimit = Math.min(Math.max(limit * 4, 500), 2000);
     const params = new URLSearchParams();
-    params.set("tag", AGENT_MESSAGE_INBOUND_TAG); // → %23agent%2Fmessage%2Finbound
+    params.set("tag", AGENT_MESSAGE_INBOUND_TAG); // → agent%2Fmessage%2Finbound
     params.set("include_content", "true");
     params.set("limit", String(fetchLimit));
     // NEWEST-first at the vault (default order_by is `updated_at`) so a hard cap drops
@@ -1508,7 +1526,7 @@ export class VaultTransport implements Transport {
 
   /**
    * List the scheduled-job notes in THIS channel's vault. Queries by the parent
-   * `#agent/job` tag (URLSearchParams encodes `#`→`%23`, `/`→`%2F`) and returns ALL job
+   * `#agent/job` tag (URLSearchParams encodes `/`→`%2F`) and returns ALL job
    * notes in the vault — the CALLER filters by `metadata.channel` (same index-free
    * pattern as loadTranscript; we don't assume a `channel` index exists). Throws
    * on a non-ok vault response so the API surfaces a clear error rather than a
@@ -1517,7 +1535,7 @@ export class VaultTransport implements Transport {
   async listJobNotes(opts?: { limit?: number }): Promise<JobNote[]> {
     const limit = opts?.limit ?? 500;
     const params = new URLSearchParams();
-    params.set("tag", AGENT_JOB_TAG); // → %23agent%2Fjob
+    params.set("tag", AGENT_JOB_TAG); // → agent%2Fjob
     params.set("include_content", "true");
     params.set("limit", String(limit));
     const url = `${this.vaultUrl}/vault/${this.vault}/api/notes?${params.toString()}`;

package/src/ui-kit.ts

@@ -376,9 +376,12 @@ export const SHELL_JS = `
     el.className = "app-status" + (kind ? " " + kind : "");
   }
   // Hub-minted agent token (cookie-gated to the logged-in operator). Cached on
-  // window.__token; pages attach it as a Bearer header and/or ?token= param.
-  // (Endpoint renamed /admin/channel-token → /admin/agent-token in the
-  // channel→agent rename; the hub 301-redirects the old path for old bookmarks.)
+  // window.__token; pages attach it as a Bearer header. (Browser SSE auth moved
+  // off the query-param token to a one-time ticket in agent#25, so the JWT never
+  // lands in a URL; this template is the retired server-rendered shell, superseded
+  // by the SPA.) Endpoint renamed /admin/channel-token to /admin/agent-token in
+  // the channel-to-agent rename; the hub 301-redirects the old path for old
+  // bookmarks.
   function fetchToken() {
     return fetch(window.location.origin + "/admin/agent-token", { credentials: "include" })
       .then(function (r) { if (!r.ok) throw new Error("token " + r.status); return r.json(); })