agents-relay 2.0.246 → 2.0.248

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -2,7 +2,7 @@ import { createHash, randomUUID } from 'node:crypto';
2
2
  import { readFile, realpath, stat } from 'node:fs/promises';
3
3
  import { resolve, relative, isAbsolute, sep, dirname, basename, join } from 'node:path';
4
4
  import { once } from 'node:events';
5
- import { pathToFileURL } from 'node:url';
5
+ import { runShortcutRevisionNode } from './shortcut-node-revision.js';
6
6
  import { spawnOwnedProcess } from './owned-process.js';
7
7
  import { validateShortcutStageGate } from './shortcut-stage-contract.js';
8
8
  import { parseAgentGraph } from './agent-graph.js';
@@ -228,9 +228,7 @@ export async function runAgentShortcut(options) {
228
228
  throw new Error(`Durable shortcut receipt ${nodeId} no longer matches its wait, execution, or content fingerprint`);
229
229
  }
230
230
  state.inFlight ??= {};
231
- // A host-bound human review suspends the parent Task *during* an in-flight
232
- // Shortcut module call. The exact accepted invocation authorizes replaying
233
- // only that node after the same Task is requeued by the lifecycle Graph.
231
+ // An accepted human invocation authorizes replay of only its in-flight node.
234
232
  let resumedReview = null;
235
233
  if (currentTask.state === 'QUEUED' && Object.keys(state.inFlight).length > 0) {
236
234
  const pending = Object.entries(state.inFlight);
@@ -373,9 +371,7 @@ export async function runAgentShortcut(options) {
373
371
  const stopHeartbeat = () => { clearInterval(heartbeat); options.signal?.removeEventListener('abort', abortFromCaller); };
374
372
  const emit = (event) => options.onNodeEvent?.({ ...event, timestamp: new Date().toISOString() });
375
373
  try {
376
- // The existing Graph executor owns node readiness for both code and model
377
- // nodes. Model nodes execute using Relay's existing durable Worker adapter,
378
- // never by routing the entire Agent Graph to one Worker.
374
+ // Graph executor runs Script and model nodes through their respective adapters.
379
375
  const missing = shortcuts.filter(item => !item.path);
380
376
  if (missing.length && !options.runModelNode)
381
377
  return await fail(`Incomplete Agent Graph shortcut coverage: ${missing.map(item => item.nodeId).join(', ')}`);
@@ -403,11 +399,13 @@ export async function runAgentShortcut(options) {
403
399
  return runCommand(args, cwd, executionAbort.signal);
404
400
  };
405
401
  emit({ nodeId: id, type: 'progress', data: { phase: shortcut ? 'shortcut.invoke' : 'worker.invoke' } });
402
+ const review = resumedReview?.nodeId === id ? resumedReview : null;
406
403
  const raw = await raceAbort(shortcut
407
- ? (async () => {
408
- const module = await import(pathToFileURL(shortcut).href);
409
- return module.run({ input: { ...safeShortcutTaskInput(task.input), projectPath, jobId: job.id, taskId: task.id, nodeId: id, agent: node.agent, predecessorOutputs, ...(resumedReview?.nodeId === id ? { reviewDecision: { status: resumedReview.status, revision: resumedReview.revision, invocationId: resumedReview.invocationId, feedback: resumedReview.feedback, comments: resumedReview.comments } } : {}) }, signal: executionAbort.signal, runCommand: trackedRunCommand });
410
- })()
404
+ ? runShortcutRevisionNode({ path: shortcut, signal: executionAbort.signal,
405
+ input: { ...safeShortcutTaskInput(task.input), projectPath, jobId: job.id, taskId: task.id, nodeId: id,
406
+ agent: node.agent, predecessorOutputs }, runCommand: trackedRunCommand,
407
+ modelNode: { id, agent: node.agent, predecessorOutputs, executionId: currentTask.executionId, signal: executionAbort.signal },
408
+ review, runModelNode: options.runModelNode, validOutput })
411
409
  : options.runModelNode({ id, agent: node.agent, predecessorOutputs, executionId: currentTask.executionId, signal: executionAbort.signal }), executionAbort.signal);
412
410
  if (leaseHeartbeatError)
413
411
  throw new Error(`Shortcut lease renewal failed: ${String(leaseHeartbeatError)}`);
@@ -87,7 +87,25 @@ export async function runShortcutJobCommand(args, id, makeRunner) {
87
87
  const projectRoot = await resolveManagedProjectPath(noGitHubMode(args) ? undefined : loaded.job.repository, arg(args, '--project-path') || loaded.job.projectPath || '', workspaceRoot);
88
88
  const projectPath = resolveRepositoryProjectPath(projectRoot, loaded.job.projectPath);
89
89
  const globalRoot = arg(args, '--global-root') || process.env.AGENTS_HOME || undefined;
90
- const missing = await missingShortcutNodes(task.agentGraph, projectPath, arg(args, '--shared-root') || process.env.AGENTS_RELAY_SHARED_ROOT || undefined, workspaceRoot, globalRoot);
90
+ const sharedRoot = arg(args, '--shared-root') || process.env.AGENTS_RELAY_SHARED_ROOT || undefined;
91
+ // The first trusted *explicit* invocation binds only resolved directories,
92
+ // not a command. Daemon recovery must never guess a Project path or execute
93
+ // argv serialized by an untrusted Task.
94
+ if (!loaded.store.mutateJob)
95
+ throw new Error('Shortcut Runner requires atomic context binding');
96
+ await loaded.store.mutateJob(id, current => {
97
+ if (current.executionMode !== 'shortcut' || current.state !== 'ACTIVE')
98
+ throw Error('Cannot bind context to an inactive Shortcut');
99
+ const ctx = { projectPath, workspaceRoot, ...(sharedRoot ? { sharedRoot } : {}), ...(globalRoot ? { globalRoot } : {}), noGitHub: noGitHubMode(args) };
100
+ const old = current.shortcutRunnerContext;
101
+ if (old && (old.projectPath !== ctx.projectPath || old.workspaceRoot !== ctx.workspaceRoot ||
102
+ old.sharedRoot !== ctx.sharedRoot || old.globalRoot !== ctx.globalRoot || old.noGitHub !== ctx.noGitHub))
103
+ throw Error('Shortcut context changed from its original trusted launch; refusing inconsistent resume');
104
+ if (!old)
105
+ current.shortcutRunnerContext = ctx;
106
+ return current;
107
+ });
108
+ const missing = await missingShortcutNodes(task.agentGraph, projectPath, sharedRoot, workspaceRoot, globalRoot);
91
109
  const previous = task.result?.data?.shortcut;
92
110
  if (previous?.workerFallback === true)
93
111
  throw new Error('Legacy whole-Graph Worker fallback is not compatible with per-node Shortcut execution; retain its original recovery ownership');
@@ -96,15 +114,18 @@ export async function runShortcutJobCommand(args, id, makeRunner) {
96
114
  process.once('SIGINT', onInterrupt);
97
115
  process.once('SIGTERM', onInterrupt);
98
116
  const execute = async (bus) => {
99
- const workerReconciler = missing.length && bus && makeRunner ? makeRunner(loaded.store, bus) : undefined;
117
+ const hasSemanticRevision = task?.state === 'QUEUED' && task.interactiveInvocation?.status === 'changes_requested' &&
118
+ Boolean(task.interactiveInvocation.decidedAt) &&
119
+ Object.values(task.result?.data?.shortcut?.inFlight ?? {}).includes(task.interactiveInvocation.executionId);
120
+ const workerReconciler = (missing.length || hasSemanticRevision) && bus && makeRunner ? makeRunner(loaded.store, bus) : undefined;
100
121
  const unwatch = workerReconciler ? await workerReconciler.watch(id) : undefined;
101
122
  try {
102
123
  const result = await runAgentShortcut({ store: loaded.store, job: loaded.job, task, projectPath,
103
- sharedRoot: arg(args, '--shared-root') || process.env.AGENTS_RELAY_SHARED_ROOT || undefined,
124
+ sharedRoot,
104
125
  workspaceRoot, globalRoot,
105
126
  concurrency: integerArg(args, '--concurrency', 4), signal: controller.signal,
106
127
  ...(resumeReceiptSelected ? { resumeReceiptSelected: true } : {}),
107
- ...(missing.length ? { runModelNode: node => {
128
+ ...((missing.length || hasSemanticRevision) ? { runModelNode: node => {
108
129
  if (!workerReconciler)
109
130
  throw new Error('Model-backed node requires a reachable EventBus and existing Relay Worker Adapter');
110
131
  return runShortcutModelNode({ store: loaded.store, reconciler: workerReconciler, jobId: id, parentTaskId: task.id, node });
@@ -124,7 +145,7 @@ export async function runShortcutJobCommand(args, id, makeRunner) {
124
145
  }
125
146
  };
126
147
  try {
127
- if (missing.length)
148
+ if (missing.length || (task?.state === 'QUEUED' && task.interactiveInvocation?.status === 'changes_requested' && Boolean(task.interactiveInvocation.decidedAt)))
128
149
  await withEventBus(args, execute);
129
150
  else
130
151
  await execute(undefined);
package/dist/pool.js CHANGED
@@ -58,17 +58,19 @@ export class RepositoryWorkerPool {
58
58
  makeReconciler;
59
59
  localInventory;
60
60
  resolveLocalJob;
61
+ onShortcutDecision;
61
62
  running = false;
62
63
  pending = false;
63
64
  reconcileLocks = new Map();
64
65
  coordinator;
65
66
  dispatchTail = Promise.resolve();
66
67
  watchedBus;
67
- constructor(concurrency, makeReconciler, localInventory, resolveLocalJob) {
68
+ constructor(concurrency, makeReconciler, localInventory, resolveLocalJob, onShortcutDecision) {
68
69
  this.concurrency = concurrency;
69
70
  this.makeReconciler = makeReconciler;
70
71
  this.localInventory = localInventory;
71
72
  this.resolveLocalJob = resolveLocalJob;
73
+ this.onShortcutDecision = onShortcutDecision;
72
74
  const reportCoordinatorError = (error, signal) => {
73
75
  observability().record({
74
76
  stage: 'reconcile', event: 'reconcile.coordinator_failed', level: 'error', outcome: 'failed',
@@ -149,6 +151,12 @@ export class RepositoryWorkerPool {
149
151
  if (signal.event.type === 'github.webhook')
150
152
  continue;
151
153
  const outcome = await reconciler.applyEvent(signal.event);
154
+ // The decision is durably applied before invoking the Shortcut CLI hook.
155
+ // A replay can also wake a still-QUEUED Task without a new decision.
156
+ if (signal.event.type === 'task.interactive_decision' &&
157
+ ['task.interactive_decision.accepted', 'task.interactive_decision.duplicate'].includes(outcome.reason) &&
158
+ await this.onShortcutDecision?.(jobId, signal.event.task_id))
159
+ continue;
152
160
  shouldReconcile ||= outcome.reconcile;
153
161
  }
154
162
  if (shouldReconcile)
@@ -160,6 +168,9 @@ export class RepositoryWorkerPool {
160
168
  for (const job of jobs) {
161
169
  if (capacity <= 0)
162
170
  break;
171
+ // Shortcut starts and review resumes are external CLI invocations, not normal Task dispatch.
172
+ if (job.executionMode === 'shortcut')
173
+ continue;
163
174
  const store = await this.requireLocalStore(job.id);
164
175
  await store.hydrate?.(job);
165
176
  const ready = job.tasks.filter(task => (task.state === 'QUEUED' && task.executionId === null) || (task.state === 'DRAFT' && task.dependencies.length > 0)).length;
package/dist/relayd.js CHANGED
@@ -10,6 +10,7 @@ import { ZAdapter } from './z-adapter.js';
10
10
  import { CodexThreadContinuation, CommandContinuation, WebhookContinuation } from './continuation.js';
11
11
  import { serveDashboard } from './dashboard.js';
12
12
  import { RepositoryWorkerPool } from './pool.js';
13
+ import { createShortcutReviewWake } from './shortcut-review-wake.js';
13
14
  import { Reconciler } from './reconciler.js';
14
15
  import { dashboardManagedJobs, GitHubStore, InMemoryStore, resolvePullRequest } from './store.js';
15
16
  import { GitHubProjectionWriter } from './projected-store.js';
@@ -391,7 +392,8 @@ export async function runDaemon(argv) {
391
392
  })();
392
393
  return githubBindingSyncInFlight;
393
394
  };
394
- const pool = new RepositoryWorkerPool(concurrency, makeReconciler, inventoryFromLocal, localJobBinding);
395
+ const shortcutReviewWake = createShortcutReviewWake(async (jobId) => (await localJobBinding(jobId))?.job ?? null);
396
+ const pool = new RepositoryWorkerPool(concurrency, makeReconciler, inventoryFromLocal, localJobBinding, shortcutReviewWake);
395
397
  const initial = cachedOverviews;
396
398
  const fallback = initial[0]?.job;
397
399
  const dashboardStore = fallback ? (await requireLocalJobBinding(fallback.id)).store : new InMemoryStore();
@@ -0,0 +1,21 @@
1
+ import { pathToFileURL } from 'node:url';
2
+ /** Preserve Script determinism: semantic owner feedback is resolved by its
3
+ * existing Agent Worker before the Script validates and requests re-review. */
4
+ export async function runShortcutRevisionNode(options) {
5
+ const { review } = options;
6
+ const module = await import(pathToFileURL(options.path).href);
7
+ let revisionWork;
8
+ if (review?.status === 'changes_requested') {
9
+ if (!options.runModelNode)
10
+ throw Error('Request Changes requires a bound Agent Worker; Shortcut script cannot perform a semantic revision');
11
+ revisionWork = await options.runModelNode({ ...options.modelNode, reviewDecision: { status: 'changes_requested',
12
+ revision: review.revision, invocationId: review.invocationId, feedback: review.feedback, comments: review.comments } });
13
+ if (!options.validOutput(revisionWork))
14
+ throw Error('Revision Worker did not return a completed Artifact result');
15
+ }
16
+ return module.run({ input: { ...options.input,
17
+ ...(review ? { reviewDecision: { status: review.status, revision: review.revision, invocationId: review.invocationId,
18
+ feedback: review.feedback, comments: review.comments } } : {}),
19
+ ...(revisionWork ? { reviewRevision: revisionWork } : {}) },
20
+ signal: options.signal, runCommand: options.runCommand });
21
+ }
@@ -11,13 +11,22 @@ export async function runShortcutModelNode(options) {
11
11
  throw new Error('Model nodes require the durable Relay SQLite store');
12
12
  if (!/^[A-Za-z_][\w.-]*$/.test(node.id))
13
13
  throw new Error('Invalid shortcut model node ID');
14
- const taskId = `shortcut-${parentTaskId}-${node.id}`;
14
+ const review = node.reviewDecision;
15
+ if (review && (!/^[a-f0-9]{40}$/.test(review.revision) || !/^[0-9a-f-]{36}$/i.test(review.invocationId)))
16
+ throw new Error('Invalid semantic Revision identity');
17
+ const taskId = `shortcut-${parentTaskId}-${node.id}${review ? '-revision-' + review.invocationId : ''}`;
15
18
  const initial = await store.load(jobId);
16
19
  const parent = initial.tasks.find(t => t.id === parentTaskId);
17
20
  if (!parent || parent.state !== 'RUNNING' || parent.executionId !== node.executionId || !parent.leaseOwner)
18
21
  throw new Error('Model node parent execution is not leased by Shortcut Runner');
19
22
  if (parent.output?.kind !== 'file' || !isAbsolute(parent.output.path))
20
23
  throw new Error('Model nodes require a canonical absolute Task output directory');
24
+ if (review) {
25
+ const recorded = parent.interactiveInvocation;
26
+ if (!recorded?.decidedAt || recorded.status !== 'changes_requested' ||
27
+ recorded.invocationId !== review.invocationId || recorded.revision !== review.revision)
28
+ throw new Error('Revision Worker requires the actual accepted Relay review');
29
+ }
21
30
  const runRoot = dirname(parent.output.path);
22
31
  const declaredRun = parent.input.match(/^- Canonical run:\s*(\/[^\r\n]+)$/m)?.[1]?.trim();
23
32
  if (declaredRun && resolve(declaredRun) !== resolve(runRoot))
@@ -44,9 +53,10 @@ export async function runShortcutModelNode(options) {
44
53
  if (state.nodes?.[node.id] || state.inFlight?.[node.id] !== node.executionId)
45
54
  throw new Error('Model node is no longer pending in the current Graph execution');
46
55
  state.workerNodes ??= {};
47
- if (state.workerNodes[node.id] && state.workerNodes[node.id] !== taskId)
56
+ const workerKey = review ? `${node.id}:revision:${review.invocationId}` : node.id;
57
+ if (state.workerNodes[workerKey] && state.workerNodes[workerKey] !== taskId)
48
58
  throw new Error('Conflicting durable Worker node mapping');
49
- state.workerNodes[node.id] = taskId;
59
+ state.workerNodes[workerKey] = taskId;
50
60
  const existing = current.tasks.find(t => t.id === taskId);
51
61
  if (existing) {
52
62
  if (existing.parentTaskId !== parentTaskId || existing.agentName !== node.agent || existing.output?.kind !== 'file' || existing.output.path !== outputPath)
@@ -57,12 +67,13 @@ export async function runShortcutModelNode(options) {
57
67
  const body = JSON.stringify({
58
68
  source: 'shortcut-graph-node', jobId, parentTaskId, nodeId: node.id, agent: node.agent,
59
69
  predecessorOutputs: node.predecessorOutputs,
70
+ ...(review ? { reviewDecision: review, revisionOf: { nodeId: node.id, commitSha: review.revision } } : {}),
60
71
  originalInput: active.input,
61
72
  ...(declaredRun ? { canonicalRunPath: declaredRun } : {}),
62
73
  ...(sourceRef ? { sourceEvidencePath: sourceRef } : {}),
63
74
  requiredResult: { status: 'COMPLETED', output: {}, artifacts: [] },
64
75
  outputPath,
65
- instruction: 'Execute only this Agent role for this DAG node. The ONLY structured DAG predecessor values are predecessorOutputs; never infer an undeclared sibling dependency. If canonicalRunPath is declared, read the authorized original source manifest and prior stage artifact files there as required by the project Agent/Stage contract; inspect and validate their real contents, source provenance, hashes and use rights. These files are allowed canonical run evidence, not an alternative DAG predecessor result and not proof of human approval. Do not claim they are absent merely because they are not repeated in predecessorOutputs. Write {status:"COMPLETED",output:{...},artifacts:[]} to outputPath only after meeting stage acceptance and send a correlated task.completed event. If a real prerequisite is unavailable, report the specific verified blocker and task.failed; do not fabricate, publish, approve or infer new permissions.'
76
+ instruction: review ? 'Revise only the existing Stage Artifact according to the human feedback within the Agent role, preserving source provenance; never invent evidence, approve, or publish. The parent Shortcut re-verifies and re-previews.' : 'Execute only this Agent role for this DAG node. The ONLY structured DAG predecessor values are predecessorOutputs; never infer an undeclared sibling dependency. If canonicalRunPath is declared, read the authorized original source manifest and prior stage artifact files there as required by the project Agent/Stage contract; inspect and validate their real contents, source provenance, hashes and use rights. These files are allowed canonical run evidence, not an alternative DAG predecessor result and not proof of human approval. Do not claim they are absent merely because they are not repeated in predecessorOutputs. Write {status:"COMPLETED",output:{...},artifacts:[]} to outputPath only after meeting stage acceptance and send a correlated task.completed event. If a real prerequisite is unavailable, report the specific verified blocker and task.failed; do not fabricate, publish, approve or infer new permissions.'
66
77
  });
67
78
  current.tasks.push(createTaskEntity(current, {
68
79
  jobId, id: taskId, title: `Shortcut model node ${node.id}`, kind: 'work', parentTaskId,
@@ -0,0 +1,64 @@
1
+ import { once } from 'node:events';
2
+ import { fileURLToPath } from 'node:url';
3
+ import { spawnOwnedProcess } from './owned-process.js';
4
+ import { errorMessage, observability } from './observability.js';
5
+ /** The interactive decision has already been applied by the canonical Relay
6
+ * handler. Invoke the *same* CLI a human would run, once per in-flight Job.
7
+ * No Shortcut scheduler, queue, or normal-Job Worker Pool dispatch required.
8
+ */
9
+ export function eligibleShortcutReviewTask(job, taskId) {
10
+ if (job.executionMode !== 'shortcut' || job.contentOnly !== true || job.state !== 'ACTIVE' || job.pause ||
11
+ !job.shortcutExecutionStartedAt || !job.shortcutRunnerContext?.projectPath ||
12
+ !job.shortcutRunnerContext.workspaceRoot)
13
+ return null;
14
+ const task = job.tasks.find(t => t.id === taskId);
15
+ if (!task?.agentGraph || task.state !== 'QUEUED' || task.executionId !== null || task.leaseOwner !== null)
16
+ return null;
17
+ const rev = task.interactiveInvocation;
18
+ const cp = task.result?.data?.shortcut;
19
+ const pending = Object.values(cp?.inFlight ?? {});
20
+ if (pending.length !== 1 || !rev?.decidedAt || !['approved', 'changes_requested'].includes(rev.status) ||
21
+ !/^[a-f0-9]{40}$/.test(rev.revision) || rev.executionId !== pending[0] || !rev.invocationId)
22
+ return null;
23
+ return task;
24
+ }
25
+ export async function launchShortcutReviewCLI(job, task) {
26
+ const ctx = job.shortcutRunnerContext;
27
+ if (!ctx)
28
+ throw Error('Missing trusted original Shortcut launch context');
29
+ const args = [fileURLToPath(new URL('./cli.js', import.meta.url)),
30
+ 'job', 'run', '--mode', 'shortcut', '--repo', job.repository, '--id', job.id, '--task-id', task.id,
31
+ '--project-path', ctx.projectPath, '--workspace-root', ctx.workspaceRoot,
32
+ ...(ctx.sharedRoot ? ['--shared-root', ctx.sharedRoot] : []),
33
+ ...(ctx.globalRoot ? ['--global-root', ctx.globalRoot] : []),
34
+ ...(ctx.noGitHub ? ['--no-github'] : [])];
35
+ const child = spawnOwnedProcess(process.execPath, args, { invocation: 'shortcut.review-resume',
36
+ correlation: { jobId: job.id, repository: job.repository, taskId: task.id },
37
+ spawn: { cwd: ctx.projectPath, stdio: ['ignore', 'pipe', 'pipe'], env: process.env } });
38
+ const stderr = [];
39
+ child.stderr?.on('data', chunk => { if (stderr.join('').length < 4000)
40
+ stderr.push(String(chunk).slice(0, 500)); });
41
+ child.stdout?.resume();
42
+ const [code, signal] = await once(child, 'close');
43
+ if (signal || (code !== 0 && code !== 3))
44
+ throw Error(`Shortcut CLI exited (${signal ?? code}): ${stderr.join('').slice(-1500)}`);
45
+ }
46
+ export function createShortcutReviewWake(loadJob, run = launchShortcutReviewCLI) {
47
+ const running = new Set();
48
+ return async (jobId, taskId) => {
49
+ const job = await loadJob(jobId);
50
+ if (!job || job.executionMode !== 'shortcut')
51
+ return false;
52
+ const task = eligibleShortcutReviewTask(job, taskId);
53
+ if (!task || running.has(jobId))
54
+ return true;
55
+ running.add(jobId);
56
+ // Return immediately to the event consumer: the CLI may wait on an Agent.
57
+ void run(job, task).catch(error => {
58
+ observability().record({ stage: 'reconcile', event: 'shortcut.review_resume_failed', level: 'error', outcome: 'failed',
59
+ message: 'Shortcut review CLI failed: ' + errorMessage(error),
60
+ correlation: { jobId, repository: job.repository, taskId } });
61
+ }).finally(() => running.delete(jobId));
62
+ return true;
63
+ };
64
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agents-relay",
3
- "version": "2.0.246",
3
+ "version": "2.0.248",
4
4
  "description": "Durable async agent jobs coordinated through GitHub pull requests",
5
5
  "repository": {
6
6
  "type": "git",
@@ -58,7 +58,7 @@ Job/Task/Execution source identity.
58
58
  Relay checks the pending invocation, persists RUNNING -> AWAITING_DECISION,
59
59
  clears the execution lease, and releases the Worker. This is a non-failure
60
60
  handoff and is not a Task completion or a Troubleshooter block.
61
- For Shortcut modules, a host-wrapped `markcut.preview` call uses the **original Shortcut Task identity**, not a reviewer child. The module returns `WAITING_REVIEW` only after the host has durably transitioned that Task to `AWAITING_DECISION`. The foreground runner exits with waiting status, keeping the in-flight node as a durable replay fence. After an authenticated accepted decision, the lifecycle requeues that same Task; a new foreground `job run --id ... --mode shortcut` resumes that node with the real `reviewDecision` in its input. Nonhuman `WAITING_EVENT` receipts are a different mechanism.
61
+ For Shortcut modules, a host-wrapped `markcut.preview` call uses the **original Shortcut Task identity**, not a reviewer child. The module returns `WAITING_REVIEW` only after the host has durably transitioned that Task to `AWAITING_DECISION`. The foreground runner exits with waiting status, keeping the in-flight node as a durable replay fence. After an authenticated accepted decision, the lifecycle requeues that same Task. The interactive decision event listener calls the same trusted Shortcut Runner CLI used for manual execution, immediately after Relay durably accepts the decision and requeues the original Task. It does not schedule Shortcuts through the normal Worker Pool. It never auto-starts draft or unlaunched Shortcut Jobs and does not add a separate Scheduler. On `changes_requested`, a Script node invokes its Agent's normal durable model Worker to revise existing Artifacts, then re-verifies and opens a new human Preview. `approved` continues the Graph. Nonhuman `WAITING_EVENT` receipts are a different mechanism.
62
62
 
63
63
  The Job stays ACTIVE; the Task does not requeue until a matching
64
64
  `task.interactive_decision` is durably accepted and the Task Graph selects