@openparachute/agent 0.1.0 → 0.1.2

package/src/web/services-manifest.test.ts

@@ -36,6 +36,7 @@ describe('upsertService', () => {
         version: '0.0.6-rc.1',
         displayName: 'Parachute Agent',
         tagline: 'Manage your Parachute agent groups + vault attachments.',
+        installDir: '/Users/test/parachute-agent',
       },
       path,
     );
@@ -50,11 +51,35 @@ describe('upsertService', () => {
           version: '0.0.6-rc.1',
           displayName: 'Parachute Agent',
           tagline: 'Manage your Parachute agent groups + vault attachments.',
+          installDir: '/Users/test/parachute-agent',
         },
       ],
     });
   });
 
+  it('self-registers installDir so hub can resolve `parachute restart agent`', () => {
+    // Regression for paraclaw#115: pre-fix the agent registered without
+    // installDir, so hub's third-party lifecycle resolution path (parachute-
+    // hub#84) couldn't find a startCmd target and `parachute restart agent`
+    // dead-ended. Self-registering the field here is the proper fix —
+    // hub#177's graceful-degradation is the safety net.
+    upsertService(
+      {
+        name: 'agent',
+        port: 1944,
+        paths: ['/agent'],
+        health: '/api/health',
+        version: '0.1.2-rc.2',
+        installDir: '/Users/test/parachute-agent',
+      },
+      path,
+    );
+    const raw = JSON.parse(readFileSync(path, 'utf8')) as {
+      services: { name: string; installDir?: string }[];
+    };
+    expect(raw.services[0].installDir).toBe('/Users/test/parachute-agent');
+  });
+
   it('replaces an existing entry with the same name in-place', () => {
     upsertService({ name: 'agent', port: 1944, paths: ['/agent'], health: '/api/health', version: 'a' }, path);
     upsertService({ name: 'agent', port: 1944, paths: ['/agent'], health: '/api/health', version: 'b' }, path);
@@ -72,12 +97,15 @@ describe('upsertService', () => {
     expect(raw.services.map((s) => s.name).sort()).toEqual(['agent', 'vault']);
   });
 
-  it('preserves hub-stamped fields on the row (e.g. installDir from parachute-hub#84)', () => {
-    // The hub stamps `installDir` onto the row at install time. Paraclaw's
-    // self-registration row shape doesn't know about that field, but the
-    // upsert must merge rather than replace so the hub-stamped value
-    // survives the second write — otherwise `parachute start agent` after
-    // an auto-start round-trip can't resolve installDir → "unknown service".
+  it('preserves fields not in the new entry on the row (merge, not replace)', () => {
+    // The agent now self-registers `installDir` (paraclaw#115), but the
+    // merge-not-replace behavior is still load-bearing for any field hub
+    // stamps that the agent's entry doesn't carry. `publicExposure` is the
+    // realistic case: it's a real first-party-schema field on hub's side
+    // (set when the operator runs `parachute expose`) but absent from
+    // paraclaw's `ServiceEntry` — so a self-registration round trip must
+    // not drop it. Spread order is `{ ...existing, ...entry }`, so the
+    // agent still wins on the fields it owns.
     writeFileSync(
       path,
       JSON.stringify({
@@ -88,7 +116,7 @@ describe('upsertService', () => {
             paths: ['/agent'],
             health: '/api/health',
             version: '0.0.7-rc.1',
-            installDir: '/Users/test/.parachute/agent',
+            publicExposure: 'loopback',
           },
         ],
       }),
@@ -104,11 +132,11 @@ describe('upsertService', () => {
       path,
     );
     const raw = JSON.parse(readFileSync(path, 'utf8')) as {
-      services: { version: string; installDir?: string }[];
+      services: { version: string; publicExposure?: string }[];
     };
     expect(raw.services).toHaveLength(1);
     expect(raw.services[0].version).toBe('0.0.8-rc.1');
-    expect(raw.services[0].installDir).toBe('/Users/test/.parachute/agent');
+    expect(raw.services[0].publicExposure).toBe('loopback');
   });
 
   it('throws on a malformed existing manifest (so we never silently overwrite)', () => {

package/src/web/services-manifest.ts

@@ -4,14 +4,14 @@
  * Mirrors `parachute-scribe/src/services-manifest.ts` deliberately — the
  * shape is the contract between every Parachute service and the hub
  * (`parachute-hub/src/services-manifest.ts` is the canonical reader).
- * Once paraclaw earns a slot in the hub's vendored fallback, the
- * manifest read flips to `.parachute/module.json`-backed and this file
- * becomes the live state-side companion. Until then, this is what makes
- * `parachute status` / `parachute expose` see paraclaw at all.
- *
  * Failure mode: any write error is logged + swallowed. Self-registration
  * is best-effort — the server still serves locally even if the manifest
  * write fails (permissions, disk full, race with another writer).
+ *
+ * `installDir` is the third-party-module hook (parachute-hub#84): hub
+ * looks the field up to resolve `parachute restart agent` back to the
+ * checkout it should drive. Self-registering it here means the agent
+ * doesn't need a vendored fallback in hub — paraclaw#115.
  */
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
@@ -26,6 +26,7 @@ export interface ServiceEntry {
   version: string;
   displayName?: string;
   tagline?: string;
+  installDir?: string;
 }
 
 interface ServicesManifest {
@@ -49,10 +50,14 @@ export function upsertService(entry: ServiceEntry, path: string = resolveManifes
   mkdirSync(dirname(path), { recursive: true });
   const manifest = readManifest(path);
   const idx = manifest.services.findIndex((s) => s.name === entry.name);
-  // Merge rather than replace so fields the hub stamps onto the row
-  // (`installDir` from parachute-hub#84, etc.) survive a self-registration
-  // pass. Paraclaw still wins for the fields it owns — port, paths,
-  // version, health — because they spread last.
+  // Merge rather than replace, intentionally diverging from
+  // `parachute-hub/src/services-manifest.ts` which full-replaces the row.
+  // The asymmetry tracks who's authoritative: hub owns the first-party
+  // shape (read → schema-validate → write), so it can replace safely;
+  // we're a third-party self-registrant preserving any fields hub stamps
+  // that we don't own (the hub#84 `installDir` slot, future hub-stamped
+  // metadata). The agent still wins for the fields it owns — port, paths,
+  // version, health, installDir — because `entry` spreads last.
   if (idx >= 0) manifest.services[idx] = { ...manifest.services[idx], ...entry };
   else manifest.services.push(entry);
   const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;

package/web/ui/index.html

@@ -3,8 +3,8 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Paraclaw</title>
-    <meta name="description" content="Manage Parachute Vault access for your Paraclaw agents." />
+    <title>Parachute Agent</title>
+    <meta name="description" content="Manage Parachute Vault access for your Parachute Agent groups." />
   </head>
   <body>
     <div id="root"></div>

package/web/ui/src/App.tsx

@@ -49,7 +49,7 @@ export function App() {
         <Link to="/settings/approvals">Settings</Link>
         <Link to="/setup">Setup</Link>
         <a
-          href="https://github.com/ParachuteComputer/paraclaw/blob/main/docs/parachute-integration.md"
+          href="https://github.com/ParachuteComputer/parachute-agent/blob/main/docs/parachute-integration.md"
           target="_blank"
           rel="noreferrer"
         >

package/web/ui/src/lib/api.test.ts

@@ -289,7 +289,7 @@ describe('getMessagingGroupDetail — happy path', () => {
           agentGroupName: 'Main',
           engageMode: 'mention',
           engagePattern: null,
-          senderScope: 'all',
+          senderScope: 'unrestricted',
           ignoredMessagePolicy: 'drop',
           priority: 0,
           createdAt: '2026-04-20T10:00:00Z',
@@ -358,7 +358,7 @@ describe('channel-wire helpers — pinned to /channels/mga/:id', () => {
       agentGroupName: 'Main',
       engageMode: 'mention',
       engagePattern: null,
-      senderScope: 'all',
+      senderScope: 'unrestricted',
       ignoredMessagePolicy: 'drop',
       priority: 0,
       createdAt: '2026-04-20T10:00:00Z',

package/web/ui/src/lib/api.ts

@@ -57,6 +57,12 @@ export interface AgentGroupView {
   name: string;
   folder: string;
   agent_provider: string | null;
+  /**
+   * Per-group secret injection policy. `all` = every in-scope secret lands in
+   * the container; `selective` = only those with an explicit assignment row.
+   * Surfaced for the GroupDetail "Secrets" panel context (paraclaw#104).
+   */
+  secret_mode: 'all' | 'selective';
   created_at: string;
   vault: VaultAttachment | null;
   status: GroupStatus | null;
@@ -777,6 +783,36 @@ export async function listStaleSessionsForSecret(secretId: string): Promise<Stal
   return r.staleSessions;
 }
 
+/**
+ * What the agent group will receive at the next session spawn — the wire
+ * mirror of `resolveInjectableSecrets()` on the host. Powers the GroupDetail
+ * "Secrets" panel (paraclaw#104). Metadata only; values never traverse this
+ * surface.
+ *
+ * `scope` explains *why* the row is included:
+ *   - `scoped`   — owned by this group
+ *   - `assigned` — global, with an explicit assignment row → this group
+ *   - `global`   — global, included only because the group is `mode='all'`
+ */
+export type SecretInclusionScope = 'global' | 'scoped' | 'assigned';
+
+export interface InjectableSecretView {
+  id: string;
+  name: string;
+  kind: SecretKind;
+  agentGroupId: string | null;
+  scope: SecretInclusionScope;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export async function listGroupInjectableSecrets(folder: string): Promise<InjectableSecretView[]> {
+  const r = await request<{ secrets: InjectableSecretView[] }>(
+    `/groups/${encodeURIComponent(folder)}/secrets`,
+  );
+  return r.secrets;
+}
+
 // --- Approvals ---
 
 export type ApprovalKind = 'install_packages' | 'add_mcp_server' | 'access-new-credential' | string;
@@ -992,8 +1028,10 @@ export type ChannelKind = 'discord' | 'telegram' | 'cli';
 
 // Wire vocabulary. See dbToApi* in src/web/routes/channels.ts for DB equivalents in src/types.ts.
 export type EngageMode = 'mention' | 'pattern' | 'all';
-// Wire vocabulary. See dbToApi* in src/web/routes/channels.ts for DB equivalents in src/types.ts.
-export type SenderScope = 'allowlist' | 'all';
+// Wire vocabulary. The wire `'unrestricted'` corresponds to the DB
+// `'all'` (paraclaw#94 — kept literal-disjoint so a grep-refactor can't
+// conflate the two unions through the translator).
+export type SenderScope = 'allowlist' | 'unrestricted';
 // Wire vocabulary. See dbToApi* in src/web/routes/channels.ts for DB equivalents in src/types.ts.
 export type IgnoredMessagePolicy = 'drop' | 'silent';
 

package/web/ui/src/lib/auth.test.ts

@@ -10,7 +10,12 @@
  */
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
-import { migrateLegacyAuthKeys } from './auth.ts';
+import {
+  buildAuthorizeUrl,
+  ensureClient,
+  migrateLegacyAuthKeys,
+  REQUESTED_SCOPES,
+} from './auth.ts';
 
 // jsdom's Storage in this vitest config doesn't reliably expose the full
 // Storage prototype methods (the `--localstorage-file` warning at runtime
@@ -137,3 +142,211 @@ describe('migrateLegacyAuthKeys', () => {
     expect(localStorage.getItem('parachute-agent.discovery')).toBe('{"hubOrigin":"http://hub"}');
   });
 });
+
+/**
+ * Bootstrap-scope narrowing — paraclaw#136. The agent SPA used to request
+ * `vault:read vault:write` at bootstrap, but every vault flow already runs
+ * the paraclaw#56 re-consent pattern (narrow `vault:<name>:admin` via
+ * extraScopes), so the broad bootstrap scopes were dead weight on the
+ * consent screen. These tests pin the post-narrowing surface so a future
+ * edit can't silently re-add vault scopes to the bootstrap grant.
+ */
+describe('REQUESTED_SCOPES + buildAuthorizeUrl', () => {
+  const baseOpts = {
+    hubOrigin: 'http://hub.test',
+    clientId: 'client-abc',
+    redirectUri: 'http://app.test/agent/oauth/callback',
+    challenge: 'challenge-xyz',
+    state: 'state-123',
+  };
+
+  it('REQUESTED_SCOPES is exactly "agent:admin agent:write" — no vault:* at bootstrap', () => {
+    expect(REQUESTED_SCOPES).toBe('agent:admin agent:write');
+    expect(REQUESTED_SCOPES).not.toMatch(/vault:/);
+  });
+
+  it('builds an authorize URL with only agent:* scopes when extraScopes is empty', () => {
+    const u = buildAuthorizeUrl(baseOpts);
+    expect(u.searchParams.get('scope')).toBe('agent:admin agent:write');
+    // Belt-and-suspenders: the URL string itself must not carry any
+    // vault scope, even URL-encoded.
+    expect(u.toString()).not.toMatch(/vault(%3A|:)/);
+  });
+
+  it('appends a narrow vault:<name>:admin scope when passed in extraScopes', () => {
+    const u = buildAuthorizeUrl({ ...baseOpts, extraScopes: ['vault:default:admin'] });
+    const scope = u.searchParams.get('scope') ?? '';
+    expect(scope.split(' ')).toEqual(['agent:admin', 'agent:write', 'vault:default:admin']);
+  });
+
+  it('de-dupes extraScopes that are already in REQUESTED_SCOPES', () => {
+    const u = buildAuthorizeUrl({
+      ...baseOpts,
+      extraScopes: ['agent:admin', 'vault:foo:admin'],
+    });
+    const scope = u.searchParams.get('scope') ?? '';
+    // agent:admin should appear exactly once even though it was passed
+    // again — the consent screen would otherwise show the same scope twice.
+    expect(scope.split(' ').filter((s) => s === 'agent:admin')).toHaveLength(1);
+    expect(scope.split(' ')).toContain('vault:foo:admin');
+  });
+
+  it('writes the standard PKCE-S256 query params alongside the scope', () => {
+    const u = buildAuthorizeUrl(baseOpts);
+    expect(u.origin + u.pathname).toBe('http://hub.test/oauth/authorize');
+    expect(u.searchParams.get('client_id')).toBe('client-abc');
+    expect(u.searchParams.get('redirect_uri')).toBe('http://app.test/agent/oauth/callback');
+    expect(u.searchParams.get('response_type')).toBe('code');
+    expect(u.searchParams.get('code_challenge')).toBe('challenge-xyz');
+    expect(u.searchParams.get('code_challenge_method')).toBe('S256');
+    expect(u.searchParams.get('state')).toBe('state-123');
+  });
+});
+
+/**
+ * Regression-pin the OAuth client_name in the `/oauth/register` body —
+ * paraclaw#137. The hub's consent screen renders this string verbatim, so
+ * it's operator-visible UX, not a free-form internal identifier. The
+ * 0.1.0 brand sweep renamed "Paraclaw web UI" → "Parachute Agent web UI"
+ * (commit 2a83e77 / PR #112); this test prevents a future rename or copy
+ * regression from silently shipping a stale brand on the consent screen.
+ *
+ * No production behavior change — the existing string literal at line ~166
+ * is the only thing this test asserts on.
+ */
+describe('ensureClient — /oauth/register body', () => {
+  it('sends client_name "Parachute Agent web UI" on first registration', async () => {
+    const fetchSpy = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ client_id: 'returned-client-id' }),
+    });
+    vi.stubGlobal('fetch', fetchSpy);
+
+    const id = await ensureClient('http://hub.test');
+
+    expect(id).toBe('returned-client-id');
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchSpy.mock.calls[0];
+    expect(url).toBe('http://hub.test/oauth/register');
+    expect(init.method).toBe('POST');
+    const body = JSON.parse(init.body as string);
+    expect(body.client_name).toBe('Parachute Agent web UI');
+    // Belt: also pin scope + auth method so a future copy edit can't ship
+    // a partially-renamed body.
+    expect(body.scope).toBe(REQUESTED_SCOPES);
+    expect(body.token_endpoint_auth_method).toBe('none');
+  });
+
+  it('reuses the cached client_id when redirect_uri matches the current bootstrap', async () => {
+    // Pre-seed a record whose redirect_uri matches what getRedirectUri()
+    // computes in this test environment (same logic as the prod helper:
+    // origin + BASE_URL + 'oauth/callback'). Cache hit ⇒ no fetch.
+    const expectedRedirect = `${window.location.origin}${import.meta.env.BASE_URL}oauth/callback`;
+    localStorage.setItem(
+      'parachute-agent.client.http://hub.test',
+      JSON.stringify({ client_id: 'cached-client-id', redirect_uri: expectedRedirect }),
+    );
+    const fetchSpy = vi.fn();
+    vi.stubGlobal('fetch', fetchSpy);
+
+    const id = await ensureClient('http://hub.test');
+
+    expect(id).toBe('cached-client-id');
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});
+
+/**
+ * Re-register the OAuth client when the SPA's redirect_uri changes —
+ * paraclaw#138. The hub binds each DCR client_id to the redirect_uri it
+ * was registered with; if the operator changes the SPA's mount path
+ * (e.g. `/claw/` → `/agent/` after the 0.1.0 rename, or any custom
+ * `PARACHUTE_AGENT_WEB_MOUNT` change), the cached client_id stops
+ * matching and `/oauth/authorize` errors out before the consent screen.
+ *
+ * Fix: cache the redirect_uri alongside the client_id and treat any
+ * mismatch (or a legacy record with no redirect_uri at all) as a cache
+ * miss so the SPA registers a fresh client_id under the new path.
+ */
+describe('ensureClient — redirect_uri-aware cache', () => {
+  function mockFetchOk(clientId: string) {
+    const fetchSpy = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ client_id: clientId }),
+    });
+    vi.stubGlobal('fetch', fetchSpy);
+    return fetchSpy;
+  }
+
+  it('re-registers when the cached redirect_uri does not match the current one', async () => {
+    // Stale cache from before a mount-path change: redirect_uri points
+    // at the old path. Current bootstrap computes a different URI, so
+    // the cached client_id is unusable on the hub.
+    localStorage.setItem(
+      'parachute-agent.client.http://hub.test',
+      JSON.stringify({
+        client_id: 'stale-client-id',
+        redirect_uri: 'http://app.test/claw/oauth/callback',
+      }),
+    );
+    const fetchSpy = mockFetchOk('fresh-client-id');
+
+    const id = await ensureClient('http://hub.test');
+
+    expect(id).toBe('fresh-client-id');
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    // The cache must now hold the freshly-registered client_id paired
+    // with the *current* redirect_uri, not the stale one — otherwise
+    // the next bootstrap would re-register on every page load.
+    const updated = JSON.parse(
+      localStorage.getItem('parachute-agent.client.http://hub.test') ?? 'null',
+    );
+    expect(updated.client_id).toBe('fresh-client-id');
+    const expectedRedirect = `${window.location.origin}${import.meta.env.BASE_URL}oauth/callback`;
+    expect(updated.redirect_uri).toBe(expectedRedirect);
+  });
+
+  it('re-registers a legacy ClientRecord that lacks a redirect_uri field (self-heals)', async () => {
+    // Records written before paraclaw#138 had only `{ client_id }`. On
+    // the first bootstrap after upgrade we treat the missing-field case
+    // as a cache miss and re-register so subsequent loads have the full
+    // record. This means existing operators see exactly one extra
+    // registration round-trip on first 0.1.x reload.
+    localStorage.setItem(
+      'parachute-agent.client.http://hub.test',
+      JSON.stringify({ client_id: 'legacy-client-id' }),
+    );
+    const fetchSpy = mockFetchOk('healed-client-id');
+
+    const id = await ensureClient('http://hub.test');
+
+    expect(id).toBe('healed-client-id');
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const healed = JSON.parse(
+      localStorage.getItem('parachute-agent.client.http://hub.test') ?? 'null',
+    );
+    expect(healed.client_id).toBe('healed-client-id');
+    expect(typeof healed.redirect_uri).toBe('string');
+    expect(healed.redirect_uri.length).toBeGreaterThan(0);
+  });
+
+  it('persists redirect_uri alongside client_id on first registration', async () => {
+    // No prior cache. After first registration, the persisted record
+    // must include both fields — otherwise subsequent bootstraps would
+    // legacy-self-heal on every load and burn a hub /oauth/register
+    // call per page reload.
+    const fetchSpy = mockFetchOk('first-client-id');
+
+    await ensureClient('http://hub.test');
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const persisted = JSON.parse(
+      localStorage.getItem('parachute-agent.client.http://hub.test') ?? 'null',
+    );
+    expect(persisted).toMatchObject({
+      client_id: 'first-client-id',
+    });
+    const expectedRedirect = `${window.location.origin}${import.meta.env.BASE_URL}oauth/callback`;
+    expect(persisted.redirect_uri).toBe(expectedRedirect);
+  });
+});

package/web/ui/src/lib/auth.ts

@@ -11,13 +11,18 @@
  *   5. POST <hub>/oauth/token         — authorization_code, then refresh_token
  *                                       on 401 from /api/* before re-login.
  *
- * Scopes: `agent:admin agent:write vault:read vault:write`. `agent:admin` is
- * required for /api/secrets writes + the setup wizard install-channel
- * step; `agent:write` is the bar for /api/approvals decisions and
- * /api/sessions/:id/close. The vault scopes anticipate the vault tokens-API
- * REST endpoint (paraclaw#4 companion vault issue); today the server still
- * shells out, but minting the user JWT with vault:* now means no re-consent
- * later.
+ * Bootstrap scopes: `agent:admin agent:write`. `agent:admin` is required
+ * for /api/secrets writes + the setup wizard install-channel step;
+ * `agent:write` is the bar for /api/approvals decisions and
+ * /api/sessions/:id/close. The agent SPA is self-contained — vault is one
+ * per-agent-group action, not the SPA's identity, so vault scopes are
+ * NOT requested at bootstrap. Per-vault flows extend with `extraScopes`
+ * on `beginLogin([\`vault:\${name}:admin\`])` (see line 199-200) — this is
+ * the paraclaw#56 re-consent pattern, request-on-demand. (paraclaw#136)
+ *
+ * Vault listing for pickers reads `/.well-known/parachute.json` (public,
+ * no scope needed); per-vault token-API access enforces `vault:<name>:admin`
+ * on the vault side regardless of what the bootstrap JWT carries.
  *
  * Existing users with cached tokens that lack a newly-required scope will
  * hit 403 with a body like `requires the X scope`. The api.ts wrapper
@@ -31,6 +36,17 @@ interface DiscoveryResponse {
 
 interface ClientRecord {
   client_id: string;
+  /**
+   * The redirect_uri the client_id was registered with. Hub-side, the
+   * DCR row is bound to the original redirect_uri — sending an authorize
+   * request with a different redirect_uri (e.g. after a mount-path
+   * change like `/claw/` → `/agent/`) fails the hub's redirect_uri
+   * check and the operator sees a hub error instead of the consent
+   * screen. Stash this alongside the client_id so bootstrap can detect
+   * the mismatch and re-register a fresh client_id with the new path.
+   * (paraclaw#138)
+   */
+  redirect_uri: string;
 }
 
 interface TokenSet {
@@ -46,7 +62,7 @@ interface FlowState {
   hub_origin: string;
 }
 
-const REQUESTED_SCOPES = "agent:admin agent:write vault:read vault:write";
+export const REQUESTED_SCOPES = "agent:admin agent:write";
 const DISCOVERY_KEY = "parachute-agent.discovery";
 const FLOW_KEY = "parachute-agent.flow";
 
@@ -148,10 +164,20 @@ async function getDiscovery(): Promise<DiscoveryResponse> {
   return fresh;
 }
 
-async function ensureClient(hubOrigin: string): Promise<string> {
-  const cached = readJson<ClientRecord>(localStorage, clientKey(hubOrigin));
-  if (cached?.client_id) return cached.client_id;
+export async function ensureClient(hubOrigin: string): Promise<string> {
   const redirectUri = getRedirectUri();
+  const cached = readJson<ClientRecord>(localStorage, clientKey(hubOrigin));
+  // Cache hit only if BOTH client_id is present AND the cached
+  // redirect_uri matches the current bootstrap's redirect_uri. A mismatch
+  // means the SPA's mount path changed (e.g. `/claw/` → `/agent/`) and
+  // the hub-side DCR row is bound to the old redirect_uri — re-using the
+  // stale client_id would fail the hub's redirect_uri check on
+  // /oauth/authorize. Treat as cache-miss → re-register a fresh client.
+  // Records written before this guard landed lack `redirect_uri`; treat
+  // those as miss so the migration self-heals. (paraclaw#138)
+  if (cached?.client_id && cached.redirect_uri === redirectUri) {
+    return cached.client_id;
+  }
   const res = await fetch(`${hubOrigin}/oauth/register`, {
     method: "POST",
     headers: { "content-type": "application/json", accept: "application/json" },
@@ -166,7 +192,10 @@ async function ensureClient(hubOrigin: string): Promise<string> {
     throw new Error(`hub /oauth/register failed: ${res.status} ${await res.text()}`);
   }
   const body = (await res.json()) as { client_id: string };
-  writeJson(localStorage, clientKey(hubOrigin), { client_id: body.client_id });
+  writeJson(localStorage, clientKey(hubOrigin), {
+    client_id: body.client_id,
+    redirect_uri: redirectUri,
+  });
   return body.client_id;
 }
 
@@ -217,23 +246,51 @@ export async function beginLogin(extraScopes: string[] = []): Promise<never> {
     hub_origin: hubOrigin,
   };
   writeJson(sessionStorage, FLOW_KEY, flow);
+  const u = buildAuthorizeUrl({
+    hubOrigin,
+    clientId,
+    redirectUri,
+    challenge,
+    state,
+    extraScopes,
+  });
+  window.location.replace(u.toString());
+  // Block until navigation actually happens — callers expect this never
+  // returns control.
+  return new Promise<never>(() => {});
+}
+
+/**
+ * Build the `/oauth/authorize` URL. Pure — no side effects, no storage
+ * reads, no network. Exported so tests can pin the scope string and the
+ * extraScopes append behavior without mocking `window.location.replace`.
+ *
+ * `extraScopes` are appended after `REQUESTED_SCOPES` and de-duped, so a
+ * caller passing a scope already in REQUESTED_SCOPES doesn't double it on
+ * the consent screen.
+ */
+export function buildAuthorizeUrl(opts: {
+  hubOrigin: string;
+  clientId: string;
+  redirectUri: string;
+  challenge: string;
+  state: string;
+  extraScopes?: string[];
+}): URL {
   const scopes = new Set(REQUESTED_SCOPES.split(/\s+/).filter(Boolean));
-  for (const s of extraScopes) {
+  for (const s of opts.extraScopes ?? []) {
     const trimmed = s.trim();
     if (trimmed) scopes.add(trimmed);
   }
-  const u = new URL(`${hubOrigin}/oauth/authorize`);
-  u.searchParams.set("client_id", clientId);
-  u.searchParams.set("redirect_uri", redirectUri);
+  const u = new URL(`${opts.hubOrigin}/oauth/authorize`);
+  u.searchParams.set("client_id", opts.clientId);
+  u.searchParams.set("redirect_uri", opts.redirectUri);
   u.searchParams.set("response_type", "code");
   u.searchParams.set("scope", Array.from(scopes).join(" "));
-  u.searchParams.set("code_challenge", challenge);
+  u.searchParams.set("code_challenge", opts.challenge);
   u.searchParams.set("code_challenge_method", "S256");
-  u.searchParams.set("state", state);
-  window.location.replace(u.toString());
-  // Block until navigation actually happens — callers expect this never
-  // returns control.
-  return new Promise<never>(() => {});
+  u.searchParams.set("state", opts.state);
+  return u;
 }
 
 /**

package/web/ui/src/routes/ChannelWireDetail.test.tsx

@@ -55,7 +55,7 @@ const baseWire: api.ChannelWireView = {
   agentGroupName: 'Main agent',
   engageMode: 'mention',
   engagePattern: null,
-  senderScope: 'all',
+  senderScope: 'unrestricted',
   ignoredMessagePolicy: 'drop',
   priority: 0,
   createdAt: '2026-04-20T10:00:00Z',
@@ -136,7 +136,7 @@ describe('ChannelWireDetail — save', () => {
       expect(api.updateChannelWire).toHaveBeenCalledWith('mga_1', {
         engageMode: 'all',
         engagePattern: null,
-        senderScope: 'all',
+        senderScope: 'unrestricted',
         ignoredMessagePolicy: 'drop',
         priority: 0,
       });

package/web/ui/src/routes/ChannelWireDetail.tsx

@@ -360,7 +360,7 @@ function RoutingRulesEditor({
           onChange={(e) => setSenderScope(e.target.value as SenderScope)}
           disabled={saving}
         >
-          <option value="all">all — anyone in the thread</option>
+          <option value="unrestricted">unrestricted — anyone in the thread</option>
           <option value="allowlist">allowlist — only members of the agent group</option>
         </select>
       </div>