@sensigo/realm 0.39.0 → 0.40.0

package/dist/workflow/yaml-loader.js

@@ -7,6 +7,7 @@ import { Ajv } from 'ajv';
 import { KNOWN_STEP_KEYS, KNOWN_WORKFLOW_KEYS, KNOWN_RETRY_KEYS, KNOWN_GATE_KEYS, } from '../types/workflow-definition.js';
 import { WorkflowError } from '../types/workflow-error.js';
 import { findUnknownKeys, renderLoaderWarning, resolveSeverity, closestKey, } from './diagnostics.js';
+import { createSourcePositionCollector } from './source-positions.js';
 import { resolveTemplates } from './template-resolver.js';
 import { normalizeTriggerFilter, validateTriggerStructure } from './trigger-schema.js';
 import { splitComparison, isPathShaped } from '../engine/comparison-expr.js';
@@ -18,20 +19,27 @@ import { assessStructuredOutputEligibility, renderIneligibleMessage, } from './s
  * used at runtime). Rejects compound `and`/`or`, multiple operators, and non-path LHS. For `when`,
  * also enforces the direct-`depends_on` reference check (Change 2). Pushes actionable errors.
  */
-function validateConditionLeaf(surface, leaf, stepName, dependsOn, errors) {
+function validateConditionLeaf(surface, leaf, stepName, dependsOn, errors, 
+/**
+ * Appends the step's source line to a message (issue #392). REQUIRED rather than optional so
+ * the compiler names every call site if this ever gains another one — an omitted resolver
+ * would silently drop positions, which is exactly the kind of quiet gap this repo keeps
+ * finding the hard way.
+ */
+withLine) {
     const split = splitComparison(leaf);
     if (split.kind === 'invalid') {
         if (split.reason === 'compound_and' || split.reason === 'compound_or') {
             const kw = split.reason === 'compound_and' ? 'and' : 'or';
             const listForm = (split.parts ?? [leaf]).map((p) => `    - "${p}"`).join('\n');
-            errors.push(`Step '${stepName}': '${surface}' uses unsupported '${kw}' — write it as a list:\n` +
-                `  ${surface}:\n${listForm}`);
+            errors.push(withLine(stepName, `Step '${stepName}': '${surface}' uses unsupported '${kw}' — write it as a list:\n` +
+                `  ${surface}:\n${listForm}`));
         }
         else if (split.reason === 'multiple_operators') {
-            errors.push(`Step '${stepName}': '${surface}' leaf '${leaf}' has multiple comparison operators — each leaf must be a single comparison.`);
+            errors.push(withLine(stepName, `Step '${stepName}': '${surface}' leaf '${leaf}' has multiple comparison operators — each leaf must be a single comparison.`));
         }
         else {
-            errors.push(`Step '${stepName}': '${surface}' leaf must not be empty.`);
+            errors.push(withLine(stepName, `Step '${stepName}': '${surface}' leaf must not be empty.`));
         }
         return;
     }
@@ -42,7 +50,7 @@ function validateConditionLeaf(surface, leaf, stepName, dependsOn, errors) {
         // $settlement one-hop reason (issue #220 §4c pin kk: the precondition witness for a
         // $settlement leaf must use the comparison spelling).
         if (surface === 'preconditions') {
-            errors.push(`Step '${stepName}': precondition '${leaf}' must be a comparison (e.g. "step.field >= 1").`);
+            errors.push(withLine(stepName, `Step '${stepName}': precondition '${leaf}' must be a comparison (e.g. "step.field >= 1").`));
             return;
         }
         // issue #220 §4c (PR-3): `$settlement.<dep>.<field>` handling lives HERE, in
@@ -52,28 +60,28 @@ function validateConditionLeaf(surface, leaf, stepName, dependsOn, errors) {
         // `surface === 'when'` — an arm there would never fire for abort_unless/preconditions). This
         // fires on ALL THREE surfaces since it runs BEFORE the generic isPathShaped check below.
         if (split.path.split('.')[0] === '$settlement') {
-            validateSettlementReference(split.path, surface, leaf, stepName, dependsOn, errors);
+            validateSettlementReference(split.path, surface, leaf, stepName, dependsOn, errors, withLine);
             return;
         }
         if (!isPathShaped(split.path)) {
-            errors.push(`Step '${stepName}': '${surface}' leaf '${leaf}' is not a valid path or comparison.`);
+            errors.push(withLine(stepName, `Step '${stepName}': '${surface}' leaf '${leaf}' is not a valid path or comparison.`));
             return;
         }
         if (surface === 'when')
-            validateWhenReference(split.path, stepName, dependsOn, errors);
+            validateWhenReference(split.path, stepName, dependsOn, errors, withLine);
         return;
     }
     // comparison
     if (split.lhsPath.split('.')[0] === '$settlement') {
-        validateSettlementReference(split.lhsPath, surface, leaf, stepName, dependsOn, errors);
+        validateSettlementReference(split.lhsPath, surface, leaf, stepName, dependsOn, errors, withLine);
         return;
     }
     if (!isPathShaped(split.lhsPath)) {
-        errors.push(`Step '${stepName}': '${surface}' leaf '${leaf}' must have a path on the left-hand side (got '${split.lhsPath}').`);
+        errors.push(withLine(stepName, `Step '${stepName}': '${surface}' leaf '${leaf}' must have a path on the left-hand side (got '${split.lhsPath}').`));
         return;
     }
     if (surface === 'when')
-        validateWhenReference(split.lhsPath, stepName, dependsOn, errors);
+        validateWhenReference(split.lhsPath, stepName, dependsOn, errors, withLine);
 }
 /**
  * issue #220 §4c (PR-3): validates a `$settlement.<dep>.<field>` reference reached from ANY of
@@ -83,7 +91,14 @@ function validateConditionLeaf(surface, leaf, stepName, dependsOn, errors) {
  * `surface === 'when'` gate. The caller must NOT fall through to the generic `isPathShaped` check
  * afterward (which rejects `$` outright) — this function's callers always `return` immediately.
  */
-function validateSettlementReference(path, surface, leaf, stepName, dependsOn, errors) {
+function validateSettlementReference(path, surface, leaf, stepName, dependsOn, errors, 
+/**
+ * Appends the step's source line to a message (issue #392). REQUIRED rather than optional so
+ * the compiler names every call site if this ever gains another one — an omitted resolver
+ * would silently drop positions, which is exactly the kind of quiet gap this repo keeps
+ * finding the hard way.
+ */
+withLine) {
     // Path-shape: a NARROWING for this ONE prefix only (never a general `$` allowance) — the
     // remainder after `$settlement` must itself be path-shaped. Rejects `$foo`, a bare `$`, and
     // garbage remainders like `$settlement.a b`.
@@ -96,21 +111,21 @@ function validateSettlementReference(path, surface, leaf, stepName, dependsOn, e
     // no backtracking. Accepts every valid `$settlement.<dep>.<field>` path identically; stricter
     // only on pathological consecutive dots (`$settlement.dep..field`), which is more correct.
     if (!/^\$settlement(\.[A-Za-z_][A-Za-z0-9_-]*)*$/.test(path)) {
-        errors.push(`Step '${stepName}': '${surface}' leaf '${leaf}' has an invalid '$settlement' reference ` +
-            `'${path}' — expected '$settlement.<dep>.<field>'.`);
+        errors.push(withLine(stepName, `Step '${stepName}': '${surface}' leaf '${leaf}' has an invalid '$settlement' reference ` +
+            `'${path}' — expected '$settlement.<dep>.<field>'.`));
         return;
     }
     // One-hop (§4c-S4): the SECOND segment must be a DIRECT dependency of this step.
     const dep = path.split('.')[1];
     if (dep === undefined) {
-        errors.push(`Step '${stepName}': '${surface}' leaf '${leaf}' references '$settlement' with no ` +
-            `dependency segment — expected '$settlement.<dep>.<field>' where '<dep>' is a direct dependency.`);
+        errors.push(withLine(stepName, `Step '${stepName}': '${surface}' leaf '${leaf}' references '$settlement' with no ` +
+            `dependency segment — expected '$settlement.<dep>.<field>' where '<dep>' is a direct dependency.`));
         return;
     }
     if (!dependsOn.includes(dep)) {
-        errors.push(`Step '${stepName}': '${surface}' references '$settlement.${dep}' — '${dep}' is not in ` +
+        errors.push(withLine(stepName, `Step '${stepName}': '${surface}' references '$settlement.${dep}' — '${dep}' is not in ` +
             `its depends_on [${dependsOn.join(', ')}]. '$settlement' paths must reference a direct ` +
-            `dependency (one-hop rule).`);
+            `dependency (one-hop rule).`));
     }
 }
 /**
@@ -118,16 +133,23 @@ function validateSettlementReference(path, surface, leaf, stepName, dependsOn, e
  * step in this step's DIRECT `depends_on` (one-hop membership — no graph traversal). Field names are
  * not checked (agent-step outputs aren't statically declared).
  */
-function validateWhenReference(path, stepName, dependsOn, errors) {
+function validateWhenReference(path, stepName, dependsOn, errors, 
+/**
+ * Appends the step's source line to a message (issue #392). REQUIRED rather than optional so
+ * the compiler names every call site if this ever gains another one — an omitted resolver
+ * would silently drop positions, which is exactly the kind of quiet gap this repo keeps
+ * finding the hard way.
+ */
+withLine) {
     const first = path.split('.')[0];
     if (first === 'run') {
         if (!(path === 'run.params' || path.startsWith('run.params.'))) {
-            errors.push(`Step '${stepName}': 'when' references '${path}' — only 'run.params.*' is available from 'run'.`);
+            errors.push(withLine(stepName, `Step '${stepName}': 'when' references '${path}' — only 'run.params.*' is available from 'run'.`));
         }
         return;
     }
     if (!dependsOn.includes(first)) {
-        errors.push(`Step '${stepName}': 'when' references step '${first}' which is not in its depends_on [${dependsOn.join(', ')}]. Add it to depends_on or use 'run.params.*'.`);
+        errors.push(withLine(stepName, `Step '${stepName}': 'when' references step '${first}' which is not in its depends_on [${dependsOn.join(', ')}]. Add it to depends_on or use 'run.params.*'.`));
     }
 }
 /** Bumped on every breaking change to WorkflowDefinition's serialized format. */
@@ -478,9 +500,14 @@ function detectDependencyCycles(edges) {
  */
 function parseWorkflowString(content, registry, opts) {
     // Step 1: Parse YAML
+    //
+    // issue #392: the position collector rides THIS parse via js-yaml's own listener — there is no
+    // second parse and no parser change. If the parse throws, `finish()` is never reached and every
+    // position is simply absent, which is the correct answer for a file that did not parse.
+    const positions = createSourcePositionCollector();
     let raw;
     try {
-        raw = load(content);
+        raw = load(content, { listener: positions.listener });
     }
     catch (err) {
         throw new WorkflowError(`YAML parse error: ${err instanceof Error ? err.message : String(err)}`, {
@@ -492,6 +519,36 @@ function parseWorkflowString(content, registry, opts) {
     }
     const errors = [];
     const warnings = [];
+    // Finalised after the parse succeeded; resolves a semantic path to its place in the source.
+    const sourceMap = positions.finish();
+    /**
+     * Appends ` (line N)` when the step's own key can be placed, and nothing when it cannot
+     * (issue #392). Used at PUSH time, never at join time — once messages are joined into one
+     * string the step each came from is no longer recoverable.
+     */
+    const withStepLine = (stepName, message) => {
+        const line = sourceMap.posOf(['steps', stepName])?.line;
+        return line === undefined ? message : `${message} (line ${line})`;
+    };
+    /**
+     * Like `withStepLine`, but names the OFFENDING KEY's own line (issue #417).
+     *
+     * For a key-scoped refusal the step's line is the wrong place to send someone: a long step has
+     * the key twenty lines below its own name, and the author reading `(line 40)` looks at the
+     * declaration rather than at the field being refused. The position map records every pairable
+     * mapping key, so the key's own line is available wherever the step's is.
+     *
+     * Falls back to the step's line, and then to no position at all — and the two real shapes land
+     * on DIFFERENT rungs, which is why both are pinned. A step body assembled through a merge key
+     * (`<<: *anchor`) leaves the KEY unpairable while the step's own name is still placeable, so it
+     * falls back to the step's line. A `use_template` step, whose keys are synthesized, exists at no
+     * line in the file at all and carries no position. Neither guesses — a wrong line number sends
+     * an author confidently to the wrong place, which is worse than sending them nowhere.
+     */
+    const withKeyLine = (stepName, key, message) => {
+        const line = sourceMap.posOf(['steps', stepName, key])?.line ?? sourceMap.posOf(['steps', stepName])?.line;
+        return line === undefined ? message : `${message} (line ${line})`;
+    };
     // Step 2: Top-level validation
     if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
         throw new WorkflowError('Invalid workflow: Workflow must be a non-null object', {
@@ -515,6 +572,7 @@ function parseWorkflowString(content, registry, opts) {
             scope: 'workflow',
             code: 'UNKNOWN_WORKFLOW_KEY',
             id: workflowId,
+            positionOf: (key) => sourceMap.posOf([key]),
         }));
     }
     // Project extensions: hard error for string-based loading (fires before any other
@@ -567,7 +625,7 @@ function parseWorkflowString(content, registry, opts) {
     // Step 3: Per-step validation
     for (const [stepName, stepRaw] of Object.entries(stepsRaw)) {
         if (typeof stepRaw !== 'object' || stepRaw === null || Array.isArray(stepRaw)) {
-            errors.push(`Step '${stepName}' must be an object`);
+            errors.push(withStepLine(stepName, `Step '${stepName}' must be an object`));
             continue;
         }
         const step = stepRaw;
@@ -588,6 +646,7 @@ function parseWorkflowString(content, registry, opts) {
             scope: 'step',
             code: 'UNKNOWN_STEP_KEY',
             step: stepName,
+            positionOf: (key) => sourceMap.posOf(['steps', stepName, key]),
         }));
         // issue #220 §4c PR ordering interlock: `$settlement` is reserved NOW (PR-1) even though the
         // namespace it names is not minted until a later PR — else the inter-PR gap could register a
@@ -605,11 +664,11 @@ function parseWorkflowString(content, registry, opts) {
         const REQUIRED_STEP = ['description', 'execution'];
         for (const field of REQUIRED_STEP) {
             if (!(field in step)) {
-                errors.push(`Step '${stepName}': missing required field '${field}'`);
+                errors.push(withStepLine(stepName, `Step '${stepName}': missing required field '${field}'`));
             }
         }
         if ('execution' in step && !VALID_EXECUTIONS.has(step['execution'])) {
-            errors.push(`Step '${stepName}': invalid execution value '${String(step['execution'])}'; must be 'auto', 'agent', 'guard', or 'finalizer'`);
+            errors.push(withStepLine(stepName, `Step '${stepName}': invalid execution value '${String(step['execution'])}'; must be 'auto', 'agent', 'guard', or 'finalizer'`));
         }
         // Finalizer step constraints (a workflow-level try/catch/finally). handler-only in v1.
         if (step['execution'] === 'finalizer') {
@@ -630,37 +689,43 @@ function parseWorkflowString(content, registry, opts) {
             ];
             for (const field of prohibited) {
                 if (step[field] !== undefined) {
-                    errors.push(`Step '${stepName}': '${field}' is not valid on execution: finalizer steps`);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': '${field}' is not valid on execution: finalizer steps`));
                 }
             }
             // A finalizer must not gate — reject any human-gate trust level.
             if (step['trust'] !== undefined && step['trust'] !== 'auto') {
-                errors.push(`Step '${stepName}': 'trust: ${String(step['trust'])}' is not valid on execution: finalizer steps (a finalizer must not gate)`);
+                errors.push(withStepLine(stepName, `Step '${stepName}': 'trust: ${String(step['trust'])}' is not valid on execution: finalizer steps (a finalizer must not gate)`));
             }
             // v1 is handler-only.
             if (step['handler'] === undefined) {
-                errors.push(`Step '${stepName}': execution: finalizer requires 'handler' (handler-only in v1)`);
+                errors.push(withStepLine(stepName, `Step '${stepName}': execution: finalizer requires 'handler' (handler-only in v1)`));
             }
             // on_outcome is required, non-empty, every value in the FinalizerTrigger enum.
             const rawOutcome = step['on_outcome'];
             if (rawOutcome === undefined) {
-                errors.push(`Step '${stepName}': execution: finalizer requires 'on_outcome'`);
+                errors.push(withStepLine(stepName, `Step '${stepName}': execution: finalizer requires 'on_outcome'`));
             }
             else {
                 const outcomes = Array.isArray(rawOutcome) ? rawOutcome : [rawOutcome];
                 if (outcomes.length === 0) {
-                    errors.push(`Step '${stepName}': 'on_outcome' must not be empty`);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'on_outcome' must not be empty`));
                 }
                 for (const o of outcomes) {
                     if (typeof o !== 'string' || !VALID_FINALIZER_TRIGGERS.has(o)) {
-                        errors.push(`Step '${stepName}': invalid on_outcome value '${String(o)}'; must be one of ${[...VALID_FINALIZER_TRIGGERS].join(', ')}`);
+                        errors.push(withStepLine(stepName, `Step '${stepName}': invalid on_outcome value '${String(o)}'; must be one of ${[...VALID_FINALIZER_TRIGGERS].join(', ')}`));
                     }
                 }
             }
         }
         // on_outcome is only valid on execution: finalizer steps.
         if (step['on_outcome'] !== undefined && step['execution'] !== 'finalizer') {
-            errors.push(`Step '${stepName}': 'on_outcome' is only valid on execution: finalizer steps`);
+            errors.push(
+            // Consumer: settlement.ts:145 (`finalizerTriggers`) — it is read only when selecting
+            // which finalizers a run's outcome should fire.
+            withKeyLine(stepName, 'on_outcome', `Step '${stepName}': 'on_outcome' is only valid on execution: finalizer steps — it ` +
+                'selects which finalizers run for a given outcome, and only finalizers are selected ' +
+                'that way, so here it would decide nothing. Move it to the finalizer that should ' +
+                'react to the outcome, or remove it.'));
         }
         // Guard step constraints.
         if (step['execution'] === 'guard') {
@@ -680,29 +745,112 @@ function parseWorkflowString(content, registry, opts) {
             ];
             for (const field of prohibited) {
                 if (step[field] !== undefined) {
-                    errors.push(`Step '${stepName}': '${field}' is not valid on execution: guard steps`);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': '${field}' is not valid on execution: guard steps`));
                 }
             }
             if (step['abort_unless'] === undefined) {
-                errors.push(`Step '${stepName}': execution: guard requires 'abort_unless'`);
+                errors.push(withStepLine(stepName, `Step '${stepName}': execution: guard requires 'abort_unless'`));
+            }
+            // issue #369: `preconditions` gets its OWN error rather than joining `prohibited` above,
+            // because the generic message ("'x' is not valid on execution: guard steps") would not say
+            // the thing that matters — this field was ACCEPTED and INERT before this check existed, so
+            // an author who wrote one has a workflow that looks guarded and never was. The generic
+            // list's own message style is issue #366's territory; the other twelve are left alone.
+            //
+            // The claim "never evaluates it there" rests on `checkPreconditions` having exactly one
+            // engine call site (execution-loop.ts:1380, inside `executeStep`), which `executeGuardStep`
+            // never reaches. A test pins that count so a second call site reds this message.
+            if (step['preconditions'] !== undefined) {
+                errors.push(withKeyLine(stepName, 'preconditions', `Step '${stepName}': 'preconditions' is not valid on execution: guard steps — the ` +
+                    `engine never evaluates it there (a guard's execution evaluates only 'abort_unless'), ` +
+                    `so the run would LOOK guarded while the declared check never ran. Move the condition ` +
+                    `into 'abort_unless'. Whether guards gain a live condition surface is an open design ` +
+                    `question (issue #366) — if admitted later, existing workflows are unaffected.`));
             }
         }
         // abort_unless and abort_message are only valid on execution: guard steps.
         if (step['abort_unless'] !== undefined && step['execution'] !== 'guard') {
-            errors.push(`Step '${stepName}': 'abort_unless' is only valid on execution: guard steps`);
+            errors.push(
+            // Consumer: execution-loop.ts:4828 — the condition list a guard evaluates before the
+            // run is allowed to continue.
+            withKeyLine(stepName, 'abort_unless', `Step '${stepName}': 'abort_unless' is only valid on execution: guard steps — it is ` +
+                'the condition list a guard evaluates before letting the run continue, and only ' +
+                'guard steps are evaluated that way, so here it would gate nothing. Put the check ' +
+                'on a guard step, or remove it.'));
         }
         if (step['abort_message'] !== undefined && step['execution'] !== 'guard') {
-            errors.push(`Step '${stepName}': 'abort_message' is only valid on execution: guard steps`);
+            errors.push(
+            // Consumer: execution-loop.ts:4943 — the text reported when a guard aborts the run.
+            // The clause is about READERSHIP, not about who aborts: `handler_abort` and
+            // `gate_expiry_abort` are seal arms too (types/run-record.ts:603-617), so "only a guard
+            // aborts" would be false. What is true is that every reader of this key is a guard path.
+            withKeyLine(stepName, 'abort_message', `Step '${stepName}': 'abort_message' is only valid on execution: guard steps — it is ` +
+                'the text reported when a guard aborts the run, and nothing but a guard reads it, ' +
+                'so here it would never be read. Move it to the guard that performs the abort, or ' +
+                'remove it.'));
         }
         // agent_profile is only valid on agent steps.
         if ('agent_profile' in step && step['execution'] !== 'agent') {
-            errors.push(`Step '${stepName}': 'agent_profile' is only valid on execution: agent steps`);
+            errors.push(
+            // Consumer: run-agent.ts:584 — resolved into the model prompt for the step.
+            withKeyLine(stepName, 'agent_profile', `Step '${stepName}': 'agent_profile' is only valid on execution: agent steps — its ` +
+                'content is resolved into the model prompt, and only an agent step makes a model ' +
+                'request, so here it would reach no model. Move it to the agent step whose prompt ' +
+                'it should shape, or remove it.'));
+        }
+        // llm_timeout_seconds (issue #401) is only valid on agent steps — no other execution kind
+        // makes a model request, so the key would be silently inert anywhere else. One `!== 'agent'`
+        // check covers auto/guard/finalizer.
+        if (step['llm_timeout_seconds'] !== undefined && step['execution'] !== 'agent') {
+            errors.push(
+            // Consumer: run-agent.ts:501-507 — the per-step clock resolution, which is the
+            // per-attempt bound on the step's model request. The range names the resolution rather
+            // than each read: :501 and :507 read the KEY, :503 reads the CLI flag it overrides.
+            withKeyLine(stepName, 'llm_timeout_seconds', `Step '${stepName}': 'llm_timeout_seconds' is only valid on execution: agent steps — ` +
+                'it bounds one model request, and no other kind makes one, so here it would bound ' +
+                'nothing. Move it to the agent step whose request it should bound, or remove it. ' +
+                "An auto step's dispatch is bounded by 'timeout_seconds', and a " +
+                "finalizer's handler by its own 'timeout_seconds'."));
+        }
+        // ...and when present it must be a positive integer (the same convention as
+        // retry.total_timeout_seconds and gate.timeout_seconds).
+        if (step['llm_timeout_seconds'] !== undefined &&
+            (!Number.isInteger(step['llm_timeout_seconds']) ||
+                step['llm_timeout_seconds'] <= 0)) {
+            errors.push(withStepLine(stepName, `Step '${stepName}': 'llm_timeout_seconds' must be a positive integer`));
+        }
+        // timeout_seconds is NOT valid on an agent step (issue #402). Nothing enforces it there:
+        // `shouldEnforceTimeout` is `execution === 'auto'`, and agent dispatch is never wrapped in
+        // `withTimeout` at all. The key is now inert as well as unenforced — issue #412 deleted the
+        // `expected_timeout` display that used to render it into the NextAction, which is what made
+        // it actively misleading rather than merely useless. The error stays: an author who writes a
+        // bound should be told it does nothing, not left to find out. The message names both bounds
+        // that DO exist, scoped to realm's own drive (an externally driven step gets neither), on
+        // the RETRY_INERT_NON_AUTO precedent below.
+        //
+        // `=== 'agent'` EXACTLY, never `!== 'auto'`: finalizers consume this key twice — the drain
+        // lease (execution-loop.ts:5226) and the handler's own bound (:5030) — and guards already
+        // reject it in the prohibited-fields list above.
+        if (step['timeout_seconds'] !== undefined && step['execution'] === 'agent') {
+            errors.push(withKeyLine(stepName, 'timeout_seconds', `Step '${stepName}': 'timeout_seconds' is not valid on execution: agent steps — ` +
+                'the engine never enforces it there (agent dispatch is never wrapped in a timeout), ' +
+                'so the step would LOOK time-bounded while nothing enforced the bound. ' +
+                "In realm's own drive the model request is bounded by 'llm_timeout_seconds' " +
+                "(or --llm-timeout) and tool calls by 'tool_timeout'."));
         }
         // idempotent (issue #101 Phase 2) is only valid on execution: auto steps — the reliably
         // time-boundable, deadline-carrying class. It is inert (no concrete deadline is ever written)
         // on agent/guard/finalizer, so it is rejected there rather than silently ignored.
         if (step['idempotent'] !== undefined && step['execution'] !== 'auto') {
-            errors.push(`Step '${stepName}': 'idempotent' is only valid on execution: auto steps`);
+            errors.push(
+            // Consumers: execution-loop.ts:2526 (the `willRetry` conjunct gating `retry.on_timeout`;
+            // the :2115 advisory mirrors the rule for loader-bypassing definitions and, by its own
+            // header, never gates) and reclaim.ts:73 (reclaim eligibility) — both act on auto
+            // dispatch.
+            withKeyLine(stepName, 'idempotent', `Step '${stepName}': 'idempotent' is only valid on execution: auto steps — it gates ` +
+                "'retry.on_timeout' and reclaim eligibility, and both act on auto dispatch, so here " +
+                'it would gate nothing. Remove it, or move the work to an auto step if you need ' +
+                'either.'));
         }
         // WARN (do not reject): an idempotent auto step in a finalizer-bearing workflow gets
         // `deadline: null` (issue #101), so the RECLAIM function is inert — `realm run reclaim --all`
@@ -734,7 +882,7 @@ function parseWorkflowString(content, registry, opts) {
         }
         // output_schema is only valid on execution: agent steps.
         if (step['output_schema'] !== undefined && step['execution'] !== 'agent') {
-            errors.push(`Step '${stepName}': 'output_schema' is only valid on execution: agent steps`);
+            errors.push(withStepLine(stepName, `Step '${stepName}': 'output_schema' is only valid on execution: agent steps`));
         }
         // issue #236 (L0 prevention layer): structured_output is only valid on execution: agent
         // steps (mirrors output_schema's rule above), and its only legal value is the literal
@@ -744,10 +892,10 @@ function parseWorkflowString(content, registry, opts) {
         // only, surfaced by validate's nudge — Deliverable 7); this loader block only ever REJECTS.
         if (step['structured_output'] !== undefined) {
             if (step['execution'] !== 'agent') {
-                errors.push(`Step '${stepName}': 'structured_output' is only valid on execution: agent steps`);
+                errors.push(withStepLine(stepName, `Step '${stepName}': 'structured_output' is only valid on execution: agent steps`));
             }
             else if (step['structured_output'] !== 'strict') {
-                errors.push(`Step '${stepName}': 'structured_output' must be the literal string 'strict' (got ${JSON.stringify(step['structured_output'])})`);
+                errors.push(withStepLine(stepName, `Step '${stepName}': 'structured_output' must be the literal string 'strict' (got ${JSON.stringify(step['structured_output'])})`));
             }
             else {
                 const verdict = assessStructuredOutputEligibility({
@@ -760,8 +908,8 @@ function parseWorkflowString(content, registry, opts) {
                     ...(step['tools'] !== undefined ? { tools: step['tools'] } : {}),
                 });
                 if (verdict.verdict === 'ineligible') {
-                    errors.push(`Step '${stepName}': 'structured_output: strict' is not eligible for this step's ` +
-                        `schema — ${renderIneligibleMessage(verdict.reasons)}`);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'structured_output: strict' is not eligible for this step's ` +
+                        `schema — ${renderIneligibleMessage(verdict.reasons)}`));
                 }
             }
         }
@@ -776,11 +924,11 @@ function parseWorkflowString(content, registry, opts) {
         // as dead config (never rejects — it's simply inert); an unknown sub-key WARNS.
         if (step['validation_exhaustion'] !== undefined) {
             if (step['execution'] !== 'agent') {
-                errors.push(`Step '${stepName}': 'validation_exhaustion' is only valid on execution: agent steps`);
+                errors.push(withStepLine(stepName, `Step '${stepName}': 'validation_exhaustion' is only valid on execution: agent steps`));
             }
             else if (typeof step['validation_exhaustion'] !== 'object' ||
                 step['validation_exhaustion'] === null) {
-                errors.push(`Step '${stepName}': 'validation_exhaustion' must be an object`);
+                errors.push(withStepLine(stepName, `Step '${stepName}': 'validation_exhaustion' must be an object`));
             }
             else {
                 const exhaustionBlock = step['validation_exhaustion'];
@@ -793,28 +941,29 @@ function parseWorkflowString(content, registry, opts) {
                     code: 'UNKNOWN_VALIDATION_EXHAUSTION_KEY',
                     step: stepName,
                     noun: 'validation_exhaustion',
+                    positionOf: (key) => sourceMap.posOf(['steps', stepName, 'validation_exhaustion', key]),
                 }));
                 if ('threshold' in exhaustionBlock &&
                     (!Number.isInteger(exhaustionBlock['threshold']) ||
                         exhaustionBlock['threshold'] < 1)) {
-                    errors.push(`Step '${stepName}': 'validation_exhaustion.threshold' must be a positive integer ` +
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'validation_exhaustion.threshold' must be a positive integer ` +
                         `(1 is legal — it disables in-drive schema-repair, since the first rejection ` +
-                        `already meets it)`);
+                        `already meets it)`));
                 }
                 const modeValue = exhaustionBlock['mode'];
                 if (modeValue !== undefined && modeValue !== 'fail' && modeValue !== 'default') {
-                    errors.push(`Step '${stepName}': 'validation_exhaustion.mode' must be 'fail' or 'default' ` +
-                        `(got: ${JSON.stringify(modeValue)})`);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'validation_exhaustion.mode' must be 'fail' or 'default' ` +
+                        `(got: ${JSON.stringify(modeValue)})`));
                 }
                 const hasDefaultOutput = 'default_output' in exhaustionBlock;
                 if (modeValue === 'default') {
                     if (!hasDefaultOutput) {
-                        errors.push(`Step '${stepName}': 'validation_exhaustion.mode: default' requires ` +
-                            `'default_output' (nothing to substitute on exhaustion)`);
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'validation_exhaustion.mode: default' requires ` +
+                            `'default_output' (nothing to substitute on exhaustion)`));
                     }
                     else if (step['output_schema'] === undefined) {
-                        errors.push(`Step '${stepName}': 'validation_exhaustion.default_output' requires the step to ` +
-                            `declare 'output_schema' (an undeclared schema makes the default unvalidatable)`);
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'validation_exhaustion.default_output' requires the step to ` +
+                            `declare 'output_schema' (an undeclared schema makes the default unvalidatable)`));
                     }
                     else {
                         // B10 — load-time AJV proof: REUSE the runtime validator so the load-time verdict can
@@ -836,8 +985,8 @@ function parseWorkflowString(content, registry, opts) {
                                 : err instanceof Error
                                     ? err.message
                                     : String(err);
-                            errors.push(`Step '${stepName}': 'validation_exhaustion.default_output' does not validate ` +
-                                `against the step's own 'output_schema': ${detail}`);
+                            errors.push(withStepLine(stepName, `Step '${stepName}': 'validation_exhaustion.default_output' does not validate ` +
+                                `against the step's own 'output_schema': ${detail}`));
                         }
                     }
                 }
@@ -874,17 +1023,17 @@ function parseWorkflowString(content, registry, opts) {
         }
         // trace_schema is only valid on execution: agent steps.
         if (step['trace_schema'] !== undefined && step['execution'] !== 'agent') {
-            errors.push(`Step '${stepName}': 'trace_schema' is only valid on execution: agent steps`);
+            errors.push(withStepLine(stepName, `Step '${stepName}': 'trace_schema' is only valid on execution: agent steps`));
         }
         // trace_validation_mode is only valid on execution: agent steps.
         if (step['trace_validation_mode'] !== undefined && step['execution'] !== 'agent') {
-            errors.push(`Step '${stepName}': 'trace_validation_mode' is only valid on execution: agent steps`);
+            errors.push(withStepLine(stepName, `Step '${stepName}': 'trace_validation_mode' is only valid on execution: agent steps`));
         }
         // trace_validation_mode must be 'warn' or 'enforce' when provided.
         if (step['trace_validation_mode'] !== undefined &&
             step['trace_validation_mode'] !== 'warn' &&
             step['trace_validation_mode'] !== 'enforce') {
-            errors.push(`Step '${stepName}': invalid trace_validation_mode '${String(step['trace_validation_mode'])}'; must be 'warn' or 'enforce'`);
+            errors.push(withStepLine(stepName, `Step '${stepName}': invalid trace_validation_mode '${String(step['trace_validation_mode'])}'; must be 'warn' or 'enforce'`));
         }
         // issue #291 (authorable gate timeout — the FIRST validation the `gate:` block has ever had):
         // the E2 positive-integer checks on timeout_seconds/reminder_seconds/reminder_max, the
@@ -894,7 +1043,7 @@ function parseWorkflowString(content, registry, opts) {
         // trust value).
         if (step['gate'] !== undefined) {
             if (typeof step['gate'] !== 'object' || step['gate'] === null) {
-                errors.push(`Step '${stepName}': 'gate' must be an object`);
+                errors.push(withStepLine(stepName, `Step '${stepName}': 'gate' must be an object`));
             }
             else {
                 const gate = step['gate'];
@@ -905,25 +1054,26 @@ function parseWorkflowString(content, registry, opts) {
                     code: 'UNKNOWN_GATE_KEY',
                     step: stepName,
                     noun: 'gate',
+                    positionOf: (key) => sourceMap.posOf(['steps', stepName, 'gate', key]),
                 }));
                 // E2: timeout_seconds/reminder_seconds/reminder_max must each be a positive integer
                 // (yaml-loader :1164-1174 precedent — the SAME convention as retry.total_timeout_seconds).
                 if ('timeout_seconds' in gate &&
                     (!Number.isInteger(gate['timeout_seconds']) || gate['timeout_seconds'] <= 0)) {
-                    errors.push(`Step '${stepName}': 'gate.timeout_seconds' must be a positive integer`);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'gate.timeout_seconds' must be a positive integer`));
                 }
                 if ('reminder_seconds' in gate &&
                     (!Number.isInteger(gate['reminder_seconds']) || gate['reminder_seconds'] <= 0)) {
-                    errors.push(`Step '${stepName}': 'gate.reminder_seconds' must be a positive integer`);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'gate.reminder_seconds' must be a positive integer`));
                 }
                 if ('reminder_max' in gate &&
                     (!Number.isInteger(gate['reminder_max']) || gate['reminder_max'] <= 0)) {
-                    errors.push(`Step '${stepName}': 'gate.reminder_max' must be a positive integer`);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'gate.reminder_max' must be a positive integer`));
                 }
                 // on_expiry must be 'settle_default' or 'abort' when provided.
                 const onExpiry = gate['on_expiry'];
                 if (onExpiry !== undefined && onExpiry !== 'settle_default' && onExpiry !== 'abort') {
-                    errors.push(`Step '${stepName}': 'gate.on_expiry' must be 'settle_default' or 'abort' (got: ${JSON.stringify(onExpiry)})`);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'gate.on_expiry' must be 'settle_default' or 'abort' (got: ${JSON.stringify(onExpiry)})`));
                 }
                 // default_choice: REQUIRED iff on_expiry === 'settle_default' (E2-style hard error,
                 // mirroring validation_exhaustion.mode:'default' requiring default_output); validated
@@ -934,8 +1084,8 @@ function parseWorkflowString(content, registry, opts) {
                 const hasDefaultChoice = 'default_choice' in gate;
                 if (onExpiry === 'settle_default') {
                     if (!hasDefaultChoice) {
-                        errors.push(`Step '${stepName}': 'gate.on_expiry: settle_default' requires 'gate.default_choice' ` +
-                            `(nothing to resolve the gate with on expiry)`);
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'gate.on_expiry: settle_default' requires 'gate.default_choice' ` +
+                            `(nothing to resolve the gate with on expiry)`));
                     }
                     else {
                         const choicesRaw = gate['choices'] ??
@@ -944,8 +1094,8 @@ function parseWorkflowString(content, registry, opts) {
                             ? choicesRaw
                             : ['approve', 'reject'];
                         if (!effectiveChoices.includes(gate['default_choice'])) {
-                            errors.push(`Step '${stepName}': 'gate.default_choice' (${JSON.stringify(gate['default_choice'])}) ` +
-                                `is not one of the step's effective choices: ${effectiveChoices.join(', ')}`);
+                            errors.push(withStepLine(stepName, `Step '${stepName}': 'gate.default_choice' (${JSON.stringify(gate['default_choice'])}) ` +
+                                `is not one of the step's effective choices: ${effectiveChoices.join(', ')}`));
                         }
                     }
                 }
@@ -995,13 +1145,13 @@ function parseWorkflowString(content, registry, opts) {
             if (typeof services !== 'object' ||
                 services === null ||
                 !(step['uses_service'] in services)) {
-                errors.push(`Step '${stepName}': uses_service '${step['uses_service']}' is not defined in 'services'`);
+                errors.push(withStepLine(stepName, `Step '${stepName}': uses_service '${step['uses_service']}' is not defined in 'services'`));
             }
         }
         // Validate retry: backoff must be a recognised value when present.
         if (step['retry'] !== undefined) {
             if (typeof step['retry'] !== 'object' || step['retry'] === null) {
-                errors.push(`Step '${stepName}': 'retry' must be an object`);
+                errors.push(withStepLine(stepName, `Step '${stepName}': 'retry' must be an object`));
             }
             else {
                 const retry = step['retry'];
@@ -1013,29 +1163,30 @@ function parseWorkflowString(content, registry, opts) {
                     code: 'UNKNOWN_RETRY_KEY',
                     step: stepName,
                     noun: 'retry',
+                    positionOf: (key) => sourceMap.posOf(['steps', stepName, 'retry', key]),
                 }));
                 if ('backoff' in retry &&
                     retry['backoff'] !== 'fixed' &&
                     retry['backoff'] !== 'linear' &&
                     retry['backoff'] !== 'exponential') {
-                    errors.push(`Step '${stepName}': 'retry.backoff' must be 'fixed', 'linear', or 'exponential'`);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'retry.backoff' must be 'fixed', 'linear', or 'exponential'`));
                 }
                 if ('max_attempts' in retry &&
                     (!Number.isInteger(retry['max_attempts']) || retry['max_attempts'] < 1)) {
-                    errors.push(`Step '${stepName}': 'retry.max_attempts' must be a positive integer`);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'retry.max_attempts' must be a positive integer`));
                 }
                 if ('base_delay_ms' in retry &&
                     (typeof retry['base_delay_ms'] !== 'number' || retry['base_delay_ms'] < 0)) {
-                    errors.push(`Step '${stepName}': 'retry.base_delay_ms' must be a non-negative number`);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'retry.base_delay_ms' must be a non-negative number`));
                 }
                 if ('max_delay_ms' in retry &&
                     (typeof retry['max_delay_ms'] !== 'number' || retry['max_delay_ms'] < 0)) {
-                    errors.push(`Step '${stepName}': 'retry.max_delay_ms' must be a non-negative number`);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'retry.max_delay_ms' must be a non-negative number`));
                 }
                 // --- issue #140: on_timeout / total_timeout_seconds --------------------------------
                 // E3: on_timeout must be a boolean (kills the 'on_timeout: "true"' silent-inert case).
                 if ('on_timeout' in retry && typeof retry['on_timeout'] !== 'boolean') {
-                    errors.push(`Step '${stepName}': 'retry.on_timeout' must be a boolean`);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'retry.on_timeout' must be a boolean`));
                 }
                 // E2: total_timeout_seconds must be a positive integer — same convention as
                 // timeout_seconds (0 is rejected here at load; a hand-built definition bypassing the
@@ -1043,16 +1194,16 @@ function parseWorkflowString(content, registry, opts) {
                 if ('total_timeout_seconds' in retry &&
                     (!Number.isInteger(retry['total_timeout_seconds']) ||
                         retry['total_timeout_seconds'] <= 0)) {
-                    errors.push(`Step '${stepName}': 'retry.total_timeout_seconds' must be a positive integer`);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'retry.total_timeout_seconds' must be a positive integer`));
                 }
                 // E1: on_timeout: true requires idempotent: true — declared, never inferred. Strict
                 // `=== true` on both loci, provably matching the engine's own conjunct.
                 if (retry['on_timeout'] === true && step['idempotent'] !== true) {
-                    errors.push(`Step '${stepName}': 'retry.on_timeout: true' requires 'idempotent: true' declared ` +
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'retry.on_timeout: true' requires 'idempotent: true' declared ` +
                         `on the step — a timeout-retry can run concurrently with the still-in-flight ` +
                         `original attempt, so the step must explicitly attest that any partial prior ` +
                         `application is harmless to re-apply. Declare 'idempotent: true' or remove ` +
-                        `'on_timeout'.`);
+                        `'on_timeout'.`));
                 }
                 // W5 (CAP-ONLY advisory — the on_timeout half of this is already an E1 hard error, so
                 // it never reaches here as a warning): the total-time cap only bounds `execution: 'auto'`
@@ -1142,15 +1293,22 @@ function parseWorkflowString(content, registry, opts) {
             }
         }
         if ('service_method' in step && !VALID_SERVICE_METHODS.has(step['service_method'])) {
-            errors.push(`Step '${stepName}': invalid service_method '${String(step['service_method'])}'; must be 'fetch', 'create', 'update', or 'delete'`);
+            errors.push(withStepLine(stepName, `Step '${stepName}': invalid service_method '${String(step['service_method'])}'; must be 'fetch', 'create', 'update', or 'delete'`));
         }
         // Validate input_map: only valid on execution: auto steps (both uses_service and handler).
         if (step['input_map'] !== undefined) {
             if (step['execution'] !== 'auto') {
-                errors.push(`Step '${stepName}': 'input_map' is only valid on execution: auto steps`);
+                errors.push(withStepLine(stepName, `Step '${stepName}': 'input_map' is only valid on execution: auto steps`));
             }
             else {
-                validateInputMapNode(step['input_map'], `Step '${stepName}': input_map`, errors, 0);
+                // issue #392: input_map's errors are minted deep inside a recursive walk that knows only
+                // its path string, not the step's position. Collected here and suffixed on the way out,
+                // so ONE step's error list never mixes positioned and bare messages — a reader seeing
+                // "(line 12)" on three of five errors would reasonably wonder what is different about
+                // the other two, and nothing is.
+                const inputMapErrors = [];
+                validateInputMapNode(step['input_map'], `Step '${stepName}': input_map`, inputMapErrors, 0);
+                errors.push(...inputMapErrors.map((e) => withStepLine(stepName, e)));
             }
         }
         // Step config may hold any JSON value (scalars, arrays, nested objects). It is passed through
@@ -1164,14 +1322,14 @@ function parseWorkflowString(content, registry, opts) {
             const adapterName = service?.['adapter'];
             const adapter = adapterName !== undefined ? registry?.getAdapter(adapterName) : undefined;
             if (adapter !== undefined && adapter.config_schema === undefined) {
-                errors.push(`Step '${stepName}': 'config' declared but adapter '${adapterName}' does not declare 'config_schema'`);
+                errors.push(withStepLine(stepName, `Step '${stepName}': 'config' declared but adapter '${adapterName}' does not declare 'config_schema'`));
             }
             else if (adapter?.config_schema !== undefined) {
                 const ajv = new Ajv();
                 const valid = ajv.validate(adapter.config_schema, step['config']);
                 if (!valid) {
                     const errMessages = ajv.errors?.map((e) => e.message ?? '').join('; ') ?? 'unknown error';
-                    errors.push(`Step '${stepName}': config validation failed against adapter config_schema: ${errMessages}`);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': config validation failed against adapter config_schema: ${errMessages}`));
                 }
             }
         }
@@ -1182,8 +1340,8 @@ function parseWorkflowString(content, registry, opts) {
             if (handler !== undefined && handler.uses_resources !== undefined) {
                 for (const resourceStepId of handler.uses_resources) {
                     if (!(resourceStepId in stepsRaw)) {
-                        errors.push(`Step '${stepName}': handler '${handlerName}' declares uses_resources '${resourceStepId}' ` +
-                            `but no step with that ID exists in this workflow`);
+                        errors.push(withStepLine(stepName, `Step '${stepName}': handler '${handlerName}' declares uses_resources '${resourceStepId}' ` +
+                            `but no step with that ID exists in this workflow`));
                     }
                 }
             }
@@ -1191,31 +1349,31 @@ function parseWorkflowString(content, registry, opts) {
         // Validate trigger_rule.
         if ('trigger_rule' in step) {
             if (!VALID_TRIGGER_RULES.has(step['trigger_rule'])) {
-                errors.push(`Step '${stepName}': invalid trigger_rule '${String(step['trigger_rule'])}'; must be one of ${[...VALID_TRIGGER_RULES].join(', ')}`);
+                errors.push(withStepLine(stepName, `Step '${stepName}': invalid trigger_rule '${String(step['trigger_rule'])}'; must be one of ${[...VALID_TRIGGER_RULES].join(', ')}`));
             }
         }
         // Validate depends_on: must be an array of existing step names.
         if ('depends_on' in step && step['depends_on'] !== undefined) {
             if (!Array.isArray(step['depends_on'])) {
-                errors.push(`Step '${stepName}': 'depends_on' must be an array`);
+                errors.push(withStepLine(stepName, `Step '${stepName}': 'depends_on' must be an array`));
             }
             else {
                 for (const dep of step['depends_on']) {
                     if (typeof dep !== 'string') {
-                        errors.push(`Step '${stepName}': depends_on entries must be strings`);
+                        errors.push(withStepLine(stepName, `Step '${stepName}': depends_on entries must be strings`));
                     }
                     else if (dep === stepName) {
-                        errors.push(`Step '${stepName}': a step cannot depend on itself`);
+                        errors.push(withStepLine(stepName, `Step '${stepName}': a step cannot depend on itself`));
                     }
                     else if (!(dep in stepsRaw)) {
-                        errors.push(`Step '${stepName}': depends_on references unknown step '${dep}'`);
+                        errors.push(withStepLine(stepName, `Step '${stepName}': depends_on references unknown step '${dep}'`));
                     }
                     else if (stepsRaw[dep]['execution'] === 'finalizer') {
                         // A domain step depending on a held-out finalizer would deadlock: the finalizer
                         // never enters the eligible set, so this step never becomes eligible and the run
                         // never seals.
-                        errors.push(`Step '${stepName}': depends_on references finalizer step '${dep}' — finalizers ` +
-                            `run at the terminal transition and are held out of the DAG; a step cannot depend on one.`);
+                        errors.push(withStepLine(stepName, `Step '${stepName}': depends_on references finalizer step '${dep}' — finalizers ` +
+                            `run at the terminal transition and are held out of the DAG; a step cannot depend on one.`));
                     }
                 }
             }
@@ -1225,29 +1383,29 @@ function parseWorkflowString(content, registry, opts) {
             const rawWhen = step['when'];
             if (typeof rawWhen === 'string') {
                 if (rawWhen.trim() === '') {
-                    errors.push(`Step '${stepName}': 'when' must be a non-empty string`);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'when' must be a non-empty string`));
                 }
                 else {
-                    validateConditionLeaf('when', rawWhen, stepName, dependsOn, errors);
+                    validateConditionLeaf('when', rawWhen, stepName, dependsOn, errors, withStepLine);
                 }
             }
             else if (Array.isArray(rawWhen)) {
                 if (rawWhen.length === 0) {
-                    errors.push(`Step '${stepName}': 'when' array must not be empty`);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'when' array must not be empty`));
                 }
                 else {
                     for (const leaf of rawWhen) {
                         if (typeof leaf !== 'string' || leaf.trim() === '') {
-                            errors.push(`Step '${stepName}': 'when' array entries must be non-empty strings`);
+                            errors.push(withStepLine(stepName, `Step '${stepName}': 'when' array entries must be non-empty strings`));
                         }
                         else {
-                            validateConditionLeaf('when', leaf, stepName, dependsOn, errors);
+                            validateConditionLeaf('when', leaf, stepName, dependsOn, errors, withStepLine);
                         }
                     }
                 }
             }
             else {
-                errors.push(`Step '${stepName}': 'when' must be a string or an array of strings`);
+                errors.push(withStepLine(stepName, `Step '${stepName}': 'when' must be a string or an array of strings`));
             }
         }
         // Validate abort_unless leaf shape (guard steps only; the LEGACY depends_on/run.params
@@ -1257,29 +1415,29 @@ function parseWorkflowString(content, registry, opts) {
             const rawAbort = step['abort_unless'];
             if (typeof rawAbort === 'string') {
                 if (rawAbort.trim() === '') {
-                    errors.push(`Step '${stepName}': 'abort_unless' must be a non-empty string`);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'abort_unless' must be a non-empty string`));
                 }
                 else {
-                    validateConditionLeaf('abort_unless', rawAbort, stepName, dependsOn, errors);
+                    validateConditionLeaf('abort_unless', rawAbort, stepName, dependsOn, errors, withStepLine);
                 }
             }
             else if (Array.isArray(rawAbort)) {
                 if (rawAbort.length === 0) {
-                    errors.push(`Step '${stepName}': 'abort_unless' array must not be empty`);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': 'abort_unless' array must not be empty`));
                 }
                 else {
                     for (const leaf of rawAbort) {
                         if (typeof leaf !== 'string' || leaf.trim() === '') {
-                            errors.push(`Step '${stepName}': 'abort_unless' array entries must be non-empty strings`);
+                            errors.push(withStepLine(stepName, `Step '${stepName}': 'abort_unless' array entries must be non-empty strings`));
                         }
                         else {
-                            validateConditionLeaf('abort_unless', leaf, stepName, dependsOn, errors);
+                            validateConditionLeaf('abort_unless', leaf, stepName, dependsOn, errors, withStepLine);
                         }
                     }
                 }
             }
             else {
-                errors.push(`Step '${stepName}': 'abort_unless' must be a string or an array of strings`);
+                errors.push(withStepLine(stepName, `Step '${stepName}': 'abort_unless' must be a string or an array of strings`));
             }
         }
         // Validate preconditions leaf shape (each must be a single comparison). Reference check is
@@ -1288,15 +1446,15 @@ function parseWorkflowString(content, registry, opts) {
         if (step['preconditions'] !== undefined) {
             const rawPre = step['preconditions'];
             if (!Array.isArray(rawPre)) {
-                errors.push(`Step '${stepName}': 'preconditions' must be an array of strings`);
+                errors.push(withStepLine(stepName, `Step '${stepName}': 'preconditions' must be an array of strings`));
             }
             else {
                 for (const leaf of rawPre) {
                     if (typeof leaf !== 'string' || leaf.trim() === '') {
-                        errors.push(`Step '${stepName}': 'preconditions' entries must be non-empty strings`);
+                        errors.push(withStepLine(stepName, `Step '${stepName}': 'preconditions' entries must be non-empty strings`));
                     }
                     else {
-                        validateConditionLeaf('preconditions', leaf, stepName, dependsOn, errors);
+                        validateConditionLeaf('preconditions', leaf, stepName, dependsOn, errors, withStepLine);
                     }
                 }
             }
@@ -1337,11 +1495,19 @@ function parseWorkflowString(content, registry, opts) {
                     leaves: step['execution'] === 'guard' ? asLeaves(step['abort_unless']) : [],
                 },
                 // `preconditions` is collected for EVERY step kind, but it is INERT on a guard: the sole
-                // `checkPreconditions` call site is `executeStep` (execution-loop.ts:1371), and a guard
+                // `checkPreconditions` call site is `executeStep` (execution-loop.ts:1380), and a guard
                 // goes through `executeGuardStep`, which evaluates only `abort_unless`. That is why the
                 // guard arm's consequence below is forked — collapsing it back into one shared string
-                // would make the error claim a wedge that cannot happen. (The inertness itself is a real
-                // adjacent gap, tracked as issue #369; this check only refuses to lie about it.)
+                // would make the error claim a wedge that cannot happen.
+                //
+                // Post-#369 a guard declaring `preconditions` is REFUSED outright by the guard block
+                // above, so this arm now only ever fires ALONGSIDE that refusal: errors accumulate rather
+                // than short-circuit, and the guard block runs first, so both messages reach the author
+                // with the prohibition printed above this one. The arm is kept, not deleted — it is what
+                // stops the dead-condition message from claiming a wedge that a guard cannot have, and a
+                // definition reaching this code by any path other than a fresh YAML load (a
+                // store-registered definition, an inline object) is never re-parsed and never sees the
+                // prohibition at all.
                 { surface: 'preconditions', leaves: asLeaves(step['preconditions']) },
             ];
             for (const { surface, leaves } of surfaces) {
@@ -1391,9 +1557,9 @@ function parseWorkflowString(content, registry, opts) {
                             : `a guard runs under ${ruleText} and 'trigger_rule' is not a valid field on ` +
                                 `execution: guard steps, so '${dep}' has always succeeded by the time this is ` +
                                 `evaluated (${consequence})`;
-                        errors.push(`Step '${stepName}': '${surface}' condition "${leaf}" can never be true — ${cause}. ` +
+                        errors.push(withStepLine(stepName, `Step '${stepName}': '${surface}' condition "${leaf}" can never be true — ${cause}. ` +
                             `Guards run only when their dependencies succeeded; for work that must happen AFTER a ` +
-                            `failure, use an 'execution: finalizer' step (see issue #366 for widening guards).`);
+                            `failure, use an 'execution: finalizer' step (see issue #366 for widening guards).`));
                     }
                     else {
                         const remedies = ['all_done', 'one_failed'];
@@ -1402,10 +1568,10 @@ function parseWorkflowString(content, registry, opts) {
                         const tail = new Set(dependsOn).size > 1
                             ? ` ('all_failed' fires only if EVERY dependency fails; 'one_success' only if at least one other dependency succeeds.)`
                             : '';
-                        errors.push(`Step '${stepName}': '${surface}' condition "${leaf}" can never be true — under ` +
+                        errors.push(withStepLine(stepName, `Step '${stepName}': '${surface}' condition "${leaf}" can never be true — under ` +
                             `${ruleText} trigger rule, '${dep}' can never be in failed_steps when this step is ` +
                             `evaluated (${consequence}). To run this step when '${dep}' fails, set trigger_rule to ` +
-                            `one of: ${remedies.join(', ')}.${tail}`);
+                            `one of: ${remedies.join(', ')}.${tail}`));
                     }
                 }
             }
@@ -1413,20 +1579,54 @@ function parseWorkflowString(content, registry, opts) {
         // Validate tools: only valid on execution: agent steps without handler.
         if (step['tools'] !== undefined &&
             (step['execution'] !== 'agent' || step['handler'] !== undefined)) {
-            errors.push(`Step '${stepName}': 'tools' is only valid on execution: agent steps without 'handler' defined`);
+            errors.push(withStepLine(stepName, `Step '${stepName}': 'tools' is only valid on execution: agent steps without 'handler' defined`));
+        }
+        // issue #413: `tool_timeout` requires `tools`. It bounds ONE tool call inside the agentic
+        // loop (run-agent.ts), and a step with no tools never enters that loop — so the key sits
+        // there bounding nothing while its author believes tool calls are capped.
+        //
+        // An EMPTY list counts as missing, and that is not pedantry: run-agent gates the tools path
+        // on `tools.length > 0`, so `tools: []` is exactly as toolless at runtime as no key at all.
+        // This one helper is also the shape check's complement further down, which is what makes
+        // "exactly one error" true by construction rather than by coincidence.
+        //
+        // NOT extended to non-array `tools` spellings — that is #391, still open. Under the
+        // `!toolsMissing` complement below, a non-array `tools` still lets the shape check fire, so
+        // nothing is silently exempted here.
+        const toolsMissing = step['tools'] === undefined ||
+            (Array.isArray(step['tools']) && step['tools'].length === 0);
+        if (step['tool_timeout'] !== undefined && toolsMissing) {
+            errors.push(withKeyLine(stepName, 'tool_timeout', `Step '${stepName}': 'tool_timeout' requires 'tools' (a declared, non-empty list) — ` +
+                'without tool calls there is ' +
+                'nothing for it to bound, so the step would carry a bound with nothing to bind. ' +
+                "In realm's own drive each tool call is capped at tool_timeout seconds (default " +
+                '30); declare at least one tool or remove the key.'));
         }
         // Validate tools: requires input_schema.
         if (step['tools'] !== undefined && step['input_schema'] === undefined) {
-            errors.push(`Step '${stepName}': 'tools' requires 'input_schema' to be defined — the agentic loop needs a schema for final output extraction`);
+            errors.push(withStepLine(stepName, `Step '${stepName}': 'tools' requires 'input_schema' to be defined — the agentic loop needs a schema for final output extraction`));
         }
         // Validate tools: entries must be in server_id:tool_name format.
         if (step['tools'] !== undefined && Array.isArray(step['tools'])) {
             for (const entry of step['tools']) {
                 if (!/^[^:]+:[^:]+$/.test(entry)) {
-                    errors.push(`Step '${stepName}': tools entry '${entry}' must be in 'server_id:tool_name' format`);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': tools entry '${entry}' must be in 'server_id:tool_name' format`));
                 }
             }
         }
+        // issue #338: the check below only runs when an `mcp_servers` block EXISTS, so the absent-block
+        // variant loaded clean — and every disclosure this loader has for tools lives inside that same
+        // fork, so the corner produced no error, no warning, and a run where the declared tools were
+        // simply never offered. ONE error per step, not one per entry: the entries are not individually
+        // wrong, the workflow is.
+        if (step['tools'] !== undefined &&
+            Array.isArray(step['tools']) &&
+            step['tools'].length > 0 &&
+            !Array.isArray(doc['mcp_servers'])) {
+            errors.push(withStepLine(stepName, `Step '${stepName}': declares tools but the workflow defines no mcp_servers — no drive ` +
+                `can ever offer these tools, so the declaration can never be satisfied. Define an ` +
+                `mcp_servers block, or remove 'tools'.`));
+        }
         // Validate tools: server_id must reference a defined mcp_server.
         if (step['tools'] !== undefined &&
             Array.isArray(step['tools']) &&
@@ -1435,33 +1635,43 @@ function parseWorkflowString(content, registry, opts) {
             for (const entry of step['tools']) {
                 const serverId = entry.split(':')[0] ?? '';
                 if (!serverIds.has(serverId)) {
-                    errors.push(`Step '${stepName}': tools entry '${entry}' references unknown MCP server '${serverId}'`);
+                    errors.push(withStepLine(stepName, `Step '${stepName}': tools entry '${entry}' references unknown MCP server '${serverId}'`));
                 }
             }
         }
         // Validate max_tool_calls: must be a positive integer.
         if (step['max_tool_calls'] !== undefined &&
             (!Number.isInteger(step['max_tool_calls']) || step['max_tool_calls'] <= 0)) {
-            errors.push(`Step '${stepName}': 'max_tool_calls' must be a positive integer`);
+            errors.push(withStepLine(stepName, `Step '${stepName}': 'max_tool_calls' must be a positive integer`));
         }
         // Validate max_fan_out: must be a positive integer.
         if (step['max_fan_out'] !== undefined &&
             (!Number.isInteger(step['max_fan_out']) || step['max_fan_out'] <= 0)) {
-            errors.push(`Step '${stepName}': 'max_fan_out' must be a positive integer`);
-        }
-        // Validate tool_timeout: must be a positive integer.
+            errors.push(withStepLine(stepName, `Step '${stepName}': 'max_fan_out' must be a positive integer`));
+        }
+        // Validate tool_timeout: must be a positive integer. Skipped where the key is not valid at
+        // all (issue #413's requires-tools check above already reported that) — the same convention
+        // as `timeout_seconds` below: an author told BOTH that the key does not belong here and that
+        // its value has the wrong shape is being pointed at the shape, which is not the problem.
+        // The `!toolsMissing` complement is the SAME helper the prohibition keys on, so the two are
+        // exhaustive and disjoint by construction: `tools: []` with a negative value reports once.
         if (step['tool_timeout'] !== undefined &&
+            !toolsMissing &&
             (!Number.isInteger(step['tool_timeout']) || step['tool_timeout'] <= 0)) {
-            errors.push(`Step '${stepName}': 'tool_timeout' must be a positive integer`);
+            errors.push(withStepLine(stepName, `Step '${stepName}': 'tool_timeout' must be a positive integer`));
         }
         // Validate timeout_seconds: must be a positive integer (issue A3). Skipped on
         // execution: guard — the guard-prohibited-fields check above already flatly rejects
         // 'timeout_seconds' there ('is not valid on execution: guard steps'); re-checking its
         // shape here would double-report the same root cause under a second, confusing message.
+        // Same suppression for the agent prohibition (issue #402), for the same reason: an author
+        // told BOTH that the key is invalid here and that its value has the wrong shape is being
+        // pointed at the shape, which is not the problem.
         if (step['timeout_seconds'] !== undefined &&
             step['execution'] !== 'guard' &&
+            step['execution'] !== 'agent' &&
             (!Number.isInteger(step['timeout_seconds']) || step['timeout_seconds'] <= 0)) {
-            errors.push(`Step '${stepName}': 'timeout_seconds' must be a positive integer`);
+            errors.push(withStepLine(stepName, `Step '${stepName}': 'timeout_seconds' must be a positive integer`));
         }
     }
     // Require at least one non-finalizer step: a workflow of only finalizers is meaningless