@lumenflow/cli 5.1.0 → 5.2.1

package/packs/sidekick/src/domain/channel.types.ts

@@ -2,23 +2,37 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 
 /**
- * WU-2735 (INIT-060 WU-7a, ADR-013 §ChannelBridge):
- * Pure domain types for the ChannelBridge port.
+ * WU-2735 (INIT-060 WU-7a) + WU-2831 (INIT-062 WU-E):
+ * Domain types for the sidekick ChannelBridge adapters.
  *
- * These types are pure domain: they MUST NOT reference Node `fs`, network
- * sockets, cloud endpoints, or any adapter-specific concept. Both the
- * filesystem adapter (this WU) and the control-plane adapter (WU-2737) shape
- * themselves around these definitions.
+ * As of WU-2831 the port-level identity, config, and send-result shapes are
+ * canonical in @lumenflow/conductor-sdk (Apache-2.0). This file re-exports
+ * those types so sidekick adapters implement the neutral port without
+ * parallel contract drift.
+ *
+ * The internal `EnvelopeKind` + `ChannelEnvelope` shape below remains the
+ * sidekick-pack wire format: it predates the canonical port and is retained
+ * for on-disk/control-plane compatibility of existing adapters. New
+ * implementers (e.g. the cloud phone bridge) SHOULD consume
+ * `@lumenflow/conductor-sdk`'s `ChannelEnvelope` instead.
  */
 
-/**
- * Branded channel identifier. The bridge mints these during `register`; the
- * brand prevents callers from forging ids from raw strings.
- */
-export type ChannelId = string & { readonly __brand: 'sidekick.ChannelId' };
+// Re-export canonical port types from the Apache-2.0 conductor SDK.
+export type {
+  BackpressurePolicy,
+  BridgeConfig,
+  ChannelId,
+  ChannelIdentity,
+  DeliveryGuarantee,
+  IdentityResolver,
+  SendResult,
+} from '@lumenflow/conductor-sdk';
 
 /**
- * Envelope dispatch classification per ADR-013 §4 backpressure split.
+ * Envelope dispatch classification — sidekick-internal wire format.
+ *
+ * Predates the canonical `BackpressurePolicy` enum in conductor-sdk.
+ * Maps: `ephemeral` ↔ `ephemeral`, `queue` ↔ `buffered` (conductor-sdk).
  *
  * - `ephemeral` — observational; may fail-silent when transport is down.
  * - `queue` — commands / approvals; must be queued and replayed on reconnect.
@@ -26,14 +40,18 @@ export type ChannelId = string & { readonly __brand: 'sidekick.ChannelId' };
 export type EnvelopeKind = 'ephemeral' | 'queue';
 
 /**
- * A channel envelope. Kept transport-agnostic: `body` is an opaque
- * JSON-serialisable payload, `content_type` labels it so receivers can dispatch
- * without snooping the body.
+ * A channel envelope (sidekick-internal wire format).
+ * Transport-agnostic: `body` is an opaque JSON-serialisable payload,
+ * `content_type` labels it so receivers can dispatch without snooping the body.
+ *
+ * Note: the canonical port-level envelope is
+ * `@lumenflow/conductor-sdk`'s `ChannelEnvelope` (uses `policy` field).
+ * Adapters translate between the two when bridging across the Apache boundary.
  */
 export interface ChannelEnvelope {
   /** Unique id per envelope (content-hash or uuid — chosen by the emitter). */
   id: string;
-  /** §4 backpressure policy — drives send path (fail-silent vs queued replay). */
+  /** Pack-internal backpressure classification. */
   kind: EnvelopeKind;
   /** MIME-like content descriptor, e.g. `application/json`, `text/plain`. */
   content_type: string;
@@ -44,41 +62,3 @@ export interface ChannelEnvelope {
   /** Optional emitter-supplied metadata (trace ids, correlation keys). */
   metadata?: Readonly<Record<string, unknown>>;
 }
-
-/**
- * Bridge registration config — identity under which a channel is opened.
- *
- * The (`provider`, `name`) pair is the canonical identity: re-registering the
- * same pair returns the same `ChannelId` (ADR-013 §ChannelBridge contract
- * rule #3 — idempotent register).
- *
- * `options` is provider-specific bag. The port does NOT inspect it; adapters
- * interpret.
- */
-export interface BridgeConfig {
-  /** Provider slug — e.g. `filesystem`, `control-plane`. */
-  provider: string;
-  /** Human-readable channel name scoped within the provider. */
-  name: string;
-  /** Provider-specific options (paths, tokens, etc.). Opaque to the port. */
-  options?: Readonly<Record<string, unknown>>;
-}
-
-/**
- * Result of a `send` attempt. `accepted` reflects the port contract: for
- * ephemeral envelopes with an unreachable transport, adapters may return
- * `{ accepted: false, reason: '...' }` rather than throwing (§4 fail-silent).
- */
-export interface SendResult {
-  accepted: boolean;
-  /** Transport-assigned id when the sink confirms receipt (optional). */
-  delivery_id?: string;
-  /** Reason when `accepted === false` (not meant for programmatic handling). */
-  reason?: string;
-  /**
-   * `true` when the sink recognised `envelope.id` on a registered channel as
-   * an at-least-once replay (WU-2737 §Idempotency; cloud contract surface).
-   * Adapters that cannot observe dedup SHOULD omit this field.
-   */
-  deduped?: boolean;
-}

package/packs/sidekick/src/ports/channel-bridge.port.ts

@@ -2,8 +2,17 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 
 /**
- * WU-2735 (INIT-060 WU-7a, ADR-013 §ChannelBridge):
- * ChannelBridge port.
+ * WU-2735 (INIT-060 WU-7a, ADR-013 §ChannelBridge) + WU-2831 (INIT-062 WU-E):
+ *
+ * Sidekick-pack ChannelBridge port.
+ *
+ * As of WU-2831 the canonical neutral port lives in `@lumenflow/conductor-sdk`
+ * under Apache-2.0 — consumers that need an AGPL-free surface (e.g. the
+ * cloud phone bridge) MUST import from there. The sidekick port below reuses
+ * the conductor-sdk identity / config / result types (no parallel drift) but
+ * keeps the pack-internal wire-format envelope (`ChannelEnvelope` with
+ * `kind: 'ephemeral' | 'queue'`) for on-disk and control-plane compatibility
+ * of existing adapters.
  *
  * Port contract — load-bearing across adapters (ADR-013 §ChannelBridge):
  *
@@ -11,14 +20,12 @@
  *   `ephemeral` envelopes (ADR-013 §4 backpressure split).
  * - `receive` yields envelopes in emit order on a single channel (§3). No
  *   cross-channel ordering guarantee.
- * - `register` is idempotent on `BridgeConfig` identity — same
- *   `(provider, name)` returns the same `ChannelId`.
+ * - `connect` (alias: `register`) is idempotent on `BridgeConfig` identity —
+ *   same `(provider, name)` returns the same `ChannelId`.
  * - `disconnect` flushes queued envelopes before closing; in-flight ephemerals
  *   may drop.
  *
- * The port MUST NOT leak filesystem- or network-specific types. Both the
- * filesystem adapter (this WU) and the cloud adapter (WU-2737) implement this
- * interface unmodified.
+ * The port MUST NOT leak filesystem- or network-specific types.
  */
 
 import type {
@@ -29,6 +36,21 @@ import type {
 } from '../domain/channel.types.js';
 
 export interface ChannelBridge {
+  /**
+   * Open (or reuse) a channel. Idempotent on `(provider, name)`.
+   *
+   * Canonical method name per the neutral conductor-sdk port (WU-2831).
+   */
+  connect(bridgeConfig: BridgeConfig): Promise<ChannelId>;
+
+  /**
+   * Legacy alias for `connect`. Retained for pack-internal call sites that
+   * predate WU-2831.
+   *
+   * @deprecated Use `connect` instead (WU-2831 port-contract alignment).
+   */
+  register(bridgeConfig: BridgeConfig): Promise<ChannelId>;
+
   /**
    * Send an envelope on a registered channel.
    *
@@ -42,11 +64,6 @@ export interface ChannelBridge {
    */
   receive(channelId: ChannelId): AsyncIterable<ChannelEnvelope>;
 
-  /**
-   * Register a channel and return its id. Idempotent on `(provider, name)`.
-   */
-  register(bridgeConfig: BridgeConfig): Promise<ChannelId>;
-
   /**
    * Close the channel. Queued envelopes flush before this resolves; ephemerals
    * in flight may be dropped.

package/packs/sidekick/tool-impl/channel-tools.ts

@@ -22,7 +22,6 @@ import {
   buildChannelMessageReceivedEvent,
   buildChannelMessageSentEvent,
   emitSidekickEvent,
-  serializeLocalChannelMessage,
 } from '../sidekick-events.js';
 
 // ---------------------------------------------------------------------------
@@ -300,16 +299,18 @@ async function channelSendViaTransport(
     };
   }
 
-  await emitSidekickEvent(
-    buildChannelMessageSentEvent({
-      provider,
-      channel,
-      content,
-      ...(transportResult.externalMessageId !== undefined
-        ? { external_message_id: transportResult.externalMessageId }
-        : {}),
-    }),
-  );
+  // WU-2830 (INIT-062 WU-D): ChannelMessageSentEvent.message is a typed
+  // ChannelMessageRecord. Provider sends do not have a local storage row,
+  // so we synthesize a record using the external id when available.
+  const providerSentMessage: ChannelMessageRecord = {
+    id: transportResult.externalMessageId ?? createId('msg'),
+    channel_id: `${provider}:${channel}`,
+    sender: 'assistant',
+    content,
+    created_at: nowIso(),
+  };
+
+  await emitSidekickEvent(buildChannelMessageSentEvent(providerSentMessage));
 
   return success(outputData);
 }
@@ -389,9 +390,8 @@ async function channelSendTool(input: unknown, context?: ToolContextLike): Promi
     );
   });
 
-  await emitSidekickEvent(
-    buildChannelMessageSentEvent(serializeLocalChannelMessage(resolvedMessage, channelName)),
-  );
+  // WU-2830: pass the typed ChannelMessageRecord directly.
+  await emitSidekickEvent(buildChannelMessageSentEvent(resolvedMessage));
 
   return success({ message: resolvedMessage as unknown as Record<string, unknown> });
 }
@@ -462,17 +462,47 @@ async function channelReceiveViaTransport(
     };
   }
 
+  // WU-2830: ChannelMessageReceivedEvent now carries typed
+  // ChannelMessageRecord[] (symmetric with the sent event). Coerce
+  // provider-opaque records into the canonical shape before emission.
+  const receivedRecords = (transportResult.records ?? []).map((record) =>
+    coerceProviderRecordToMessageRecord(record, `${provider}:${channel}`),
+  );
+
   await emitSidekickEvent(
     buildChannelMessageReceivedEvent({
       provider,
       channel,
-      count: transportResult.records?.length ?? 0,
+      messages: receivedRecords,
     }),
   );
 
   return success(outputData);
 }
 
+function coerceProviderRecordToMessageRecord(
+  record: unknown,
+  fallbackChannelId: string,
+): ChannelMessageRecord {
+  // WU-2830: provider transports declare `records?: unknown[]`. Type-narrow
+  // to build a ChannelMessageRecord without unsafe casts; missing fields
+  // fall back to sensible defaults so downstream consumers always see a
+  // complete, typed payload.
+  const source = record && typeof record === 'object' ? (record as Record<string, unknown>) : {};
+  const now = nowIso();
+  const id = typeof source.id === 'string' && source.id.length > 0 ? source.id : createId('msg');
+  const channel_id =
+    typeof source.channel_id === 'string' && source.channel_id.length > 0
+      ? source.channel_id
+      : fallbackChannelId;
+  const sender =
+    typeof source.sender === 'string' && source.sender.length > 0 ? source.sender : 'external';
+  const content = typeof source.content === 'string' ? source.content : '';
+  const created_at =
+    typeof source.created_at === 'string' && source.created_at.length > 0 ? source.created_at : now;
+  return { id, channel_id, sender, content, created_at };
+}
+
 async function channelReceiveTool(input: unknown, _context?: ToolContextLike): Promise<ToolOutput> {
   const parsed = toRecord(input);
   const channelName = asNonEmptyString(parsed.channel);
@@ -511,7 +541,8 @@ async function channelReceiveTool(input: unknown, _context?: ToolContextLike): P
   await emitSidekickEvent(
     buildChannelMessageReceivedEvent({
       channel: channelName ?? DEFAULT_CHANNEL_NAME,
-      count: items.length,
+      // WU-2830: carry the full typed ChannelMessageRecord[] payload.
+      messages: items,
     }),
   );
 

package/packs/sidekick/tool-impl/system-tools.ts

@@ -12,11 +12,7 @@ import {
   type ToolContextLike,
   type ToolOutput,
 } from './shared.js';
-import {
-  buildStateRehydratedEvent,
-  emitSidekickEvent,
-  snapshotSidekickState,
-} from '../sidekick-events.js';
+import { emitSidekickStateRehydration, snapshotSidekickState } from '../sidekick-events.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -51,7 +47,9 @@ async function initTool(context?: ToolContextLike): Promise<ToolOutput> {
     }),
   );
 
-  await emitSidekickEvent(buildStateRehydratedEvent(await snapshotSidekickState()));
+  // WU-2830 (INIT-062 WU-D): chunked rehydration replaces the monolithic
+  // `state_rehydrated` emission — unbounded snapshots cannot stream.
+  await emitSidekickStateRehydration(await snapshotSidekickState());
 
   return success({
     initialized: true,

package/packs/software-delivery/manifest.ts

@@ -31,6 +31,25 @@ export type {
 } from './manifest-schema.js';
 
 const FULL_WORKSPACE_SCOPE_PATTERN = '**';
+// WU-2833 (INIT-062 WU-G): the canonical read-only workspace scope used by
+// validation runners like gates / gates:docs. Exposed so remote callers
+// cannot mis-declare a read-only runner with a broader write scope.
+export const SOFTWARE_DELIVERY_READ_SCOPE_PATTERN = FULL_WORKSPACE_SCOPE_PATTERN;
+/**
+ * WU-2833 (INIT-062 WU-G): tools whose runtime handlers perform only
+ * read-side inspection (no filesystem mutation, no git mutation). Any
+ * attempt to re-declare these tools with permission: write or admin MUST
+ * fail the pack:validate gate so the security posture established by
+ * WU-2810/2811/2816 cannot drift without an explicit ADR.
+ */
+export const SOFTWARE_DELIVERY_READ_ONLY_RUNNER_TOOLS = ['gates', 'gates:docs'] as const;
+export type SoftwareDeliveryReadOnlyRunnerTool =
+  (typeof SOFTWARE_DELIVERY_READ_ONLY_RUNNER_TOOLS)[number];
+// WU-2833: metrics:snapshot reads the workspace to compute DORA metrics
+// but writes the computed snapshot back into workspace state. This narrow
+// write scope keeps mobile/cloud tokens for metrics:snapshot from leaking
+// full-tree write access (principle of least privilege).
+const SOFTWARE_DELIVERY_WORKSPACE_STATE_WRITE_PATTERN = '.lumenflow/state/**';
 const SOFTWARE_DELIVERY_WRITE_DIRECTORY_PATTERNS = [
   '.changeset/**',
   '.claude/**',
@@ -99,6 +118,10 @@ const WU_UNBLOCK_TOOL_ENTRY = 'tool-impl/wu-lifecycle-tools.ts#wuUnblockTool';
 const WU_RELEASE_TOOL_ENTRY = 'tool-impl/wu-lifecycle-tools.ts#wuReleaseTool';
 const WU_RECOVER_TOOL_ENTRY = 'tool-impl/wu-lifecycle-tools.ts#wuRecoverTool';
 const WU_REPAIR_TOOL_ENTRY = 'tool-impl/wu-lifecycle-tools.ts#wuRepairTool';
+// WU-2833 (INIT-062 WU-G): admin-mode wu:repair wrapper that forces the
+// `--admin` flag; exposed as a separate manifest tool so approvals can
+// be attached to the privileged surface independently of wu:repair.
+const WU_REPAIR_ADMIN_TOOL_ENTRY = 'tool-impl/wu-lifecycle-tools.ts#wuRepairAdminTool';
 const GATES_TOOL_ENTRY = 'tool-impl/wu-lifecycle-tools.ts#gatesTool';
 // WU-2729 (INIT-060 Phase 2): gates:docs exposes docs-only gate runs via a
 // dedicated manifest entry so remote callers can request the docs gate
@@ -210,6 +233,11 @@ const TOOL_PERMISSIONS = {
   'wu:recover': 'write',
   'wu:release': 'write',
   'wu:repair': 'write',
+  // WU-2833 (INIT-062 WU-G): privileged recovery surface for cloud-team
+  // phone UX. Distinct tool name so an approval gate + admin permission
+  // can be declared without widening the scope of the default wu:repair
+  // implementer tool.
+  'wu:repair:admin': 'admin',
   'wu:sandbox': 'write',
   'wu:status': 'read',
   'wu:unblock': 'write',
@@ -241,8 +269,12 @@ const TOOL_PERMISSIONS = {
   'lane:suggest': 'write',
   'flow:bottlenecks': 'read',
   'flow:report': 'read',
-  gates: 'write',
-  'gates:docs': 'write',
+  // WU-2833 (INIT-062 WU-G): gates and gates:docs are read-only validation
+  // runners. Mobile/cloud tokens for these tools must not carry workspace
+  // write access (principle of least privilege; matches the security
+  // posture established by WU-2810/2811/2816).
+  gates: 'read',
+  'gates:docs': 'read',
   'file:delete': 'write',
   'file:edit': 'write',
   'file:read': 'read',
@@ -278,7 +310,11 @@ const TOOL_PERMISSIONS = {
   'lumenflow:release': 'write',
   'lumenflow:upgrade': 'write',
   metrics: 'read',
-  'metrics:snapshot': 'read',
+  // WU-2833 (INIT-062 WU-G): metrics:snapshot reads the workspace and
+  // writes a DORA snapshot back into .lumenflow/state/. Permission role
+  // is "write" because it mutates state; the explicit SCOPE_OVERRIDE
+  // narrows the write path to .lumenflow/state/** (no full-tree write).
+  'metrics:snapshot': 'write',
   'lumenflow:metrics': 'read',
   'signal:cleanup': 'write',
   'sync:templates': 'write',
@@ -320,6 +356,7 @@ const TOOL_ENTRY_OVERRIDES: Partial<Record<ToolName, string>> = {
   'wu:release': WU_RELEASE_TOOL_ENTRY,
   'wu:recover': WU_RECOVER_TOOL_ENTRY,
   'wu:repair': WU_REPAIR_TOOL_ENTRY,
+  'wu:repair:admin': WU_REPAIR_ADMIN_TOOL_ENTRY,
   'wu:infer-lane': WU_INFER_LANE_TOOL_ENTRY,
   gates: GATES_TOOL_ENTRY,
   'gates:docs': GATES_DOCS_TOOL_ENTRY,
@@ -415,9 +452,36 @@ function requiredScopesForPermission(permission: ToolPermission): PathScope[] {
     return createPathScopes([FULL_WORKSPACE_SCOPE_PATTERN], TOOL_SCOPE_ACCESS.READ);
   }
 
+  // WU-2833: admin permission inherits the same constrained write-scope
+  // set as write permission. The admin distinction is carried by the
+  // required_approvals gate, not by broader path access.
   return createPathScopes(SOFTWARE_DELIVERY_WRITE_SCOPE_PATTERNS, TOOL_SCOPE_ACCESS.WRITE);
 }
 
+/**
+ * WU-2833 (INIT-062 WU-G): per-tool scope overrides for tools whose
+ * runtime semantics do not match the default read/write scope set. Used
+ * sparingly — only when a tool legitimately needs both read and a narrow
+ * write scope (or vice versa).
+ */
+const SCOPE_OVERRIDES: Partial<Record<string, PathScope[]>> = {
+  // metrics:snapshot reads the full workspace to compute DORA metrics,
+  // then writes the snapshot back into workspace state. The narrow write
+  // scope prevents mobile/cloud tokens from leaking full-tree write.
+  'metrics:snapshot': [
+    {
+      type: TOOL_SCOPE_TYPES.PATH,
+      pattern: FULL_WORKSPACE_SCOPE_PATTERN,
+      access: TOOL_SCOPE_ACCESS.READ,
+    },
+    {
+      type: TOOL_SCOPE_TYPES.PATH,
+      pattern: SOFTWARE_DELIVERY_WORKSPACE_STATE_WRITE_PATTERN,
+      access: TOOL_SCOPE_ACCESS.WRITE,
+    },
+  ],
+};
+
 /**
  * WU-2729 (INIT-060 Phase 2): the 10 software-delivery pack tools that are
  * callable remotely via POST /tools/:name. The HTTP surface uses this list
@@ -460,17 +524,23 @@ const APPROVAL_OVERRIDES: Partial<Record<ToolName, readonly string[]>> = {
   'plan:promote': [SOFTWARE_DELIVERY_APPROVAL_IDS.REMOTE_MUTATION],
   'initiative:create': [SOFTWARE_DELIVERY_APPROVAL_IDS.REMOTE_MUTATION],
   'initiative:add-wu': [SOFTWARE_DELIVERY_APPROVAL_IDS.REMOTE_MUTATION],
+  // WU-2833: privileged recovery MUST present an explicit approval gate
+  // to conductor/phone UX before dispatch. Without this the admin tool
+  // is indistinguishable from wu:repair from an authorisation standpoint.
+  'wu:repair:admin': [SOFTWARE_DELIVERY_APPROVAL_IDS.REMOTE_MUTATION],
 };
 
 function requiredApprovalsForTool(name: ToolName): string[] | undefined {
-  // WU-2729: only the 10 remote-callable tools carry explicit
+  // WU-2729: the 10 remote-callable tools carry explicit
   // required_approvals metadata (even if empty). Other tools leave the
   // field undefined so the manifest stays minimally descriptive.
+  // WU-2833: admin-permission tools also carry explicit approvals so the
+  // privileged surface cannot be invoked without a visible approval gate.
   const isRemoteCallable = (REMOTE_CALLABLE_TOOLS as readonly string[]).includes(name);
-  if (!isRemoteCallable) {
+  const override = APPROVAL_OVERRIDES[name];
+  if (!isRemoteCallable && override === undefined) {
     return undefined;
   }
-  const override = APPROVAL_OVERRIDES[name];
   return override ? [...override] : [];
 }
 
@@ -487,11 +557,15 @@ function createManifestTools(): SoftwareDeliveryManifestTool[] {
   return (Object.keys(TOOL_PERMISSIONS) as ToolName[]).map((name) => {
     const permission = TOOL_PERMISSIONS[name];
     const approvals = requiredApprovalsForTool(name);
+    // WU-2833: per-tool scope overrides take priority over the default
+    // permission-derived scope set so read-plus-narrow-write tools like
+    // metrics:snapshot can declare both accesses on a single entry.
+    const scopeOverride = SCOPE_OVERRIDES[name];
     const entry: SoftwareDeliveryManifestTool = {
       name,
       entry: resolveToolEntry(name),
       permission,
-      required_scopes: requiredScopesForPermission(permission),
+      required_scopes: scopeOverride ? [...scopeOverride] : requiredScopesForPermission(permission),
     };
     if (approvals !== undefined) {
       entry.required_approvals = approvals;
@@ -543,6 +617,19 @@ const SOFTWARE_DELIVERY_EMITTED_EVENT_KINDS = [
   'software-delivery:plan_created',
   'software-delivery:plan_linked',
   'software-delivery:plan_promoted',
+  // WU-2832 (INIT-062 WU-F): close the cloud-team polling gap with 9
+  // additional ephemeral kinds. Validation pair (validated/invalid),
+  // recovery, preflight, escalation, ratchet, bottleneck, DORA snapshot,
+  // and replay-artifact addressable by event_id.
+  'software-delivery:wu_spec_validated',
+  'software-delivery:wu_spec_invalid',
+  'software-delivery:wu_recovered',
+  'software-delivery:wu_preflight_failed',
+  'software-delivery:wu_escalation_resolved',
+  'software-delivery:test_ratchet_adjusted',
+  'software-delivery:flow_bottleneck_detected',
+  'software-delivery:dora_metric_snapshot',
+  'software-delivery:replay_artifact_published',
 ] as const;
 const SOFTWARE_DELIVERY_REQUIRED_SURFACES = ['http'] as const;
 

package/packs/software-delivery/manifest.yaml

@@ -200,6 +200,15 @@ tools:
     entry: tool-impl/wu-lifecycle-tools.ts#wuRepairTool
     permission: write
     required_scopes: *softwareDeliveryWriteScopes
+  # WU-2833 (INIT-062 WU-G): privileged wu:repair surface for cloud-team
+  # phone UX. Distinct tool name so approval gate + admin permission can
+  # be declared without widening the default wu:repair surface.
+  - name: wu:repair:admin
+    entry: tool-impl/wu-lifecycle-tools.ts#wuRepairAdminTool
+    permission: admin
+    required_scopes: *softwareDeliveryWriteScopes
+    required_approvals:
+      - software-delivery:remote_mutation
   - name: wu:sandbox
     entry: tool-impl/wu-lifecycle-tools.ts#wuSandboxTool
     permission: write
@@ -377,15 +386,26 @@ tools:
         access: read
     required_approvals: []
   # gate:*
+  # WU-2833 (INIT-062 WU-G): gates / gates:docs are read-only validation
+  # runners. Declaring them permission: write would grant mobile/cloud
+  # tokens full-tree write access via required_scopes (the security model
+  # hardened by WU-2810/2811/2816). Re-declare as permission: read and
+  # scope them to SOFTWARE_DELIVERY_READ_SCOPE (wildcard path, read).
   - name: gates
     entry: tool-impl/wu-lifecycle-tools.ts#gatesTool
-    permission: write
-    required_scopes: *softwareDeliveryWriteScopes
+    permission: read
+    required_scopes:
+      - type: path
+        pattern: '**'
+        access: read
     required_approvals: []
   - name: gates:docs
     entry: tool-impl/wu-lifecycle-tools.ts#gatesDocsTool
-    permission: write
-    required_scopes: *softwareDeliveryWriteScopes
+    permission: read
+    required_scopes:
+      - type: path
+        pattern: '**'
+        access: read
     required_approvals: []
   # file:*
   - name: file:delete
@@ -577,13 +597,20 @@ tools:
       - type: path
         pattern: '**'
         access: read
+  # WU-2833 (INIT-062 WU-G): metrics:snapshot reads the workspace and
+  # writes a DORA snapshot to .lumenflow/state/. Declared permission:
+  # write with narrow write scope + full-read scope (principle of least
+  # privilege — no full-tree write).
   - name: metrics:snapshot
     entry: tool-impl/flow-metrics-tools.ts#metricsSnapshotTool
-    permission: read
+    permission: write
     required_scopes:
       - type: path
         pattern: '**'
         access: read
+      - type: path
+        pattern: .lumenflow/state/**
+        access: write
   - name: lumenflow:metrics
     entry: tool-impl/runtime-native-tools.ts#lumenflowMetricsTool
     permission: read
@@ -686,6 +713,16 @@ emitted_event_kinds:
   - software-delivery:plan_created
   - software-delivery:plan_linked
   - software-delivery:plan_promoted
+  # WU-2832 (INIT-062 WU-F): close the cloud-team polling gap.
+  - software-delivery:wu_spec_validated
+  - software-delivery:wu_spec_invalid
+  - software-delivery:wu_recovered
+  - software-delivery:wu_preflight_failed
+  - software-delivery:wu_escalation_resolved
+  - software-delivery:test_ratchet_adjusted
+  - software-delivery:flow_bottleneck_detected
+  - software-delivery:dora_metric_snapshot
+  - software-delivery:replay_artifact_published
 subscribed_event_kinds: []
 required_approvals: []
 surfaces_required:

package/packs/software-delivery/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/packs-software-delivery",
-  "version": "5.1.0",
+  "version": "5.2.1",
   "description": "Software delivery pack for LumenFlow — work units, gates, lanes, initiatives, and agent coordination",
   "keywords": [
     "lumenflow",

package/packs/software-delivery/tool-impl/wu-lifecycle-tools.ts

@@ -698,6 +698,36 @@ export async function wuRepairTool(input: unknown): Promise<ToolOutput> {
   return executeLifecycleTool(LIFECYCLE_TOOLS.WU_REPAIR, args);
 }
 
+/**
+ * WU-2833 (INIT-062 WU-G): privileged wu:repair variant registered as a
+ * distinct pack tool (wu:repair:admin) so cloud-team phone UX can expose
+ * admin recovery behind a remote_mutation approval gate without widening
+ * the default wu:repair surface. Forces `--admin` on every invocation.
+ */
+export async function wuRepairAdminTool(input: unknown): Promise<ToolOutput> {
+  const parsed = toRecord(input);
+
+  const args: string[] = ['--admin'];
+  const id = toStringValue(parsed.id);
+  if (id) {
+    args.push('--id', id);
+  }
+  if (parsed.check === true) {
+    args.push('--check');
+  }
+  if (parsed.all === true) {
+    args.push('--all');
+  }
+  if (parsed.claim === true) {
+    args.push('--claim');
+  }
+  if (parsed.repair_state === true) {
+    args.push('--repair-state');
+  }
+
+  return executeLifecycleTool(LIFECYCLE_TOOLS.WU_REPAIR, args);
+}
+
 export async function wuStatusTool(input: unknown): Promise<ToolOutput> {
   const parsed = toRecord(input);
   const id = toStringValue(parsed.id);