@cat-factory/app 0.217.2 → 0.218.0

package/app/components/settings/MergeRolePolicyEditor.vue

@@ -0,0 +1,226 @@
+<script setup lang="ts">
+// The ROLE layer of one merge preset: what happens to a run depending on WHO started it.
+//
+// Two settings, edited together because they answer the same question at two strengths. A role can
+// be held to stricter per-class rules than the preset's base map (`classRulesByRole`), or held to
+// dry runs entirely (`dryRunRoles`): the pipeline works and opens its pull request, and nothing
+// merges. The second outranks the first, which is why a sandboxed role says so on its row rather
+// than leaving the class rules below reading as the policy.
+//
+// Composition is NARROW-ONLY, so this editor only offers a role rules STRICTER than the base one
+// (see MergeRolePolicyEditor.logic.ts). A looser rule is discarded by the engine, and an editor
+// that offered it would be reporting a policy that does nothing.
+import { computed, ref } from 'vue'
+import { RULEABLE_CHANGE_CLASSES, WORKSPACE_ROLES } from '@cat-factory/contracts'
+import type {
+  ClassRulesByRole,
+  DryRunRoles,
+  MergeClassRule,
+  MergeClassRules,
+  RuleableChangeClass,
+  WorkspaceRole,
+} from '~/types/merge'
+import {
+  INHERIT_RULE,
+  roleClassRuleRows,
+  roleNarrowedCount,
+  setRoleClassRule,
+  toggleDryRunRole,
+  type RoleRuleSelection,
+} from '~/components/settings/MergeRolePolicyEditor.logic'
+
+const props = defineProps<{
+  /** The preset's per-role narrowing map; a role with no entry is exactly the base rules. */
+  classRulesByRole: ClassRulesByRole
+  /** The roles whose runs this preset sandboxes. */
+  dryRunRoles: DryRunRoles
+  /** The base rules the role layer narrows, so each row can show what it inherits. */
+  classRules: MergeClassRules
+  /**
+   * Whether the preset auto-merges at all. With the master switch off, every pull request already
+   * waits for a human, so a role's per-class narrowing has nothing left to subtract. The SANDBOX
+   * still does: it refuses the MANUAL merge too, which is the one thing the master switch leaves
+   * open. The two halves of this editor therefore stop being equally meaningful, and saying so is
+   * what keeps the inert half from reading as a policy that is doing something.
+   */
+  autoMergeEnabled: boolean
+  disabled?: boolean
+}>()
+
+const emit = defineEmits<{
+  'update:classRulesByRole': [ClassRulesByRole]
+  'update:dryRunRoles': [DryRunRoles]
+}>()
+
+const { t } = useI18n()
+
+// Role + class + rule labels. Exhaustive Records keyed off the contract unions (a new member fails
+// the typecheck) holding LITERAL catalog keys so the typed-message-key check sees them. The role
+// names are the roster's, so the two surfaces name a tier identically.
+const ROLE_LABEL_KEYS: Record<WorkspaceRole, string> = {
+  admin: 'layout.workspaceMembers.roles.admin',
+  member: 'layout.workspaceMembers.roles.member',
+  viewer: 'layout.workspaceMembers.roles.viewer',
+}
+const CLASS_LABEL_KEYS: Record<RuleableChangeClass, string> = {
+  docs: 'merge.changeClass.docs',
+  test: 'merge.changeClass.test',
+  dependency: 'merge.changeClass.dependency',
+  config: 'merge.changeClass.config',
+  source: 'merge.changeClass.source',
+  schema: 'merge.changeClass.schema',
+}
+const RULE_LABEL_KEYS: Record<MergeClassRule, string> = {
+  thresholds: 'settings.riskPolicy.classRules.rule.thresholds',
+  always: 'settings.riskPolicy.classRules.rule.always',
+  never: 'settings.riskPolicy.classRules.rule.never',
+}
+
+/** Which role groups are expanded. Collapsed by default: most presets narrow nothing. */
+const expanded = ref<Partial<Record<WorkspaceRole, boolean>>>({})
+function toggleExpanded(role: WorkspaceRole) {
+  expanded.value = { ...expanded.value, [role]: !expanded.value[role] }
+}
+
+const roles = computed(() =>
+  WORKSPACE_ROLES.map((role) => {
+    const entry: MergeClassRules | undefined = props.classRulesByRole[role]
+    const narrowed = roleNarrowedCount(entry)
+    return {
+      role,
+      label: t(ROLE_LABEL_KEYS[role]),
+      sandboxed: props.dryRunRoles.includes(role),
+      narrowed,
+      open: !!expanded.value[role],
+      rows: roleClassRuleRows(props.classRules, entry).map((row) => ({
+        ...row,
+        label: t(CLASS_LABEL_KEYS[row.changeClass]),
+        // The stored rule first (it may be one a later base edit made redundant), then whatever
+        // still narrows. "Same as policy" is the absent state and always leads.
+        items: [
+          { value: INHERIT_RULE, label: t('settings.riskPolicy.roleRules.inherit') },
+          ...row.options.map((rule) => ({ value: rule, label: t(RULE_LABEL_KEYS[rule]) })),
+        ],
+      })),
+    }
+  }),
+)
+
+/** How many classes carry a base rule stricter than nothing, for the "narrows nothing" hint. */
+const anyBaseRule = computed(() =>
+  RULEABLE_CHANGE_CLASSES.some((changeClass) => !!props.classRules[changeClass]),
+)
+
+function setSandboxed(role: WorkspaceRole, sandboxed: boolean) {
+  emit('update:dryRunRoles', toggleDryRunRole(props.dryRunRoles, role, sandboxed))
+}
+
+function setRule(role: WorkspaceRole, changeClass: RuleableChangeClass, rule: RoleRuleSelection) {
+  emit('update:classRulesByRole', setRoleClassRule(props.classRulesByRole, role, changeClass, rule))
+}
+</script>
+
+<template>
+  <div data-testid="merge-role-policy" class="space-y-2">
+    <div>
+      <span class="block text-[10px] uppercase tracking-wide text-slate-500">
+        {{ t('settings.riskPolicy.roleRules.heading') }}
+      </span>
+      <p class="mt-0.5 text-[11px] leading-snug text-slate-500">
+        {{ t('settings.riskPolicy.roleRules.help') }}
+      </p>
+      <!-- Auto-merge off already sends every pull request to a human, so only the sandbox half of
+           this editor still changes anything (it refuses the manual merge as well). -->
+      <p
+        v-if="!autoMergeEnabled"
+        class="mt-1 text-[11px] leading-snug text-amber-400/90"
+        data-testid="merge-role-auto-merge-off"
+      >
+        {{ t('settings.riskPolicy.roleRules.autoMergeOffWarning') }}
+      </p>
+    </div>
+
+    <div
+      v-for="group in roles"
+      :key="group.role"
+      class="rounded-md border border-slate-700/50 bg-slate-900/30 px-2 py-1.5"
+      :data-testid="`merge-role-group-${group.role}`"
+    >
+      <div class="flex flex-wrap items-center gap-2">
+        <span class="min-w-[5rem] text-xs text-slate-300">{{ group.label }}</span>
+        <USwitch
+          :model-value="group.sandboxed"
+          size="sm"
+          :disabled="disabled"
+          :label="t('settings.riskPolicy.roleRules.sandboxLabel')"
+          :data-testid="`merge-role-sandbox-${group.role}`"
+          @update:model-value="setSandboxed(group.role, $event)"
+        />
+        <UButton
+          color="neutral"
+          variant="ghost"
+          size="xs"
+          :icon="group.open ? 'i-lucide-chevron-down' : 'i-lucide-chevron-right'"
+          :data-testid="`merge-role-expand-${group.role}`"
+          @click="toggleExpanded(group.role)"
+        >
+          {{
+            group.narrowed === 0
+              ? t('settings.riskPolicy.roleRules.noRules')
+              : t(
+                  'settings.riskPolicy.roleRules.ruleCount',
+                  { count: group.narrowed },
+                  group.narrowed,
+                )
+          }}
+        </UButton>
+      </div>
+
+      <!-- A sandboxed role merges nothing at all, so the class rules below cannot make its runs
+           any stricter. They stay editable (removing the sandbox brings them straight back) and
+           the row says which of the two is actually governing. -->
+      <p
+        v-if="group.sandboxed"
+        class="mt-1 text-[11px] leading-snug text-amber-400/90"
+        :data-testid="`merge-role-sandbox-note-${group.role}`"
+      >
+        {{ t('settings.riskPolicy.roleRules.sandboxNote') }}
+      </p>
+
+      <div v-if="group.open" class="mt-2 space-y-1.5 border-t border-slate-800 pt-2">
+        <p v-if="!anyBaseRule" class="text-[11px] leading-snug text-slate-500">
+          {{ t('settings.riskPolicy.roleRules.baseHint') }}
+        </p>
+        <div
+          v-for="row in group.rows"
+          :key="row.changeClass"
+          class="flex flex-wrap items-center gap-2"
+          :data-testid="`merge-role-row-${group.role}-${row.changeClass}`"
+        >
+          <span class="min-w-[7rem] text-xs text-slate-400">{{ row.label }}</span>
+          <USelect
+            :model-value="row.selected"
+            :items="row.items"
+            value-key="value"
+            size="sm"
+            class="w-52"
+            :disabled="disabled || row.items.length === 1"
+            :data-testid="`merge-role-rule-${group.role}-${row.changeClass}`"
+            @update:model-value="setRule(group.role, row.changeClass, $event as RoleRuleSelection)"
+          />
+          <!-- Nothing left to narrow: the base rule already routes this class to a human. -->
+          <span v-if="row.items.length === 1" class="text-[11px] text-slate-500">
+            {{ t('settings.riskPolicy.roleRules.alreadyStrictest') }}
+          </span>
+          <span
+            v-else-if="row.redundant"
+            class="text-[11px] text-amber-400/90"
+            :data-testid="`merge-role-redundant-${group.role}-${row.changeClass}`"
+          >
+            {{ t('settings.riskPolicy.roleRules.redundant') }}
+          </span>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>

package/app/components/settings/RiskPolicyPanel.vue

@@ -5,7 +5,13 @@
 // task inspector's "Merge policy" dropdown selects from. Exactly one preset is the
 // default; it cannot be deleted or un-defaulted (the backend enforces this too).
 import { computed, reactive, ref, watch } from 'vue'
-import type { MergeClassRules, RiskPolicy, RequirementConcernLevel } from '~/types/merge'
+import type {
+  ClassRulesByRole,
+  DryRunRoles,
+  MergeClassRules,
+  RiskPolicy,
+  RequirementConcernLevel,
+} from '~/types/merge'
 import type { StepGating } from '@cat-factory/contracts'
 import {
   RISK_POLICY_AXES,
@@ -13,6 +19,7 @@ import {
   type RiskPolicyAxis,
 } from '~/utils/riskPolicy'
 import MergeClassRulesEditor from '~/components/settings/MergeClassRulesEditor.vue'
+import MergeRolePolicyEditor from '~/components/settings/MergeRolePolicyEditor.vue'
 
 const { t } = useI18n()
 
@@ -78,6 +85,11 @@ interface Draft {
   // Per-change-class auto-merge rules. An OMITTED class means "use the score ceilings above",
   // so `{}` is the identity — the editor stores `thresholds` as an omission for that reason.
   classRules: MergeClassRules
+  // The ROLE layer over those rules: per-role narrowing (narrow-only, so `{}` is the identity)
+  // and the roles whose runs are sandboxed. Both replace the stored value wholesale on save,
+  // which is why clearing one in the editor is a plain omission.
+  classRulesByRole: ClassRulesByRole
+  dryRunRoles: DryRunRoles
   // Implementation-fork decision gating (edited 0..100, stored 0..1); disabled ⇒ off in `auto`.
   forkEnabled: boolean
   forkMinComplexity: number
@@ -115,6 +127,8 @@ function toDraft(p: RiskPolicy): Draft {
     maxRequirementConcernAllowed: p.maxRequirementConcernAllowed,
     autoMergeEnabled: p.autoMergeEnabled,
     classRules: { ...p.classRules },
+    classRulesByRole: { ...p.classRulesByRole },
+    dryRunRoles: [...p.dryRunRoles],
     forkEnabled: p.forkDecision?.enabled ?? false,
     forkMinComplexity: Math.round((p.forkDecision?.minComplexity ?? 0.5) * 100),
     forkMinRisk: Math.round((p.forkDecision?.minRisk ?? 0.4) * 100),
@@ -158,6 +172,8 @@ async function save(p: RiskPolicy) {
       maxRequirementConcernAllowed: d.maxRequirementConcernAllowed,
       autoMergeEnabled: d.autoMergeEnabled,
       classRules: d.classRules,
+      classRulesByRole: d.classRulesByRole,
+      dryRunRoles: d.dryRunRoles,
       forkDecision: forkGating(d),
     })
     toast.add({
@@ -213,7 +229,12 @@ const draft = reactive<Draft>({
   maxRequirementIterations: 6,
   maxRequirementConcernAllowed: 'none',
   autoMergeEnabled: true,
+  // The create row authors the numbers only. Class and role rules start at their identity and
+  // are edited on the saved preset, where each rule can be shown beside the base rule (and the
+  // track record) it narrows — neither reads as anything on a policy that does not exist yet.
   classRules: {},
+  classRulesByRole: {},
+  dryRunRoles: [],
   forkEnabled: false,
   forkMinComplexity: 50,
   forkMinRisk: 40,
@@ -367,6 +388,19 @@ async function create() {
         />
       </div>
 
+      <!-- The role layer over those rules: what a run may do depending on WHO started it, up to
+           and including a full sandbox. Directly under the base rules it narrows, since a role
+           rule is only readable against the rule it applies to. -->
+      <div class="mt-3 rounded-md border border-slate-800 bg-slate-900/40 p-3">
+        <MergeRolePolicyEditor
+          v-model:class-rules-by-role="drafts[p.id]!.classRulesByRole"
+          v-model:dry-run-roles="drafts[p.id]!.dryRunRoles"
+          :class-rules="drafts[p.id]!.classRules"
+          :auto-merge-enabled="drafts[p.id]!.autoMergeEnabled"
+          :disabled="busy === p.id"
+        />
+      </div>
+
       <!-- Implementation-fork decision gate: propose materially different approaches before the
            Coder writes code (in `auto` tri-state, gated on the task estimate). -->
       <div class="mt-3 rounded-md border border-slate-800 bg-slate-900/40 p-3">

package/app/composables/useRunStart.spec.ts

@@ -0,0 +1,204 @@
+import { describe, expect, it, vi } from 'vitest'
+import { nextTick, ref, type Ref } from 'vue'
+import type { Block, Pipeline } from '~/types/domain'
+import type { RiskPolicy, WorkspaceRole } from '~/types/merge'
+import { useBoardStore } from '~/stores/board'
+import { useExecutionStore } from '~/stores/execution'
+import { useRiskPoliciesStore } from '~/stores/riskPolicies'
+import { useUiModeStore } from '~/stores/uiMode'
+import { useDryRunPolicy, useRunStart } from '~/composables/useRunStart'
+
+// `useRunStart` resolves the mode a start will run in from two independent facts: what the user
+// asked for, and whether the task's merge preset sandboxes their role. The stores are real (a
+// fresh Pinia per test); only the caller's resolved RBAC role and the store's start command are
+// stubbed, since neither an HTTP call nor an auth gate is what these assertions are about.
+const pipeline = { id: 'pl_build', name: 'Build' } as Pipeline
+
+const preset = (over: Partial<RiskPolicy> = {}): RiskPolicy =>
+  ({
+    id: 'mp_balanced',
+    name: 'Balanced',
+    maxComplexity: 0.6,
+    maxRisk: 0.4,
+    maxImpact: 0.5,
+    ciMaxAttempts: 10,
+    maxRequirementIterations: 6,
+    maxRequirementConcernAllowed: 'none',
+    maxTesterQualityIterations: 3,
+    releaseWatchWindowMinutes: 30,
+    releaseMaxAttempts: 1,
+    humanReviewGraceMinutes: 10,
+    judgeMinScore: 0.7,
+    judgeMaxBounces: 2,
+    autoMergeEnabled: true,
+    classRules: {},
+    classRulesByRole: {},
+    dryRunRoles: [],
+    isDefault: true,
+    createdAt: 0,
+    ...over,
+  }) as RiskPolicy
+
+/**
+ * Seed a board governed by `policy`, signed in as `role`, and hand back the composable.
+ *
+ * `b1` is the task under test. `b2` is a second one carrying its own preset, so a test can move
+ * the id the composable is bound to: that is what the inspector does, being mounted once for the
+ * session and following the board selection rather than being rebuilt per block.
+ */
+function setup(options: {
+  role: WorkspaceRole | null
+  policy?: RiskPolicy
+  otherPolicy?: RiskPolicy
+  advanced?: boolean
+}) {
+  const start = vi.fn().mockResolvedValue(true)
+  vi.stubGlobal('useWorkspaceAccess', () => ({ role: { value: options.role } }))
+  useBoardStore().blocks = [
+    { id: 'b1', level: 'task', title: 'Task' } as Block,
+    { id: 'b2', level: 'task', title: 'Other task', riskPolicyId: 'mp_other' } as Block,
+  ]
+  const other = options.otherPolicy ?? preset({ id: 'mp_other', isDefault: false })
+  useRiskPoliciesStore().hydrate([options.policy ?? preset(), other])
+  useUiModeStore().setMode(options.advanced === false ? 'basic' : 'advanced')
+  useExecutionStore().start = start
+  const blockId: Ref<string | undefined> = ref('b1')
+  return { run: useRunStart(blockId), start, blockId }
+}
+
+describe('useRunStart', () => {
+  it('starts live by default, sending no mode at all', async () => {
+    const { run, start } = setup({ role: 'member' })
+    expect(run.dryRun.value).toBe(false)
+    await run.start(pipeline)
+    expect(start).toHaveBeenCalledWith('b1', pipeline, { mode: undefined })
+  })
+
+  it('sends the request when the initiator asks for a sandbox', async () => {
+    const { run, start } = setup({ role: 'member' })
+    run.setRequested(true)
+    expect(run.dryRun.value).toBe(true)
+    await run.start(pipeline)
+    expect(start).toHaveBeenCalledWith('b1', pipeline, { mode: 'dry_run' })
+  })
+
+  it('clears the request once it has been spent, so the next run is live again', async () => {
+    const { run } = setup({ role: 'member' })
+    run.setRequested(true)
+    await run.start(pipeline)
+    expect(run.requested.value).toBe(false)
+  })
+
+  it('reports a policy sandbox and offers nothing to ask for', () => {
+    const { run } = setup({ role: 'member', policy: preset({ dryRunRoles: ['member'] }) })
+    expect(run.forced.value).toBe(true)
+    expect(run.dryRun.value).toBe(true)
+    expect(run.canRequest.value).toBe(false)
+  })
+
+  // The engine reads the preset itself and reports the sandbox as policy rather than as a
+  // request, which is what lets the run explain a sandbox its initiator never chose. Re-sending
+  // it from here would file it under "they asked for this".
+  it('sends no mode for a policy sandbox: the engine settles that, not the caller', async () => {
+    const { run, start } = setup({ role: 'member', policy: preset({ dryRunRoles: ['member'] }) })
+    await run.start(pipeline)
+    expect(start).toHaveBeenCalledWith('b1', pipeline, { mode: undefined })
+  })
+
+  it('leaves a role the preset does not list alone', () => {
+    const { run } = setup({ role: 'admin', policy: preset({ dryRunRoles: ['member'] }) })
+    expect(run.forced.value).toBe(false)
+    expect(run.canRequest.value).toBe(true)
+  })
+
+  // Auth-disabled dev resolves no role, so no entry can match. Reading absence as a tier would
+  // sandbox every run on a deployment that runs with auth off.
+  it('never force-sandboxes a caller with no resolved role', () => {
+    const { run } = setup({
+      role: null,
+      policy: preset({ dryRunRoles: ['admin', 'member', 'viewer'] }),
+    })
+    expect(run.forced.value).toBe(false)
+  })
+
+  // The request is an override of the default a basic-tier user would otherwise have got, and
+  // hiding it leaves exactly that default. A policy sandbox is not an override, so it is not
+  // subject to the tier at all.
+  it('offers the request only on the advanced tier, and states a sandbox on both', () => {
+    expect(setup({ role: 'member', advanced: false }).run.canRequest.value).toBe(false)
+    const basicForced = setup({
+      role: 'member',
+      advanced: false,
+      policy: preset({ dryRunRoles: ['member'] }),
+    })
+    expect(basicForced.run.forced.value).toBe(true)
+    expect(basicForced.run.dryRun.value).toBe(true)
+  })
+
+  it('falls back to the workspace default preset for a task that picks none', () => {
+    const { run } = setup({ role: 'member', policy: preset({ dryRunRoles: ['member'] }) })
+    expect(run.preset.value?.id).toBe('mp_balanced')
+    expect(run.forced.value).toBe(true)
+  })
+
+  // The request belongs to the block it was made on, and the surface holding it outlives that
+  // block: the inspector is mounted once and follows the board selection. Carrying the request
+  // across would sandbox the NEXT run started, on a task nobody armed it for, with the Run
+  // button's icon the only tell and reading as a property of the task now shown.
+  it('drops a pending request when the block changes under it', async () => {
+    const { run, blockId, start } = setup({ role: 'member' })
+    run.setRequested(true)
+    expect(run.dryRun.value).toBe(true)
+
+    blockId.value = 'b2'
+    await nextTick()
+
+    expect(run.requested.value).toBe(false)
+    expect(run.dryRun.value).toBe(false)
+    await run.start(pipeline)
+    expect(start).toHaveBeenCalledWith('b2', pipeline, { mode: undefined })
+  })
+
+  // The other half of following the selection: the policy read is per BLOCK, so moving to a task
+  // governed by a sandboxing preset must report the sandbox rather than the previous task's.
+  it('re-reads the policy for the block it is now bound to', async () => {
+    const { run, blockId } = setup({
+      role: 'member',
+      otherPolicy: preset({ id: 'mp_other', isDefault: false, dryRunRoles: ['member'] }),
+    })
+    expect(run.forced.value).toBe(false)
+
+    blockId.value = 'b2'
+    await nextTick()
+
+    expect(run.forced.value).toBe(true)
+    expect(run.canRequest.value).toBe(false)
+  })
+})
+
+// The board's one-tap start and its drag-drop start resolve a task at the moment of the action
+// and have no block to bind a composable to, so they read the policy through the same functions
+// `useRunStart` wraps. Sharing them is what keeps a sandbox from being visible on one start
+// surface and silent on another.
+describe('useDryRunPolicy', () => {
+  it('answers per block, for a target resolved at the moment of the start', () => {
+    setup({
+      role: 'member',
+      otherPolicy: preset({ id: 'mp_other', isDefault: false, dryRunRoles: ['member'] }),
+    })
+    const { forcedFor, presetFor } = useDryRunPolicy()
+    expect(forcedFor('b1')).toBe(false)
+    expect(forcedFor('b2')).toBe(true)
+    expect(presetFor('b2')?.id).toBe('mp_other')
+  })
+
+  // A block with no preset of its own is governed by the workspace default, and so is one the
+  // board cannot resolve: the same fallback the engine makes, rather than reading an unresolved
+  // block as unsandboxed, which would state the safer-looking answer without knowing it.
+  it('falls back to the workspace default for a block carrying no preset', () => {
+    setup({ role: 'member', policy: preset({ dryRunRoles: ['member'] }) })
+    const { forcedFor } = useDryRunPolicy()
+    expect(forcedFor('b1')).toBe(true)
+    expect(forcedFor(undefined)).toBe(true)
+  })
+})

package/app/composables/useRunStart.ts

@@ -0,0 +1,112 @@
+import { computed, ref, toValue, watch, type MaybeRefOrGetter } from 'vue'
+import { dryRunForcedForRole, type RunMode } from '@cat-factory/contracts'
+import type { Pipeline, RiskPolicy } from '~/types/domain'
+import { useBoardStore } from '~/stores/board'
+import { useExecutionStore } from '~/stores/execution'
+import { useRiskPoliciesStore } from '~/stores/riskPolicies'
+import { useUiModeStore } from '~/stores/uiMode'
+
+/**
+ * Whether this deployment's merge policy sandboxes the signed-in user's runs on a given block:
+ * the pipeline works and opens its pull request, and nothing merges.
+ *
+ * Exposed as FUNCTIONS of a block id rather than as computeds over one, because the start
+ * surfaces ask the question in two shapes and both must get the same answer. A control bound to
+ * a block (the inspector's Run menu, the focus view's picker) asks about that block and re-asks
+ * when the selection moves; the board's drop handler resolves its target at the moment of the
+ * drop and has no block to bind to. {@link useRunStart} wraps these for the first shape.
+ *
+ * `dryRunForcedForRole` is the contracts rule the engine applies at admission, not a restated
+ * `includes`: reading the role's absence (auth-disabled dev, where the SPA resolves no role) is
+ * the part that has to agree, since guessing a tier there would sandbox a whole deployment.
+ */
+export function useDryRunPolicy() {
+  const board = useBoardStore()
+  const riskPolicies = useRiskPoliciesStore()
+  const access = useWorkspaceAccess()
+
+  /**
+   * The preset that governs this task's merge decision: its own, else the workspace default
+   * (the same resolution the engine makes, via the store).
+   */
+  function presetFor(blockId: string | undefined): RiskPolicy | null {
+    return riskPolicies.resolve(board.getBlock(blockId ?? '')?.riskPolicyId)
+  }
+
+  /** That preset sandboxes runs started by the signed-in user's role, whatever they ask for. */
+  function forcedFor(blockId: string | undefined): boolean {
+    return dryRunForcedForRole(presetFor(blockId)?.dryRunRoles, access.role.value)
+  }
+
+  return { presetFor, forcedFor }
+}
+
+/**
+ * The run-mode half of starting a run, shared by every surface that offers a pipeline to start
+ * (the inspector's Run menu, the focus view's picker) so the three facts below cannot drift into
+ * two answers on two surfaces.
+ *
+ * A run is either live or a SANDBOX (`dry_run`): the pipeline works and opens its pull request,
+ * and nothing merges, at either exit. Two things can put it there, and they are not the same
+ * thing to a person reading the control:
+ *
+ *  - **A request.** The initiator asked for a sandbox on this run. An override of the default,
+ *    unset until asked for and never persisted, so it is `advanced`-tier: hiding it leaves
+ *    exactly the live run a basic-tier user would otherwise have started.
+ *  - **The task's merge preset.** It sandboxes the roles it lists (`dryRunRoles`), and a run
+ *    cannot ask its way out of that, which is the whole point of the setting. So it is stated
+ *    in BOTH tiers, and it REPLACES the request control rather than sitting beside it: a toggle
+ *    over a decision already made would be the concealed-setting failure in reverse.
+ */
+export function useRunStart(blockId: MaybeRefOrGetter<string | undefined>) {
+  const execution = useExecutionStore()
+  const uiMode = useUiModeStore()
+  const policy = useDryRunPolicy()
+
+  /** The caller's own explicit ask for THIS block. */
+  const requested = ref(false)
+
+  const preset = computed(() => policy.presetFor(toValue(blockId)))
+
+  /** This preset sandboxes runs started by the signed-in user's role, whatever they ask for. */
+  const forced = computed(() => policy.forcedFor(toValue(blockId)))
+
+  /** Whether to offer the request control at all: nothing to ask for once policy decided it. */
+  const canRequest = computed(() => uiMode.isAdvanced && !forced.value)
+
+  /** What the run WILL be, for a control that describes the start it is about to make. */
+  const dryRun = computed(() => forced.value || requested.value)
+
+  // The request belongs to the block it was made on, and the surfaces holding it OUTLIVE that
+  // block: the inspector is mounted once for the whole session and follows the board selection.
+  // Without this, arming a sandbox on one task and then selecting another silently sandboxes the
+  // next run started, on a task nobody asked it for. The button's icon is the only tell, and it
+  // reads as a property of the task now shown.
+  watch(
+    () => toValue(blockId),
+    () => {
+      requested.value = false
+    },
+  )
+
+  function setRequested(value: boolean) {
+    requested.value = value
+  }
+
+  /**
+   * Start `pipeline` on this block. Only an EXPLICIT request travels: a forced sandbox is the
+   * server's own reading of the preset, and re-sending it as a request would file the run's mode
+   * under "the initiator asked for this" when they did not, costing the run the advisory that
+   * explains a sandbox nobody chose.
+   */
+  async function start(pipeline: Pipeline): Promise<boolean> {
+    const id = toValue(blockId)
+    if (!id) return false
+    const mode: RunMode | undefined = requested.value ? 'dry_run' : undefined
+    const started = await execution.start(id, pipeline, { mode })
+    if (started) requested.value = false
+    return started
+  }
+
+  return { preset, forced, canRequest, dryRun, requested, setRequested, start }
+}

package/app/stores/execution/commands.ts

@@ -1,6 +1,6 @@
 import type { Ref } from 'vue'
 import type { ExecutionInstance, Pipeline } from '~/types/domain'
-import type { RequestStepChangesInput } from '@cat-factory/contracts'
+import type { RequestStepChangesInput, RunMode } from '@cat-factory/contracts'
 import type { IterationCapChoice } from '~/types/execution'
 import type { ReviewEffort } from '~/types/merge'
 import { useWorkspaceStore } from '~/stores/workspace'
@@ -36,8 +36,17 @@ export function createExecutionCommands(ctx: ExecutionCommandContext) {
    * pinned to an individual-usage model (Claude) needs the initiator's personal
    * password — supplied transparently from the local cache, and prompted via the
    * credential modal (then retried) when the server replies 428.
+   *
+   * `mode: 'dry_run'` REQUESTS a sandboxed run: the pipeline works and opens its pull request,
+   * and nothing merges. It is a request, not a decision — the task's merge preset can sandbox a
+   * role's runs whatever they asked for, so what the run got is read back off the run's own
+   * `mode`, never assumed from what was sent here.
    */
-  async function start(blockId: string, pipeline: Pipeline): Promise<boolean> {
+  async function start(
+    blockId: string,
+    pipeline: Pipeline,
+    options?: { mode?: RunMode },
+  ): Promise<boolean> {
     const ws = useWorkspaceStore()
     const personal = usePersonalSubscriptionsStore()
     // Returns false when the user cancels the personal-password prompt OR the start was
@@ -45,7 +54,15 @@ export function createExecutionCommands(ctx: ExecutionCommandContext) {
     // caller can revert its "Starting…" state without its own error handling.
     try {
       return await personal.withCredential(async (password) => {
-        await api.startExecution(ws.requireId(), blockId, { pipelineId: pipeline.id }, password)
+        await api.startExecution(
+          ws.requireId(),
+          blockId,
+          // Omitted rather than `mode: 'live'` for an ordinary start: `live` is what the absent
+          // field already means, and asking for it explicitly would read as a request to opt OUT
+          // of a policy sandbox, which is not something a start may do.
+          { pipelineId: pipeline.id, ...(options?.mode ? { mode: options.mode } : {}) },
+          password,
+        )
         await ws.refresh()
       })
     } catch (e) {