@fitlab-ai/agent-infra 0.9.11 → 0.9.12

package/dist/lib/task/pr-delivery-fact.js

@@ -0,0 +1,182 @@
+const PR_DELIVERY_FACT_KEY = 'pr_delivery_fact';
+function factError(message) {
+    return Object.assign(new Error(`PR_DELIVERY_FACT_INVALID: ${message}`), { code: 'PR_DELIVERY_FACT_INVALID' });
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function exactKeys(value, keys, label) {
+    const actual = Object.keys(value).sort();
+    const expected = [...keys].sort();
+    if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+        throw factError(`${label} has an invalid field set`);
+    }
+}
+function text(value, label) {
+    if (typeof value !== 'string' || !value || value.trim() !== value)
+        throw factError(`${label} must be a non-empty string`);
+    return value;
+}
+function nullableText(value, label) {
+    return value === null ? null : text(value, label);
+}
+function positiveNumber(value, label) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw factError(`${label} must be a positive integer`);
+    return value;
+}
+function optionalTimestamp(value, label) {
+    const result = nullableText(value, label);
+    if (result !== null && Number.isNaN(Date.parse(result)))
+        throw factError(`${label} must be a valid timestamp`);
+    return result;
+}
+function parseIdentity(value) {
+    if (!isRecord(value))
+        throw factError('identity must be an object');
+    exactKeys(value, ['repository', 'number', 'nodeId', 'url', 'head', 'base'], 'identity');
+    const head = parseRef(value.head, 'head');
+    const base = parseRef(value.base, 'base');
+    return {
+        repository: text(value.repository, 'identity.repository'),
+        number: positiveNumber(value.number, 'identity.number'),
+        nodeId: text(value.nodeId, 'identity.nodeId'),
+        url: text(value.url, 'identity.url'),
+        head,
+        base
+    };
+}
+function parseRef(value, label) {
+    if (!isRecord(value))
+        throw factError(`${label} must be an object`);
+    exactKeys(value, ['repository', 'ref', 'sha'], label);
+    return {
+        repository: text(value.repository, `${label}.repository`),
+        ref: text(value.ref, `${label}.ref`),
+        sha: text(value.sha, `${label}.sha`)
+    };
+}
+function parseFact(value) {
+    if (!isRecord(value))
+        throw factError('fact must be an object');
+    if (value.version !== 1 || typeof value.state !== 'string')
+        throw factError('version or state is invalid');
+    if (value.state === 'unbound') {
+        exactKeys(value, ['version', 'state', 'reason'], 'unbound fact');
+        if (value.reason !== 'initial')
+            throw factError('unbound reason is invalid');
+        return { version: 1, state: 'unbound', reason: value.reason };
+    }
+    if (value.state === 'skipped') {
+        exactKeys(value, ['version', 'state', 'reason', 'decidedAt'], 'skipped fact');
+        if (value.reason !== 'explicit')
+            throw factError('skipped reason is invalid');
+        const decidedAt = text(value.decidedAt, 'skipped.decidedAt');
+        if (Number.isNaN(Date.parse(decidedAt)))
+            throw factError('skipped.decidedAt must be a valid timestamp');
+        return { version: 1, state: 'skipped', reason: 'explicit', decidedAt };
+    }
+    if (value.state !== 'bound')
+        throw factError('state is invalid');
+    exactKeys(value, ['version', 'state', 'identity', 'binding', 'provenance'], 'bound fact');
+    if (!isRecord(value.binding))
+        throw factError('binding must be an object');
+    exactKeys(value.binding, ['status', 'source', 'verifiedAt', 'issueNumber', 'remoteState', 'mergedAt', 'mergeCommitSha'], 'binding');
+    if (value.binding.status !== 'verified')
+        throw factError('binding status is invalid');
+    const sources = ['created', 'reused', 'explicit-bind', 'external-unique', 'external-explicit'];
+    if (!sources.includes(value.binding.source))
+        throw factError('binding source is invalid');
+    const verifiedAt = text(value.binding.verifiedAt, 'binding.verifiedAt');
+    if (Number.isNaN(Date.parse(verifiedAt)))
+        throw factError('binding.verifiedAt must be a valid timestamp');
+    const issueNumber = value.binding.issueNumber === null ? null : positiveNumber(value.binding.issueNumber, 'binding.issueNumber');
+    if (value.binding.remoteState !== 'open' && value.binding.remoteState !== 'closed')
+        throw factError('binding.remoteState is invalid');
+    const mergedAt = optionalTimestamp(value.binding.mergedAt, 'binding.mergedAt');
+    const mergeCommitSha = nullableText(value.binding.mergeCommitSha, 'binding.mergeCommitSha');
+    if (Boolean(mergedAt) !== Boolean(mergeCommitSha))
+        throw factError('mergedAt and mergeCommitSha must be paired');
+    if (!isRecord(value.provenance))
+        throw factError('provenance must be an object');
+    exactKeys(value.provenance, ['establishedBy'], 'provenance');
+    const provenance = ['create-post', 'reuse', 'explicit-bind', 'external-unique', 'external-explicit'];
+    if (!provenance.includes(value.provenance.establishedBy))
+        throw factError('provenance.establishedBy is invalid');
+    if (value.provenance.establishedBy !== provenanceForSource(value.binding.source)) {
+        throw factError('binding.source and provenance.establishedBy do not match');
+    }
+    return {
+        version: 1,
+        state: 'bound',
+        identity: parseIdentity(value.identity),
+        binding: {
+            status: 'verified',
+            source: value.binding.source,
+            verifiedAt,
+            issueNumber,
+            remoteState: value.binding.remoteState,
+            mergedAt,
+            mergeCommitSha
+        },
+        provenance: { establishedBy: value.provenance.establishedBy }
+    };
+}
+function decodePrDeliveryFact(value) {
+    if (typeof value === 'string') {
+        try {
+            return parseFact(JSON.parse(value));
+        }
+        catch (error) {
+            throw error instanceof Error && error.message.startsWith('PR_DELIVERY_FACT_INVALID:') ? error : factError('value is not valid JSON');
+        }
+    }
+    return parseFact(value);
+}
+function encodePrDeliveryFact(fact) {
+    return JSON.stringify(parseFact(fact));
+}
+function readPrDeliveryFact(metadata) {
+    if (!Object.hasOwn(metadata, PR_DELIVERY_FACT_KEY) || metadata[PR_DELIVERY_FACT_KEY] === '')
+        return { status: 'missing', fact: null };
+    try {
+        return { status: 'valid', fact: decodePrDeliveryFact(metadata[PR_DELIVERY_FACT_KEY]) };
+    }
+    catch (error) {
+        return { status: 'invalid', fact: null, error: error instanceof Error ? error : factError(String(error)) };
+    }
+}
+function buildUnboundFact() {
+    return { version: 1, state: 'unbound', reason: 'initial' };
+}
+function buildSkippedFact(decidedAt) {
+    return parseFact({ version: 1, state: 'skipped', reason: 'explicit', decidedAt });
+}
+function provenanceForSource(source) {
+    return source === 'created' ? 'create-post' : source === 'reused' ? 'reuse' : source;
+}
+function buildBoundFact(input) {
+    return parseFact({
+        version: 1,
+        state: 'bound',
+        identity: input.identity,
+        binding: {
+            status: 'verified',
+            source: input.source,
+            verifiedAt: input.verifiedAt,
+            issueNumber: input.issueNumber ?? null,
+            remoteState: input.remoteState,
+            mergedAt: input.mergedAt ?? null,
+            mergeCommitSha: input.mergeCommitSha ?? null
+        },
+        provenance: { establishedBy: provenanceForSource(input.source) }
+    });
+}
+function factFrontmatterMutation(fact) {
+    return { set: { [PR_DELIVERY_FACT_KEY]: encodePrDeliveryFact(fact) } };
+}
+function identityFromPullRequest(pullRequest) {
+    return parseIdentity(pullRequest);
+}
+export { PR_DELIVERY_FACT_KEY, buildBoundFact, buildSkippedFact, buildUnboundFact, decodePrDeliveryFact, encodePrDeliveryFact, factFrontmatterMutation, identityFromPullRequest, readPrDeliveryFact };
+//# sourceMappingURL=pr-delivery-fact.js.map

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

@@ -5,7 +5,7 @@ import { locateActivityLog, pairEntries, startedBackedRows } from './activity-lo
 import { parseArtifactName, validateCompletedArtifact } from './artifact-lifecycle.js';
 import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.js';
 import { finalizeReviewSummaryContent } from './review-artifacts.js';
-import { inspectDecisionDetailDuplicates, repairDecisionDetailDuplicates } from './decision-details.js';
+import { inspectDecisionDetailDuplicates } from './decision-details.js';
 import { resolveTaskRef } from './resolve-ref.js';
 import { validateLifecycleExecution } from './lifecycle-execution.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.js';
@@ -118,19 +118,15 @@ function finalizeReviewSummaryUnlocked(request, options = {}) {
         return failed(request, 'REVIEW_LEDGER_INVALID', `${ledgerError.code}: ${ledgerError.message}`, resolved.taskId);
     }
     const stageStatus = summarizeLedgerStage(rows, stage);
-    const repaired = repairDecisionDetailDuplicates(artifactContent);
-    if (!repaired.ok) {
-        return failed(request, 'REVIEW_DECISION_DETAIL_INVALID', `${repaired.code}: ${repaired.message}`, resolved.taskId, stageStatus);
-    }
-    const detailInspection = inspectDecisionDetailDuplicates(repaired.content);
+    const detailInspection = inspectDecisionDetailDuplicates(artifactContent);
     if (!detailInspection.ok) {
         return failed(request, 'REVIEW_DECISION_DETAIL_INVALID', `${detailInspection.code}: ${detailInspection.message}`, resolved.taskId, stageStatus);
     }
-    const transformed = finalizeReviewSummaryContent(repaired.content, stageStatus.unresolvedFindingCounts);
+    const transformed = finalizeReviewSummaryContent(artifactContent, stageStatus.unresolvedFindingCounts);
     if (!transformed.ok) {
         return failed(request, transformed.code, transformed.message, resolved.taskId, stageStatus);
     }
-    if (!repaired.changed && !transformed.changed) {
+    if (!transformed.changed) {
         return {
             ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, stageStatus),
             status: 'no-op',

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

@@ -44,6 +44,14 @@ export function extractReviewBaseline(content) {
     const match = String(content).match(/^[-*]?\s*\*\*(?:审查基线提交|Review Baseline Commit)\*\*[:：]\s*(.*?)\s*$/m);
     return match ? match[1].trim().replace(/`/g, "") : "";
 }
+export function extractReviewTargetHead(content) {
+    const match = String(content).match(/^[-*]?\s*\*\*(?:审查目标提交|审查目标 HEAD|Review Target Commit|Review Target Head)\*\*[:：]\s*(.*?)\s*$/m);
+    return match ? match[1].trim().replace(/`/g, "") : "";
+}
+export function extractReviewedHead(content) {
+    const match = String(content).match(/^[-*]?\s*\*\*(?:审查已检视提交|已检视提交|Reviewed Head Commit|Reviewed Head)\*\*[:：]\s*(.*?)\s*$/m);
+    return match ? match[1].trim().replace(/`/g, "") : "";
+}
 export function extractReviewDiffBase(content) {
     const match = String(content).match(/^[-*]?\s*\*\*(?:审查差异基线|Reviewed Diff Base)\*\*[:：]\s*(.*?)\s*$/m);
     return match ? match[1].trim().replace(/`/g, "") : "";

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

@@ -4,7 +4,7 @@ import path from "node:path";
 import process from "node:process";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { extractReviewBaseline, extractReviewDiffBase, extractReviewDiffFingerprint, extractReviewedSnapshotTree, findAuthoritativeReviewCodeArtifact, loadPostReviewConfig, parseReviewVerdict, resolvePostReviewGlobs } from "./verification-review.js";
+import { extractReviewBaseline, extractReviewTargetHead, extractReviewedHead, extractReviewDiffBase, extractReviewDiffFingerprint, extractReviewedSnapshotTree, findAuthoritativeReviewCodeArtifact, loadPostReviewConfig, parseReviewVerdict, resolvePostReviewGlobs } from "./verification-review.js";
 import { check as checkPlatformSync } from "../platform/verification-sync.js";
 import { check as checkRequiredChecks } from "../platform/verification-required.js";
 import { inspectPlatformPullRequest } from "../platform/pull-requests.js";
@@ -19,6 +19,8 @@ import { inspectDecisionDetailDuplicates } from "./decision-details.js";
 import { loadVerificationConfig } from "./verification-config.js";
 import { snapshotReview } from "../git/review-snapshot.js";
 import { OrchestrationStateError, readRun } from "./orchestration.js";
+import { resolveDeliveryTarget } from "./delivery-target.js";
+import { readPrDeliveryFact } from "./pr-delivery-fact.js";
 const TASK_ENUMS = {
     type: ["feature", "bugfix", "refactor", "docs", "chore"],
     workflow: ["feature-development", "bug-fix", "refactoring"],
@@ -176,13 +178,12 @@ function validateCleanCompletionEvidence(run) {
         || !shaPattern.test(evidence.headTree)
         || !shaPattern.test(evidence.worktreeTree)
         || !shaPattern.test(evidence.lastReviewedCommit)
-        || !Number.isInteger(evidence.prNumber)
-        || evidence.prNumber <= 0
-        || !shaPattern.test(evidence.prHead)) {
+        || !(evidence.prNumber === null || (Number.isInteger(evidence.prNumber) && evidence.prNumber > 0))
+        || !(evidence.prHead === null || shaPattern.test(evidence.prHead))) {
         return 'Clean completion evidence has an invalid structure';
     }
     if (evidence.head !== evidence.lastReviewedCommit
-        || evidence.head !== evidence.prHead
+        || (evidence.prHead !== null && evidence.head !== evidence.prHead)
         || evidence.headTree !== evidence.worktreeTree) {
         return 'Clean completion evidence does not bind matching commit and tree identities';
     }
@@ -251,10 +252,8 @@ function checkOrchestrationEvidence({ taskDir }) {
         if (evidenceError)
             return failResult('orchestration-evidence', evidenceError);
     }
-    else if (run.status === 'completed' && (run.receipts.length === 0
-        || run.receipts.at(-1)?.stage !== 'commit'
-        || run.receipts.at(-1)?.status !== 'consumed')) {
-        return failResult('orchestration-evidence', 'Completed run requires a final consumed commit receipt');
+    else if (run.status === 'completed') {
+        return failResult('orchestration-evidence', 'Completed run requires reviewed-head-clean completion evidence');
     }
     if (run.pendingDelegation && !['prepared', 'activated', 'stage-completed'].includes(run.pendingDelegation.status)) {
         return failResult('orchestration-evidence', `Pending receipt has unsafe status '${run.pendingDelegation.status}'`);
@@ -434,19 +433,20 @@ function checkRequiredPrDelivery({ taskDir, repositoryRoot, mode }) {
         return failResult('required-pr-delivery', 'Project configuration is invalid');
     }
     const flow = projectConfig.prFlow;
-    const status = String(task.metadata.pr_status || 'pending');
-    const prNumber = parsePrNumber(task.metadata.pr_number);
+    const factRead = readPrDeliveryFact(task.metadata);
+    if (factRead.status === 'invalid')
+        return failResult('required-pr-delivery', factRead.error.message);
+    const fact = factRead.status === 'valid' ? factRead.fact : null;
+    const status = fact?.state || 'unbound';
+    const prNumber = fact?.state === 'bound' ? fact.identity.number : null;
     if (flow === 'disabled')
         return passResult('required-pr-delivery', 'Pull request delivery is disabled by project policy');
-    if (flow === 'required' && (status !== 'created' || prNumber === null)) {
+    if (flow === 'required' && (status !== 'bound' || prNumber === null)) {
         return failResult('required-pr-delivery', 'Project policy requires a bound pull request before completion');
     }
-    if (flow !== 'required' && status === 'pending') {
+    if (flow !== 'required' && status === 'unbound') {
         return failResult('required-pr-delivery', 'Pull request delivery is pending; create a PR or explicitly skip it');
     }
-    if (status === 'created' && prNumber === null) {
-        return failResult('required-pr-delivery', 'Task claims a created pull request without a valid pr_number');
-    }
     if (flow === 'required') {
         if (mode === 'gate') {
             return passResult('required-pr-delivery', 'Bound pull request shape is valid; merged-state inspection is reserved for hard preflight');
@@ -458,13 +458,15 @@ function checkRequiredPrDelivery({ taskDir, repositoryRoot, mode }) {
         const pullRequest = inspected.pullRequest;
         const repository = inspected.platform.repository?.toLowerCase() || '';
         const taskBranch = String(task.metadata.branch || '').trim();
+        const deliveryBaseRef = String(task.metadata.delivery_base_ref || projectConfig.delivery?.baseRef || '').trim();
         if (inspected.status !== 'no-op' || !pullRequest || pullRequest.number !== prNumber) {
             return failResult('required-pr-delivery', 'Bound pull request identity could not be verified');
         }
         if (!repository
             || pullRequest.repository.toLowerCase() !== repository
             || pullRequest.base.repository.toLowerCase() !== repository
-            || (taskBranch && pullRequest.head.ref !== taskBranch)) {
+            || (taskBranch && pullRequest.head.ref !== taskBranch)
+            || (deliveryBaseRef && pullRequest.base.ref !== deliveryBaseRef)) {
             return failResult('required-pr-delivery', 'Bound pull request identity does not match the task');
         }
         if (pullRequest.state !== 'closed' || !pullRequest.mergedAt || !pullRequest.mergeCommitSha) {
@@ -966,9 +968,13 @@ function checkPostReviewCommit({ taskDir, config }) {
     const task = loadTask(taskDir);
     if (!task.ok)
         return failResult("post-review-commit", task.message);
+    const factRead = readPrDeliveryFact(task.metadata);
+    if (factRead.status === 'invalid')
+        return failResult("post-review-commit", factRead.error.message);
+    const fact = factRead.status === 'valid' ? factRead.fact : null;
     const lastReviewedCommit = task.ok ? (task.metadata.last_reviewed_commit || "").trim() : "";
     const globs = resolvePostReviewGlobs(config, loadPostReviewConfig(repoRoot));
-    const hasPullRequest = Number(task.metadata.pr_number) > 0;
+    const hasPullRequest = fact?.state === 'bound';
     let inspected = null;
     if (hasPullRequest) {
         inspected = inspectPlatformPullRequest(task.metadata.id, { cwd: gitRoot });
@@ -1124,28 +1130,46 @@ function checkReviewFact({ taskDir, artifactFile }) {
     }
     const content = fs.readFileSync(resolvedArtifact.path, "utf8");
     const verdict = parseReviewVerdict(content);
-    const reviewBaseline = extractReviewBaseline(content);
+    const reviewTargetHead = extractReviewTargetHead(content);
+    const reviewReviewedHead = extractReviewedHead(content);
     const reviewDiffBase = extractReviewDiffBase(content);
     const reviewedFingerprint = extractReviewDiffFingerprint(content);
     const reviewedTree = extractReviewedSnapshotTree(content);
     if (!["通过", "需要修改", "拒绝", "Approved", "Changes Requested", "Rejected"].includes(verdict)) {
         return failResult("review-fact", `Unsupported review verdict '${verdict}'`);
     }
+    const deliveryRemote = String(task.metadata.delivery_remote || "").trim();
+    const deliveryBaseRef = String(task.metadata.delivery_base_ref || "").trim();
+    if (!deliveryRemote || !deliveryBaseRef) {
+        return failResult("review-fact", "Task delivery target is not bound; re-run task branch preparation before review-code");
+    }
+    if (!reviewTargetHead || !reviewReviewedHead || !reviewDiffBase) {
+        return failResult("review-fact", "Review fact must record target head, reviewed head, and diff base");
+    }
     let gitRoot;
     let head;
     let baseline;
+    let targetHead;
     let diffBase;
     try {
         gitRoot = execFileSync("git", ["-C", taskDir, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
         head = execFileSync("git", ["-C", gitRoot, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
-        baseline = execFileSync("git", ["-C", gitRoot, "rev-parse", `${reviewBaseline}^{commit}`], { encoding: "utf8" }).trim();
-        diffBase = execFileSync("git", ["-C", gitRoot, "rev-parse", `${reviewDiffBase || reviewBaseline}^{commit}`], { encoding: "utf8" }).trim();
+        const target = resolveDeliveryTarget(gitRoot, { remote: deliveryRemote, baseRef: deliveryBaseRef });
+        if (!target.ok)
+            throw new Error(target.message);
+        const reviewedRef = reviewReviewedHead;
+        baseline = execFileSync("git", ["-C", gitRoot, "rev-parse", `${reviewedRef}^{commit}`], { encoding: "utf8" }).trim();
+        targetHead = execFileSync("git", ["-C", gitRoot, "rev-parse", `${reviewTargetHead}^{commit}`], { encoding: "utf8" }).trim();
+        const computed = execFileSync("git", ["-C", gitRoot, "merge-base", baseline, targetHead], { encoding: "utf8" }).trim();
+        diffBase = execFileSync("git", ["-C", gitRoot, "rev-parse", `${reviewDiffBase}^{commit}`], { encoding: "utf8" }).trim();
+        if (diffBase !== computed)
+            throw new Error('saved review diff base does not match merge-base(reviewed head, target head)');
     }
     catch {
-        return blockedResult("review-fact", `Unable to resolve review baseline '${reviewBaseline}' in the task repository; re-run review-code`);
+        return blockedResult("review-fact", `Unable to resolve saved review commits in the task repository; re-run review-code`);
     }
     if (baseline !== head) {
-        return failResult("review-fact", `Review baseline ${baseline.slice(0, 8)} does not match current HEAD ${head.slice(0, 8)}; re-run review-code`);
+        return failResult("review-fact", `Reviewed head ${baseline.slice(0, 8)} does not match current HEAD ${head.slice(0, 8)}; re-run review-code`);
     }
     let actualSnapshot;
     try {
@@ -1170,7 +1194,7 @@ function checkReviewFact({ taskDir, artifactFile }) {
         const lastReviewedCommit = String(task.metadata.last_reviewed_commit || "").trim();
         const cleanSnapshot = actualSnapshot.tree === execFileSync("git", ["-C", gitRoot, "rev-parse", `${baseline}^{tree}`], { encoding: "utf8" }).trim();
         if (cleanSnapshot && lastReviewedCommit !== baseline) {
-            return failResult("review-fact", `Approved clean review must set task last_reviewed_commit to baseline ${baseline.slice(0, 8)}`);
+            return failResult("review-fact", `Approved clean review must set task last_reviewed_commit to reviewed head ${baseline.slice(0, 8)}`);
         }
         if (!cleanSnapshot && lastReviewedCommit) {
             return failResult("review-fact", "Approved review with uncommitted changes must remain unanchored until commit");

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

@@ -1,3 +1,3 @@
-export { extractReviewBaseline, extractReviewDiffBase, extractReviewDiffFingerprint, extractReviewedSnapshotTree, findAuthoritativeReviewCodeArtifact, loadPostReviewConfig, parseReviewVerdict, resolvePostReviewGlobs } from './review-fingerprint.js';
+export { extractReviewBaseline, extractReviewTargetHead, extractReviewedHead, extractReviewDiffBase, extractReviewDiffFingerprint, extractReviewedSnapshotTree, findAuthoritativeReviewCodeArtifact, loadPostReviewConfig, parseReviewVerdict, resolvePostReviewGlobs } from './review-fingerprint.js';
 export { parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.js';
 //# sourceMappingURL=verification-review.js.map

package/dist/lib/update.js

@@ -43,6 +43,7 @@ async function cmdSync() {
     const sandboxAdded = !config.sandbox;
     const taskAdded = !config.task;
     const labelsAdded = !config.labels;
+    const deliveryAdded = !config.delivery;
     if (platformAdded)
         config.platform = structuredClone(defaults.platform);
     if (sandboxAdded)
@@ -51,6 +52,8 @@ async function cmdSync() {
         config.task = structuredClone(defaults.task);
     if (labelsAdded)
         config.labels = structuredClone(defaults.labels);
+    if (deliveryAdded)
+        config.delivery = structuredClone(defaults.delivery);
     const workflowPlan = planAgentClientReconciliation({
         config: config,
         mutation: { type: 'replace-state', state: normalizedOriginal.state },
@@ -98,6 +101,9 @@ async function cmdSync() {
             if (labelsAdded) {
                 info(`Default labels.in config added to ${CONFIG_PATH}.`);
             }
+            if (deliveryAdded) {
+                info(`Default delivery target added to ${CONFIG_PATH}.`);
+            }
         }
         else {
             info(`File registry changed in ${CONFIG_PATH}.`);
@@ -114,6 +120,9 @@ async function cmdSync() {
         if (hasNewEntries && platformAdded) {
             info(`Default platform config added to ${CONFIG_PATH}.`);
         }
+        if (hasNewEntries && deliveryAdded) {
+            info(`Default delivery target added to ${CONFIG_PATH}.`);
+        }
         ok(`Updated ${CONFIG_PATH}`);
     }
     // done

package/dist/lifecycle-build-manifest.json

@@ -1,6 +1,6 @@
 {
   "protocolVersion": 3,
-  "packageVersion": "0.9.11",
-  "sourceInputHash": "00e07caf1313615df10d46ae620767d7d15c3cc59712c1da581623057b87e0a6",
-  "internalExecutableBuildHash": "8a481b1d79da5e5f31ef79cd3428f1b51df2b859e70724e50dcc5910f8ee40c6"
+  "packageVersion": "0.9.12",
+  "sourceInputHash": "5e1b341aad5fe825884f4dbdbd01d0752ca66107d1ccb4b0fe4d8d3aae49120d",
+  "internalExecutableBuildHash": "39bf2c60e3a9b834d4a24ab3088f108583d15ee2bdc77e6376e517921be47c80"
 }

package/lib/agent-clients/adapters/codex-lifecycle/build-identity.ts

@@ -22,6 +22,14 @@ type LifecycleBuildIdentityOptions = Readonly<{
 type LifecycleManifestFiles = Readonly<{
   executableFiles: readonly string[];
   contractFiles: readonly string[];
+  launcherShebang: LifecycleLauncherShebang;
+}>;
+
+type LifecycleLauncherShebang = Readonly<{
+  sourceFile: string;
+  compiledFile: string;
+  canonicalLine: string;
+  acceptedLines: readonly string[];
 }>;
 
 type IdentityVerification = Readonly<{
@@ -53,6 +61,56 @@ function normalizeRelativePath(value: string): string {
   return value.replaceAll('\\', '/');
 }
 
+function isSafeLifecyclePath(value: unknown): value is string {
+  return exactText(value)
+    && value === normalizeRelativePath(value)
+    && !path.isAbsolute(value)
+    && !/^[A-Za-z]:[\\/]/u.test(value)
+    && !value.split('/').includes('..');
+}
+
+function isLifecycleLauncherLine(value: unknown): value is string {
+  return typeof value === 'string'
+    && value.length > 1
+    && value.slice(0, -1).trim() === value.slice(0, -1)
+    && value.startsWith('#!')
+    && value.endsWith('\n')
+    && value.indexOf('\n') === value.length - 1
+    && !value.includes('\r');
+}
+
+function readLifecycleLauncherShebang(
+  value: unknown,
+  executableFiles: readonly string[]
+): LifecycleLauncherShebang {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('Lifecycle manifest launcher shebang policy is invalid');
+  }
+  const policy = value as Record<string, unknown>;
+  if (!isSafeLifecyclePath(policy.sourceFile)
+    || !isSafeLifecyclePath(policy.compiledFile)
+    || !isLifecycleLauncherLine(policy.canonicalLine)
+    || !Array.isArray(policy.acceptedLines)
+    || !policy.acceptedLines.every(isLifecycleLauncherLine)
+    || new Set(policy.acceptedLines).size !== policy.acceptedLines.length
+    || !policy.acceptedLines.includes(policy.canonicalLine)
+    || !executableFiles.includes(policy.sourceFile)
+    || policy.compiledFile !== normalizeRelativePath(path.join(
+      'dist',
+      policy.sourceFile.endsWith('.ts')
+        ? policy.sourceFile.replace(/\.ts$/u, '.js')
+        : policy.sourceFile
+    ))) {
+    throw new Error('Lifecycle manifest launcher shebang policy is invalid');
+  }
+  return Object.freeze({
+    sourceFile: policy.sourceFile,
+    compiledFile: policy.compiledFile,
+    canonicalLine: policy.canonicalLine,
+    acceptedLines: Object.freeze([...policy.acceptedLines])
+  });
+}
+
 function readLifecycleManifestFiles(packageRoot: string): LifecycleManifestFiles {
   const file = path.join(
     packageRoot,
@@ -65,18 +123,21 @@ function readLifecycleManifestFiles(packageRoot: string): LifecycleManifestFiles
   const value = JSON.parse(fs.readFileSync(file, 'utf8')) as {
     executableFiles?: unknown;
     contractFiles?: unknown;
+    launcherShebang?: unknown;
   };
   if (!Array.isArray(value.executableFiles)
     || !Array.isArray(value.contractFiles)
-    || !value.executableFiles.every(exactText)
-    || !value.contractFiles.every(exactText)
+    || !value.executableFiles.every(isSafeLifecyclePath)
+    || !value.contractFiles.every(isSafeLifecyclePath)
     || new Set(value.executableFiles).size !== value.executableFiles.length
     || new Set(value.contractFiles).size !== value.contractFiles.length) {
     throw new Error('Lifecycle manifest file list is invalid');
   }
+  const executableFiles = Object.freeze([...value.executableFiles] as string[]);
   return Object.freeze({
-    executableFiles: Object.freeze([...value.executableFiles] as string[]),
-    contractFiles: Object.freeze([...value.contractFiles] as string[])
+    executableFiles,
+    contractFiles: Object.freeze([...value.contractFiles] as string[]),
+    launcherShebang: readLifecycleLauncherShebang(value.launcherShebang, executableFiles)
   });
 }
 
@@ -94,7 +155,28 @@ function executablePackageRoot(): string {
   }
 }
 
-function hashFiles(root: string, files: readonly string[]): string {
+function normalizeLifecycleLauncherBytes(
+  relative: string,
+  content: Buffer,
+  policy: LifecycleLauncherShebang
+): Buffer {
+  const normalized = normalizeRelativePath(relative);
+  if (normalized !== policy.sourceFile && normalized !== policy.compiledFile) return content;
+  const lineEnd = content.indexOf(0x0a);
+  if (lineEnd < 0) return content;
+  const firstLine = content.subarray(0, lineEnd + 1);
+  if (!policy.acceptedLines.some((line) => Buffer.from(line).equals(firstLine))) return content;
+  return Buffer.concat([
+    Buffer.from(policy.canonicalLine),
+    content.subarray(lineEnd + 1)
+  ]);
+}
+
+function hashFiles(
+  root: string,
+  files: readonly string[],
+  launcherShebang?: LifecycleLauncherShebang
+): string {
   const hash = crypto.createHash('sha256');
   for (const relative of [...new Set(files.map(normalizeRelativePath))].sort()) {
     if (path.isAbsolute(relative) || relative.split(/[\\/]/u).includes('..')) {
@@ -107,7 +189,10 @@ function hashFiles(root: string, files: readonly string[]): string {
     }
     hash.update(relative);
     hash.update('\0');
-    hash.update(fs.readFileSync(file));
+    const content = fs.readFileSync(file);
+    hash.update(launcherShebang
+      ? normalizeLifecycleLauncherBytes(relative, content, launcherShebang)
+      : content);
     hash.update('\0');
   }
   return hash.digest('hex');
@@ -157,7 +242,7 @@ function computeLifecycleBuildIdentity(
   if (!exactText(packageJson.version)) throw new Error('Lifecycle package version is invalid');
   let internalExecutableBuildHash: string;
   if (options.executableFiles) {
-    internalExecutableBuildHash = hashFiles(repoRoot, options.executableFiles);
+    internalExecutableBuildHash = hashFiles(repoRoot, options.executableFiles, defaults.launcherShebang);
   } else {
     const manifestFile = path.join(executableRoot, 'dist', 'lifecycle-build-manifest.json');
     if (fs.existsSync(manifestFile)) {
@@ -177,16 +262,25 @@ function computeLifecycleBuildIdentity(
         const compiledFiles = defaults.executableFiles.map((file) =>
           file.endsWith('.ts') ? path.join('dist', file.replace(/\.ts$/u, '.js')) : file
         );
-        if (hashFiles(executableRoot, resolveLifecycleExecutableFiles(executableRoot, compiledFiles)) !== manifest.internalExecutableBuildHash) {
+        if (hashFiles(
+          executableRoot,
+          resolveLifecycleExecutableFiles(executableRoot, compiledFiles),
+          defaults.launcherShebang
+        ) !== manifest.internalExecutableBuildHash) {
           throw new Error('Lifecycle compiled executable build does not match its manifest');
         }
-      } else if (hashFiles(executableRoot, resolveLifecycleExecutableFiles(executableRoot, defaults.executableFiles)) !== manifest.sourceInputHash) {
+      } else if (hashFiles(
+        executableRoot,
+        resolveLifecycleExecutableFiles(executableRoot, defaults.executableFiles),
+        defaults.launcherShebang
+      ) !== manifest.sourceInputHash) {
         throw new Error('Lifecycle executable build manifest is stale or invalid');
       }
       internalExecutableBuildHash = manifest.internalExecutableBuildHash;
     } else internalExecutableBuildHash = hashFiles(
       executableRoot,
-      resolveLifecycleExecutableFiles(executableRoot, defaults.executableFiles)
+      resolveLifecycleExecutableFiles(executableRoot, defaults.executableFiles),
+      defaults.launcherShebang
     );
   }
   return Object.freeze({
@@ -249,6 +343,7 @@ export type {
   IdentityVerification,
   LifecycleIdentityWarning,
   LifecycleBuildIdentity,
+  LifecycleLauncherShebang,
   LifecycleManifestFiles,
   LifecycleBuildIdentityOptions
 };

package/lib/agent-clients/adapters/codex-lifecycle/manifest-files.json

@@ -30,5 +30,16 @@
     ".agents/hooks/lifecycle-delegation.js",
     ".agents/skills/run-task/SKILL.md",
     ".agents/rules/lifecycle-orchestration.md"
-  ]
+  ],
+  "launcherShebang": {
+    "sourceFile": "bin/internal-cli.ts",
+    "compiledFile": "dist/bin/internal-cli.js",
+    "canonicalLine": "#!/usr/bin/env node\n",
+    "acceptedLines": [
+      "#!/usr/bin/env node\n",
+      "#!/opt/homebrew/opt/node/bin/node\n",
+      "#!/usr/local/opt/node/bin/node\n",
+      "#!/home/linuxbrew/.linuxbrew/opt/node/bin/node\n"
+    ]
+  }
 }