@fitlab-ai/agent-infra 0.11.8 → 0.11.10

package/dist/lib/task/platform-operation-recovery.js

@@ -18,6 +18,8 @@ import { canonicalizeSummaryBody } from '../platform/comment-safety.js';
 import { platformResult } from '../platform/types.js';
 import { resolveTaskRef } from './resolve-ref.js';
 import { readPlatformOperationJournal, recordPlatformOperation } from './platform-operation-journal.js';
+import { providerErrorRetryable } from '../platform/provider-validation.js';
+const DEFAULT_RECOVERY_ATTEMPTS = 3;
 function labelsMatchOwnedPrefix(actual, expected, prefix) {
     return actual.filter((label) => label.startsWith(prefix)).sort().join('\0')
         === expected.filter((label) => label.startsWith(prefix)).sort().join('\0');
@@ -26,7 +28,7 @@ function fieldsMatchExpected(actual, expected) {
     return Object.entries(expected).every(([name, value]) => actual[name] === value);
 }
 function result(status, recovered, pending, error = null) {
-    return { status, changed: recovered.length > 0, recovered, pending, error };
+    return { status, changed: recovered.length > 0, recovered, pending, error: error ? { code: error.code, message: error.message } : null };
 }
 function summaryPayload(taskDir, taskId) {
     const file = path.join(taskDir, '.delivery-summary.json');
@@ -198,7 +200,7 @@ async function replayPullRequestSummary(taskId, operation, agent, cwd, client) {
         ? await resolved.value.provider.comments.list({ context: providerOperationContext(resolved.value), parent: identity })
         : unsupportedProviderOperation(resolved.value.provider, 'comments.list');
     if (!listed.ok)
-        return platformResult(listed.error.retryable ? 'blocked' : 'failed', { error: providerError(listed.error, 'PLATFORM_PROVIDER_OPERATION_FAILED') });
+        return platformResult(providerErrorRetryable(listed.error.code) ? 'blocked' : 'failed', { error: providerError(listed.error, 'PLATFORM_PROVIDER_OPERATION_FAILED') });
     const marker = `<!-- sync-pr:${taskId}:summary -->`;
     const summaries = listed.value.filter((comment) => normalizeCommentContent(comment.body).split('\n', 1)[0] === marker);
     if (summaries.length > 1)
@@ -293,7 +295,7 @@ async function replayPullRequest(taskId, operation, agent, cwd) {
     }
     return recoverCreatedPullRequest(taskId, { agent, cwd, base: intent.baseRef || '', head: intent.headRef || '', skipQueue: true });
 }
-async function recoverPlatformOperations(taskRef, selection, options) {
+async function recoverPlatformOperationsOnce(taskRef, selection, options) {
     const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
     if (!resolved.ok)
         return result('failed', [], [], { code: resolved.code, message: resolved.message, retryable: false });
@@ -307,34 +309,23 @@ async function recoverPlatformOperations(taskRef, selection, options) {
     }
     const candidates = journal.operations.filter((operation) => operation.id !== options.excludeId
         && (operation.state === 'queued' || operation.state === 'pending' || operation.state === 'unknown'
-            || (operation.state === 'failed' && operation.lastCode !== 'PLATFORM_OPERATION_SUPERSEDED')))
-        .filter((operation) => selection === 'all' || operation.dependency === selection)
-        .sort((left, right) => left.updatedAt.localeCompare(right.updatedAt));
+            || (operation.state === 'failed' && operation.lastCode !== 'PLATFORM_OPERATION_SUPERSEDED')));
     if (!candidates.length)
         return result('no-op', [], []);
+    const head = candidates[0];
+    if (selection !== 'all' && head.dependency !== selection) {
+        return result('blocked', [], candidates.map((operation) => operation.id), {
+            code: 'PLATFORM_OPERATION_RECOVERY_PENDING',
+            message: 'The first unresolved platform operation belongs to another recovery selection',
+            retryable: true
+        });
+    }
     const limit = options.limit === undefined ? candidates.length : Math.max(1, options.limit);
     const recovered = [];
     const pending = [];
     const selected = candidates.slice(0, limit);
     for (const [index, operation] of selected.entries()) {
-        if (operation.state === 'failed') {
-            pending.push(operation.id);
-            return result('blocked', recovered, pending, {
-                code: operation.lastCode || 'PLATFORM_OPERATION_FAILED',
-                message: 'A previous platform operation failed permanently; later writes remain queued',
-                retryable: false
-            });
-        }
-        if (operation.attempts >= operation.maxAttempts) {
-            pending.push(operation.id, ...selected.slice(index + 1).map((next) => next.id));
-            pending.push(...candidates.slice(limit).map((next) => next.id));
-            return result('blocked', recovered, pending, {
-                code: operation.lastCode || 'PLATFORM_OPERATION_RETRY_LIMIT_REACHED',
-                message: 'A previous platform operation exhausted its recovery attempts; later writes remain queued',
-                retryable: false
-            });
-        }
-        if (operation.kind !== 'issue-create') {
+        {
             try {
                 recordPlatformOperation({
                     taskRef: resolved.taskId, cwd: resolved.repoRoot, kind: operation.kind,
@@ -368,8 +359,8 @@ async function recoverPlatformOperations(taskRef, selection, options) {
             if (current.id !== operation.id) {
                 try {
                     recordPlatformOperation({ taskRef: resolved.taskId, cwd: resolved.repoRoot, kind: operation.kind, target: operation.target,
-                        expectedDigest: operation.expectedDigest, issueMetadata: operation.issueMetadata, dependency: operation.dependency,
-                        state: 'failed', lastCode: 'PLATFORM_OPERATION_SUPERSEDED' });
+                        expectedDigest: current.expectedDigest, issueMetadata: current.issueMetadata, dependency: operation.dependency,
+                        state: 'queued', replaceOperationId: operation.id });
                     targetOperation = { ...operation, expectedDigest: current.expectedDigest, issueMetadata: current.issueMetadata, id: current.id };
                 }
                 catch (error) {
@@ -396,7 +387,7 @@ async function recoverPlatformOperations(taskRef, selection, options) {
             if (current.id !== operation.id) {
                 try {
                     recordPlatformOperation({ taskRef: resolved.taskId, cwd: resolved.repoRoot, kind: operation.kind, target: operation.target,
-                        expectedDigest: operation.expectedDigest, dependency: operation.dependency, state: 'failed', lastCode: 'PLATFORM_OPERATION_SUPERSEDED' });
+                        expectedDigest: current.expectedDigest, dependency: operation.dependency, state: 'queued', replaceOperationId: operation.id });
                     targetOperation = { ...operation, expectedDigest: current.expectedDigest, id: current.id };
                 }
                 catch (error) {
@@ -437,7 +428,7 @@ async function recoverPlatformOperations(taskRef, selection, options) {
                 ...(operation.pullRequestSummary ? { pullRequestSummary: operation.pullRequestSummary } : {}),
                 ...(operation.pullRequestReview ? { pullRequestReview: operation.pullRequestReview } : {}),
                 dependency: operation.dependency,
-                state: succeeded ? 'succeeded' : remote.status === 'failed' && remote.error?.retryable === false ? 'failed' : 'unknown',
+                state: succeeded ? 'succeeded' : 'unknown',
                 lastCode: remote.error?.code ?? null
             });
         }
@@ -455,5 +446,81 @@ async function recoverPlatformOperations(taskRef, selection, options) {
     pending.push(...remaining);
     return result(pending.length ? 'blocked' : recovered.length ? 'applied' : 'no-op', recovered, pending, pending.length ? { code: 'PLATFORM_OPERATION_RECOVERY_PENDING', message: 'Platform operations remain pending after the recovery budget', retryable: true } : null);
 }
+async function recoverPlatformOperations(taskRef, selection, options) {
+    const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
+    if (!resolved.ok)
+        return result('failed', [], [], { code: resolved.code, message: resolved.message, retryable: false });
+    let initial;
+    try {
+        initial = readPlatformOperationJournal(resolved.taskId, resolved.repoRoot);
+    }
+    catch (error) {
+        const value = error;
+        return result('failed', [], [], { code: value.code || 'PLATFORM_OPERATION_JOURNAL_INVALID', message: value.message || String(error), retryable: false });
+    }
+    const eligible = (operation) => operation.id !== options.excludeId
+        && (operation.state === 'queued' || operation.state === 'pending' || operation.state === 'unknown'
+            || (operation.state === 'failed' && operation.lastCode !== 'PLATFORM_OPERATION_SUPERSEDED'));
+    const first = initial.operations.filter(eligible);
+    if (!first.length)
+        return result('no-op', [], []);
+    const operationLimit = options.limit === undefined ? first.length : Math.max(1, options.limit);
+    const attemptLimit = options.attempts ?? DEFAULT_RECOVERY_ATTEMPTS;
+    if (!Number.isSafeInteger(attemptLimit) || attemptLimit <= 0) {
+        return result('failed', [], [], { code: 'PLATFORM_OPERATION_RECOVERY_PAYLOAD_INVALID', message: 'Recovery attempts must be a positive safe integer', retryable: false });
+    }
+    const recovered = [];
+    for (let operationIndex = 0; operationIndex < operationLimit; operationIndex += 1) {
+        let latest;
+        try {
+            latest = readPlatformOperationJournal(resolved.taskId, resolved.repoRoot);
+        }
+        catch (error) {
+            const value = error;
+            return result('failed', recovered, [], { code: value.code || 'PLATFORM_OPERATION_JOURNAL_INVALID', message: value.message || String(error), retryable: false });
+        }
+        const head = latest.operations.find(eligible);
+        if (!head)
+            break;
+        if (selection !== 'all' && head.dependency !== selection) {
+            const pending = latest.operations.filter(eligible).map((operation) => operation.id);
+            return result('blocked', recovered, pending, {
+                code: 'PLATFORM_OPERATION_RECOVERY_PENDING',
+                message: 'The first unresolved platform operation belongs to another recovery selection',
+                retryable: true
+            });
+        }
+        let last = null;
+        for (let attempt = 0; attempt < attemptLimit; attempt += 1) {
+            last = await recoverPlatformOperationsOnce(taskRef, selection, { ...options, limit: 1 });
+            recovered.push(...last.recovered.filter((id) => !recovered.includes(id)));
+            if (last.recovered.length > 0 || last.status === 'applied' || last.status === 'no-op')
+                break;
+        }
+        if (!last || (last.recovered.length === 0 && last.status !== 'applied' && last.status !== 'no-op')) {
+            let current;
+            try {
+                current = readPlatformOperationJournal(resolved.taskId, resolved.repoRoot);
+            }
+            catch {
+                return result('blocked', recovered, [head.id], last?.error ?? null);
+            }
+            const pending = current.operations.filter(eligible).map((operation) => operation.id);
+            return result(last?.status === 'failed' ? 'failed' : 'blocked', recovered, pending, last?.error ?? {
+                code: 'PLATFORM_OPERATION_RECOVERY_PENDING',
+                message: 'The first queued platform operation remains unresolved after this recovery run',
+                retryable: true
+            });
+        }
+    }
+    let remaining;
+    try {
+        remaining = readPlatformOperationJournal(resolved.taskId, resolved.repoRoot).operations.filter(eligible).map((operation) => operation.id);
+    }
+    catch {
+        remaining = [];
+    }
+    return result(remaining.length ? 'blocked' : recovered.length ? 'applied' : 'no-op', recovered, remaining, remaining.length ? { code: 'PLATFORM_OPERATION_RECOVERY_PENDING', message: 'Platform operations remain queued after this recovery run', retryable: true } : null);
+}
 export { fieldsMatchExpected, labelsMatchOwnedPrefix, recoverPlatformOperations };
 //# sourceMappingURL=platform-operation-recovery.js.map

package/dist/lib/task/review-fingerprint.js

@@ -1,7 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { artifactName, maxArtifactRound } from "./artifact-name.js";
-import { invalidationBlocks, isArtifactInvalidated, parseInvalidationDocument } from "./invalidation.js";
+import { inspectArtifactDirectory } from "./artifact-lifecycle.js";
 const REVIEWED_TREE_RE = /^[a-f0-9]{40,64}$/;
 export function parseReviewedGitTree(value) {
     return REVIEWED_TREE_RE.test(value) ? value : null;
@@ -28,32 +27,11 @@ export function resolvePostReviewGlobs(config = {}, reviewConfig = {}) {
     return [":/", ...excludes.map((p) => `:(top,exclude)${p}`)];
 }
 export function findAuthoritativeReviewCodeArtifact(taskDir) {
-    const entries = fs.existsSync(taskDir) ? fs.readdirSync(taskDir) : [];
-    const round = maxArtifactRound(entries, "review-code");
-    if (round === 0) {
+    const inventory = inspectArtifactDirectory(taskDir, 'review-code');
+    if (inventory.status !== 'ready' || !inventory.latest) {
         return { ok: false, round: 0, fileName: null, path: null, error: null };
     }
-    const fileName = artifactName("review-code", round);
-    let taskContent;
-    try {
-        taskContent = fs.readFileSync(path.join(taskDir, "task.md"), "utf8");
-    }
-    catch (error) {
-        return {
-            ok: false, round, fileName, path: null,
-            error: error instanceof Error ? error.message : String(error)
-        };
-    }
-    const invalidation = parseInvalidationDocument(taskContent);
-    if (!invalidation.ok) {
-        return { ok: false, round, fileName, path: null, error: invalidation.message };
-    }
-    if (invalidationBlocks(invalidation.document)) {
-        return { ok: false, round, fileName, path: null, error: "artifact invalidation is incomplete; reconcile task.md before using review-code" };
-    }
-    if (isArtifactInvalidated(invalidation.document, "review-code", fileName)) {
-        return { ok: false, round, fileName, path: null, error: `${fileName} is invalidated; re-run review-code` };
-    }
+    const { round, name: fileName } = inventory.latest;
     return {
         ok: true,
         round,

package/dist/lib/task/verification-engine.js

@@ -19,7 +19,7 @@ import { inspectDecisionDetailDuplicates } from "./decision-details.js";
 import { parseImplementationInputs } from "./implementation-inputs.js";
 import { scanVisibleMarkdown } from "./markdown.js";
 import { loadVerificationConfig } from "./verification-config.js";
-import { inspectActivityLog } from "./activity-log.js";
+import { inspectActivityLog, pairEntries } from "./activity-log.js";
 import { parseWorkflowWarnings } from "./workflow-warnings.js";
 import { OrchestrationStateError, readRun } from "./orchestration.js";
 import { readPrDeliveryFact } from "./pr-delivery-fact.js";
@@ -30,9 +30,11 @@ import { normalizeVerificationRecord } from './gate-policy.js';
 import { manualValidationFinalSummaryProjectionMatches } from "./manual-validation-receipt.js";
 import { readManualValidationCompletion } from "./manual-validation-completion.js";
 import { sha256File } from "./artifact-receipts.js";
+import { inspectArtifactDirectory } from "./artifact-lifecycle.js";
+import { parseArtifactName } from "./artifact-name.js";
 import { summaryCommentState } from "../platform/pr-summary.js";
 import { taskIssueIdentity } from "../platform/task-identities.js";
-import { hasArtifactCompletionFact, hasArtifactCompletionLog } from './completion-facts.js';
+import { hasArtifactCompletionFact, hasArtifactCompletionLog, parseCompletionFacts } from './completion-facts.js';
 import { inspectReviewIdentity } from './review-identity.js';
 const TASK_ENUMS = {
     type: ["feature", "bugfix", "refactor", "docs", "chore"],
@@ -264,7 +266,7 @@ function checkOrchestrationEvidence({ taskDir }) {
     return passResult('orchestration-evidence', 'Persisted orchestration model and delegation evidence is internally consistent');
 }
 // === Check Functions ===
-function checkTaskMeta({ taskDir, config, repositoryRoot }) {
+function checkTaskMeta({ taskDir, config, repositoryRoot, skillName, artifactFile }) {
     const task = loadTask(taskDir);
     if (!task.ok) {
         return failResult("task-meta", task.message);
@@ -306,7 +308,22 @@ function checkTaskMeta({ taskDir, config, repositoryRoot }) {
     }
     const expectedStep = config.expected_step;
     if (expectedStep && metadata.current_step !== expectedStep) {
-        return failResult("task-meta", `Expected current_step '${expectedStep}', got '${metadata.current_step || "(empty)"}'`);
+        let validLifecycleArtifact = false;
+        if (currentTask) {
+            const activityConfig = loadVerificationConfig(repositoryRoot, skillName).checks?.["activity-log"];
+            const { section, invalidEntries } = inspectActivityLog(task.content);
+            if (activityConfig && section && invalidEntries.length === 0) {
+                let latestAction = "";
+                for (const entry of section.entries) {
+                    if (!ACTIVITY_LOG_STARTED_RE.test(entry.step))
+                        latestAction = entry.step;
+                }
+                validLifecycleArtifact = checkArtifactLifecycleActivityLog(taskDir, artifactFile, skillName, activityConfig, task, section.entries, latestAction)?.status === "pass";
+            }
+        }
+        if (!validLifecycleArtifact) {
+            return failResult("task-meta", `Expected current_step '${expectedStep}', got '${metadata.current_step || "(empty)"}'`);
+        }
     }
     const expectedStatus = config.expected_status;
     if (expectedStatus && metadata.status !== expectedStatus) {
@@ -604,7 +621,73 @@ function checkImplementationInput({ taskDir, artifactFile }) {
     }
     return passResult("implementation-input", `${actionDecision} matches Activity Log, report, and task table`);
 }
-function checkActivityLog({ taskDir, config }) {
+const ARTIFACT_ACTIVITY_STAGES = {
+    "analyze-task": { family: "analysis", event: "analyze.completed" },
+    "plan-task": { family: "plan", event: "plan.completed" },
+    "review-analysis": { family: "review-analysis", event: "review-analysis.completed" },
+    "review-plan": { family: "review-plan", event: "review-plan.completed" },
+    "code-task": { family: "code", event: "code.completed" },
+    "review-code": { family: "review-code", event: "review-code.completed" }
+};
+function checkArtifactLifecycleActivityLog(taskDir, artifactFile, skillName, config, task, entries, latestAction) {
+    const stage = ARTIFACT_ACTIVITY_STAGES[skillName];
+    if (!stage)
+        return null;
+    const inventory = inspectArtifactDirectory(taskDir, stage.family);
+    if (inventory.status !== "ready" || !inventory.latest) {
+        return failResult("activity-log", `Current ${stage.family} artifact is unavailable: ${inventory.error?.message ?? "no artifact exists"}`);
+    }
+    const output = artifactFile || inventory.latest.name;
+    if (output !== inventory.latest.name) {
+        return failResult("activity-log", `Artifact '${output}' is not the current ${stage.family} artifact; rerun ${skillName} for '${inventory.latest.name}'`);
+    }
+    const identity = parseArtifactName(output);
+    if (!identity || identity.family !== stage.family) {
+        return failResult("activity-log", `Artifact '${output}' does not belong to ${stage.family}`);
+    }
+    if (!hasArtifactCompletionFact(task.content, path.join(taskDir, output), stage.event)) {
+        return failResult("activity-log", `Completion fact for '${output}' is missing or stale; rerun ${skillName} to record a current completion`);
+    }
+    const frontmatter = parseTypedTaskFrontmatter(task.content);
+    const fact = parseCompletionFacts(frontmatter.completion_facts).find((item) => item.event === stage.event && item.output === output);
+    if (!fact)
+        return failResult("activity-log", `Completion fact for '${output}' is missing; rerun ${skillName}`);
+    if (!Array.isArray(fact.lifecycleInputs)) {
+        return failResult("activity-log", `Completion fact for '${output}' has no input snapshot; rerun ${skillName}`);
+    }
+    for (const input of fact.lifecycleInputs) {
+        if (!input || typeof input.name !== "string" || !/^[a-f0-9]{64}$/u.test(input.sha256)) {
+            return failResult("activity-log", `Completion fact for '${output}' has an invalid input snapshot; rerun ${skillName}`);
+        }
+        const inputIdentity = parseArtifactName(input.name);
+        if (!inputIdentity)
+            return failResult("activity-log", `Completion fact for '${output}' has invalid input '${input.name}'; rerun ${skillName}`);
+        const inputInventory = inspectArtifactDirectory(taskDir, inputIdentity.family);
+        if (inputInventory.status !== "ready" || inputInventory.latest?.name !== input.name
+            || sha256File(path.join(taskDir, input.name)) !== input.sha256) {
+            return failResult("activity-log", `Input '${input.name}' changed or is no longer current; rerun ${skillName} to refresh '${output}'`);
+        }
+    }
+    const expectedAction = new RegExp(config.expected_action_pattern);
+    const roundAction = entries.find((entry) => {
+        if (ACTIVITY_LOG_STARTED_RE.test(entry.step))
+            return false;
+        if (!expectedAction.test(entry.step))
+            return false;
+        expectedAction.lastIndex = 0;
+        const actionRound = /\(Round (\d+)/.exec(entry.step)?.[1];
+        return actionRound === String(identity.round) && entry.note.includes(`→ ${output}`);
+    });
+    if (!roundAction) {
+        return failResult("activity-log", `No completed Activity Log row records '${output}' for ${skillName} Round ${identity.round}`);
+    }
+    if (skillName === "plan-task" && /^(?:Human Decision|Decision)\b/.test(latestAction)
+        && expectedAction.test(latestAction)) {
+        return passResult("activity-log", `Plan completion '${output}' is current; latest action '${latestAction}' is a human decision`);
+    }
+    return passResult("activity-log", `Current ${stage.family} completion '${output}' is valid for Round ${identity.round}`);
+}
+function checkActivityLog({ taskDir, config, skillName, artifactFile }) {
     const task = loadTask(taskDir);
     if (!task.ok) {
         return failResult("activity-log", task.message);
@@ -638,6 +721,9 @@ function checkActivityLog({ taskDir, config }) {
             doneActions.push(action);
         }
     }
+    const artifactLifecycleResult = checkArtifactLifecycleActivityLog(taskDir, artifactFile, skillName, config, task, entries, latestAction);
+    if (artifactLifecycleResult)
+        return artifactLifecycleResult;
     if (config.expected_action_pattern && !new RegExp(config.expected_action_pattern).test(latestAction)) {
         const expected = new RegExp(config.expected_action_pattern);
         let index = doneActions.length - 1;
@@ -799,7 +885,10 @@ async function checkManualValidation({ taskDir, repositoryRoot }) {
     const inspectedLog = inspectActivityLog(task.content);
     if (!inspectedLog.section)
         return failResult("manual-validation", "Activity Log is missing or invalid");
-    const reviewDoneIndex = inspectedLog.section.entries.findIndex((entry) => entry.step === `Review Code (Round ${review.round})`);
+    const reviewRow = pairEntries(inspectedLog.section.entries).find((row) => row.step === `Review Code (Round ${review.round})` && row.started !== '' && row.done !== '');
+    const reviewDoneIndex = reviewRow
+        ? inspectedLog.section.entries.findIndex((entry) => entry.step === reviewRow.step && entry.time === reviewRow.done)
+        : -1;
     const completedIndex = inspectedLog.section.entries.findIndex((entry) => entry.step === "Complete Manual Validation"
         && entry.note.includes(`Manual validation passed → ${artifactName};`)
         && entry.note.includes(`transaction=${receipt.transactionId};`)

package/dist/lib/task/verification.js

@@ -22,7 +22,6 @@ const VERIFICATION_CATALOG = {
     'commit.completed': gate('commit', 'active'),
     'complete-task.preflight': { skill: 'complete-task', expectedState: 'active', mode: 'checks', checks: ['required-pr-delivery'] },
     'complete-task.hard-preflight': { skill: 'complete-task', expectedState: 'active', mode: 'checks', checks: ['required-pr-delivery'] },
-    'complete-task.prepared': gate('complete-task', 'active'),
     'complete-task.completed': gate('complete-task', 'completed'),
     'create-pr.completed': gate('create-pr', 'active'),
     'create-task.completed': gate('create-task', 'active'),

package/dist/lib/task/write.js

@@ -6,7 +6,6 @@ import { parseTypedTaskFrontmatter, updateTaskFrontmatter } from './frontmatter.
 import { resolveTaskRef } from './resolve-ref.js';
 import { mutateTableRow, upsertSection } from './sections.js';
 import { validateCurrentTaskContract } from './current-contract.js';
-import { invalidationBlocks, parseInvalidationDocument } from './invalidation.js';
 const DEFAULT_FILE_SYSTEM = {
     readFileSync: (file) => fs.readFileSync(file, 'utf8'),
     statModeSync: (file) => fs.statSync(file).mode,
@@ -91,16 +90,6 @@ function writeTaskCore(request, options = {}) {
         if (!contract.ok) {
             return failure(request, identity, contract.code, contract.message);
         }
-        if (invalidationBlocks(contract.invalidation)
-            && options.invalidationContext !== 'source-completion'
-            && options.invalidationContext !== 'reconcile') {
-            return failure(request, identity, 'TASK_INVALIDATION_BLOCKED', 'task has an incomplete artifact invalidation operation; reconcile it before writing downstream state');
-        }
-    }
-    else {
-        const invalidation = parseInvalidationDocument(original);
-        if (!invalidation.ok)
-            return failure(request, identity, 'TASK_INVALIDATION_INVALID', invalidation.message);
     }
     let candidate = original;
     const operations = [];

package/dist/lib/update.js

@@ -132,8 +132,8 @@ async function cmdSync() {
     ok('Seed files synced successfully!');
     console.log('');
     if (workflowPlan.nextSteps.length === 0) {
-        console.log('  No Agent Client project integration enabled.');
-        console.log(`  Configure "customTUIs" in ${CONFIG_PATH} if needed.`);
+        console.log('  No Agent Client or sandbox custom tool integration enabled.');
+        console.log(`  Configure a custom tool in "sandbox.tools.definitions" and select it in "sandbox.tools.ids" in ${CONFIG_PATH}.`);
         console.log('');
     }
     else {

package/dist/lifecycle-build-manifest.json

@@ -1,6 +1,6 @@
 {
   "protocolVersion": 3,
-  "packageVersion": "0.11.8",
-  "sourceInputHash": "6ddb72f8b50137d5148a47172bd7eb2628b17a937ae647ac38350e582ba08124",
-  "internalExecutableBuildHash": "c886e015506879620bb490f1ea5977d9952f2bbb4515d3a0b49e0ec184b48028"
+  "packageVersion": "0.11.10",
+  "sourceInputHash": "3500e8eb7fac8bbad3d95124002f8042af3d160185a5b635eb9b4d8f88a991cb",
+  "internalExecutableBuildHash": "51a4c472b6a54b3ca3c28ab049683175d3ea4730fe560868f853cd603b5a98f1"
 }

package/lib/agent-clients/custom-tool-invocations.ts

@@ -0,0 +1,129 @@
+type CustomToolInvocation = Readonly<{
+  name: string;
+  invocation: string;
+}>;
+
+type CustomToolInvocationDiagnosticCode =
+  | 'INVALID_CUSTOM_TOOL_CONFIG'
+  | 'INVALID_CUSTOM_TOOL_INVOCATION'
+  | 'INVALID_CUSTOM_TOOL_INVOCATION_PLACEHOLDER';
+
+type CustomToolInvocationDiagnostic = Readonly<{
+  code: CustomToolInvocationDiagnosticCode;
+  path: string;
+}>;
+
+type NormalizeCustomToolInvocationsResult = Readonly<{
+  items: readonly CustomToolInvocation[];
+  diagnostics: readonly CustomToolInvocationDiagnostic[];
+}>;
+
+const ALLOWED_PLACEHOLDERS = Object.freeze(['skillName', 'projectName']);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptySingleLine(value: unknown): value is string {
+  return typeof value === 'string'
+    && value.trim() !== ''
+    && !/[\r\n]/.test(value);
+}
+
+function hasValidPlaceholders(invocation: string): boolean {
+  const placeholders = [
+    ...invocation.matchAll(/\$\{([^}]+)\}/g)
+  ].map((match) => match[1]!);
+  return placeholders.includes('skillName')
+    && placeholders.every((placeholder) =>
+      ALLOWED_PLACEHOLDERS.includes(placeholder)
+    )
+    && !invocation
+      .replaceAll('${skillName}', '')
+      .replaceAll('${projectName}', '')
+      .includes('${');
+}
+
+function normalizeCustomToolInvocations(config: unknown): NormalizeCustomToolInvocationsResult {
+  const items: CustomToolInvocation[] = [];
+  const diagnostics: CustomToolInvocationDiagnostic[] = [];
+
+  const root = isRecord(config) ? config : {};
+  const sandbox = isRecord(root.sandbox) ? root.sandbox : {};
+  const sandboxTools = isRecord(sandbox.tools) ? sandbox.tools : { ids: ['agent-infra'] };
+  const definitions = sandboxTools.definitions ?? {};
+  const selectedIds = sandboxTools.ids;
+
+  if (!Array.isArray(selectedIds)) {
+    return Object.freeze({
+      items: Object.freeze([]),
+      diagnostics: Object.freeze([
+        Object.freeze({
+          code: 'INVALID_CUSTOM_TOOL_CONFIG' as const,
+          path: 'sandbox.tools.ids'
+        })
+      ])
+    });
+  }
+
+  if (!isRecord(definitions)) {
+    return Object.freeze({
+      items: Object.freeze([]),
+      diagnostics: Object.freeze([
+        Object.freeze({
+          code: 'INVALID_CUSTOM_TOOL_CONFIG' as const,
+          path: 'sandbox.tools.definitions'
+        })
+      ])
+    });
+  }
+
+  for (const [index, id] of selectedIds.entries()) {
+    if (typeof id !== 'string') {
+      diagnostics.push({
+        code: 'INVALID_CUSTOM_TOOL_INVOCATION',
+        path: `sandbox.tools.ids[${index}]`
+      });
+      continue;
+    }
+    const candidate = definitions[id];
+    if (!isRecord(candidate)) continue;
+    if (candidate.invoke === undefined) continue;
+    const base = `sandbox.tools.definitions.${id}`;
+    const name = candidate.name === undefined ? id : candidate.name;
+    if (!isNonEmptySingleLine(name)) {
+      diagnostics.push({ code: 'INVALID_CUSTOM_TOOL_INVOCATION', path: `${base}.name` });
+      continue;
+    }
+    if (!isNonEmptySingleLine(candidate.invoke)) {
+      diagnostics.push({ code: 'INVALID_CUSTOM_TOOL_INVOCATION', path: `${base}.invoke` });
+      continue;
+    }
+    if (!hasValidPlaceholders(candidate.invoke)) {
+      diagnostics.push({
+        code: 'INVALID_CUSTOM_TOOL_INVOCATION_PLACEHOLDER',
+        path: `${base}.invoke`
+      });
+      continue;
+    }
+    items.push(Object.freeze({
+      name,
+      invocation: candidate.invoke
+    }));
+  }
+
+  return Object.freeze({
+    items: Object.freeze(items),
+    diagnostics: Object.freeze(
+      diagnostics.map((diagnostic) => Object.freeze(diagnostic))
+    )
+  });
+}
+
+export { normalizeCustomToolInvocations };
+export type {
+  CustomToolInvocation,
+  CustomToolInvocationDiagnostic,
+  CustomToolInvocationDiagnosticCode,
+  NormalizeCustomToolInvocationsResult
+};

package/lib/agent-clients/next-steps.ts

@@ -2,7 +2,7 @@ import { listEnabledAgentClientAdapters } from './registry.ts';
 import { renderAgentClientInvocation } from './invocation.ts';
 import semver from 'semver';
 import { isTaskScopeSkill } from '../task/skill-scope.ts';
-import type { CustomTUI } from './custom-tuis.ts';
+import type { CustomToolInvocation } from './custom-tool-invocations.ts';
 import type { AgentClientId, AgentClientState } from './types.ts';
 
 type NextStepCommand = Readonly<{
@@ -15,7 +15,7 @@ type NextStepCommand = Readonly<{
 type RenderNextStepsInput = Readonly<{
   projectName: string;
   state: AgentClientState;
-  customTUIs: readonly CustomTUI[];
+  customToolInvocations: readonly CustomToolInvocation[];
   skillName: string;
   taskRef?: string;
   version?: string;
@@ -69,7 +69,7 @@ function renderNextStepCommands(
       )
     })
   );
-  const custom = input.customTUIs.map(
+  const custom = input.customToolInvocations.map(
     (tool): NextStepCommand => Object.freeze({
       source: 'custom',
       displayName: tool.name,

package/lib/agent-clients/reconcile.ts

@@ -4,7 +4,7 @@ import path from 'node:path';
 
 import defaults from '../defaults.json' with { type: 'json' };
 import { normalizeAgentClients, serializeAgentClients } from './config.ts';
-import { normalizeCustomTUIs } from './custom-tuis.ts';
+import { normalizeCustomToolInvocations } from './custom-tool-invocations.ts';
 import { renderNextStepCommands } from './next-steps.ts';
 import { planAgentClientProjectAssets } from './project-assets.ts';
 import {
@@ -216,11 +216,11 @@ function planAgentClientReconciliation(input: Readonly<{
     delete (nextConfig.files as Record<string, unknown>).managedBaselines;
   }
 
-  const custom = normalizeCustomTUIs(input.projectRoot, input.config.customTUIs ?? []);
+  const custom = normalizeCustomToolInvocations(input.config);
   const nextSteps = renderNextStepCommands({
     projectName,
     state: desired,
-    customTUIs: custom.items,
+    customToolInvocations: custom.items,
     skillName: 'update-agent-infra'
   });
   const actionableSeed = seedOperations.some((operation) =>