qlogicagent 2.20.2 → 2.20.4

package/dist/types/orchestration/goal-mode-adapters.d.ts

@@ -5,6 +5,18 @@ import type { ProductOrchestrator } from "./agent-instance.js";
 import type { HostRunStateAuthority } from "./run-state-host-authority.js";
 import type { LeaderPort, PhaseRunnerPort } from "./goal-loop-coordinator.js";
 import { type AcceptanceCriterion, type AcceptanceDelta, type PhaseSpec } from "./goal-run-types.js";
+export type GoalVerifyCommandValidation = {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+/**
+ * Persisted Goal verifiers are unattended acceptance contracts, not general-purpose shell scripts.
+ * Reject known stdin, interactive, host-specific and nondeterministic constructs before persistence;
+ * runVerifyDeltas repeats the check for old snapshots and defense in depth.
+ */
+export declare function validateGoalVerifyCommand(command: string): GoalVerifyCommandValidation;
 /**
  * #2 verify 输出的头尾截断:测试/构建命令的失败摘要通常在输出**末尾**(框架的 summary 行),裸
  * slice(0,N) 保头丢尾会把真正的失败原因截掉,判官只能看到无关的开头。超限时保留头尾各半,并在
@@ -110,6 +122,10 @@ export declare function parsePhaseSpec(reply: string, availableAgentIds: string[
  */
 export declare function validateAssessDeltas(rawDeltas: AcceptanceDelta[], changedFiles: string[], log?: {
     warn(msg: string): void;
+}, context?: {
+    criteria?: AcceptanceCriterion[];
+    outputTexts?: string[];
+    assignmentReceiptLines?: string[];
 }): AcceptanceDelta[];
 /**
  * #1②: the judge-prompt view of this phase's project changed files. The PROMPT is windowed to stay

package/dist/types/orchestration/goal-run-types.d.ts

@@ -20,6 +20,9 @@ export interface AcceptanceCriterion {
     id: string;
     criterion: string;
     status: AcceptanceStatus;
+    /** Output-only criteria (reply/copy/summary/etc.) are accepted from the Product task result text,
+     *  never by inventing a shell verifier or citing an unrelated file. */
+    evidenceSource?: "output" | "host.product.assignment";
     evidence?: AcceptanceEvidence[];
     reason?: string;
     verify?: string;
@@ -71,7 +74,7 @@ export interface GoalQueuedMessage {
 export interface GoalRunEvent {
     seq: number;
     ts: string;
-    type: "goal_started" | "phase_planned" | "phase_started" | "task_settled" | "phase_assessed" | "progress_compacted" | "goal_edited" | "message_queued" | "paused" | "resumed" | "stopped" | "phase_boundary" | "ended";
+    type: "goal_started" | "checklist_initialized" | "phase_planned" | "phase_started" | "task_settled" | "phase_assessed" | "progress_compacted" | "goal_edited" | "message_queued" | "paused" | "resumed" | "stopped" | "phase_boundary" | "round_message" | "ended";
     payload: Record<string, unknown>;
 }
 /** Derived Goal checkpoint stored by Gateway RunState, rebuildable by replaying events. */
@@ -83,6 +86,8 @@ export interface PersistedGoalRunState {
     currentGoal: string;
     goalUpdatedAt?: string;
     checklistVersion: number;
+    /** False only between the durable start acknowledgement and the detached leader initialization. */
+    checklistInitialized?: boolean;
     status: GoalRunStatus;
     pauseState: GoalPauseState;
     phaseIndex: number;

package/dist/types/orchestration/product-budget.d.ts

@@ -16,6 +16,27 @@ export interface BudgetCheck {
     elapsed: number;
     maxDuration?: number;
 }
+/**
+ * The persisted budget shape — SINGLE source of truth, owned here and consumed by
+ * product-persistence's execution and planning snapshots.
+ *
+ * It must stay round-trippable: `serialize()` is the only writer and `resume()` rebuilds the tracker
+ * from these exact fields. The ceilings are live state (raiseBudget mutates them), not construction
+ * config, so dropping them from the snapshot silently removes every guard from a resumed run.
+ */
+export interface PersistedBudgetState {
+    maxTotalTokens?: number;
+    maxDuration?: number;
+    usedTokens: number;
+    startedAt: number;
+    warningEmitted: boolean;
+    /**
+     * Absent on a planning snapshot: a planning session carries only the ceilings, and nothing has run
+     * yet, so there is no in/out split to record. Present on every execution snapshot.
+     */
+    inputTokens?: number;
+    outputTokens?: number;
+}
 export declare class ProductBudgetTracker {
     private maxTotalTokens?;
     private maxDuration?;
@@ -56,20 +77,18 @@ export declare class ProductBudgetTracker {
         maxTotalTokens?: number;
         maxDuration?: number;
     }): void;
-    /** Restore from persisted budget data. (input/output optional for back-compat with older snapshots.) */
-    restore(data: {
-        usedTokens: number;
-        startedAt: number;
-        warningEmitted: boolean;
-        inputTokens?: number;
-        outputTokens?: number;
-    }): void;
-    /** Serialize for persistence. */
-    serialize(): {
-        usedTokens: number;
-        startedAt: number;
-        warningEmitted: boolean;
-        inputTokens: number;
-        outputTokens: number;
-    };
+    /**
+     * Restore from persisted budget data. Also re-applies the persisted ceilings so a single
+     * `restore()` fully rebuilds the tracker — callers that already passed them to the constructor
+     * are unaffected (same values), and callers that forget can no longer end up unbounded.
+     * A planning snapshot has no in/out split yet, so those default to 0 rather than being required.
+     */
+    restore(data: PersistedBudgetState): void;
+    /**
+     * Serialize for persistence. MUST emit the ceilings: they are live state (raiseBudget mutates
+     * them) and resume() rebuilds the tracker from this snapshot alone. Omitting them made every
+     * resumed or rolled-back run unbounded, because check() short-circuits on a falsy ceiling.
+     * Absent ceilings stay absent so an unbudgeted run is not accidentally given one.
+     */
+    serialize(): PersistedBudgetState;
 }

package/dist/types/orchestration/product-persistence.d.ts

@@ -2,6 +2,7 @@
  * Product persistence facade over the Gateway-owned RunStateStore.
  */
 import type { ProductPhase, ProductInstanceDef } from "../protocol/wire/acp-agent-management.js";
+import type { PersistedBudgetState } from "./product-budget.js";
 import type { SerializedNode } from "./dag-scheduler.js";
 import type { PlanningSession } from "./product-planner.js";
 import { type HostRunStateAuthority } from "./run-state-host-authority.js";
@@ -13,13 +14,8 @@ export interface PersistedProductState {
     cwd: string;
     instances: ProductInstanceDef[];
     tasks: SerializedNode[];
-    budget: {
-        maxTotalTokens?: number;
-        maxDuration?: number;
-        usedTokens: number;
-        startedAt: number;
-        warningEmitted: boolean;
-    };
+    /** Owned by ProductBudgetTracker — see PersistedBudgetState for the round-trip contract. */
+    budget: PersistedBudgetState;
     createdAt: string;
     lastCheckpointAt: string;
     /** Last durably announced attempt number for each stable task id. */
@@ -42,13 +38,8 @@ export interface PersistedProductPlanningState {
     cwd: string;
     instances: ProductInstanceDef[];
     tasks: SerializedNode[];
-    budget: {
-        maxTotalTokens?: number;
-        maxDuration?: number;
-        usedTokens: number;
-        startedAt: number;
-        warningEmitted: boolean;
-    };
+    /** Owned by ProductBudgetTracker — see PersistedBudgetState for the round-trip contract. */
+    budget: PersistedBudgetState;
     createdAt: string;
     lastCheckpointAt: string;
     planningSession: PlanningSession;

package/dist/types/orchestration/product-planner.d.ts

@@ -115,15 +115,43 @@ export interface DagMutation {
     taskId: string;
     details?: Record<string, unknown>;
 }
+/**
+ * Human-readable form of an execution-phase leader reply.
+ *
+ * The raw reply is prose plus a JSON mutation array. Showing it verbatim puts machine payload in the
+ * conversation; showing nothing leaves the user's question unanswered. So: prose without the JSON
+ * block, and when the leader answered only in JSON, a line naming what it actually changed.
+ */
+export declare function describeExecutionReply(response: string, mutations: DagMutation[]): string;
 export declare class ProductPlanner {
     private providerDirectory;
     private callbacks;
     private sessions;
     private sessionAuthorities;
+    /** Issues from the most recent plan semantic check, quoted back in the reprompt (empty = passed). */
+    private lastPlanIssues;
     constructor(providerDirectory: HostAgentProviderDirectory, callbacks?: PlannerCallbacks);
     private resolveOwnerAuthority;
     private assertSessionOwner;
     private getOrRestoreSession;
+    /**
+     * Phases where the ORCHESTRATOR owns this run's RunState key. The planner and the orchestrator write
+     * the SAME key for the same productId; ownership hands over at markExecuting() and never comes back
+     * (markAwaitingConfirmation only rolls back a create() that never started executing).
+     */
+    private static readonly EXECUTION_OWNED_PHASES;
+    /** True once execution owns the checkpoint — the planner must neither write it nor mutate phase. */
+    private executionHasTakenOver;
+    /**
+     * Persist the planning snapshot — unless execution has taken the key over.
+     *
+     * A leader turn is dispatched detached (`void runLeaderTurn`) with a 10-minute ceiling, so it can land
+     * long after the user confirmed and the DAG started. It used to write unconditionally, stamping a
+     * `stateKind:"planning"` snapshot over the live execution checkpoint — after which loadProductState()
+     * returns undefined for that run (it rejects planning snapshots), so a crash in that window made the
+     * executing run unresumable and reset usedTokens/task states. Dropping the stale write is correct:
+     * the planning dialogue it carried is no longer the authority for this run.
+     */
     private checkpointPlanningSession;
     private publishNotification;
     /**
@@ -229,6 +257,16 @@ export declare class ProductPlanner {
     restoreSession(data: PlanningSession, authority?: HostRunStateAuthority): void;
     private handlePlanningMessage;
     private handleExecutionMessage;
+    /**
+     * One leader turn over the Gateway delegate.
+     *
+     * `stream` opts INTO product.planningDelta and defaults to off. Only turns the user actually asked
+     * for belong in the conversation: the planning turn and a run-time steering message. The acceptance
+     * judge and the automatic failure consultation are internal machinery — they used to stream too, so
+     * every task acceptance pushed `VERDICT: PASS FEEDBACK: -` into the leader conversation. Nothing
+     * rendered that channel during a run, so the pollution stayed invisible until the run window
+     * surfaced it. Defaulting to silent means a future internal call site cannot leak by omission.
+     */
     private sendToLeader;
     /**
      * Extract a JSON object from the leader's reply. The leader (an LLM) formats the block

package/dist/types/orchestration/product-worktree.d.ts

@@ -11,7 +11,9 @@ export declare function getWorktreeDiff(worktreePath: string): Promise<string>;
 export declare function listWorktreeChangedFiles(worktreePath: string): Promise<string[]>;
 /** Copy the changed files from a task worktree back into the product workspace. */
 export declare function materializeWorktreeChanges(worktreePath: string, targetRoot: string): Promise<void>;
-/** Remove a git worktree. */
-export declare function removeWorktree(gitRoot: string, path: string): Promise<void>;
+/** Remove a git worktree. When `branch` is given, also delete the worktree's throwaway branch
+ *  (created by createWorktree's `-B solo/<name>`); best effort — the branch never carries commits
+ *  of its own, but leaving it behind litters the user's repo with one `solo/*` ref per racer. */
+export declare function removeWorktree(gitRoot: string, path: string, branch?: string): Promise<void>;
 /** Merge a worktree branch into the current branch. */
 export declare function mergeWorktree(gitRoot: string, worktreeBranch: string): Promise<string>;

package/dist/types/orchestration/solo-evaluator.d.ts

@@ -8,7 +8,8 @@
  *   3. On completion of initial task, agents enter "idle" state (process kept alive)
  *   4. User can send follow-up messages to individual agents via solo.message
  *   5. User triggers evaluation via solo.evaluate (or skips directly to solo.select)
- *   6. solo.select → merge winning worktree, clean up others
+ *   6. solo.select → materialize the winner's worktree changes into the workspace, clean up all
+ *      worktrees + solo/* branches
  *
  * Key design:
  *   - Solo = special project type persisted by the Gateway RunState authority
@@ -34,8 +35,16 @@ export interface SoloCallbacks {
     onAgentActivity?: (soloId: string, agentId: string, toolName: string) => void;
     /** Token usage report after agent completes. */
     onAgentUsage?: (soloId: string, agentId: string, inputTokens: number, outputTokens: number) => void;
+    /** Full (capped) unified diff of a competitor's worktree once a turn settles — the same diff the
+     *  judge scores, so the user can inspect actual changes instead of only the agent's self-report. */
+    onAgentDiff?: (soloId: string, agentId: string, diff: string) => void;
+    /** Run-level state transition (running/evaluating/…): lets the UI narrate the auto-judge phase. */
+    onState?: (soloId: string, state: SoloState, projectId: string) => void;
     /** Required Gateway delegate access; Solo fails loud when the Host rail is unavailable. */
     getDelegateBridge?: () => DelegateBridge | undefined;
+    /** Ready (launchable) agent provider ids — used to prefer an INDEPENDENT judge over a competitor
+     *  scoring its own race. Best effort: absent/failing falls back to a participant judge. */
+    listReadyAgentIds?: () => Promise<string[]>;
     /**
      * Race reached a terminal state WITHOUT an evaluation winner (all agents failed, or cancelled).
      * The success path uses onEvaluation; this lets the host write back the plan project's planStatus
@@ -78,6 +87,18 @@ export declare class SoloEvaluator {
     private snapshotSession;
     private queuePersistSession;
     private publishNotification;
+    /** Announce the run-level state so the UI can narrate phases (esp. the auto-judge window). */
+    private publishState;
+    /**
+     * Resolve a session, lazily rehydrating from the Host RunState checkpoint after an engine
+     * restart — without this, every restart turned live races into zombies (uncancellable,
+     * unadoptable, undeletable, forever "运行中" in history).
+     *
+     * A restart killed the racer processes, so a checkpointed "running"/"pending" agent can never
+     * settle: mark it failed to make the run actionable. Same for a mid-flight "evaluating" run —
+     * the judge turn is gone; drop back to "running" so select/cancel/evaluate stay available.
+     */
+    private requireSession;
     /**
      * Start a Solo Mode PK session.
      * Creates worktrees, spawns agents in parallel, waits for completion, then evaluates.
@@ -119,16 +140,35 @@ export declare class SoloEvaluator {
         soloId: string;
         displayId: string;
     } | null;
+    /**
+     * Replay each in-flight agent's already-streamed turn text (reconnect/refresh resume). The status
+     * snapshot only carries SETTLED turn text; this hands back what the current turn has produced so
+     * far, so a refresh mid-race doesn't blank the streaming columns until the next delta.
+     */
+    replayLiveText(soloId: string, emit: (agentDisplayId: string, text: string) => void): Promise<void>;
     /** Get the current status of a solo session. */
     getStatus(soloId: string): SoloStatus | null;
     /** Cancel a running solo session. Kill all agents and clean up worktrees. */
     cancel(soloId: string): Promise<void>;
     /**
-     * Select a winner and merge their worktree into the main branch.
+     * Select a winner and adopt their worktree changes into the workspace.
+     *
+     * Racers never commit on their `solo/*` branch, so the old `git merge --no-ff` here was a no-op
+     * ("Already up to date") and the follow-up cleanup then deleted every uncommitted产物. Adoption
+     * now COPIES the winner's staged/untracked changes back (same materialize path Product mode uses)
+     * and only cleans up after the copy succeeded — a materialize failure keeps all worktrees intact.
      */
     select(params: SoloSelectParams): Promise<string>;
     /** Delete a solo session, killing agents and cleaning up worktrees if still active. */
     delete(soloId: string): Promise<void>;
+    /**
+     * Pick a ready agent that is NOT racing to act as an independent judge (小智优先). Returns a
+     * synthetic member on the same supervised delegate rail: unique seq (= agents.length) keeps its
+     * memberKey distinct, cwd = the project workspace (the judge only reads the prompt; evaluation
+     * turns are stream-suppressed and its memberId is unknown to getMemberContext, so nothing leaks
+     * into competitor columns). Best effort — any failure falls back to a participant judge.
+     */
+    private resolveExternalJudge;
     /**
      * Build an evaluation prompt and send to the user-chosen evaluator agent.
      * Returns evaluation result.

package/dist/types/orchestration/solo-spec-builder.d.ts

@@ -35,6 +35,9 @@ export interface SpecChatDeps {
     /** (a) Owner global memory cheat-sheet — the spec moderator must honor standing
      *  preferences/boundaries (language, style, hard limits) when drafting the spec. */
     globalMemoryIndex?: string | null;
+    /** 上一轮已形成的规格草稿。多轮打磨必须在它的基础上增量更新——不回传会导致第二轮起模型
+     *  凭对话重写整份规格,用户此前敲定的约束/验收被静默丢弃。 */
+    previousSpec?: SoloSpec | null;
 }
 /** R3 多轮对话式 spec:agent 通过此工具产出/更新结构化规格(类比 plan_mode 的 plan 入参)。 */
 export declare const SET_SPEC_TOOL_NAME = "set_spec";

package/dist/types/orchestration/testing/delegate-test-bridge.d.ts

@@ -10,6 +10,12 @@ interface LegacyTurnFixture {
             outputTokens: number;
         };
     } | null;
+    /**
+     * Optional streamed chunks for this turn, replayed through the caller's sink before the result
+     * resolves. The bridge used to drop the sink entirely, so no test could observe which turns stream —
+     * which is how every acceptance verdict reached the leader conversation unnoticed.
+     */
+    streamDeltas?(memberId: string, prompt: string): string[];
 }
 /** Test-only adapter for migrating orchestration fixtures from the retired local spawn lane. */
 export declare function makeDelegateTestBridge(processManager: LegacyTurnFixture): DelegateBridge;

package/dist/types/orchestration/testing/run-state-client-double.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Test double helper for HostRunStateClient.
+ *
+ * The RunState client contract is hand-rolled into ~19 inline object literals across the orchestration
+ * tests, each cast with `as never`. That cast means TypeScript cannot tell a double from a real client,
+ * so adding a method to the contract breaks every one of them at RUNTIME instead of at compile time —
+ * which is exactly what happened when `openWithCheckpoint` was introduced.
+ *
+ * This wrapper derives the atomic method from whatever `open`/`checkpoint` the double already provides,
+ * so existing spies and their assertions keep working unchanged: `openWithCheckpoint` still routes
+ * through the double's own `checkpoint` spy, preserving every "checkpoint was called with X" assertion.
+ */
+export declare function runStateClientDouble<T extends Record<string, unknown>>(partial: T): never;

package/dist/types/orchestration/workflow/builtin-capabilities.d.ts

@@ -0,0 +1,3 @@
+import type { CapabilityEntry } from "./capability-catalog.js";
+/** Fresh copies prevent Host/UI consumers from mutating the shared contract. */
+export declare function builtinWorkflowCapabilities(): CapabilityEntry[];

package/dist/types/orchestration/workflow/capability-catalog.d.ts

@@ -16,9 +16,40 @@ export interface CapabilityEntry {
     toolName?: string;
     server?: string;
     tool?: string;
+    /** Machine-readable planning hints owned by Runtime, not prose invented by the Agent. */
+    useWhen?: string[];
+    avoidWhen?: string[];
+    keywords?: string[];
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    inputPorts?: Array<{
+        name: string;
+        type: string;
+        required?: boolean;
+    }>;
+    outputPorts?: Array<{
+        name: string;
+        type: string;
+    }>;
+    requiredParams?: string[];
+    sideEffectLevel?: "none" | "local" | "external";
+    permissionHints?: string[];
+    constraints?: string[];
+    examples?: Array<{
+        intent: string;
+        params?: Record<string, unknown>;
+    }>;
 }
 /** Render the Host-owned catalog for the AI graph builder prompt. */
 export declare function renderCatalogForPrompt(entries: CapabilityEntry[], perCategoryCap?: number): string;
+/**
+ * Select a compact, deterministic capability working set before the Agent turn.
+ * The full catalog remains available through list_capabilities for long-tail discovery.
+ */
+export declare function selectRelevantCapabilities(entries: CapabilityEntry[], intent: string, options?: {
+    limit?: number;
+    preferredIds?: string[];
+}): CapabilityEntry[];
 /** Extract canonical references for anti-hallucination validation. */
 export declare function collectCapabilityRefs(def: {
     nodes: {

package/dist/types/orchestration/workflow/cron-schedule.d.ts

@@ -3,9 +3,8 @@
  *
  * `validateCron` (trigger-validation.ts) guarantees a stored schedule is structurally valid; this
  * module turns a validated cron string into a concrete "next fire time" so the in-process
- * WorkflowScheduler can arm a timer. Pure, side-effect-free, and UTC-based for determinism — the
- * scheduler injects its own clock, and tests pin time exactly. (A future local-timezone offset is a
- * caller concern; the engine itself is UTC so the same input always yields the same output.)
+ * WorkflowScheduler can arm a timer. Pure, side-effect-free, and deterministic for an explicit
+ * IANA timezone. Legacy callers that omit a timezone retain UTC semantics.
  *
  * Grammar matches validateCron exactly: 5-field (min hour dom month dow) or 6-field (+ leading
  * seconds); each field is a comma-list of star / star-step / value / range / stepped-range, with
@@ -34,4 +33,4 @@ export declare function parseCron(cron: string): ParsedCron;
  * exists within a ~5-year horizon (e.g. an impossible date like "0 0 30 2 *"). Deterministic: the
  * same (cron, afterMs) always returns the same value.
  */
-export declare function nextCronTime(cron: string, afterMs: number): number;
+export declare function nextCronTime(cron: string, afterMs: number, timezone?: string): number;

package/dist/types/orchestration/workflow/expression.d.ts

@@ -10,7 +10,8 @@
  *   - context roots: $input · $json · $node("name") · $now · $vars · $trigger
  *   - accessors: `.prop` and `[index]` / `["key"]`
  *   - literals: string ('..' / ".."), number, true/false/null
- *   - whitelist functions: len, upper, lower, default, jsonpath, date
+ *   - whitelist functions: len, upper, lower, default, jsonpath, date,
+ *     eq, ne, gt, gte, lt, lte, not, and, or, contains
  *
  * fail-loud: unknown roots/functions, reads through null/undefined, and prototype-escape keys
  * all throw. Absent *leaf* keys evaluate to undefined (so `default(x, fb)` works).

package/dist/types/orchestration/workflow/n8n-import.d.ts

@@ -1,4 +1,5 @@
 import type { WorkflowDef } from "./node-schema.js";
+import type { WorkflowTemplateSetupManifest } from "./workflow-template-setup.js";
 export interface N8nImportOptions {
     strictTemplates?: boolean;
 }
@@ -54,6 +55,8 @@ export interface N8nImportResult {
     def: WorkflowDef;
     report: N8nConversionReport;
 }
+/** Turn imported n8n credential references into one centralized Host-owned connection form. */
+export declare function n8nConnectionSetupManifest(report: N8nConversionReport): WorkflowTemplateSetupManifest | undefined;
 export declare class N8nImportError extends Error {
     readonly errors: string[];
     constructor(errors: string[]);

package/dist/types/orchestration/workflow/node-registry.d.ts

@@ -8,7 +8,7 @@
  */
 import type { NodeExecutor } from "./node-schema.js";
 /**
- * Node kinds whose builtin executor is an import-only stub a host is meant to replace.
+ * Node kinds whose builtin executor is a Host-binding placeholder.
  * installHostExecutors overrides ONLY these when already present; any other
  * pre-registered kind is kept. Single source of the "rebindable kind" rule.
  */
@@ -22,7 +22,7 @@ export declare class NodeRegistry {
     /**
      * Wire host-backed executors — the single source of the host-wiring rule used by the
      * runtime, the gateway handler, and tests. Absent kinds are registered; an already-present
-     * rebindable kind (agentBinding/modelBinding, whose builtin is an import-only stub) is
+     * rebindable kind (whose builtin is a Host-binding placeholder) is
      * overridden; any other already-present kind is kept (caller's pre-registration wins).
      */
     installHostExecutors(executors: Record<string, NodeExecutor>): void;

package/dist/types/orchestration/workflow/node-schema.d.ts

@@ -89,6 +89,8 @@ export interface ExecutorContext {
     kind: string;
     /** Owning workflow id (def.id) — lets host-backed nodes (approval) tag outbound notifications. */
     workflowId?: string;
+    /** Durable run identity used by Host-backed observability and recovery projections. */
+    runId?: string;
     /** This run's trigger kind (manual/schedule/…) — drives fine-grained unattended audits (IT-7b). */
     triggerKind?: string;
     /** 0-based; increments per loop iteration (drives the cache key, spec §A5). */
@@ -120,6 +122,8 @@ export interface ExecutorHost {
     httpRequest(req: HttpHostRequest): Promise<DataItem[]>;
     /** Invoke an MCP server tool. */
     invokeMcp(req: McpHostRequest): Promise<DataItem[]>;
+    /** Execute an installed n8n ecosystem node in the Host-owned compatibility worker. */
+    runN8nNode?(req: N8nNodeHostRequest): Promise<Record<string, DataItem[]>>;
     /** Send a message out through a channel (飞书/微信/…) via the xiaozhiclaw channel layer. */
     sendChannel(req: ChannelHostRequest): Promise<DataItem[]>;
     /** Project-scoped memory (memdir) read/write/search for the `memory` kind (spec D25). */
@@ -128,8 +132,8 @@ export interface ExecutorHost {
     runSubworkflow?(req: SubworkflowHostRequest): Promise<DataItem[]>;
     /**
      * Human-in-the-loop approval (D34): notify the owner and AWAIT the decision in-memory
-     * (the run stays "running"; the node shows pending). A restart loses pending approvals —
-     * the run then fails loud (durable suspended-run resumption is a tracked follow-up).
+     * (the run stays "running"; the node shows pending). The Runtime Host persists suspended-run
+     * state and reconstructs the approval wait after restart.
      */
     approval?(req: ApprovalHostRequest): Promise<{
         approved: boolean;
@@ -138,8 +142,8 @@ export interface ExecutorHost {
     }>;
     /**
      * D34 wait-until-webhook: suspend the branch until the given webhook path is called
-     * (await-in-memory, same posture as approval — the run stays "running"; a restart loses the
-     * wait and the run fails loud; checkpoint replay recovers prior steps on re-run).
+     * (same posture as approval). The Runtime Host persists the checkpoint and re-registers the
+     * webhook wait after restart.
      */
     waitWebhook?(req: WebhookWaitHostRequest): Promise<Record<string, unknown>>;
 }
@@ -163,6 +167,8 @@ export interface HttpHostRequest {
     url: string;
     headers?: Record<string, string>;
     body?: unknown;
+    /** Stable across retries/recovery for downstream de-duplication. */
+    idempotencyKey?: string;
     signal?: AbortSignal;
 }
 export interface McpHostRequest {
@@ -171,11 +177,21 @@ export interface McpHostRequest {
     args: Record<string, unknown>;
     signal?: AbortSignal;
 }
+export interface N8nNodeHostRequest {
+    n8nType: string;
+    version?: number;
+    parameters: Record<string, unknown>;
+    connectionIds?: Record<string, string>;
+    input: DataItem[];
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
 export interface ChannelHostRequest {
     channel: string;
     target?: string;
     payload: unknown;
     input: DataItem[];
+    idempotencyKey?: string;
     signal?: AbortSignal;
 }
 export interface SubworkflowHostRequest {

package/dist/types/orchestration/workflow/params-schema.d.ts

@@ -13,7 +13,8 @@
  *   - a value that is a `{{ }}` template is skipped for type checks (resolved at runtime).
  *   - an `__ASK__: 问题` sentinel (brace-less ON PURPOSE so it bypasses the {{ }} expression gate in
  *     validateDefExpressions) counts as "present but pending" (the agent honestly marking an unknown,
- *     not a hallucination) — surfaced by collectClarifications for the 待补 badge + activation gate.
+ *     not a hallucination) — surfaced by collectClarifications for the pending-field badge and
+ *     execution-readiness validation.
  */
 import type { CapabilityEntry } from "./capability-catalog.js";
 /** Per-kind params schemas. `trigger` (workflow-level trigger def) and
@@ -30,7 +31,7 @@ type NodeLike = {
 /**
  * Resolve the schema governing a canonical node's params.
  */
-export declare function resolveNodeParamsSchema(node: NodeLike, _entries: CapabilityEntry[]): Record<string, unknown> | undefined;
+export declare function resolveNodeParamsSchema(node: NodeLike, entries: CapabilityEntry[]): Record<string, unknown> | undefined;
 /**
  * Validate every node's params against its resolved schema. Returns human-readable Chinese errors
  * (empty = clean). Skips `trigger` (trigger def is validated elsewhere) and `manual` (placeholder).
@@ -38,11 +39,11 @@ export declare function resolveNodeParamsSchema(node: NodeLike, _entries: Capabi
  */
 export declare function validateParamsAgainstSchema(def: {
     nodes: NodeLike[];
-}, _entries: CapabilityEntry[]): string[];
+}, entries: CapabilityEntry[]): string[];
 /**
- * Collect every `{{ __ASK__ }}` placeholder in a def (top-level params + one level into `args`).
- * Drives the canvas "待补" badge and the activation gate (a workflow with pending asks cannot be
- * activated). Empty = nothing pending.
+ * Collect every brace-less `__ASK__` placeholder in a def (top-level params + one level into
+ * `args`). Drives the canvas pending-field badge and execution-readiness validation. Empty =
+ * nothing pending.
  */
 export declare function collectAskPlaceholders(def: {
     nodes: NodeLike[];

package/dist/types/orchestration/workflow/qla-executor-host.d.ts

@@ -7,7 +7,7 @@
  */
 import type { LLMTransport } from "../../runtime/ports/index.js";
 import { type DataItem } from "./data-item.js";
-import type { ExecutorHost, MemoryHostRequest, SubworkflowHostRequest, ApprovalHostRequest, WebhookWaitHostRequest } from "./node-schema.js";
+import type { ExecutorHost, N8nNodeHostRequest, MemoryHostRequest, SubworkflowHostRequest, ApprovalHostRequest, WebhookWaitHostRequest } from "./node-schema.js";
 /** Injected boundary capabilities — supplied by the handler host that owns the real runners. */
 export interface QlaExecutorHostDeps {
     /** Run one agent turn (spawn external ACP agent + sendTask). Returns the agent's text output. */
@@ -29,6 +29,8 @@ export interface QlaExecutorHostDeps {
         args: Record<string, unknown>;
         signal?: AbortSignal;
     }) => Promise<unknown>;
+    /** Execute an installed n8n ecosystem node through the embedding Host. */
+    runN8nNode?: (req: N8nNodeHostRequest) => Promise<Record<string, DataItem[]>>;
     /**
      * Send a message out through a channel via the xiaozhiclaw channel layer.
      * Undefined in standalone qlogicagent (no gateway) → channel nodes fail-loud (D12/D13).
@@ -37,6 +39,7 @@ export interface QlaExecutorHostDeps {
         channel: string;
         target?: string;
         payload: unknown;
+        idempotencyKey?: string;
         signal?: AbortSignal;
     }) => Promise<unknown>;
     /**