fix(automation): recover the seeded row id from the bag, not just record.id

A non-default recordIdField makes the seeded row id a column other than id,
so an action's declared recordIdParam gave that value a third key the record
does not carry: not a column, not record.id, not a derivable name. It read as
caller-supplied and the screen was SKIPPED, not paused, on a launch that
supplied nothing. The dispatcher seeds the same row id under every id key it
knows, so params.recordId (and the camelCase alias) recover it without knowing
the action-level name.

Also states the accepted cost: a screen field named recordId or the object-id
alias is always collected interactively.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XpTx2tbq3pZRYAdoGt6E6Y

Author: claude

.changeset/screen-flow-headless-satisfaction.md

@@ -12,7 +12,7 @@ Two independent halves:
 - **A screen the caller already answered no longer pauses.** When the caller named at least one of the screen's own fields and every `required` one has a value from that caller, there is nothing left to collect and the run continues. Optional fields may come from anywhere (including a declared `defaultValue`).
 - **`list_actions` publishes a flow action's inputs.** A `type: 'flow'` action's contract is its target flow's `isInput` variables, not `action.params`; those are now surfaced in declaration order with the `label`, `type`, `required` and select `options` of the screen field that collects each one. An action that declares its own `params[]` keeps them — the flow is read only where the action declared nothing.
 
-**Interactive runs are unchanged.** A console launch carries the record it was launched from and that record's id — never a value for the screen's own fields — so the form renders exactly as before. That covers both shapes a launch actually supplies: a subject-record column named like one of the screen's fields, and a field named like one of the row-id keys the dispatch doors seed (`recordId`, the camelCase `<object>Id` alias, an action's declared `recordIdParam`), none of which counts as the caller answering the screen. Two screens never take the new path, because they declare nothing to satisfy and must not be answered vacuously: a message-only screen (no fields), and any screen whose author wrote `waitForInput: true`. `waitForInput: false` remains the wrong tool for the headless case — it skips the form for interactive users too.
+**Interactive runs are unchanged.** A console launch carries the record it was launched from and that record's id — never a value for the screen's own fields — so the form renders exactly as before. That covers both shapes a launch actually supplies: a subject-record column named like one of the screen's fields, and a field named like one of the row-id keys the dispatch doors seed (`recordId`, the camelCase `<object>Id` alias, an action's declared `recordIdParam`), none of which counts as the caller answering the screen — the two fixed names outright, and any value equal to the launched row's id whatever key carries it. One accepted cost of that: **a screen field named `recordId` or `<object>Id` is always collected interactively**, even from a headless caller. Two screens never take the new path, because they declare nothing to satisfy and must not be answered vacuously: a message-only screen (no fields), and any screen whose author wrote `waitForInput: true`. `waitForInput: false` remains the wrong tool for the headless case — it skips the form for interactive users too.
 
 ⚠️ One known gap, on the trigger-record leg only: a run continued from the **durable** suspended-run store judges against a JSON copy of its context, so a later wizard screen whose field collides with a **non-scalar** column (an array or object) of the trigger record can read as caller-supplied and be skipped. Scalar columns are unaffected, as is any run that has not been through a pause.
 

content/docs/automation/flows.mdx

@@ -753,7 +753,11 @@ The screen is treated as answered only when **all** of these hold:
   row id a launch carries does **not** count as naming a field: both dispatch
   doors seed it into the params bag under `recordId` and the camelCase
   `<object>Id` alias (and under an action's declared `recordIdParam`), and none
-  of those is the caller supplying a screen value;
+  of those is the caller supplying a screen value. The two fixed names are
+  refused outright, and any value equal to the launched row's id is refused
+  whatever key carries it — so **a screen field named `recordId` or `<object>Id`
+  is always collected interactively**, even from a headless caller. Name a field
+  you want a headless caller to fill something else;
 - every `required` field has a value (an empty or blank string is no value),
   supplied by that caller. A value that came from the trigger record, from an
   earlier node or from a declared `defaultValue` does not answer a `required`

packages/services/service-automation/src/builtin/screen-headless-satisfaction.test.ts

@@ -293,6 +293,40 @@ describe('screen headless satisfaction (#15705)', () => {
         expect(res.status).toBe('paused');
     });
 
+    /**
+     * The shape review round 2 drove, and the one this file's author had
+     * characterised as pause-only when it in fact SKIPPED.
+     *
+     * `recordIdField: 'token'` makes the seeded row id the record's `token`
+     * column rather than its `id`, and `recordIdParam: 'sessionToken'` gives
+     * that value a THIRD key the record does not carry. So: not a column (the
+     * record leg cannot see it), not `record.id` (the row-id value leg, as
+     * first written, could not see it either), and not a derivable name. It
+     * read as caller-supplied on a launch that supplied nothing, and the run
+     * completed with `{ sessionToken: 'tok_9' }`.
+     *
+     * What closes it: the dispatcher seeds the SAME row id under every one of
+     * its id keys, so `params.recordId` still carries it and the value is
+     * recoverable from the bag itself, without knowing the action-level name.
+     */
+    it('CONTROL — a non-id `recordIdField` seeded under a third `recordIdParam` name does not satisfy it', async () => {
+        const flow: any = followupFlow();
+        flow.nodes[1].config.fields = [{ name: 'sessionToken', label: 'Session', type: 'text', required: true }];
+        flow.variables = [{ name: 'sessionToken', type: 'text', isInput: true, isOutput: true }];
+        register({}, flow);
+        // The authentic `seedFlowActionParams` bag for
+        // `recordIdField: 'token'` + `recordIdParam: 'sessionToken'`: the row
+        // id is `record.token`, seeded under all three id keys.
+        const session = { id: 'sess_1', token: 'tok_9', label: 'Web session' };
+        const res = await engine.execute('schedule_followup', {
+            record: session,
+            object: 'crm_lead',
+            params: { ...session, recordId: 'tok_9', crmLeadId: 'tok_9', sessionToken: 'tok_9' },
+        } as AutomationContext);
+        expect(res.status).toBe('paused');
+        expect(res.screen?.nodeId).toBe('screen_1');
+    });
+
     it('trigger door: a genuine caller param still satisfies the screen', async () => {
         register();
         const res = await engine.execute('schedule_followup', triggerDoorContext('lead_1', {

packages/services/service-automation/src/screen-input-contract.ts

@@ -221,20 +221,37 @@ function callerSupplied(
   if (!params || params[name] === undefined) return false;
   // Row-id seeds first: neither leg below can disprove them, because the
   // trigger door sets no record and none of these names is a column.
-  if (name === 'recordId') return false;
   const objectName = typeof context?.object === 'string' ? context.object.trim() : '';
   // The camelCase alias both doors seed, derived the same way they derive it.
-  if (objectName && name === `${objectName.replace(/_([a-z])/g, (_m: string, c: string) => c.toUpperCase())}Id`) {
-    return false;
-  }
+  const aliasKey = objectName
+    ? `${objectName.replace(/_([a-z])/g, (_m: string, c: string) => c.toUpperCase())}Id`
+    : undefined;
+  if (name === 'recordId' || (aliasKey !== undefined && name === aliasKey)) return false;
+
   const record = context?.record;
-  // The action's declared `recordIdParam` may seed a THIRD name this executor
-  // cannot know, always with the row id as its value — so the value is what
-  // refuses it. A caller who genuinely sends the row id as a screen value only
-  // loses the skip, which is this module's standing failure direction.
-  if (record?.id !== undefined && Object.is(params[name], record.id)) return false;
+  const value = params[name];
+  // The action's declared `recordIdParam` seeds a THIRD name this executor
+  // cannot know — action-level metadata is not on the context — so its VALUE
+  // is what refuses it. The dispatcher seeds the SAME row id under every id
+  // key it knows, which makes the id recoverable from the bag itself:
+  //
+  //  - `params.recordId`, always seeded, and the only candidate that survives
+  //    a NON-DEFAULT `recordIdField`. That case is why this leg exists: with
+  //    `recordIdField: 'token'` the row id is `record.token`, so comparing
+  //    against `record.id` alone missed it and the screen was SKIPPED, not
+  //    paused — measured, then pinned.
+  //  - the camelCase alias's value, seeded the same way, as a second reading
+  //    of the same id for the case where a record column shadows `recordId`;
+  //  - `record.id`, which covers the record-bearing doors directly.
+  //
+  // A caller who genuinely sends the row id as a screen value only loses the
+  // skip, which is this module's standing failure direction.
+  const seededRowIds: unknown[] = [params.recordId, record?.id];
+  if (aliasKey !== undefined) seededRowIds.push(params[aliasKey]);
+  if (seededRowIds.some((id) => id !== undefined && Object.is(value, id))) return false;
+
   if (!record || !Object.prototype.hasOwnProperty.call(record, name)) return true;
-  return !Object.is(params[name], record[name]);
+  return !Object.is(value, record[name]);
 }
 
 /**