@cat-factory/app 0.215.2 → 0.216.0

package/README.md

@@ -18,6 +18,9 @@ The SPA source lives under `app/` (the Nuxt srcDir).
 - [Interface modes (basic / advanced)](#interface-modes-basic--advanced)
 - [Agent tiers (basic / intermediate / advanced)](#agent-tiers-basic--intermediate--advanced)
 - [In-app tutorial tours](#in-app-tutorial-tours)
+- [Real-time store coherence](#real-time-store-coherence-avoid-the-full-refresh-clobber)
+- [Internationalization (i18n) authoring](#internationalization-i18n-authoring)
+- [Extending the layer (consumer modules)](#extending-the-layer-consumer-modules)
 - [Key UI surfaces](#key-ui-surfaces)
 - [Develop & test](#develop--test)
 
@@ -329,7 +332,7 @@ is SUPPRESSED rather than unmounted, because it holds the running tour's resolve
 remount would re-resolve it against gates that may have flipped since the tour started.
 
 The decisions behind this surface, and why each alternative was rejected, are recorded in
-[ADR 0033](../../backend/docs/adr/0033-in-app-tutorials.md). This section is the authority on how
+[ADR 0036](../../backend/docs/adr/0036-in-app-tutorials.md). This section is the authority on how
 the thing WORKS.
 
 A tour is **data, not components**: an ordered list of steps, each pointing at an on-screen
@@ -511,6 +514,111 @@ guard scans the layer for both ways an id is named: written onto an element, or
 `testId` field on a data contribution (the whole `nav-*` family reaches the DOM that way). It
 is scoped to the built-in catalog, since a consumer's tours anchor on its own layer.
 
+## Real-time store coherence: avoid the full-refresh CLOBBER
+
+The recurring product bug behind most e2e flakes: a stale full-snapshot refresh clobbering newer
+live state. The SPA has two delivery shapes and mixing them wrong drops live-added state with NO
+event left to restore it.
+
+- **Know how your entity is delivered.** A `board` event is COARSE: no payload, only a debounced
+  full `workspace.refresh()`, and `hydrate` REPLACES whole lists. A spawned task/module block
+  reaches the browser ONLY this way. Targeted events (`execution`/`bootstrap`/`initiative`) carry
+  the entity and `upsert` it, so they don't clobber. Prefer a targeted upsert for anything that
+  must appear reliably.
+- **Full refreshes MUST be monotonic.** Two `refresh()` calls can be in flight; a staler one
+  resolving later overwrites the newer. `workspace.refresh()` guards this with a sequence. Do not
+  reintroduce an unguarded `hydrate(await fetch())`, and apply the guard to any new coalesced
+  refresh path.
+- **Never gate readiness on a snapshot a later resync can undo.** The on-connect resync flips
+  `connected` only after it settles (which is why e2e gates on `data-connected`).
+- **A REPLACE-style `hydrate` must never silently drop live-only state.** Either fold that state
+  into the snapshot or reconcile rather than replace.
+- **An action's OPTIMISTIC ECHO is a clobber too, and it bypasses both guards above.** A store
+  that awaits a mutation and then assigns the returned sub-state onto the cached run
+  (`step.forkDecision`, `step.prReview`, `step.judge`, `step.followUps`) is writing straight past
+  `upsert`'s `rev` check. Where the mutation WAKES THE DRIVER, the driver's next emit routinely
+  beats the HTTP response, so the echo puts the run back; if the run then parks, nothing emits
+  again and the newer state is gone for good (the fork-chat reply that vanished, leaving a
+  "thinking…" bubble spinning). Every echo therefore goes through
+  `execution.echoAfter(executionId, send, apply)`, which captures the run's `rev` before the
+  request and drops the echo if anything advanced it. Never hand-roll the await-then-assign.
+- **Pin it with a store-level unit test** (`stores/workspace.spec.ts` for refreshes,
+  `stores/execution.spec.ts` for echoes): drive the two orderings and assert the fresher one
+  wins.
+
+## Internationalization (i18n) authoring
+
+All user-facing SPA copy goes through `@nuxtjs/i18n`; never hard-code a display string. This
+layer ships the base `en` locale, and a downstream deployment overrides by dropping its own files
+(the per-layer deep-merge is the override seam, consumer wins key by key). Migration status:
+[`docs/localization.md`](../../docs/localization.md).
+
+- `i18n/locales/<locale>.json`: the catalogs (the v9+ `i18n/` convention, NOT `app/locales/`).
+- `i18n/i18n.config.ts`: runtime vue-i18n behaviour only (fallback locale, the named
+  `numberFormats`/`datetimeFormats`). Messages are deliberately NOT here so the module can
+  deep-merge across the `extends` chain. Referenced as the BARE filename
+  `vueI18n: 'i18n.config.ts'`, never `layerDir`-anchored.
+- `package.json` `files` MUST include `"i18n"`. Release-blocking.
+
+**Adding a string**: add the key to `en.json` under the feature namespace, resolve with
+`t('feature.area.key')`, and format numbers/dates through `$n`/`$d` (the named formats), never
+raw `Intl`.
+
+**Key conventions**: one namespace per feature; **leaf keys mirror the enum/code value verbatim**
+so a dynamic lookup is total; **no cross-key concatenation** (a full sentence is ONE key with
+`{named}` placeholders, plurals use the pipe form).
+
+**Component mechanics that bite:**
+
+- `useI18n` is auto-imported; destructure in `<script setup>` and use those fns in the template
+  so the typed-key check sees literal keys. Never `import` it.
+- Plural + interpolation: `t(key, { vendor, count }, count)`, where the THIRD arg is the choice.
+- **Code/format-example placeholders stay INLINE**, not in the catalog; required when they
+  contain `{`/`}` (vue-i18n metacharacters). Only prose placeholders get a key. Same for brand
+  names.
+- **No HTML in message bodies**: drop mid-sentence `<strong>`, or use `<i18n-t>` with slots.
+- For a vendor/enum-keyed set, build an array of STATIC literal `t()` keys, one per member.
+  Reserve the runtime-assembled key + exhaustive `Record` guard for lookups genuinely unknown
+  until runtime.
+- Straight quotes, no em-dashes in new entries.
+
+**Translator descriptions (`@<key>` siblings): default to NONE.** They live only in `en.json` and
+are notes to a translator, never runtime data. Add one ONLY when a competent translator seeing
+the English and the key path could plausibly get it wrong: homograph / part-of-speech ambiguity
+(`@close`), proper nouns that must NOT be translated (`@kaizen`), umbrella strings hiding cases
+the text doesn't show, placeholder/format constraints, or plural-form requirements beyond
+English's two.
+
+**Presenting a backend failure**: raw backend prose is DETAIL, never the description. Even with
+no `reason` to key off, a failure is described from its STATUS CLASS through an exhaustive
+`Record<ApiErrorCode, …>` of translated copy, and the untranslated `message` (plus a validation
+400's `issues` and the envelope's `requestId`) is reached through a "Show details" disclosure
+that reveals it in place. So a non-English user is never handed English as the primary
+explanation, and the elaborate operator remedies the backend does write stay one click away
+rather than being dropped. A new failure-presenting surface copies that split (the
+`usePipelineErrorToast.ts` pattern; the wire vocabulary comes from `@cat-factory/contracts`).
+
+**Drift guards** (oxlint has no `no-raw-text` rule, so these replace it):
+
+1. **Typed message keys** make a statically written unknown `t('literal.key')` a typecheck
+   failure. This does NOT cover a runtime-assembled key.
+2. For enum→key lookups, guard with an **exhaustive `Record<TheEnum, string>`** keyed off the
+   contracts union, plus a runtime `te()` fallback. Never rely on tier 1 alone for a
+   reason/status-keyed lookup.
+3. `pnpm --filter @cat-factory/app run i18n:check` hard-fails on MISSING keys and reports unused
+   ones as non-blocking warnings (the catalog legitimately seeds keys ahead of use).
+4. **Locale parity**: `i18n-locale-parity.mjs --since origin/<base>` requires a PR that adds,
+   changes, or removes an `en.json` key to make the SAME change in every other locale. It is
+   change-coupling against the merge-base, NOT full key parity.
+
+**Translate for real: NEVER ship an English string as a non-`en` value.** The parity gate checks
+only that the key exists, so it will pass a verbatim English copy, and that copy is a bug. The
+only values that may legitimately match `en` are proper nouns identical across languages
+(`DeepSeek`, `AWS Bedrock`). If you genuinely cannot produce a translation, say so in the PR
+rather than committing a placeholder that reads as done.
+
+Migration is incremental: when you touch a component, lift its visible copy into the catalog.
+
 ## Extending the layer (consumer modules)
 
 A deployment can contribute its own components (result windows, nav entries, inspector

package/app/components/inputGate/InputGateNotice.vue

@@ -0,0 +1,176 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import type { InputGateIssue, InputGateIssueCode, RunInputGate } from '@cat-factory/contracts'
+import type { InputGateTone } from '~/utils/inputGate'
+import { useInputGateStore } from '~/stores/inputGate'
+
+// The PRE-TOKEN INPUT GATE's notice: what the structural check found in the task's authored
+// input, and the two ways out. Shown wherever a run parked on the gate is surfaced (the
+// inspector's execution panel, the step-detail overlay), so it is a plain component over a
+// verdict rather than an overlay of its own, its remedy is to go and edit the task, which is a
+// board action a modal would be in the way of.
+//
+// Every line of copy is keyed off the finding CODE, never off backend prose: the backend does
+// not localize, and its `describeInputGateIssues` summary is a detail line for logs.
+
+const props = defineProps<{
+  /** The run's verdict. Which verdicts earn a notice is `inputGateNoticeFor`'s decision. */
+  gate: RunInputGate
+  /**
+   * How to present it (see {@link InputGateTone}). Passed in rather than re-derived from
+   * `gate.status`, because the advisory tone is NOT a status: it is a `passed` verdict that
+   * happens to carry findings, and a component deriving its own tone would have to repeat that
+   * rule and would go on rendering advisories as if the run had been cleared with nothing found.
+   */
+  tone: InputGateTone
+  /** The run this verdict belongs to, for the resolve calls. */
+  executionId: string
+  /** Compact form drops the explanatory paragraph (used inside the step-detail rail). */
+  compact?: boolean
+}>()
+
+const { t, te } = useI18n()
+const inputGate = useInputGateStore()
+
+/**
+ * Finding code → its translated copy, as an EXHAUSTIVE `Record` of LITERAL keys. Two guards in
+ * one: the Record fails to compile when a code is added without copy, and the literal keys are
+ * what the typed-message-key check can see (an assembled `\`inputGate.issue.${code}.title\`` is
+ * invisible to it). The `te` fallback below covers the case neither can, a run PERSISTED under
+ * a code this build has since retired.
+ */
+const ISSUE_KEYS = {
+  description_missing: {
+    title: 'inputGate.issue.description_missing.title',
+    hint: 'inputGate.issue.description_missing.hint',
+  },
+  description_placeholder: {
+    title: 'inputGate.issue.description_placeholder.title',
+    hint: 'inputGate.issue.description_placeholder.hint',
+  },
+  description_thin: {
+    title: 'inputGate.issue.description_thin.title',
+    hint: 'inputGate.issue.description_thin.hint',
+  },
+  reproduction_missing: {
+    title: 'inputGate.issue.reproduction_missing.title',
+    hint: 'inputGate.issue.reproduction_missing.hint',
+  },
+  review_target_missing: {
+    title: 'inputGate.issue.review_target_missing.title',
+    hint: 'inputGate.issue.review_target_missing.hint',
+  },
+  success_criteria_missing: {
+    title: 'inputGate.issue.success_criteria_missing.title',
+    hint: 'inputGate.issue.success_criteria_missing.hint',
+  },
+} as const satisfies Record<InputGateIssueCode, { title: string; hint: string }>
+
+/**
+ * The findings, blocking first. Sorting here rather than trusting the emitted order keeps the
+ * thing a human must fix at the top even when an advisory was found earlier in the check.
+ */
+const issues = computed<InputGateIssue[]>(() =>
+  [...props.gate.issues].sort((a, b) =>
+    a.severity === b.severity ? 0 : a.severity === 'blocking' ? -1 : 1,
+  ),
+)
+
+/** Only a parked verdict has anything to answer; the other two tones are a record. */
+const blocking = computed(() => props.tone === 'blocked')
+
+/** Title + body keys per tone, as literals so the typed-message-key check can see them. */
+const TONE_COPY: Record<InputGateTone, { title: string; body: string }> = {
+  blocked: { title: 'inputGate.blockedTitle', body: 'inputGate.blockedBody' },
+  waived: { title: 'inputGate.waivedTitle', body: 'inputGate.waivedBody' },
+  advisory: { title: 'inputGate.advisoryTitle', body: 'inputGate.advisoryBody' },
+}
+const copy = computed(() => TONE_COPY[props.tone])
+
+/** A finding's translated title, falling back to the generic line for a retired code. */
+function issueTitle(code: InputGateIssueCode): string {
+  const key = ISSUE_KEYS[code]?.title
+  return key && te(key) ? t(key) : t('inputGate.issue.unknown.title')
+}
+
+/** A finding's translated remedy hint, on the same fallback. */
+function issueHint(code: InputGateIssueCode): string {
+  const key = ISSUE_KEYS[code]?.hint
+  return key && te(key) ? t(key) : t('inputGate.issue.unknown.hint')
+}
+
+async function resolve(choice: 'recheck' | 'proceed') {
+  await inputGate.resolve(props.executionId, choice)
+}
+</script>
+
+<template>
+  <div
+    class="rounded-lg border p-3"
+    :class="
+      blocking
+        ? 'border-amber-300 bg-amber-50 dark:border-amber-800 dark:bg-amber-950/40'
+        : 'border-default bg-elevated/40'
+    "
+    :data-tone="tone"
+    data-testid="input-gate-notice"
+  >
+    <div class="flex items-start gap-2">
+      <UIcon
+        :name="blocking ? 'i-lucide-file-question' : 'i-lucide-info'"
+        class="mt-0.5 size-4 shrink-0"
+        :class="blocking ? 'text-amber-600 dark:text-amber-400' : 'text-muted'"
+      />
+      <div class="min-w-0 flex-1">
+        <p class="text-sm font-medium">{{ t(copy.title) }}</p>
+        <p v-if="!compact" class="text-muted mt-0.5 text-xs">{{ t(copy.body) }}</p>
+
+        <ul class="mt-2 space-y-1.5">
+          <li v-for="issue in issues" :key="issue.code" class="flex items-start gap-2 text-xs">
+            <UBadge
+              :color="issue.severity === 'blocking' ? 'warning' : 'neutral'"
+              variant="subtle"
+              size="sm"
+            >
+              {{
+                issue.severity === 'blocking'
+                  ? t('inputGate.severity.blocking')
+                  : t('inputGate.severity.advisory')
+              }}
+            </UBadge>
+            <span class="min-w-0">
+              <span class="font-medium">{{ issueTitle(issue.code) }}</span>
+              <span class="text-muted">, {{ issueHint(issue.code) }}</span>
+            </span>
+          </li>
+        </ul>
+
+        <div v-if="blocking" class="mt-3 flex flex-wrap items-center gap-2">
+          <UButton
+            color="primary"
+            size="xs"
+            icon="i-lucide-refresh-cw"
+            :loading="inputGate.resolving"
+            data-testid="input-gate-recheck"
+            @click="resolve('recheck')"
+          >
+            {{ t('inputGate.recheck') }}
+          </UButton>
+          <UButton
+            color="neutral"
+            variant="ghost"
+            size="xs"
+            :disabled="inputGate.resolving"
+            data-testid="input-gate-proceed"
+            @click="resolve('proceed')"
+          >
+            {{ t('inputGate.proceed') }}
+          </UButton>
+          <span class="text-muted text-xs">{{ t('inputGate.recheckHint') }}</span>
+        </div>
+
+        <p v-if="inputGate.error" class="text-error mt-2 text-xs">{{ inputGate.error }}</p>
+      </div>
+    </div>
+  </div>
+</template>

package/app/components/panels/AgentStepDetail.vue

@@ -20,6 +20,7 @@ import { useStepTimer } from '~/composables/useStepTimer'
 import { useStepProse } from '~/composables/useStepProse'
 import { useStepApproval } from '~/composables/useStepApproval'
 import { dedicatedParkView } from '~/utils/pipelineRender'
+import InputGateNotice from '~/components/inputGate/InputGateNotice.vue'
 
 // Detail overlay for a single pipeline step. Opened by clicking an agent in the
 // inspector list (TaskExecution) or the focus-view pipeline (PipelineProgress) via
@@ -168,7 +169,21 @@ const companionExceeded = computed(() => approvalPending.value && !!step.value?.
 // resolver refuses these server-side, so the rail is replaced by a redirect to that window.
 // Computed live, since a coder step can park on one WHILE this overlay is already open
 // (the routing in `dispatchStepView` only covers the open click).
-const dedicatedPark = computed(() => (step.value ? dedicatedParkView(step.value) : null))
+const dedicatedPark = computed(() =>
+  step.value ? dedicatedParkView(step.value, instance.value) : null,
+)
+/**
+ * The PRE-TOKEN INPUT GATE's verdict when it is what holds this step. Answered INLINE here
+ * (unlike the other dedicated parks, which redirect to a window): its remedy is to edit the
+ * task, so there is no second modal to send anyone to.
+ *
+ * Only the PARK, hence the literal `blocked` tone at the call site: this overlay exists to
+ * answer one step's park, and an advisory finding is about the run rather than this step. It is
+ * reported once, on the run panel, instead of on every step overlay opened under it.
+ */
+const inputGateVerdict = computed(() =>
+  dedicatedPark.value === 'input-gate' ? (instance.value?.inputGate ?? null) : null,
+)
 /** The generic approve/request-changes/reject rail applies (no dedicated surface owns the park). */
 const genericApprovalPending = computed(
   () => approvalPending.value && !companionExceeded.value && !dedicatedPark.value,
@@ -181,7 +196,7 @@ function openDedicatedWindow() {
   if (!c || !park) return
   close()
   if (park === 'follow-ups') ui.openFollowUps(c.instanceId, c.stepIndex)
-  else ui.openForkDecision(c.instanceId, c.stepIndex)
+  else if (park === 'fork-decision') ui.openForkDecision(c.instanceId, c.stepIndex)
 }
 
 function close() {
@@ -433,8 +448,17 @@ async function copyOutput() {
               <!-- a park a dedicated window owns (fork choice / follow-up triage): the
                    generic approval rail can't resolve it (the server refuses), so point
                    the human at the window that can -->
+              <!-- the pre-token input gate holds this step: answered here, in place -->
+              <InputGateNotice
+                v-if="inputGateVerdict && instance"
+                :gate="inputGateVerdict"
+                tone="blocked"
+                :execution-id="instance.id"
+                compact
+              />
+
               <div
-                v-if="dedicatedPark"
+                v-if="dedicatedPark && dedicatedPark !== 'input-gate'"
                 class="rounded-xl border border-amber-500/30 bg-amber-500/5 p-4"
                 data-testid="dedicated-park-redirect"
               >

package/app/components/panels/inspector/TaskExecution.vue

@@ -16,6 +16,8 @@ import { useNowTick, stepDurationLabel } from '~/composables/useStepTimer'
 import type { PipelineStep } from '~/types/execution'
 import type { ChangeClass, ReviewEffort } from '~/types/merge'
 import MergeEffortChips from '~/components/merge/MergeEffortChips.vue'
+import InputGateNotice from '~/components/inputGate/InputGateNotice.vue'
+import { inputGateNoticeFor } from '~/utils/inputGate'
 
 const props = defineProps<{ block: Block }>()
 
@@ -58,6 +60,14 @@ const isEmpty = computed(
 // A failed run is no longer executing: a step left mid-flight must stop showing
 // its live "Spinning up…" phase (the shared failure banner renders below).
 const runFailed = computed(() => instance.value?.status === 'failed')
+/**
+ * The run's PRE-TOKEN INPUT GATE notice: the park while it holds the run, the waiver once
+ * somebody overruled it, and the ADVISORY findings a `passed` verdict still carries (which is
+ * the entire product of `advisory` mode, and how `standard` mode reports a thin description).
+ * Read off the RUN, not a step: the gate guards the first dispatch and leaves nothing
+ * kind-specific behind. Which verdicts earn a notice is `inputGateNoticeFor`'s call.
+ */
+const inputGateNotice = computed(() => inputGateNoticeFor(instance.value))
 
 // A failed pipeline run surfaces the shared failure banner + retry — the
 // execution failure surface that the old `pr_ready` flip used to hide.
@@ -298,6 +308,16 @@ async function mergePr() {
           </UButton>
         </div>
       </div>
+      <!-- What the task's input check found. Rendered above the step list because it is a fact
+           about the RUN, and because the remedy for a park is to edit the task, not open a step.
+           An advisory verdict renders here too: nothing was parked, but something was found. -->
+      <InputGateNotice
+        v-if="inputGateNotice"
+        :gate="inputGateNotice.gate"
+        :tone="inputGateNotice.tone"
+        :execution-id="instance.id"
+        class="mb-2"
+      />
       <ul class="space-y-1">
         <li
           v-for="(s, i) in instance.steps"
@@ -417,7 +437,7 @@ async function mergePr() {
               v-else-if="
                 s.approval &&
                 s.approval.status === 'pending' &&
-                dedicatedParkView(s) === 'fork-decision'
+                dedicatedParkView(s, instance) === 'fork-decision'
               "
               color="primary"
               variant="soft"
@@ -434,7 +454,7 @@ async function mergePr() {
               v-else-if="
                 s.approval &&
                 s.approval.status === 'pending' &&
-                dedicatedParkView(s) === 'follow-ups'
+                dedicatedParkView(s, instance) === 'follow-ups'
               "
               color="primary"
               variant="soft"
@@ -461,8 +481,17 @@ async function mergePr() {
             >
               {{ t('inspector.execution.reviewFindings') }}
             </UButton>
+            <!-- The generic approve/review rail. Reached only once no dedicated surface owns
+                 the park: the branches above took the fork and follow-up windows, so the one
+                 left to exclude is the PRE-TOKEN INPUT GATE, which rides `step.approval` too
+                 but is refused by the generic resolver server-side (approving it would mark the
+                 run's first working step done and skip the work). It is answered by the notice
+                 above the list. Asked of `dedicatedParkView` rather than re-derived here, so
+                 the rule that decides which surface owns a park lives in exactly one place. -->
             <UButton
-              v-else-if="s.approval && s.approval.status === 'pending'"
+              v-else-if="
+                s.approval && s.approval.status === 'pending' && !dedicatedParkView(s, instance)
+              "
               color="warning"
               variant="soft"
               size="xs"

package/app/components/pipeline/PipelineProgress.vue

@@ -681,7 +681,7 @@ const ITEM_ICON: Record<string, string> = {
               s.approval &&
               s.approval.status === 'pending' &&
               !prReviewAwaiting(s) &&
-              !dedicatedParkView(s)
+              !dedicatedParkView(s, props.instance)
             "
             class="mt-3"
           >

package/app/components/settings/WorkspaceSettingsPanel.vue

@@ -11,7 +11,7 @@
 // standalone modals).
 import { reactive, ref, watch } from 'vue'
 import { useReactiveSlots } from '@modular-vue/runtime'
-import type { ReviewFrictionMode, TaskLimitMode } from '~/types/domain'
+import type { InputGateMode, ReviewFrictionMode, TaskLimitMode } from '~/types/domain'
 import RiskPolicyPanel from '~/components/settings/RiskPolicyPanel.vue'
 import IssueTrackerPanel from '~/components/settings/IssueTrackerPanel.vue'
 import ServiceFragmentDefaultsPanel from '~/components/settings/ServiceFragmentDefaultsPanel.vue'
@@ -151,6 +151,12 @@ const MODES = computed<{ value: TaskLimitMode; label: string }[]>(() => [
   { value: 'per_type', label: t('settings.workspaceSettings.taskLimit.modes.per_type') },
 ])
 
+const INPUT_GATE_MODES = computed<{ value: InputGateMode; label: string }[]>(() => [
+  { value: 'standard', label: t('settings.workspaceSettings.inputGate.modes.standard') },
+  { value: 'advisory', label: t('settings.workspaceSettings.inputGate.modes.advisory') },
+  { value: 'off', label: t('settings.workspaceSettings.inputGate.modes.off') },
+])
+
 const REVIEW_FRICTION_MODES = computed<{ value: ReviewFrictionMode; label: string }[]>(() => [
   { value: 'off', label: t('settings.workspaceSettings.reviewFriction.modes.off') },
   { value: 'warn', label: t('settings.workspaceSettings.reviewFriction.modes.warn') },
@@ -175,6 +181,7 @@ const draft = reactive({
   artifactRetentionDays: 14,
   kaizenEnabled: true,
   allowInitiatorPat: true,
+  inputGateMode: 'standard' as InputGateMode,
   reviewFrictionMode: 'off' as ReviewFrictionMode,
   reviewFrictionWarnCount: 3,
   reviewFrictionBlockCountEnabled: false,
@@ -195,6 +202,7 @@ function hydrate() {
   draft.artifactRetentionDays = s.artifactRetentionDays
   draft.kaizenEnabled = s.kaizenEnabled
   draft.allowInitiatorPat = s.allowInitiatorPat
+  draft.inputGateMode = s.inputGateMode
   draft.reviewFrictionMode = s.reviewFrictionMode
   draft.reviewFrictionWarnCount = s.reviewFrictionWarnCount
   // The hard-block knobs are nullable (null ⇒ that trigger is off); a per-trigger checkbox is
@@ -252,6 +260,7 @@ async function save() {
       artifactRetentionDays: draft.artifactRetentionDays,
       kaizenEnabled: draft.kaizenEnabled,
       allowInitiatorPat: draft.allowInitiatorPat,
+      inputGateMode: draft.inputGateMode,
       reviewFrictionMode: draft.reviewFrictionMode,
       reviewFrictionWarnCount: draft.reviewFrictionWarnCount,
       reviewFrictionBlockCount: blockCount,
@@ -359,6 +368,30 @@ async function save() {
               </div>
             </section>
 
+            <!-- The pre-token input gate: the structural check of a task's own wording, run
+                 before a run's first agent step is dispatched. -->
+            <section class="space-y-2">
+              <h3 class="text-sm font-semibold text-slate-200">
+                {{ t('settings.workspaceSettings.inputGate.heading') }}
+              </h3>
+              <p class="text-[11px] text-slate-400">
+                {{ t('settings.workspaceSettings.inputGate.body') }}
+              </p>
+              <label class="block w-64">
+                <span class="mb-1 block text-[10px] uppercase tracking-wide text-slate-500">{{
+                  t('settings.workspaceSettings.inputGate.mode')
+                }}</span>
+                <USelect
+                  v-model="draft.inputGateMode"
+                  :items="INPUT_GATE_MODES"
+                  value-key="value"
+                  size="sm"
+                  class="w-full"
+                  data-testid="input-gate-mode"
+                />
+              </label>
+            </section>
+
             <!-- Review-debt friction on task creation -->
             <section class="space-y-2">
               <h3 class="text-sm font-semibold text-slate-200">

package/app/composables/api/inputGate.ts

@@ -0,0 +1,25 @@
+import { resolveInputGateContract, type ResolveInputGateChoice } from '@cat-factory/contracts'
+import type { ApiContext } from './context'
+
+/**
+ * The PRE-TOKEN INPUT GATE: a run whose task states nothing an agent could act on parks before
+ * its first dispatch, having spent no tokens. This resolves that park: `recheck` re-evaluates
+ * the task as it now stands (the fix is verified, not asserted), `proceed` waives the findings.
+ *
+ * There is deliberately no read: the verdict rides the run (`ExecutionInstance.inputGate`),
+ * which the board snapshot and the live stream already carry.
+ */
+export function inputGateApi({ send, ws }: ApiContext) {
+  return {
+    resolveInputGate: (
+      workspaceId: string,
+      executionId: string,
+      body: { choice: ResolveInputGateChoice },
+    ) =>
+      send(resolveInputGateContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { executionId },
+        body,
+      }),
+  }
+}

package/app/composables/useApi.ts

@@ -13,6 +13,7 @@ import { documentsApi } from './api/documents'
 import { executionApi } from './api/execution'
 import { followUpsApi } from './api/followUps'
 import { forkDecisionApi } from './api/forkDecision'
+import { inputGateApi } from './api/inputGate'
 import { judgeApi } from './api/judge'
 import { prReviewApi } from './api/prReview'
 import { fragmentsApi } from './api/fragments'
@@ -129,6 +130,7 @@ export function useApi() {
     ...reviewsApi(ctx),
     ...followUpsApi(ctx),
     ...forkDecisionApi(ctx),
+    ...inputGateApi(ctx),
     ...judgeApi(ctx),
     ...prReviewApi(ctx),
     ...humanTestApi(ctx),

package/app/composables/usePipelineErrorToast.ts

@@ -80,6 +80,14 @@ const CONFLICT_INFO: Record<Exclude<ConflictReason, BespokeConflictReason>, Conf
     titleKey: 'errors.conflict.title.dependencies_unmet',
     descriptionKey: 'errors.conflict.description.dependencies_unmet',
   },
+  input_gate_not_parked: {
+    titleKey: 'errors.conflict.title.input_gate_not_parked',
+    descriptionKey: 'errors.conflict.description.input_gate_not_parked',
+  },
+  input_gate_parked: {
+    titleKey: 'errors.conflict.title.input_gate_parked',
+    descriptionKey: 'errors.conflict.description.input_gate_parked',
+  },
   task_limit_reached: {
     titleKey: 'errors.conflict.title.task_limit_reached',
     descriptionKey: 'errors.conflict.description.task_limit_reached',

package/app/stores/inputGate.ts

@@ -0,0 +1,58 @@
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import type { ResolveInputGateChoice, RunInputGate } from '@cat-factory/contracts'
+import { useApi } from '~/composables/useApi'
+import { useWorkspaceStore } from '~/stores/workspace'
+import { useExecutionStore } from '~/stores/execution'
+
+/**
+ * The PRE-TOKEN INPUT GATE's action surface. The verdict itself lives on the run
+ * (`instance.inputGate`) and is kept fresh by the execution stream, so this store only wraps the
+ * `resolve` action, tracks the in-flight state so the notice can disable its buttons, and
+ * reflects the returned verdict back so the UI updates before the stream echoes it.
+ *
+ * The echo goes through {@link ExecutionStore.echoAfter} rather than a bare assignment: a
+ * successful resolve WAKES THE DURABLE DRIVER, whose next emit routinely beats this HTTP
+ * response, so an unguarded write would put the released run back into `blocked` and, if the
+ * run then parks on something else, leave it there with nothing left to emit.
+ */
+export const useInputGateStore = defineStore('inputGate', () => {
+  const api = useApi()
+  const workspace = useWorkspaceStore()
+  const execution = useExecutionStore()
+
+  /** True while a resolve call is in flight (drives the buttons' spinner / disabled state). */
+  const resolving = ref(false)
+  /** The last error message from an action, surfaced inline; cleared on the next action. */
+  const error = ref<string | null>(null)
+
+  /**
+   * Resolve the parked gate. `recheck` re-evaluates the task as it now stands and releases the
+   * run only if the blocking gaps are genuinely gone. A still-blocked verdict comes back as an
+   * ordinary 200 with refreshed findings rather than an error, because nothing went wrong: the
+   * task is just not fixed yet. `proceed` waives the findings.
+   */
+  async function resolve(
+    executionId: string,
+    choice: ResolveInputGateChoice,
+  ): Promise<RunInputGate | null> {
+    error.value = null
+    resolving.value = true
+    try {
+      return await execution.echoAfter(
+        executionId,
+        () => api.resolveInputGate(workspace.requireId(), executionId, { choice }),
+        (gate, instance) => {
+          instance.inputGate = gate as RunInputGate
+        },
+      )
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : 'Failed to resolve'
+      throw e
+    } finally {
+      resolving.value = false
+    }
+  }
+
+  return { resolving, error, resolve }
+})