@tea-agent/loop-agent 0.27.1 → 0.28.1-beta.1

package/dist/workflows/dag/output-protocol.js

@@ -62,126 +62,68 @@ export function firstNonEmptyLine(text) {
     }
     return undefined;
 }
-function extractSingleJsonObjectText(text) {
+/**
+ * Parse the JSON-only review verdict protocol. The complete trimmed output
+ * must be exactly one JSON object: fences, prose, partial objects, and
+ * concatenated objects are all rejected before schema validation.
+ */
+export function parseJsonReviewVerdict(text) {
     const trimmed = String(text).trim();
     if (!trimmed)
         return { ok: false, reason: "missing JSON output" };
-    const extractBalancedObject = (source) => {
-        for (let start = 0; start < source.length; start += 1) {
-            if (source[start] !== "{")
-                continue;
-            let depth = 0;
-            let inString = false;
-            let escaped = false;
-            for (let index = start; index < source.length; index += 1) {
-                const char = source[index];
-                if (inString) {
-                    if (escaped)
-                        escaped = false;
-                    else if (char === "\\")
-                        escaped = true;
-                    else if (char === '"')
-                        inString = false;
-                    continue;
-                }
-                if (char === '"')
-                    inString = true;
-                else if (char === "{")
-                    depth += 1;
-                else if (char === "}" && --depth === 0) {
-                    const candidate = source.slice(start, index + 1);
-                    try {
-                        const parsed = JSON.parse(candidate);
-                        if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
-                            return candidate;
-                    }
-                    catch {
-                        // Continue scanning for the next complete object.
-                    }
-                    break;
-                }
-            }
-        }
-        return undefined;
-    };
-    const direct = extractBalancedObject(trimmed);
-    if (direct)
-        return { ok: true, jsonText: direct };
-    const fencedMatches = Array.from(trimmed.matchAll(/```(?:json)?\s*([\s\S]*?)\s*```/gi));
-    if (fencedMatches.length === 1) {
-        const jsonText = fencedMatches[0][1].trim();
-        const fencedObject = extractBalancedObject(jsonText);
-        if (fencedObject)
-            return { ok: true, jsonText: fencedObject };
-        return {
-            ok: false,
-            reason: "single fenced block is not a JSON object",
-        };
-    }
-    if (fencedMatches.length > 1) {
-        return {
-            ok: false,
-            reason: "multiple fenced JSON candidates found; expected exactly one JSON object",
-        };
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
     }
-    return {
-        ok: false,
-        reason: "output is not a single JSON object; expected only JSON with no Markdown or prose",
-    };
-}
-function validateJsonReviewVerdict(text) {
-    const extracted = extractSingleJsonObjectText(text);
-    if (!extracted.ok) {
+    catch (error) {
         return {
             ok: false,
-            failureCategory: "protocol-invalid",
-            reason: extracted.reason,
-            firstNonEmptyLine: firstNonEmptyLine(text),
+            reason: `output must be exactly one JSON object: ${error instanceof Error ? error.message : String(error)}`,
         };
     }
-    let parsed;
-    try {
-        parsed = JSON.parse(extracted.jsonText);
-    }
-    catch (error) {
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
         return {
             ok: false,
-            failureCategory: "protocol-invalid",
-            reason: `invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
-            firstNonEmptyLine: firstNonEmptyLine(text),
+            reason: "output must be exactly one JSON object",
         };
     }
     const checked = reviewJsonVerdictSchema.safeParse(parsed);
     if (!checked.success) {
         return {
             ok: false,
-            failureCategory: "protocol-invalid",
             reason: `JSON review verdict schema violation: ${checked.error.issues
                 .map((issue) => `${issue.path.join(".") || "<root>"} ${issue.message}`)
                 .join("; ")}`,
-            firstNonEmptyLine: firstNonEmptyLine(text),
         };
     }
     const blockingFindings = checked.data.findings.filter((finding) => finding.severity === "Critical" || finding.severity === "Important");
     if (checked.data.verdict === "pass" && blockingFindings.length > 0) {
         return {
             ok: false,
-            failureCategory: "protocol-invalid",
             reason: "JSON review verdict cannot be pass when Critical or Important findings are present",
-            firstNonEmptyLine: firstNonEmptyLine(text),
         };
     }
     if (checked.data.verdict === "request-revision" &&
         checked.data.findings.length === 0) {
         return {
             ok: false,
-            failureCategory: "protocol-invalid",
             reason: "JSON review verdict request-revision requires at least one finding",
-            firstNonEmptyLine: firstNonEmptyLine(text),
         };
     }
     return { ok: true, verdict: checked.data.verdict };
 }
+function validateJsonReviewVerdict(text) {
+    const parsed = parseJsonReviewVerdict(text);
+    if (!parsed.ok) {
+        return {
+            ok: false,
+            failureCategory: "protocol-invalid",
+            reason: parsed.reason,
+            firstNonEmptyLine: firstNonEmptyLine(text),
+        };
+    }
+    return { ok: true, verdict: parsed.verdict };
+}
 /**
  * Validate node output against an explicit outputProtocol.
  * Pure function — does not mutate run facts.
@@ -206,6 +148,29 @@ export function validateOutputProtocol(protocol, text) {
             reason: `missing first non-empty line; expected one of: ${protocol.validLines.map((l) => JSON.stringify(l)).join(" or ")}`,
         };
     }
+    const isReviewVerdict = protocol.validLines.length === 2 && protocol.validLines.includes("VERDICT: pass") && protocol.validLines.includes("VERDICT: request-revision");
+    // Models frequently prepend a short explanation despite the protocol
+    // instruction. Recover only when there is exactly one unambiguous protocol
+    // line; conflicting or repeated verdicts remain fail-closed.
+    const candidates = isReviewVerdict ? text
+        .split("\n")
+        .map((line) => normalizeVerdictCandidateLine(line.trim()))
+        .filter((line) => protocol.validLines.includes(line)) : [];
+    const uniqueCandidates = [...new Set(candidates)];
+    if (uniqueCandidates.length > 1) {
+        return {
+            ok: false,
+            failureCategory: "protocol-invalid",
+            reason: `conflicting protocol lines found: ${uniqueCandidates.map((line) => JSON.stringify(line)).join(" and ")}`,
+            firstNonEmptyLine: first,
+        };
+    }
+    if (protocol.validLines.includes(first)) {
+        return { ok: true, matchedLine: first };
+    }
+    if (uniqueCandidates.length === 1) {
+        return { ok: true, matchedLine: uniqueCandidates[0] };
+    }
     if (!protocol.validLines.includes(first)) {
         return {
             ok: false,

package/dist/workflows/dag/report.js

@@ -4,7 +4,7 @@ import path from "node:path";
 import { resolveCliPath } from "../../shared/path-refs.js";
 import { z } from "zod";
 import { repairArtifactSchema } from "./repair-artifact.js";
-import { dagRunDirExists, getDagRunDir, locateDagRun, readDagRunSpec, readDagRunState, } from "./lifecycle.js";
+import { dagRunDirExists, getDagRunDir, isDagExecutionLifecycle, locateDagRun, readDagRunSpec, readDagRunState, } from "./lifecycle.js";
 export const DAG_CLOSEOUT_DRAFT_DISCLAIMER = "> **Advisory only.** Derived from completed run facts. Canonical source remains `dag report --json` and `.harness/dag-runs/completed/<run-id>/`. Do not treat this draft as authoritative.";
 import { dagNormalizedFailureCategorySchema, normalizeDagFailureCategory, } from "./failure-category.js";
 import { dagProductLineFailureCategoryValues, routeDagFailure, } from "./failure-routing.js";
@@ -659,7 +659,14 @@ async function locateRunForReport(repoRoot, runId, filter) {
         if (!located) {
             throw new Error(`dag run not found: ${runId}`);
         }
-        return { ...located, runId };
+        if (!isDagExecutionLifecycle(located.lifecycle)) {
+            throw new Error(`dag run not found: ${runId}`);
+        }
+        return {
+            lifecycle: located.lifecycle,
+            runDir: located.runDir,
+            runId,
+        };
     }
     const runDir = getDagRunDir(repoRoot, filter, runId);
     if (!(await dagRunDirExists(runDir))) {

package/dist/workflows/dag/rerun-run.js

@@ -4,9 +4,9 @@ import path from "node:path";
 import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
 import { resolveRunningControllerIdentity } from "../../shared/package-metadata.js";
 import { readControllerIdentityArtifact, captureControllerIdentity } from "./controller-identity.js";
-import { DAG_RUNS_DIR, getDagRunDir, locateDagRun, readDagRunSpec, readDagRunState, } from "./lifecycle.js";
+import { DAG_RUNS_DIR, getDagRunDir, isDagNonExecutionLifecycle, locateDagRun, readDagRunSpec, readDagRunState, } from "./lifecycle.js";
 import { buildDagRunId, runDagContinuation, } from "./runner.js";
-import { evaluateDagRerunPlan, evaluateLiveDagRerunBindings, } from "./rerun-plan.js";
+import { computePlanHash, evaluateDagRerunPlan, evaluateLiveDagRerunBindings, } from "./rerun-plan.js";
 import { prepareActiveRunDir, writeNodeRecord, writeRunSpec, writeRunState, } from "./run-store.js";
 import { cloneParentSkillSnapshotForContinuation, readSkillSnapshot, } from "./skill-snapshot.js";
 import { topoSortToRanks } from "./topo.js";
@@ -123,6 +123,65 @@ export async function planDagRerun(input) {
         const nonCompletedSpec = await readDagRunSpec(located.runDir);
         const nonCompletedState = await readDagRunState(located.runDir);
         const nonCompletedWorkerHints = await detectWorkerManagedRun(located.runDir, nonCompletedState, nonCompletedSpec);
+        // evaluateDagRerunPlan only accepts execution lifecycles. Audit parents must
+        // not be cast to "active" (reconcile) or "paused" (resume). Also avoid routing
+        // audit through evaluate: missing workspace checkpoint would surface as
+        // standalone-task-rerun instead of the required fail-closed manual action.
+        if (isDagNonExecutionLifecycle(located.lifecycle)) {
+            const bindingStatus = await evaluateLiveDagRerunBindings({
+                cwd: input.cwd,
+                parentSpec: nonCompletedSpec,
+            });
+            const workerAssociation = nonCompletedWorkerHints.workerManaged
+                ? {
+                    kind: "worker-managed",
+                    ...(nonCompletedWorkerHints.featureId
+                        ? { featureId: nonCompletedWorkerHints.featureId }
+                        : {}),
+                    ...(nonCompletedWorkerHints.taskId
+                        ? { taskId: nonCompletedWorkerHints.taskId }
+                        : {}),
+                    ...(nonCompletedWorkerHints.workerRunId
+                        ? { workerRunId: nonCompletedWorkerHints.workerRunId }
+                        : {}),
+                }
+                : { kind: "standalone" };
+            const planWithoutHash = {
+                schemaVersion: 1,
+                eligible: false,
+                parentRunId: input.parentRunId,
+                parentLifecycle: located.lifecycle,
+                selectedNodeId: input.selectedNodeId,
+                rewriteApplied: false,
+                resetNodeIds: [],
+                importedNodeIds: [],
+                blockingNodes: [],
+                reasonCodes: ["parent-lifecycle-ineligible"],
+                blockedReasons: ["parent-lifecycle-ineligible"],
+                risk: "high",
+                bindings: {
+                    sourceBindingMatched: bindingStatus.sourceBindingMatched,
+                    taskContractBindingMatched: bindingStatus.taskContractBindingMatched,
+                    controllerIdentityMatched: true,
+                    skillSnapshotVerified: true,
+                    workspaceMatched: false,
+                },
+                workerAssociation,
+                estimatedExecution: {
+                    nodeCount: 0,
+                    piCallCount: 0,
+                    shellNodeCount: 0,
+                    avoidedNodeCount: 0,
+                    avoidedPiCallCount: 0,
+                },
+                suggestedAction: "manual",
+            };
+            return {
+                ...planWithoutHash,
+                planHash: computePlanHash(planWithoutHash),
+            };
+        }
+        const parentLifecycle = located.lifecycle === "active" ? "active" : "paused";
         return evaluateDagRerunPlan({
             cwd: input.cwd,
             parentRunId: input.parentRunId,
@@ -130,7 +189,7 @@ export async function planDagRerun(input) {
             parentRunDir: located.runDir,
             parentSpec: nonCompletedSpec,
             parentState: nonCompletedState,
-            parentLifecycle: located.lifecycle,
+            parentLifecycle,
             workerManaged: nonCompletedWorkerHints.workerManaged,
             workerAssociation: nonCompletedWorkerHints.workerManaged
                 ? {

package/dist/workflows/dag/run-store.js

@@ -11,10 +11,15 @@ export async function writeRunState(runDir, state, options) {
 export async function readRunSpec(runDir) {
     return readDagRunSpec(runDir);
 }
-export async function prepareActiveRunDir(runDir) {
+/** Prepare any lifecycle run directory (active / dry-run / init-only / …). */
+export async function prepareRunDir(runDir) {
     await rm(runDir, { recursive: true, force: true });
     await mkdir(runDir, { recursive: true });
 }
+/** @deprecated Prefer prepareRunDir; kept as thin alias for execute callers. */
+export async function prepareActiveRunDir(runDir) {
+    await prepareRunDir(runDir);
+}
 export async function writeRunSpec(runDir, spec) {
     await writeJsonAtomic(path.join(runDir, "run.json"), spec);
 }

package/dist/workflows/dag/runner.js

@@ -7,7 +7,7 @@ import { readCandidateRecord } from "../../infrastructure/evaluation/candidate-s
 import { CANONICAL_TASK_ID_PATTERN, formatLocalCompactDate, } from "../../task/runtime.js";
 import { assertFrozenBudget, initRunBudgetLedger, preflightBudgetOrBreach, recordFinishedNodeBudget, writeBudgetLedgerArtifacts, } from "./budget-enforcement.js";
 import { getDagRunDir, isTerminalDagRunStatus, locateDagRun, readHumanApprovalArtifact, requireActiveDagRun, } from "./lifecycle.js";
-import { moveToCompletedRunDir, moveToPausedRunDir, prepareActiveRunDir, writeRunSpec, writeRunState, } from "./run-store.js";
+import { moveToCompletedRunDir, moveToPausedRunDir, prepareRunDir, writeRunSpec, writeRunState, } from "./run-store.js";
 import { evaluateNodeLiveness, resolveLivenessPolicy, } from "./liveness-policy.js";
 import { createDagNodeExecutor } from "./executor-registry.js";
 import { executeDagPiNode } from "../../executors/dag-pi-executor.js";
@@ -126,12 +126,18 @@ export function createInitialRunState(spec, opts, ranks, runId = opts.runId ?? "
                 : {}),
         };
     }
+    const executionMode = opts.dryRun
+        ? "dry-run"
+        : opts.initOnly
+            ? "init-only"
+            : "execute";
     const state = {
         version: 1,
         title: spec.title,
         runId,
         cwd: opts.cwd,
         startedAt: new Date().toISOString(),
+        executionMode,
         runner: {
             pid: process.pid,
             hostname: hostname(),
@@ -212,8 +218,14 @@ export async function runDag(spec, opts) {
     const activeRunDir = getDagRunDir(opts.cwd, "active", state.runId);
     const completedRunDir = getDagRunDir(opts.cwd, "completed", state.runId);
     const pausedRunDir = getDagRunDir(opts.cwd, "paused", state.runId);
-    const runDir = activeRunDir;
-    await prepareActiveRunDir(runDir);
+    // R-A2: non-execution modes use dedicated lifecycles; only execute enters active/.
+    const lifecycleDir = state.executionMode === "dry-run"
+        ? "dry-run"
+        : state.executionMode === "init-only"
+            ? "init-only"
+            : "active";
+    const runDir = getDagRunDir(opts.cwd, lifecycleDir, state.runId);
+    await prepareRunDir(runDir);
     await writeRunSpec(runDir, spec);
     // Freeze the running controller identity as a run-owned fact before the
     // first canonical state write, reusing the identity resolved for preflight.

package/dist/workflows/dag/types.js

@@ -10,6 +10,27 @@ export const dagNodeExecutorSchema = z.enum(["pi", "shell", "static"]);
 export const CURSOR_DAG_EXECUTOR_REMOVED_ERROR = 'executor "cursor" is no longer supported; regenerate the DAG with Pi-only writers (implement-pi / repair-pi)';
 export const CURSOR_EXECUTOR_MODELS_REMOVED_ERROR = "executorModels.cursor is no longer supported; use executorModels.pi only";
 export const dagToolProfileSchema = z.enum(["read-only", "write"]);
+/** Static command capabilities only; tasks cannot inject executables or shell prefixes. */
+export const dagCommandCapabilitySchema = z.enum(["playwright-cli"]);
+export const dagCommandPolicySchema = z.discriminatedUnion("mode", [
+    z.object({ mode: z.literal("deny") }).strict(),
+    z
+        .object({
+        mode: z.literal("capability-allowlist"),
+        capabilities: z.array(dagCommandCapabilitySchema).min(1),
+    })
+        .strict(),
+]);
+/** Undefined / omitted commandPolicy is treated as deny by executors and validators. */
+export function resolveDagCommandPolicy(policy) {
+    return policy ?? { mode: "deny" };
+}
+export function dagCommandPolicyAllows(policy, capability) {
+    const resolved = resolveDagCommandPolicy(policy);
+    if (resolved.mode !== "capability-allowlist")
+        return false;
+    return resolved.capabilities.includes(capability);
+}
 export const dagOutputModeSchema = z.enum(["default", "structured-required"]);
 export const dagShellPresetSchema = z.enum(["loop-agent-standard-verify"]);
 export const dagVerifyQuotaSchema = z.enum(["1", "3", "full"]);
@@ -319,6 +340,7 @@ export const dagBackendTestPipelineSchema = z.enum([
     "markdown-execute-html",
     "markdown-manifest",
 ]);
+export const dagFrontendBrowserToolPreflightSchema = z.object({}).strict();
 export const dagFrontendTestEvidenceValidationSchema = z.object({}).strict();
 export const dagFrontendTestCaseChecklistSchema = z.object({}).strict();
 export const dagFrontendTestHtmlReportSchema = z.object({}).strict();
@@ -369,6 +391,7 @@ export const dagShellConfigSchema = z.object({
     frontendVerificationBundle: dagFrontendVerificationBundleSchema.optional(),
     frontendReviewContext: dagFrontendReviewContextSchema.optional(),
     frontendTestCaseChecklist: dagFrontendTestCaseChecklistSchema.optional(),
+    frontendBrowserToolPreflight: dagFrontendBrowserToolPreflightSchema.optional(),
     frontendTestEvidenceValidation: dagFrontendTestEvidenceValidationSchema.optional(),
     frontendTestL5Report: z.object({}).strict().optional(),
     frontendTestHtmlReport: dagFrontendTestHtmlReportSchema.optional(),
@@ -416,6 +439,7 @@ export const dagDynamicExpansionChildTaskSchema = z.object({
     outputContract: z.string().optional(),
     staticResultTemplate: z.string().optional(),
     toolProfile: dagToolProfileSchema.optional(),
+    commandPolicy: dagCommandPolicySchema.optional(),
     writePolicy: dagWritePolicySchema.optional(),
     allowedPaths: z.array(z.string()).optional().default([]),
     forbiddenPaths: z.array(z.string()).optional().default([]),
@@ -487,6 +511,7 @@ export const dagDynamicLoopBodyTaskSchema = z.object({
     outputContract: z.string().optional(),
     staticResultTemplate: z.string().optional(),
     toolProfile: dagToolProfileSchema.optional(),
+    commandPolicy: dagCommandPolicySchema.optional(),
     writePolicy: dagWritePolicySchema.optional(),
     allowedPaths: z.array(z.string()).optional().default([]),
     forbiddenPaths: z.array(z.string()).optional().default([]),
@@ -558,6 +583,8 @@ export const dagTaskSchema = z.object({
     role: dagRoleSchema.optional(),
     skills: z.array(z.string()).optional(),
     toolProfile: dagToolProfileSchema.optional(),
+    /** Default deny: file write (toolProfile=write) does not grant command execution. */
+    commandPolicy: dagCommandPolicySchema.optional(),
     writePolicy: dagWritePolicySchema.optional(),
     writeSet: z.array(z.string()).optional(),
     piStep: z.string().optional(),

package/dist/workflows/dag/validate.js

@@ -1,4 +1,4 @@
-import { DEFAULT_DAG_EXECUTOR_MODELS, ENV_VAR_NAME_PATTERN, } from "./types.js";
+import { DEFAULT_DAG_EXECUTOR_MODELS, ENV_VAR_NAME_PATTERN, dagCommandPolicyAllows, resolveDagCommandPolicy, } from "./types.js";
 import { resolveShellCommands } from "../../executors/shell-executor.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
 import { resolveRepairTaskForGate } from "./repair-artifact.js";
@@ -461,6 +461,7 @@ function validateShellTaskConfig(task, spec, issues) {
         !shell.jsonArtifactGate &&
         !shell.backendTestPipeline &&
         !shell.frontendPrewriteGate &&
+        !shell.frontendBrowserToolPreflight &&
         !shell.frontendVerificationBundle &&
         !shell.frontendReviewContext &&
         !shell.frontendTestCaseChecklist &&
@@ -623,6 +624,104 @@ function validateWriterOutcomePolicyTaskConfig(task, issues) {
         });
     }
 }
+function isFrontendEvidenceWriteSet(writeSet) {
+    const entries = writeSet ?? [];
+    if (entries.length === 0)
+        return false;
+    return entries.every((entry) => {
+        const normalized = entry.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+        return (normalized === "testcase/frontend/evidence/**" ||
+            normalized.startsWith("testcase/frontend/evidence/"));
+    });
+}
+function isFrontendBrowserExecutorTask(task) {
+    const skills = task.skills ?? [];
+    return (task.executor === "pi" &&
+        task.toolProfile === "write" &&
+        skills.includes("playwright-cli") &&
+        isFrontendEvidenceWriteSet(task.writeSet));
+}
+function taskMentionsPlaywrightCliContract(task) {
+    const prompt = `${task.subtask_prompt}\n${task.outputContract ?? ""}`;
+    return /playwright[_-]?cli/i.test(prompt);
+}
+/**
+ * Command capability is orthogonal to file write. Fail closed when:
+ * - frontend browser executors lack playwright-cli capability
+ * - capability is granted without skill/prompt contract or outside evidence writeSet
+ * - non-browser nodes receive command capability
+ */
+function validateCommandPolicyTaskConfig(task, issues) {
+    const policy = resolveDagCommandPolicy(task.commandPolicy);
+    const allowsPlaywright = dagCommandPolicyAllows(task.commandPolicy, "playwright-cli");
+    const isBrowserExecutor = isFrontendBrowserExecutorTask(task);
+    if (isBrowserExecutor && !allowsPlaywright) {
+        issues.push({
+            type: "invalid-command-policy",
+            message: `frontend-test browser executor requires playwright-cli command capability (task ${task.id})`,
+        });
+    }
+    if (policy.mode === "deny") {
+        return;
+    }
+    if (task.executor !== "pi") {
+        issues.push({
+            type: "invalid-command-policy",
+            message: `task ${task.id} commandPolicy requires executor=pi`,
+        });
+        return;
+    }
+    if (allowsPlaywright) {
+        const skills = task.skills ?? [];
+        if (!skills.includes("playwright-cli")) {
+            issues.push({
+                type: "invalid-command-policy",
+                message: `task ${task.id} playwright-cli command capability requires skills to include playwright-cli`,
+            });
+        }
+        if (!taskMentionsPlaywrightCliContract(task)) {
+            issues.push({
+                type: "invalid-command-policy",
+                message: `task ${task.id} playwright-cli command capability requires prompt/outputContract to reference playwright_cli`,
+            });
+        }
+        if (!isFrontendEvidenceWriteSet(task.writeSet)) {
+            issues.push({
+                type: "invalid-command-policy",
+                message: `task ${task.id} playwright-cli command capability requires frontend evidence writeSet under testcase/frontend/evidence/`,
+            });
+        }
+        if (task.toolProfile !== "write") {
+            issues.push({
+                type: "invalid-command-policy",
+                message: `task ${task.id} playwright-cli command capability requires toolProfile=write for evidence mutation`,
+            });
+        }
+    }
+}
+function validateDynamicChildCommandPolicy(task, issues) {
+    const expansion = task.dynamicExpansion;
+    if (!expansion)
+        return;
+    const child = expansion.childTask;
+    const synthetic = {
+        id: `${task.id}-child-template`,
+        depends_on: [],
+        complexity: child.complexity,
+        subtask_prompt: child.subtaskPromptTemplate,
+        executor: child.executor,
+        role: child.role,
+        skills: child.skills,
+        toolProfile: child.toolProfile,
+        commandPolicy: child.commandPolicy,
+        writePolicy: child.writePolicy,
+        allowedPaths: child.allowedPaths,
+        forbiddenPaths: child.forbiddenPaths,
+        writeSet: child.writeSet,
+        outputContract: child.outputContract,
+    };
+    validateCommandPolicyTaskConfig(synthetic, issues);
+}
 function validateDecisionGateTaskConfig(task, issues) {
     if (!task.decisionGate?.enabled) {
         return;
@@ -727,6 +826,25 @@ export function collectForbiddenExecutorIssues(spec, forbiddenExecutors) {
         implicitDefault: rawTasks[index]?.executor === undefined,
     }));
 }
+/** Revalidate a rendered dynamic child before it enters state or executes. */
+export function assertValidMaterializedDagTask(task) {
+    const issues = [];
+    // A minimal v2 carrier makes write-policy validation strict while avoiding
+    // unrelated parent graph/rank checks.  Dynamic templates are validated at
+    // init; this guards values introduced by {{item}} rendering.
+    const spec = { version: 2, tasks: [task] };
+    validateTaskWritePolicy(task, spec, issues);
+    validateShellTaskConfig(task, spec, issues);
+    validateStaticTaskConfig(task, issues);
+    validateDecisionGateTaskConfig(task, issues);
+    validateRetryPolicyTaskConfig(task, issues);
+    validateOutputProtocolTaskConfig(task, issues);
+    validateWriterOutcomePolicyTaskConfig(task, issues);
+    validateCommandPolicyTaskConfig(task, issues);
+    if (issues.length > 0) {
+        throw new Error(`invalid materialized dynamic child ${task.id}: ${issues.map((issue) => issue.message).join("; ")}`);
+    }
+}
 export function validateDagSpec(spec) {
     const issues = [];
     if (spec.tasks.length === 0) {
@@ -778,6 +896,8 @@ export function validateDagSpec(spec) {
         validateRetryPolicyTaskConfig(task, issues);
         validateOutputProtocolTaskConfig(task, issues);
         validateWriterOutcomePolicyTaskConfig(task, issues);
+        validateCommandPolicyTaskConfig(task, issues);
+        validateDynamicChildCommandPolicy(task, issues);
         validateProjectGovernanceTaskConfig(task, spec, issues);
         validateFailureAwareDependsOn(task, spec, issues);
     }

package/docs/architecture/runtime-boundaries.md

@@ -141,7 +141,7 @@ Runner / Loop         ──(迁移中)──>  逐步改为仅经 Store / Appli
 版本化自举包含两个不同的冻结层，不能用其中一个替代另一个：
 
 | 层 | 冻结对象 | 生命周期 | 权威证据 |
-|---|---|---|---|
+| --- | --- | --- | --- |
 | Controller identity | 实际发布包、entry/realEntry、launch spec、binary hash、portable package fingerprint | Feature/batch/Task/final verification | Worker、Task Pool、batch/Feature、QA/final evidence 中的 `controllerIdentity` |
 | DAG skill snapshot | 某个 run 实际注入 prompt 的 ordered skill profiles、learned flag、budgets 与 dynamic bindings | 单个 DAG run，包括 pause/resume | `state.skillSnapshotRef` + `<runDir>/.runtime/skill-snapshot.json` |
 
@@ -150,7 +150,7 @@ Runner / Loop         ──(迁移中)──>  逐步改为仅经 Store / Appli
 **规则摘要**
 
 | From | May import | Must not import |
-|------|------------|-----------------|
+| ------ | ------------ | ----------------- |
 | `src/commands/**` | application, workflows, infrastructure, task, records, executors, shared | — |
 | `src/workflows/**` | executors, task, records, shared, application（目标） | `src/commands/**` |
 | `src/executors/**` | shared, 外部 SDK | `src/commands/**`, `src/cli/**` |
@@ -169,7 +169,7 @@ Runner / Loop         ──(迁移中)──>  逐步改为仅经 Store / Appli
 以下脚本由 `scripts/check-repo.sh` 调用（Phase 0 起）：
 
 | Script | 检查内容 | 失败条件 |
-|--------|----------|----------|
+| -------- | ---------- | ---------- |
 | `scripts/check-architecture-boundaries.sh` | workflow/executor forbidden import，及 Worker → CLI/commands/application import | 新的未 allowlist violation |
 | `scripts/check-command-registry-drift.sh` | `command-reference.md` 中的 top-level command vs `src/cli/catalog.ts` | 文档引用未注册 command |
 | `scripts/check-exec-plan-index-sync.sh` | `ai_workspace/loop-agent/exec-plans/{active,completed}` 目录文件 vs 对应 `README.md` 索引 | 任一 plan 文件未在索引登记 |
@@ -190,23 +190,25 @@ bash scripts/check-skill-entry.sh
 
 Runtime 变更另需 `npm run typecheck` 及对应 targeted Vitest（见 exec plan 各 Phase 验证关口）。
 
-## Client session 瞬态恢复边界
+## Client session 恢复边界
 
-主会话模型偶尔会返回非标准 502 / `LLMRequestError` / 网络抖动 / 超时响应；OpenCode 可能先解析为 `TypeValidationError` 再落成 `UnknownError`，导致内置 APIError 重试不命中。loop-agent 通过 **项目级 OpenCode 插件补偿** 与 **Pi 用户级配置显式启用** 处理该缺口，不修改 OpenCode/Pi 上游，也不引入外部监督器。
+主会话模型有两类常见缺口：**瞬态 UnknownError**（非标准 502 / `LLMRequestError` / 网络抖动 / 超时经 TypeValidation 落入 UnknownError，内置 APIError 重试不命中）与 **上下文过大**（含内网中文「请求上下文过大」及常见英文 overflow 文案，默认 overflow 识别不全）。loop-agent 通过 **职责分离的项目级产物** 补偿，不修改 OpenCode/Pi 上游，也不引入外部监督器，不改默认模型 `contextWindow`。
 
 | 面 | 路径 / 入口 | 边界 |
-|---|---|---|
-| OpenCode 项目插件 | `.opencode/plugins/loop-agent-transient-retry.js`（init surface `generated`） | 直接返回真实 `Hooks.event`，分发 `session.error` / `session.status` / `session.idle` / `message.updated`；每个 session 保存 pending error，busy/retry/unknown/status API 失败只暂停恢复，后续 idle 事件重新驱动单一 worker。`client.session.status({ throwOnError: true })` 在退避前后确认 idle，`client.session.promptAsync(..., throwOnError: true)` 仅在 1.18.9 的 204 响应明确返回对象型 `data` 时计入一次 attempt 并续接同一 session；只有成功完成的 assistant message 清零连续失败计数。认证/权限/配额/上下文溢出/取消/业务错误走 `plugin-ignore-permanent-error` |
+| --- | --- | --- |
+| OpenCode transient-retry | `.opencode/plugins/loop-agent-transient-retry.js`（init surface `generated`） | 仅瞬态 UnknownError resume；busy/retry 门控 + backoff；overflow/401/配额/取消/业务标 permanent（`plugin-ignore-permanent-error`），**不** compact |
+| OpenCode overflow-compact | `.opencode/plugins/loop-agent-context-overflow-compact.js`（init surface `generated`） | 仅 context overflow → `session.compact`（无则 `summarize`）+ 有限 `promptAsync` 续接；`MAX_OVERFLOW_RECOVERIES ≤ 2`；session 锁；非 overflow 不动作 |
+| Pi project extension | `.pi/extensions/loop-agent-context-overflow.js`（init surface `generated`） | `message_end` 上将 overflow `errorMessage` 幂等改写为 `context_length_exceeded:` 前缀，触发 Pi 原生 compact/retry；**不**写 `~/.pi` settings / compaction / 模型窗口 |
 | Pi 用户配置 | `~/.pi/agent/settings.json` | **不**进入项目 `.harness/init-surface.json` hash；仅 `--client-recovery=user` 可字段级补缺并原子写；`auto`/`project`/`off` 与 `check-update` 默认零写 home；读取时只有 `ENOENT` 视为缺文件，其他 I/O 错误 fail closed |
-| CLI mode | `--client-recovery=auto\|project\|user\|off`（默认 `auto`） | `auto`/`project` 只装项目插件；`user` = 项目插件 + 显式 Pi 合并；`off` 全跳过 |
-| Ownership | recorded sha256 + apply-safe | 插件缺失可补、与 recorded hash 一致可升级；用户改过 → model merge / human decision，禁止静默覆盖 |
+| CLI mode | `--client-recovery=auto\|project\|user\|off`（默认 `auto`） | `auto`/`project` 安装上述三份项目产物；`user` = 三产物 + 显式 Pi retry 合并；`off` 全跳过 |
+| Ownership | recorded sha256 + apply-safe | 三份 generated 缺失可补、与 recorded hash 一致可升级；用户改过 → model merge / human decision，禁止静默覆盖 |
 
-实现落点：`src/commands/client-recovery.ts`（纯逻辑与生成器）+ `src/commands/init.ts`（编排）。
+实现落点：`src/commands/client-recovery.ts`（共享 `isContextOverflow`、生成器与 install）+ `src/commands/init.ts`（surface 编排与 `written` 投影）。
 
 ## 演进里程碑
 
 | Phase | 边界变化 |
-|-------|----------|
+| ------- | ---------- |
 | 0（当前） | 文档 + 机器 guard；已知 loop/actions.ts 耦合 advisory |
 | 1 | CLI command definition 单源 |
 | 2 | Skill entry 瘦身 + frontmatter references |