@caupulican/pi-adaptative 0.81.39 → 0.81.40

package/dist/core/orchestration/worker-execution-contract.js

@@ -0,0 +1,179 @@
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { isPlainRecord } from "../util/value-guards.js";
+import { isHarnessCapability, ORCHESTRATION_SCHEMA_VERSION, ORCHESTRATION_THINKING_LEVELS, } from "./contracts.js";
+import { OrchestrationProfileError, parseOrchestrationProfile } from "./profile-registry.js";
+import { intersectRiskBudgets, validateRiskBudget } from "./risk-budget.js";
+export class WorkerExecutionContractError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WorkerExecutionContractError";
+    }
+}
+function exactKeys(record, allowed) {
+    const allowedSet = new Set(allowed);
+    return Object.keys(record).every((key) => allowedSet.has(key));
+}
+function parseModelBinding(value, label) {
+    if (!isPlainRecord(value) ||
+        !exactKeys(value, ["provider", "modelId", "thinkingLevel"]) ||
+        typeof value.provider !== "string" ||
+        !value.provider.trim() ||
+        typeof value.modelId !== "string" ||
+        !value.modelId.trim() ||
+        typeof value.thinkingLevel !== "string" ||
+        !ORCHESTRATION_THINKING_LEVELS.includes(value.thinkingLevel)) {
+        throw new WorkerExecutionContractError(`${label} model binding is invalid.`);
+    }
+    return {
+        provider: value.provider,
+        modelId: value.modelId,
+        thinkingLevel: value.thinkingLevel,
+    };
+}
+function stringArray(value, label) {
+    if (!Array.isArray(value) || !value.every((entry) => typeof entry === "string" && entry.length > 0)) {
+        throw new WorkerExecutionContractError(`${label} must be an array of non-empty strings.`);
+    }
+    if (new Set(value).size !== value.length) {
+        throw new WorkerExecutionContractError(`${label} contains duplicates.`);
+    }
+    return [...value];
+}
+function parseAuthority(value, profile, label) {
+    if (!isPlainRecord(value) ||
+        !exactKeys(value, ["capabilities", "toolNames", "readPaths", "writePaths", "deniedPaths", "budget"])) {
+        throw new WorkerExecutionContractError(`${label} authority is invalid.`);
+    }
+    const capabilities = stringArray(value.capabilities, `${label} authority capabilities`);
+    if (!capabilities.every(isHarnessCapability)) {
+        throw new WorkerExecutionContractError(`${label} authority contains an unknown capability.`);
+    }
+    if (capabilities.some((capability) => !profile.capabilityCeiling.includes(capability))) {
+        throw new WorkerExecutionContractError(`${label} authority exceeds its profile capability ceiling.`);
+    }
+    const toolNames = stringArray(value.toolNames, `${label} authority toolNames`);
+    if (toolNames.some((toolName) => !profile.toolNames.includes(toolName))) {
+        throw new WorkerExecutionContractError(`${label} authority contains a tool outside its profile.`);
+    }
+    const readPaths = stringArray(value.readPaths, `${label} authority readPaths`);
+    const writePaths = stringArray(value.writePaths, `${label} authority writePaths`);
+    const deniedPaths = stringArray(value.deniedPaths, `${label} authority deniedPaths`);
+    if ([...readPaths, ...writePaths, ...deniedPaths].some((entry) => !path.isAbsolute(entry))) {
+        throw new WorkerExecutionContractError(`${label} authority paths must be absolute.`);
+    }
+    if (!isPlainRecord(value.budget)) {
+        throw new WorkerExecutionContractError(`${label} authority budget is invalid.`);
+    }
+    const budget = structuredClone(value.budget);
+    try {
+        validateRiskBudget(budget, `${label} authority budget`);
+    }
+    catch (error) {
+        throw new WorkerExecutionContractError(error instanceof Error ? error.message : String(error));
+    }
+    if (!isDeepStrictEqual(intersectRiskBudgets(profile.budget, budget), budget)) {
+        throw new WorkerExecutionContractError(`${label} authority exceeds its profile budget.`);
+    }
+    const readGranted = capabilities.some((capability) => capability === "filesystem.read" || capability === "worktree.read");
+    const writeGranted = capabilities.some((capability) => capability === "filesystem.write" || capability === "worktree.mutate");
+    if (readGranted && readPaths.length === 0) {
+        throw new WorkerExecutionContractError(`${label} read authority lacks a positive path scope.`);
+    }
+    if (writeGranted && writePaths.length === 0) {
+        throw new WorkerExecutionContractError(`${label} write authority lacks a positive path scope.`);
+    }
+    return {
+        capabilities: capabilities,
+        toolNames,
+        readPaths,
+        writePaths,
+        deniedPaths,
+        budget,
+    };
+}
+function parseProfileContract(value, label) {
+    if (!isPlainRecord(value) ||
+        !exactKeys(value, ["schemaVersion", "profile", "modelBinding", "authority", "soul"]) ||
+        value.schemaVersion !== ORCHESTRATION_SCHEMA_VERSION) {
+        throw new WorkerExecutionContractError(`${label} is invalid.`);
+    }
+    let profile;
+    try {
+        profile = parseOrchestrationProfile(value.profile);
+    }
+    catch (error) {
+        throw new WorkerExecutionContractError(error instanceof OrchestrationProfileError ? error.message : `${label} profile is invalid.`);
+    }
+    if (profile.role === "orchestrator") {
+        throw new WorkerExecutionContractError(`${label} cannot materialize an orchestrator profile.`);
+    }
+    const modelBinding = parseModelBinding(value.modelBinding, label);
+    if (!profile.modelPolicy.candidates.some((candidate) => isDeepStrictEqual(candidate, modelBinding))) {
+        throw new WorkerExecutionContractError(`${label} model binding is not declared by its profile.`);
+    }
+    if (value.soul !== undefined && (typeof value.soul !== "string" || !value.soul.trim())) {
+        throw new WorkerExecutionContractError(`${label} soul is invalid.`);
+    }
+    const authority = parseAuthority(value.authority, profile, label);
+    return {
+        schemaVersion: ORCHESTRATION_SCHEMA_VERSION,
+        profile,
+        modelBinding,
+        authority,
+        ...(typeof value.soul === "string" ? { soul: value.soul } : {}),
+    };
+}
+export function parseWorkerExecutionContract(value) {
+    if (!isPlainRecord(value) ||
+        !exactKeys(value, ["schemaVersion", "worker", "verifier"]) ||
+        value.schemaVersion !== ORCHESTRATION_SCHEMA_VERSION) {
+        throw new WorkerExecutionContractError("Worker execution contract is invalid.");
+    }
+    const worker = parseProfileContract(value.worker, "Worker execution contract");
+    const verifier = value.verifier
+        ? parseProfileContract(value.verifier, "Worker verifier execution contract")
+        : undefined;
+    if (worker.profile.requireIndependentVerification) {
+        if (!verifier || worker.profile.verificationProfileId !== verifier.profile.profileId) {
+            throw new WorkerExecutionContractError("Worker execution contract is missing its owner-pinned verifier.");
+        }
+        if (verifier.profile.role !== "verifier") {
+            throw new WorkerExecutionContractError("Worker verifier execution contract does not use a verifier profile.");
+        }
+    }
+    else if (verifier) {
+        throw new WorkerExecutionContractError("Worker execution contract has an unexpected verifier.");
+    }
+    return {
+        schemaVersion: ORCHESTRATION_SCHEMA_VERSION,
+        worker,
+        ...(verifier ? { verifier } : {}),
+    };
+}
+function snapshotProfile(profile) {
+    const { sourcePath: _sourcePath, ...persisted } = profile;
+    return structuredClone(persisted);
+}
+function snapshotResolvedProfile(source) {
+    return {
+        schemaVersion: ORCHESTRATION_SCHEMA_VERSION,
+        profile: snapshotProfile(source.profile),
+        modelBinding: structuredClone(source.modelBinding),
+        authority: structuredClone(source.authority),
+        ...(source.soul ? { soul: source.soul } : {}),
+    };
+}
+export function createWorkerExecutionContract(args) {
+    return parseWorkerExecutionContract({
+        schemaVersion: ORCHESTRATION_SCHEMA_VERSION,
+        worker: snapshotResolvedProfile(args.worker),
+        ...(args.verifier ? { verifier: snapshotResolvedProfile(args.verifier) } : {}),
+    });
+}
+export function verifierWorkerExecutionContract(contract) {
+    return contract.verifier
+        ? parseWorkerExecutionContract({ schemaVersion: ORCHESTRATION_SCHEMA_VERSION, worker: contract.verifier })
+        : undefined;
+}
+//# sourceMappingURL=worker-execution-contract.js.map

package/dist/core/orchestration/worker-execution-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-execution-contract.js","sourceRoot":"","sources":["../../../src/core/orchestration/worker-execution-contract.ts"],"names":[],"mappings":"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","sourcesContent":["import path from \"node:path\";\nimport { isDeepStrictEqual } from \"node:util\";\nimport { isPlainRecord } from \"../util/value-guards.ts\";\nimport {\n\tisHarnessCapability,\n\tORCHESTRATION_SCHEMA_VERSION,\n\tORCHESTRATION_THINKING_LEVELS,\n\ttype OrchestrationModelBinding,\n\ttype OrchestrationProfile,\n\ttype WorkerExecutionAuthorityContract,\n\ttype WorkerExecutionContract,\n\ttype WorkerProfileExecutionContract,\n} from \"./contracts.ts\";\nimport { OrchestrationProfileError, parseOrchestrationProfile } from \"./profile-registry.ts\";\nimport { intersectRiskBudgets, validateRiskBudget } from \"./risk-budget.ts\";\n\nexport class WorkerExecutionContractError extends Error {\n\tconstructor(message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"WorkerExecutionContractError\";\n\t}\n}\n\nfunction exactKeys(record: Record<string, unknown>, allowed: readonly string[]): boolean {\n\tconst allowedSet = new Set(allowed);\n\treturn Object.keys(record).every((key) => allowedSet.has(key));\n}\n\nfunction parseModelBinding(value: unknown, label: string): OrchestrationModelBinding {\n\tif (\n\t\t!isPlainRecord(value) ||\n\t\t!exactKeys(value, [\"provider\", \"modelId\", \"thinkingLevel\"]) ||\n\t\ttypeof value.provider !== \"string\" ||\n\t\t!value.provider.trim() ||\n\t\ttypeof value.modelId !== \"string\" ||\n\t\t!value.modelId.trim() ||\n\t\ttypeof value.thinkingLevel !== \"string\" ||\n\t\t!ORCHESTRATION_THINKING_LEVELS.includes(value.thinkingLevel as (typeof ORCHESTRATION_THINKING_LEVELS)[number])\n\t) {\n\t\tthrow new WorkerExecutionContractError(`${label} model binding is invalid.`);\n\t}\n\treturn {\n\t\tprovider: value.provider,\n\t\tmodelId: value.modelId,\n\t\tthinkingLevel: value.thinkingLevel as (typeof ORCHESTRATION_THINKING_LEVELS)[number],\n\t};\n}\n\nfunction stringArray(value: unknown, label: string): string[] {\n\tif (!Array.isArray(value) || !value.every((entry) => typeof entry === \"string\" && entry.length > 0)) {\n\t\tthrow new WorkerExecutionContractError(`${label} must be an array of non-empty strings.`);\n\t}\n\tif (new Set(value).size !== value.length) {\n\t\tthrow new WorkerExecutionContractError(`${label} contains duplicates.`);\n\t}\n\treturn [...value];\n}\n\nfunction parseAuthority(\n\tvalue: unknown,\n\tprofile: OrchestrationProfile,\n\tlabel: string,\n): WorkerExecutionAuthorityContract {\n\tif (\n\t\t!isPlainRecord(value) ||\n\t\t!exactKeys(value, [\"capabilities\", \"toolNames\", \"readPaths\", \"writePaths\", \"deniedPaths\", \"budget\"])\n\t) {\n\t\tthrow new WorkerExecutionContractError(`${label} authority is invalid.`);\n\t}\n\tconst capabilities = stringArray(value.capabilities, `${label} authority capabilities`);\n\tif (!capabilities.every(isHarnessCapability)) {\n\t\tthrow new WorkerExecutionContractError(`${label} authority contains an unknown capability.`);\n\t}\n\tif (capabilities.some((capability) => !profile.capabilityCeiling.includes(capability))) {\n\t\tthrow new WorkerExecutionContractError(`${label} authority exceeds its profile capability ceiling.`);\n\t}\n\tconst toolNames = stringArray(value.toolNames, `${label} authority toolNames`);\n\tif (toolNames.some((toolName) => !profile.toolNames.includes(toolName))) {\n\t\tthrow new WorkerExecutionContractError(`${label} authority contains a tool outside its profile.`);\n\t}\n\tconst readPaths = stringArray(value.readPaths, `${label} authority readPaths`);\n\tconst writePaths = stringArray(value.writePaths, `${label} authority writePaths`);\n\tconst deniedPaths = stringArray(value.deniedPaths, `${label} authority deniedPaths`);\n\tif ([...readPaths, ...writePaths, ...deniedPaths].some((entry) => !path.isAbsolute(entry))) {\n\t\tthrow new WorkerExecutionContractError(`${label} authority paths must be absolute.`);\n\t}\n\tif (!isPlainRecord(value.budget)) {\n\t\tthrow new WorkerExecutionContractError(`${label} authority budget is invalid.`);\n\t}\n\tconst budget = structuredClone(value.budget);\n\ttry {\n\t\tvalidateRiskBudget(budget, `${label} authority budget`);\n\t} catch (error) {\n\t\tthrow new WorkerExecutionContractError(error instanceof Error ? error.message : String(error));\n\t}\n\tif (!isDeepStrictEqual(intersectRiskBudgets(profile.budget, budget), budget)) {\n\t\tthrow new WorkerExecutionContractError(`${label} authority exceeds its profile budget.`);\n\t}\n\tconst readGranted = capabilities.some(\n\t\t(capability) => capability === \"filesystem.read\" || capability === \"worktree.read\",\n\t);\n\tconst writeGranted = capabilities.some(\n\t\t(capability) => capability === \"filesystem.write\" || capability === \"worktree.mutate\",\n\t);\n\tif (readGranted && readPaths.length === 0) {\n\t\tthrow new WorkerExecutionContractError(`${label} read authority lacks a positive path scope.`);\n\t}\n\tif (writeGranted && writePaths.length === 0) {\n\t\tthrow new WorkerExecutionContractError(`${label} write authority lacks a positive path scope.`);\n\t}\n\treturn {\n\t\tcapabilities: capabilities as WorkerExecutionAuthorityContract[\"capabilities\"],\n\t\ttoolNames,\n\t\treadPaths,\n\t\twritePaths,\n\t\tdeniedPaths,\n\t\tbudget,\n\t};\n}\n\nfunction parseProfileContract(value: unknown, label: string): WorkerProfileExecutionContract {\n\tif (\n\t\t!isPlainRecord(value) ||\n\t\t!exactKeys(value, [\"schemaVersion\", \"profile\", \"modelBinding\", \"authority\", \"soul\"]) ||\n\t\tvalue.schemaVersion !== ORCHESTRATION_SCHEMA_VERSION\n\t) {\n\t\tthrow new WorkerExecutionContractError(`${label} is invalid.`);\n\t}\n\tlet profile: OrchestrationProfile;\n\ttry {\n\t\tprofile = parseOrchestrationProfile(value.profile);\n\t} catch (error) {\n\t\tthrow new WorkerExecutionContractError(\n\t\t\terror instanceof OrchestrationProfileError ? error.message : `${label} profile is invalid.`,\n\t\t);\n\t}\n\tif (profile.role === \"orchestrator\") {\n\t\tthrow new WorkerExecutionContractError(`${label} cannot materialize an orchestrator profile.`);\n\t}\n\tconst modelBinding = parseModelBinding(value.modelBinding, label);\n\tif (!profile.modelPolicy.candidates.some((candidate) => isDeepStrictEqual(candidate, modelBinding))) {\n\t\tthrow new WorkerExecutionContractError(`${label} model binding is not declared by its profile.`);\n\t}\n\tif (value.soul !== undefined && (typeof value.soul !== \"string\" || !value.soul.trim())) {\n\t\tthrow new WorkerExecutionContractError(`${label} soul is invalid.`);\n\t}\n\tconst authority = parseAuthority(value.authority, profile, label);\n\treturn {\n\t\tschemaVersion: ORCHESTRATION_SCHEMA_VERSION,\n\t\tprofile,\n\t\tmodelBinding,\n\t\tauthority,\n\t\t...(typeof value.soul === \"string\" ? { soul: value.soul } : {}),\n\t};\n}\n\nexport function parseWorkerExecutionContract(value: unknown): WorkerExecutionContract {\n\tif (\n\t\t!isPlainRecord(value) ||\n\t\t!exactKeys(value, [\"schemaVersion\", \"worker\", \"verifier\"]) ||\n\t\tvalue.schemaVersion !== ORCHESTRATION_SCHEMA_VERSION\n\t) {\n\t\tthrow new WorkerExecutionContractError(\"Worker execution contract is invalid.\");\n\t}\n\tconst worker = parseProfileContract(value.worker, \"Worker execution contract\");\n\tconst verifier = value.verifier\n\t\t? parseProfileContract(value.verifier, \"Worker verifier execution contract\")\n\t\t: undefined;\n\tif (worker.profile.requireIndependentVerification) {\n\t\tif (!verifier || worker.profile.verificationProfileId !== verifier.profile.profileId) {\n\t\t\tthrow new WorkerExecutionContractError(\"Worker execution contract is missing its owner-pinned verifier.\");\n\t\t}\n\t\tif (verifier.profile.role !== \"verifier\") {\n\t\t\tthrow new WorkerExecutionContractError(\"Worker verifier execution contract does not use a verifier profile.\");\n\t\t}\n\t} else if (verifier) {\n\t\tthrow new WorkerExecutionContractError(\"Worker execution contract has an unexpected verifier.\");\n\t}\n\treturn {\n\t\tschemaVersion: ORCHESTRATION_SCHEMA_VERSION,\n\t\tworker,\n\t\t...(verifier ? { verifier } : {}),\n\t};\n}\n\nfunction snapshotProfile(profile: OrchestrationProfile): OrchestrationProfile {\n\tconst { sourcePath: _sourcePath, ...persisted } = profile;\n\treturn structuredClone(persisted) as OrchestrationProfile;\n}\n\nfunction snapshotResolvedProfile(source: {\n\tprofile: OrchestrationProfile;\n\tmodelBinding: OrchestrationModelBinding;\n\tauthority: WorkerExecutionAuthorityContract;\n\tsoul?: string;\n}): WorkerProfileExecutionContract {\n\treturn {\n\t\tschemaVersion: ORCHESTRATION_SCHEMA_VERSION,\n\t\tprofile: snapshotProfile(source.profile),\n\t\tmodelBinding: structuredClone(source.modelBinding),\n\t\tauthority: structuredClone(source.authority),\n\t\t...(source.soul ? { soul: source.soul } : {}),\n\t};\n}\n\nexport function createWorkerExecutionContract(args: {\n\tworker: {\n\t\tprofile: OrchestrationProfile;\n\t\tmodelBinding: OrchestrationModelBinding;\n\t\tauthority: WorkerExecutionAuthorityContract;\n\t\tsoul?: string;\n\t};\n\tverifier?: {\n\t\tprofile: OrchestrationProfile;\n\t\tmodelBinding: OrchestrationModelBinding;\n\t\tauthority: WorkerExecutionAuthorityContract;\n\t\tsoul?: string;\n\t};\n}): WorkerExecutionContract {\n\treturn parseWorkerExecutionContract({\n\t\tschemaVersion: ORCHESTRATION_SCHEMA_VERSION,\n\t\tworker: snapshotResolvedProfile(args.worker),\n\t\t...(args.verifier ? { verifier: snapshotResolvedProfile(args.verifier) } : {}),\n\t});\n}\n\nexport function verifierWorkerExecutionContract(\n\tcontract: WorkerExecutionContract,\n): WorkerExecutionContract | undefined {\n\treturn contract.verifier\n\t\t? parseWorkerExecutionContract({ schemaVersion: ORCHESTRATION_SCHEMA_VERSION, worker: contract.verifier })\n\t\t: undefined;\n}\n"]}

package/dist/core/orchestration/worker-result-adapter.d.ts

@@ -0,0 +1,21 @@
+import type { WorkerClaim } from "../autonomy/contracts.ts";
+import { type WorkerResultContract } from "./contracts.ts";
+import type { StartedDelegationAttempt } from "./delegation-ledger.ts";
+/** Sole host-owned conversion from an untrusted claim to a fenced durable result. */
+export declare function createWorkerResultContract(args: {
+    handle: StartedDelegationAttempt;
+    claim: WorkerClaim;
+    accepted: boolean;
+    costUsd?: number;
+    cwd: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    wallClockMs: number;
+    toolCalls: number;
+    verificationRequired?: boolean;
+    verificationCriterionIds?: readonly string[];
+    reasonCode?: string;
+    createdAt?: string;
+}): WorkerResultContract;
+//# sourceMappingURL=worker-result-adapter.d.ts.map

package/dist/core/orchestration/worker-result-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-result-adapter.d.ts","sourceRoot":"","sources":["../../../src/core/orchestration/worker-result-adapter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAIN,KAAK,oBAAoB,EACzB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAqEvE,qFAAqF;AACrF,wBAAgB,0BAA0B,CAAC,IAAI,EAAE;IAChD,MAAM,EAAE,wBAAwB,CAAC;IACjC,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,wBAAwB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,oBAAoB,CA6CvB","sourcesContent":["import { existsSync, statSync } from \"node:fs\";\nimport path from \"node:path\";\nimport { pathToFileURL } from \"node:url\";\nimport type { WorkerClaim } from \"../autonomy/contracts.ts\";\nimport {\n\ttype ArtifactContract,\n\ttype EvidenceContract,\n\tORCHESTRATION_SCHEMA_VERSION,\n\ttype WorkerResultContract,\n} from \"./contracts.ts\";\nimport type { StartedDelegationAttempt } from \"./delegation-ledger.ts\";\n\nfunction artifactForChangedFile(cwd: string, changedPath: string, index: number, createdAt: string): ArtifactContract {\n\tconst absolutePath = path.isAbsolute(changedPath) ? path.resolve(changedPath) : path.resolve(cwd, changedPath);\n\tlet sizeBytes: number | undefined;\n\ttry {\n\t\tif (existsSync(absolutePath)) sizeBytes = statSync(absolutePath).size;\n\t} catch {\n\t\t// The path remains useful evidence even if it disappeared before metadata collection.\n\t}\n\treturn {\n\t\tartifactId: `changed-file-${index + 1}`,\n\t\tkind: \"file\",\n\t\turi: pathToFileURL(absolutePath).href,\n\t\t...(sizeBytes !== undefined ? { sizeBytes } : {}),\n\t\tcreatedAt,\n\t};\n}\n\nfunction evidenceForClaim(claim: WorkerClaim, createdAt: string): EvidenceContract[] {\n\tconst findings = claim.evidence?.findings ?? [];\n\treturn findings.map((finding, index) => ({\n\t\tevidenceId: `worker-finding-${index + 1}`,\n\t\tkind: \"observation\",\n\t\tsummary: finding.summary,\n\t\tartifactIds: [],\n\t\ttrusted: false,\n\t\tcreatedAt,\n\t\t...(finding.confidence !== undefined ? { metadata: { confidence: finding.confidence } } : {}),\n\t}));\n}\n\nfunction verificationEvidence(\n\tclaim: WorkerClaim,\n\taccepted: boolean,\n\tcriterionIds: readonly string[],\n\tcreatedAt: string,\n): EvidenceContract[] {\n\tif (!claim.verification) return [];\n\tconst trustedReview = accepted;\n\treturn [\n\t\t{\n\t\t\tevidenceId: \"independent-review\",\n\t\t\tkind: \"review\",\n\t\t\tsummary: claim.summary,\n\t\t\tartifactIds: [],\n\t\t\ttrusted: trustedReview,\n\t\t\tcreatedAt,\n\t\t\tmetadata: {\n\t\t\t\tsubjectTaskId: claim.verification.subjectTaskId,\n\t\t\t\tverdict: claim.verification.verdict,\n\t\t\t\treasonCodes: [...claim.verification.reasonCodes],\n\t\t\t},\n\t\t},\n\t\t...criterionIds.map(\n\t\t\t(criterionId, index): EvidenceContract => ({\n\t\t\t\tevidenceId: `independent-review-criterion-${index + 1}`,\n\t\t\t\tcriterionId,\n\t\t\t\tkind: \"review\",\n\t\t\t\tsummary: claim.summary,\n\t\t\t\tartifactIds: [],\n\t\t\t\ttrusted: trustedReview && claim.verification?.verdict === \"accepted\",\n\t\t\t\tcreatedAt,\n\t\t\t\tmetadata: { subjectTaskId: claim.verification?.subjectTaskId ?? \"\" },\n\t\t\t}),\n\t\t),\n\t];\n}\n\n/** Sole host-owned conversion from an untrusted claim to a fenced durable result. */\nexport function createWorkerResultContract(args: {\n\thandle: StartedDelegationAttempt;\n\tclaim: WorkerClaim;\n\taccepted: boolean;\n\tcostUsd?: number;\n\tcwd: string;\n\tinputTokens?: number;\n\toutputTokens?: number;\n\ttotalTokens?: number;\n\twallClockMs: number;\n\ttoolCalls: number;\n\tverificationRequired?: boolean;\n\tverificationCriterionIds?: readonly string[];\n\treasonCode?: string;\n\tcreatedAt?: string;\n}): WorkerResultContract {\n\tconst createdAt = args.createdAt ?? new Date().toISOString();\n\tconst claim = args.claim;\n\tconst status: WorkerResultContract[\"status\"] =\n\t\tclaim.status === \"completed\"\n\t\t\t? args.accepted && !args.verificationRequired\n\t\t\t\t? \"completed\"\n\t\t\t\t: \"partial\"\n\t\t\t: claim.status;\n\tconst artifacts = claim.changedFiles.map((changedPath, index) =>\n\t\tartifactForChangedFile(args.cwd, changedPath, index, createdAt),\n\t);\n\tconst blockers = claim.blockers ?? [];\n\treturn {\n\t\tschemaVersion: ORCHESTRATION_SCHEMA_VERSION,\n\t\tresultId: `result-${args.handle.attemptId}-${args.handle.fencingToken}`,\n\t\tobjectiveId: args.handle.objectiveId,\n\t\ttaskId: args.handle.taskId,\n\t\tattemptId: args.handle.attemptId,\n\t\tleaseId: args.handle.leaseId,\n\t\tfencingToken: args.handle.fencingToken,\n\t\tstatus,\n\t\treasonCode: args.reasonCode ?? `worker_${claim.status}`,\n\t\tsummary: claim.summary,\n\t\tartifacts,\n\t\tevidence: [\n\t\t\t...evidenceForClaim(claim, createdAt),\n\t\t\t...verificationEvidence(claim, args.accepted, args.verificationCriterionIds ?? [], createdAt),\n\t\t],\n\t\terrors: blockers.map((message) => ({ code: \"worker_blocker\", message, retryable: false })),\n\t\t...(args.verificationRequired\n\t\t\t? { nextAction: \"independent_verification_required\" }\n\t\t\t: !args.accepted || claim.parentReviewRequired\n\t\t\t\t? { nextAction: \"parent_review\" }\n\t\t\t\t: {}),\n\t\tusage: {\n\t\t\t...(args.inputTokens !== undefined ? { inputTokens: args.inputTokens } : {}),\n\t\t\t...(args.outputTokens !== undefined ? { outputTokens: args.outputTokens } : {}),\n\t\t\t...(args.totalTokens !== undefined ? { totalTokens: args.totalTokens } : {}),\n\t\t\t...(args.costUsd !== undefined ? { costUsd: args.costUsd } : {}),\n\t\t\twallClockMs: args.wallClockMs,\n\t\t\ttoolCalls: args.toolCalls,\n\t\t},\n\t\tcreatedAt,\n\t};\n}\n"]}

package/dist/core/orchestration/worker-result-adapter.js

@@ -0,0 +1,109 @@
+import { existsSync, statSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { ORCHESTRATION_SCHEMA_VERSION, } from "./contracts.js";
+function artifactForChangedFile(cwd, changedPath, index, createdAt) {
+    const absolutePath = path.isAbsolute(changedPath) ? path.resolve(changedPath) : path.resolve(cwd, changedPath);
+    let sizeBytes;
+    try {
+        if (existsSync(absolutePath))
+            sizeBytes = statSync(absolutePath).size;
+    }
+    catch {
+        // The path remains useful evidence even if it disappeared before metadata collection.
+    }
+    return {
+        artifactId: `changed-file-${index + 1}`,
+        kind: "file",
+        uri: pathToFileURL(absolutePath).href,
+        ...(sizeBytes !== undefined ? { sizeBytes } : {}),
+        createdAt,
+    };
+}
+function evidenceForClaim(claim, createdAt) {
+    const findings = claim.evidence?.findings ?? [];
+    return findings.map((finding, index) => ({
+        evidenceId: `worker-finding-${index + 1}`,
+        kind: "observation",
+        summary: finding.summary,
+        artifactIds: [],
+        trusted: false,
+        createdAt,
+        ...(finding.confidence !== undefined ? { metadata: { confidence: finding.confidence } } : {}),
+    }));
+}
+function verificationEvidence(claim, accepted, criterionIds, createdAt) {
+    if (!claim.verification)
+        return [];
+    const trustedReview = accepted;
+    return [
+        {
+            evidenceId: "independent-review",
+            kind: "review",
+            summary: claim.summary,
+            artifactIds: [],
+            trusted: trustedReview,
+            createdAt,
+            metadata: {
+                subjectTaskId: claim.verification.subjectTaskId,
+                verdict: claim.verification.verdict,
+                reasonCodes: [...claim.verification.reasonCodes],
+            },
+        },
+        ...criterionIds.map((criterionId, index) => ({
+            evidenceId: `independent-review-criterion-${index + 1}`,
+            criterionId,
+            kind: "review",
+            summary: claim.summary,
+            artifactIds: [],
+            trusted: trustedReview && claim.verification?.verdict === "accepted",
+            createdAt,
+            metadata: { subjectTaskId: claim.verification?.subjectTaskId ?? "" },
+        })),
+    ];
+}
+/** Sole host-owned conversion from an untrusted claim to a fenced durable result. */
+export function createWorkerResultContract(args) {
+    const createdAt = args.createdAt ?? new Date().toISOString();
+    const claim = args.claim;
+    const status = claim.status === "completed"
+        ? args.accepted && !args.verificationRequired
+            ? "completed"
+            : "partial"
+        : claim.status;
+    const artifacts = claim.changedFiles.map((changedPath, index) => artifactForChangedFile(args.cwd, changedPath, index, createdAt));
+    const blockers = claim.blockers ?? [];
+    return {
+        schemaVersion: ORCHESTRATION_SCHEMA_VERSION,
+        resultId: `result-${args.handle.attemptId}-${args.handle.fencingToken}`,
+        objectiveId: args.handle.objectiveId,
+        taskId: args.handle.taskId,
+        attemptId: args.handle.attemptId,
+        leaseId: args.handle.leaseId,
+        fencingToken: args.handle.fencingToken,
+        status,
+        reasonCode: args.reasonCode ?? `worker_${claim.status}`,
+        summary: claim.summary,
+        artifacts,
+        evidence: [
+            ...evidenceForClaim(claim, createdAt),
+            ...verificationEvidence(claim, args.accepted, args.verificationCriterionIds ?? [], createdAt),
+        ],
+        errors: blockers.map((message) => ({ code: "worker_blocker", message, retryable: false })),
+        ...(args.verificationRequired
+            ? { nextAction: "independent_verification_required" }
+            : !args.accepted || claim.parentReviewRequired
+                ? { nextAction: "parent_review" }
+                : {}),
+        usage: {
+            ...(args.inputTokens !== undefined ? { inputTokens: args.inputTokens } : {}),
+            ...(args.outputTokens !== undefined ? { outputTokens: args.outputTokens } : {}),
+            ...(args.totalTokens !== undefined ? { totalTokens: args.totalTokens } : {}),
+            ...(args.costUsd !== undefined ? { costUsd: args.costUsd } : {}),
+            wallClockMs: args.wallClockMs,
+            toolCalls: args.toolCalls,
+        },
+        createdAt,
+    };
+}
+//# sourceMappingURL=worker-result-adapter.js.map

package/dist/core/orchestration/worker-result-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-result-adapter.js","sourceRoot":"","sources":["../../../src/core/orchestration/worker-result-adapter.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync, statSync } from \"node:fs\";\nimport path from \"node:path\";\nimport { pathToFileURL } from \"node:url\";\nimport type { WorkerClaim } from \"../autonomy/contracts.ts\";\nimport {\n\ttype ArtifactContract,\n\ttype EvidenceContract,\n\tORCHESTRATION_SCHEMA_VERSION,\n\ttype WorkerResultContract,\n} from \"./contracts.ts\";\nimport type { StartedDelegationAttempt } from \"./delegation-ledger.ts\";\n\nfunction artifactForChangedFile(cwd: string, changedPath: string, index: number, createdAt: string): ArtifactContract {\n\tconst absolutePath = path.isAbsolute(changedPath) ? path.resolve(changedPath) : path.resolve(cwd, changedPath);\n\tlet sizeBytes: number | undefined;\n\ttry {\n\t\tif (existsSync(absolutePath)) sizeBytes = statSync(absolutePath).size;\n\t} catch {\n\t\t// The path remains useful evidence even if it disappeared before metadata collection.\n\t}\n\treturn {\n\t\tartifactId: `changed-file-${index + 1}`,\n\t\tkind: \"file\",\n\t\turi: pathToFileURL(absolutePath).href,\n\t\t...(sizeBytes !== undefined ? { sizeBytes } : {}),\n\t\tcreatedAt,\n\t};\n}\n\nfunction evidenceForClaim(claim: WorkerClaim, createdAt: string): EvidenceContract[] {\n\tconst findings = claim.evidence?.findings ?? [];\n\treturn findings.map((finding, index) => ({\n\t\tevidenceId: `worker-finding-${index + 1}`,\n\t\tkind: \"observation\",\n\t\tsummary: finding.summary,\n\t\tartifactIds: [],\n\t\ttrusted: false,\n\t\tcreatedAt,\n\t\t...(finding.confidence !== undefined ? { metadata: { confidence: finding.confidence } } : {}),\n\t}));\n}\n\nfunction verificationEvidence(\n\tclaim: WorkerClaim,\n\taccepted: boolean,\n\tcriterionIds: readonly string[],\n\tcreatedAt: string,\n): EvidenceContract[] {\n\tif (!claim.verification) return [];\n\tconst trustedReview = accepted;\n\treturn [\n\t\t{\n\t\t\tevidenceId: \"independent-review\",\n\t\t\tkind: \"review\",\n\t\t\tsummary: claim.summary,\n\t\t\tartifactIds: [],\n\t\t\ttrusted: trustedReview,\n\t\t\tcreatedAt,\n\t\t\tmetadata: {\n\t\t\t\tsubjectTaskId: claim.verification.subjectTaskId,\n\t\t\t\tverdict: claim.verification.verdict,\n\t\t\t\treasonCodes: [...claim.verification.reasonCodes],\n\t\t\t},\n\t\t},\n\t\t...criterionIds.map(\n\t\t\t(criterionId, index): EvidenceContract => ({\n\t\t\t\tevidenceId: `independent-review-criterion-${index + 1}`,\n\t\t\t\tcriterionId,\n\t\t\t\tkind: \"review\",\n\t\t\t\tsummary: claim.summary,\n\t\t\t\tartifactIds: [],\n\t\t\t\ttrusted: trustedReview && claim.verification?.verdict === \"accepted\",\n\t\t\t\tcreatedAt,\n\t\t\t\tmetadata: { subjectTaskId: claim.verification?.subjectTaskId ?? \"\" },\n\t\t\t}),\n\t\t),\n\t];\n}\n\n/** Sole host-owned conversion from an untrusted claim to a fenced durable result. */\nexport function createWorkerResultContract(args: {\n\thandle: StartedDelegationAttempt;\n\tclaim: WorkerClaim;\n\taccepted: boolean;\n\tcostUsd?: number;\n\tcwd: string;\n\tinputTokens?: number;\n\toutputTokens?: number;\n\ttotalTokens?: number;\n\twallClockMs: number;\n\ttoolCalls: number;\n\tverificationRequired?: boolean;\n\tverificationCriterionIds?: readonly string[];\n\treasonCode?: string;\n\tcreatedAt?: string;\n}): WorkerResultContract {\n\tconst createdAt = args.createdAt ?? new Date().toISOString();\n\tconst claim = args.claim;\n\tconst status: WorkerResultContract[\"status\"] =\n\t\tclaim.status === \"completed\"\n\t\t\t? args.accepted && !args.verificationRequired\n\t\t\t\t? \"completed\"\n\t\t\t\t: \"partial\"\n\t\t\t: claim.status;\n\tconst artifacts = claim.changedFiles.map((changedPath, index) =>\n\t\tartifactForChangedFile(args.cwd, changedPath, index, createdAt),\n\t);\n\tconst blockers = claim.blockers ?? [];\n\treturn {\n\t\tschemaVersion: ORCHESTRATION_SCHEMA_VERSION,\n\t\tresultId: `result-${args.handle.attemptId}-${args.handle.fencingToken}`,\n\t\tobjectiveId: args.handle.objectiveId,\n\t\ttaskId: args.handle.taskId,\n\t\tattemptId: args.handle.attemptId,\n\t\tleaseId: args.handle.leaseId,\n\t\tfencingToken: args.handle.fencingToken,\n\t\tstatus,\n\t\treasonCode: args.reasonCode ?? `worker_${claim.status}`,\n\t\tsummary: claim.summary,\n\t\tartifacts,\n\t\tevidence: [\n\t\t\t...evidenceForClaim(claim, createdAt),\n\t\t\t...verificationEvidence(claim, args.accepted, args.verificationCriterionIds ?? [], createdAt),\n\t\t],\n\t\terrors: blockers.map((message) => ({ code: \"worker_blocker\", message, retryable: false })),\n\t\t...(args.verificationRequired\n\t\t\t? { nextAction: \"independent_verification_required\" }\n\t\t\t: !args.accepted || claim.parentReviewRequired\n\t\t\t\t? { nextAction: \"parent_review\" }\n\t\t\t\t: {}),\n\t\tusage: {\n\t\t\t...(args.inputTokens !== undefined ? { inputTokens: args.inputTokens } : {}),\n\t\t\t...(args.outputTokens !== undefined ? { outputTokens: args.outputTokens } : {}),\n\t\t\t...(args.totalTokens !== undefined ? { totalTokens: args.totalTokens } : {}),\n\t\t\t...(args.costUsd !== undefined ? { costUsd: args.costUsd } : {}),\n\t\t\twallClockMs: args.wallClockMs,\n\t\t\ttoolCalls: args.toolCalls,\n\t\t},\n\t\tcreatedAt,\n\t};\n}\n"]}

package/dist/core/process-identity.d.ts

@@ -0,0 +1,11 @@
+/** Cross-process identity carried by managed child sessions. */
+export declare const PI_PARENT_PID_ENV = "PI_PARENT_PID";
+export declare const PI_PARENT_SESSION_ENV = "PI_PARENT_SESSION";
+export declare const PI_ORCHESTRATION_AGENT_ID_ENV = "PI_ORCHESTRATION_AGENT_ID";
+export declare const PI_TASK_REF_ENV = "PI_TASK_REF";
+/** A malformed or non-positive parent pid is ignored. */
+export declare function getParentPid(env?: NodeJS.ProcessEnv): number | undefined;
+export declare function getParentSessionId(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function getOrchestrationAgentId(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function getProcessTaskRef(env?: NodeJS.ProcessEnv): string | undefined;
+//# sourceMappingURL=process-identity.d.ts.map

package/dist/core/process-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-identity.d.ts","sourceRoot":"","sources":["../../src/core/process-identity.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAEhE,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AACjD,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AACzD,eAAO,MAAM,6BAA6B,8BAA8B,CAAC;AACzE,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAE7C,yDAAyD;AACzD,wBAAgB,YAAY,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAKrF;AAED,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAG3F;AAED,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAGhG;AAED,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAG1F","sourcesContent":["/** Cross-process identity carried by managed child sessions. */\n\nexport const PI_PARENT_PID_ENV = \"PI_PARENT_PID\";\nexport const PI_PARENT_SESSION_ENV = \"PI_PARENT_SESSION\";\nexport const PI_ORCHESTRATION_AGENT_ID_ENV = \"PI_ORCHESTRATION_AGENT_ID\";\nexport const PI_TASK_REF_ENV = \"PI_TASK_REF\";\n\n/** A malformed or non-positive parent pid is ignored. */\nexport function getParentPid(env: NodeJS.ProcessEnv = process.env): number | undefined {\n\tconst raw = env[PI_PARENT_PID_ENV];\n\tif (raw === undefined) return undefined;\n\tconst value = Number.parseInt(raw, 10);\n\treturn Number.isFinite(value) && value > 0 ? value : undefined;\n}\n\nexport function getParentSessionId(env: NodeJS.ProcessEnv = process.env): string | undefined {\n\tconst value = env[PI_PARENT_SESSION_ENV]?.trim();\n\treturn value && value.length > 0 ? value : undefined;\n}\n\nexport function getOrchestrationAgentId(env: NodeJS.ProcessEnv = process.env): string | undefined {\n\tconst value = env[PI_ORCHESTRATION_AGENT_ID_ENV]?.trim();\n\treturn value && value.length > 0 ? value : undefined;\n}\n\nexport function getProcessTaskRef(env: NodeJS.ProcessEnv = process.env): string | undefined {\n\tconst value = env[PI_TASK_REF_ENV]?.trim();\n\treturn value && value.length > 0 ? value : undefined;\n}\n"]}

package/dist/core/process-identity.js

@@ -0,0 +1,26 @@
+/** Cross-process identity carried by managed child sessions. */
+export const PI_PARENT_PID_ENV = "PI_PARENT_PID";
+export const PI_PARENT_SESSION_ENV = "PI_PARENT_SESSION";
+export const PI_ORCHESTRATION_AGENT_ID_ENV = "PI_ORCHESTRATION_AGENT_ID";
+export const PI_TASK_REF_ENV = "PI_TASK_REF";
+/** A malformed or non-positive parent pid is ignored. */
+export function getParentPid(env = process.env) {
+    const raw = env[PI_PARENT_PID_ENV];
+    if (raw === undefined)
+        return undefined;
+    const value = Number.parseInt(raw, 10);
+    return Number.isFinite(value) && value > 0 ? value : undefined;
+}
+export function getParentSessionId(env = process.env) {
+    const value = env[PI_PARENT_SESSION_ENV]?.trim();
+    return value && value.length > 0 ? value : undefined;
+}
+export function getOrchestrationAgentId(env = process.env) {
+    const value = env[PI_ORCHESTRATION_AGENT_ID_ENV]?.trim();
+    return value && value.length > 0 ? value : undefined;
+}
+export function getProcessTaskRef(env = process.env) {
+    const value = env[PI_TASK_REF_ENV]?.trim();
+    return value && value.length > 0 ? value : undefined;
+}
+//# sourceMappingURL=process-identity.js.map

package/dist/core/process-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-identity.js","sourceRoot":"","sources":["../../src/core/process-identity.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAEhE,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,CAAC;AACjD,MAAM,CAAC,MAAM,qBAAqB,GAAG,mBAAmB,CAAC;AACzD,MAAM,CAAC,MAAM,6BAA6B,GAAG,2BAA2B,CAAC;AACzE,MAAM,CAAC,MAAM,eAAe,GAAG,aAAa,CAAC;AAE7C,yDAAyD;AACzD,MAAM,UAAU,YAAY,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG,EAAsB;IACtF,MAAM,GAAG,GAAG,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACvC,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAAA,CAC/D;AAED,MAAM,UAAU,kBAAkB,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG,EAAsB;IAC5F,MAAM,KAAK,GAAG,GAAG,CAAC,qBAAqB,CAAC,EAAE,IAAI,EAAE,CAAC;IACjD,OAAO,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAAA,CACrD;AAED,MAAM,UAAU,uBAAuB,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG,EAAsB;IACjG,MAAM,KAAK,GAAG,GAAG,CAAC,6BAA6B,CAAC,EAAE,IAAI,EAAE,CAAC;IACzD,OAAO,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAAA,CACrD;AAED,MAAM,UAAU,iBAAiB,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG,EAAsB;IAC3F,MAAM,KAAK,GAAG,GAAG,CAAC,eAAe,CAAC,EAAE,IAAI,EAAE,CAAC;IAC3C,OAAO,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAAA,CACrD","sourcesContent":["/** Cross-process identity carried by managed child sessions. */\n\nexport const PI_PARENT_PID_ENV = \"PI_PARENT_PID\";\nexport const PI_PARENT_SESSION_ENV = \"PI_PARENT_SESSION\";\nexport const PI_ORCHESTRATION_AGENT_ID_ENV = \"PI_ORCHESTRATION_AGENT_ID\";\nexport const PI_TASK_REF_ENV = \"PI_TASK_REF\";\n\n/** A malformed or non-positive parent pid is ignored. */\nexport function getParentPid(env: NodeJS.ProcessEnv = process.env): number | undefined {\n\tconst raw = env[PI_PARENT_PID_ENV];\n\tif (raw === undefined) return undefined;\n\tconst value = Number.parseInt(raw, 10);\n\treturn Number.isFinite(value) && value > 0 ? value : undefined;\n}\n\nexport function getParentSessionId(env: NodeJS.ProcessEnv = process.env): string | undefined {\n\tconst value = env[PI_PARENT_SESSION_ENV]?.trim();\n\treturn value && value.length > 0 ? value : undefined;\n}\n\nexport function getOrchestrationAgentId(env: NodeJS.ProcessEnv = process.env): string | undefined {\n\tconst value = env[PI_ORCHESTRATION_AGENT_ID_ENV]?.trim();\n\treturn value && value.length > 0 ? value : undefined;\n}\n\nexport function getProcessTaskRef(env: NodeJS.ProcessEnv = process.env): string | undefined {\n\tconst value = env[PI_TASK_REF_ENV]?.trim();\n\treturn value && value.length > 0 ? value : undefined;\n}\n"]}

package/dist/core/process-matrix/codes.d.ts

@@ -11,6 +11,7 @@
  *   tmux-dispatched agent. A worker knows its parent's pid and winds down gracefully -- never
  *   silently -- when that parent disappears.
  */
+import type { AgentIdentityContract } from "../orchestration/contracts.ts";
 export type ProcessRole = "master" | "worker";
 /**
  * - `running` -- normal operation.
@@ -25,16 +26,24 @@ export type ProcessStatus = "running" | "winding_down" | "resumable" | "adopted"
 export type WindDownReason = "parent_lost" | "parent_shutdown" | "user_cleanup";
 /** What a wound-down worker leaves behind so its task can be picked back up. */
 export interface ResumablePayload {
-    laneKey?: string;
+    agent: AgentIdentityContract;
+    taskRef?: string;
     taskSummary?: string;
     lastCode: ProcessStatus;
 }
+/** Durable terminal notification outbox for one worker process. */
+export interface ProcessTerminalHandoff {
+    code: number | null;
+    signal: string | null;
+    observedAt: string;
+    notificationDeliveredAt?: string;
+}
 /** One process-matrix entry: one file under `state/process-matrix/<entryId>.json` (see `store.ts`). */
 export interface ProcessMatrixEntry {
     entryId: string;
     role: ProcessRole;
+    agent: AgentIdentityContract;
     pid: number;
-    sessionId: string;
     hostname: string;
     startedAt: string;
     heartbeatAt: string;
@@ -42,12 +51,13 @@ export interface ProcessMatrixEntry {
     /** Worker-only: the pid of the process that launched this one. */
     parentPid?: number;
     parentSessionId?: string;
-    laneKey?: string;
     tmuxSession?: string;
     tmuxPanePid?: number;
     taskRef?: string;
+    taskSummary?: string;
     windDownReason?: WindDownReason;
     resumable?: ResumablePayload;
+    terminal?: ProcessTerminalHandoff;
 }
 /** What a master decides to do about one orphaned worker during the startup scan. */
 export type CleanupAction = "adopt" | "cleanup" | "leave";
@@ -68,5 +78,6 @@ export interface ReconcileMatrixResult {
     code: "reconciled";
     kept: ProcessMatrixEntry[];
     prunedEntryIds: string[];
+    recoveredEntryIds: string[];
 }
 //# sourceMappingURL=codes.d.ts.map

package/dist/core/process-matrix/codes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codes.d.ts","sourceRoot":"","sources":["../../../src/core/process-matrix/codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE9C;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,cAAc,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE5F,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,iBAAiB,GAAG,cAAc,CAAC;AAEhF,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,aAAa,CAAC;CACxB;AAED,uGAAuG;AACvG,MAAM,WAAW,kBAAkB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,WAAW,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;IACtB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,SAAS,CAAC,EAAE,gBAAgB,CAAC;CAC7B;AAED,qFAAqF;AACrF,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;AAE1D;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjH,iGAAiG;AACjG,MAAM,WAAW,qBAAqB;IACrC,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,kBAAkB,EAAE,CAAC;IAC3B,cAAc,EAAE,MAAM,EAAE,CAAC;CACzB","sourcesContent":["/**\n * Process-matrix SSOT for tagged result codes and shared record types.\n *\n * Every process-matrix lifecycle transition is expressed as one of the string-literal codes/status\n * values below -- callers (the runtime, the master orphan scan, the worker watcher) branch on\n * `code`/`status`, NEVER on a message/substring (the same doctrine as `worktree-sync/codes.ts`).\n *\n * The matrix tracks two roles:\n * - `master`: the top-level interactive/direct session (or the root of a launch chain).\n * - `worker`: a session launched with a known parent (`PI_PARENT_PID`/`--parent-pid`), e.g. a\n *   tmux-dispatched agent. A worker knows its parent's pid and winds down gracefully -- never\n *   silently -- when that parent disappears.\n */\n\nexport type ProcessRole = \"master\" | \"worker\";\n\n/**\n * - `running` -- normal operation.\n * - `winding_down` -- a lifecycle transition is in progress (parent lost, parent shutdown, or a\n *   cooperative user-requested cleanup); the process is finishing up before exit.\n * - `resumable` -- wound down leaving a payload describing how to pick the task back up.\n * - `adopted` -- claimed by a new parent after the original parent was lost (retained by\n *   `reconcileMatrix` alongside `resumable`, TTL-gated).\n * - `closed` -- terminal; safe to prune.\n */\nexport type ProcessStatus = \"running\" | \"winding_down\" | \"resumable\" | \"adopted\" | \"closed\";\n\nexport type WindDownReason = \"parent_lost\" | \"parent_shutdown\" | \"user_cleanup\";\n\n/** What a wound-down worker leaves behind so its task can be picked back up. */\nexport interface ResumablePayload {\n\tlaneKey?: string;\n\ttaskSummary?: string;\n\tlastCode: ProcessStatus;\n}\n\n/** One process-matrix entry: one file under `state/process-matrix/<entryId>.json` (see `store.ts`). */\nexport interface ProcessMatrixEntry {\n\tentryId: string;\n\trole: ProcessRole;\n\tpid: number;\n\tsessionId: string;\n\thostname: string;\n\tstartedAt: string;\n\theartbeatAt: string;\n\tstatus: ProcessStatus;\n\t/** Worker-only: the pid of the process that launched this one. */\n\tparentPid?: number;\n\tparentSessionId?: string;\n\tlaneKey?: string;\n\ttmuxSession?: string;\n\ttmuxPanePid?: number;\n\ttaskRef?: string;\n\twindDownReason?: WindDownReason;\n\tresumable?: ResumablePayload;\n}\n\n/** What a master decides to do about one orphaned worker during the startup scan. */\nexport type CleanupAction = \"adopt\" | \"cleanup\" | \"leave\";\n\n/**\n * What a worker learns by re-reading its OWN fresh matrix entry (a master may have written an\n * adoption or a cooperative-cleanup request into it -- see `docs/process-matrix.md`).\n */\nexport type WorkerDirective = { code: \"adopt\"; parentPid: number } | { code: \"user_cleanup\" } | { code: \"none\" };\n\n/** Outcome of a `reconcileMatrix` pass: which entries survive and which were pruned, and why. */\nexport interface ReconcileMatrixResult {\n\tcode: \"reconciled\";\n\tkept: ProcessMatrixEntry[];\n\tprunedEntryIds: string[];\n}\n"]}
+{"version":3,"file":"codes.d.ts","sourceRoot":"","sources":["../../../src/core/process-matrix/codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAE3E,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE9C;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,cAAc,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE5F,MAAM,MAAM,cAAc,GAAG,aAAa,GAAG,iBAAiB,GAAG,cAAc,CAAC;AAEhF,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,qBAAqB,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,aAAa,CAAC;CACxB;AAED,mEAAmE;AACnE,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,uBAAuB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,uGAAuG;AACvG,MAAM,WAAW,kBAAkB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,qBAAqB,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;IACtB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,QAAQ,CAAC,EAAE,sBAAsB,CAAC;CAClC;AAED,qFAAqF;AACrF,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;AAE1D;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjH,iGAAiG;AACjG,MAAM,WAAW,qBAAqB;IACrC,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,kBAAkB,EAAE,CAAC;IAC3B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC5B","sourcesContent":["/**\n * Process-matrix SSOT for tagged result codes and shared record types.\n *\n * Every process-matrix lifecycle transition is expressed as one of the string-literal codes/status\n * values below -- callers (the runtime, the master orphan scan, the worker watcher) branch on\n * `code`/`status`, NEVER on a message/substring (the same doctrine as `worktree-sync/codes.ts`).\n *\n * The matrix tracks two roles:\n * - `master`: the top-level interactive/direct session (or the root of a launch chain).\n * - `worker`: a session launched with a known parent (`PI_PARENT_PID`/`--parent-pid`), e.g. a\n *   tmux-dispatched agent. A worker knows its parent's pid and winds down gracefully -- never\n *   silently -- when that parent disappears.\n */\n\nimport type { AgentIdentityContract } from \"../orchestration/contracts.ts\";\n\nexport type ProcessRole = \"master\" | \"worker\";\n\n/**\n * - `running` -- normal operation.\n * - `winding_down` -- a lifecycle transition is in progress (parent lost, parent shutdown, or a\n *   cooperative user-requested cleanup); the process is finishing up before exit.\n * - `resumable` -- wound down leaving a payload describing how to pick the task back up.\n * - `adopted` -- claimed by a new parent after the original parent was lost (retained by\n *   `reconcileMatrix` alongside `resumable`, TTL-gated).\n * - `closed` -- terminal; safe to prune.\n */\nexport type ProcessStatus = \"running\" | \"winding_down\" | \"resumable\" | \"adopted\" | \"closed\";\n\nexport type WindDownReason = \"parent_lost\" | \"parent_shutdown\" | \"user_cleanup\";\n\n/** What a wound-down worker leaves behind so its task can be picked back up. */\nexport interface ResumablePayload {\n\tagent: AgentIdentityContract;\n\ttaskRef?: string;\n\ttaskSummary?: string;\n\tlastCode: ProcessStatus;\n}\n\n/** Durable terminal notification outbox for one worker process. */\nexport interface ProcessTerminalHandoff {\n\tcode: number | null;\n\tsignal: string | null;\n\tobservedAt: string;\n\tnotificationDeliveredAt?: string;\n}\n\n/** One process-matrix entry: one file under `state/process-matrix/<entryId>.json` (see `store.ts`). */\nexport interface ProcessMatrixEntry {\n\tentryId: string;\n\trole: ProcessRole;\n\tagent: AgentIdentityContract;\n\tpid: number;\n\thostname: string;\n\tstartedAt: string;\n\theartbeatAt: string;\n\tstatus: ProcessStatus;\n\t/** Worker-only: the pid of the process that launched this one. */\n\tparentPid?: number;\n\tparentSessionId?: string;\n\ttmuxSession?: string;\n\ttmuxPanePid?: number;\n\ttaskRef?: string;\n\ttaskSummary?: string;\n\twindDownReason?: WindDownReason;\n\tresumable?: ResumablePayload;\n\tterminal?: ProcessTerminalHandoff;\n}\n\n/** What a master decides to do about one orphaned worker during the startup scan. */\nexport type CleanupAction = \"adopt\" | \"cleanup\" | \"leave\";\n\n/**\n * What a worker learns by re-reading its OWN fresh matrix entry (a master may have written an\n * adoption or a cooperative-cleanup request into it -- see `docs/process-matrix.md`).\n */\nexport type WorkerDirective = { code: \"adopt\"; parentPid: number } | { code: \"user_cleanup\" } | { code: \"none\" };\n\n/** Outcome of a `reconcileMatrix` pass: which entries survive and which were pruned, and why. */\nexport interface ReconcileMatrixResult {\n\tcode: \"reconciled\";\n\tkept: ProcessMatrixEntry[];\n\tprunedEntryIds: string[];\n\trecoveredEntryIds: string[];\n}\n"]}

package/dist/core/process-matrix/codes.js.map

@@ -1 +1 @@
-{"version":3,"file":"codes.js","sourceRoot":"","sources":["../../../src/core/process-matrix/codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG","sourcesContent":["/**\n * Process-matrix SSOT for tagged result codes and shared record types.\n *\n * Every process-matrix lifecycle transition is expressed as one of the string-literal codes/status\n * values below -- callers (the runtime, the master orphan scan, the worker watcher) branch on\n * `code`/`status`, NEVER on a message/substring (the same doctrine as `worktree-sync/codes.ts`).\n *\n * The matrix tracks two roles:\n * - `master`: the top-level interactive/direct session (or the root of a launch chain).\n * - `worker`: a session launched with a known parent (`PI_PARENT_PID`/`--parent-pid`), e.g. a\n *   tmux-dispatched agent. A worker knows its parent's pid and winds down gracefully -- never\n *   silently -- when that parent disappears.\n */\n\nexport type ProcessRole = \"master\" | \"worker\";\n\n/**\n * - `running` -- normal operation.\n * - `winding_down` -- a lifecycle transition is in progress (parent lost, parent shutdown, or a\n *   cooperative user-requested cleanup); the process is finishing up before exit.\n * - `resumable` -- wound down leaving a payload describing how to pick the task back up.\n * - `adopted` -- claimed by a new parent after the original parent was lost (retained by\n *   `reconcileMatrix` alongside `resumable`, TTL-gated).\n * - `closed` -- terminal; safe to prune.\n */\nexport type ProcessStatus = \"running\" | \"winding_down\" | \"resumable\" | \"adopted\" | \"closed\";\n\nexport type WindDownReason = \"parent_lost\" | \"parent_shutdown\" | \"user_cleanup\";\n\n/** What a wound-down worker leaves behind so its task can be picked back up. */\nexport interface ResumablePayload {\n\tlaneKey?: string;\n\ttaskSummary?: string;\n\tlastCode: ProcessStatus;\n}\n\n/** One process-matrix entry: one file under `state/process-matrix/<entryId>.json` (see `store.ts`). */\nexport interface ProcessMatrixEntry {\n\tentryId: string;\n\trole: ProcessRole;\n\tpid: number;\n\tsessionId: string;\n\thostname: string;\n\tstartedAt: string;\n\theartbeatAt: string;\n\tstatus: ProcessStatus;\n\t/** Worker-only: the pid of the process that launched this one. */\n\tparentPid?: number;\n\tparentSessionId?: string;\n\tlaneKey?: string;\n\ttmuxSession?: string;\n\ttmuxPanePid?: number;\n\ttaskRef?: string;\n\twindDownReason?: WindDownReason;\n\tresumable?: ResumablePayload;\n}\n\n/** What a master decides to do about one orphaned worker during the startup scan. */\nexport type CleanupAction = \"adopt\" | \"cleanup\" | \"leave\";\n\n/**\n * What a worker learns by re-reading its OWN fresh matrix entry (a master may have written an\n * adoption or a cooperative-cleanup request into it -- see `docs/process-matrix.md`).\n */\nexport type WorkerDirective = { code: \"adopt\"; parentPid: number } | { code: \"user_cleanup\" } | { code: \"none\" };\n\n/** Outcome of a `reconcileMatrix` pass: which entries survive and which were pruned, and why. */\nexport interface ReconcileMatrixResult {\n\tcode: \"reconciled\";\n\tkept: ProcessMatrixEntry[];\n\tprunedEntryIds: string[];\n}\n"]}
+{"version":3,"file":"codes.js","sourceRoot":"","sources":["../../../src/core/process-matrix/codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG","sourcesContent":["/**\n * Process-matrix SSOT for tagged result codes and shared record types.\n *\n * Every process-matrix lifecycle transition is expressed as one of the string-literal codes/status\n * values below -- callers (the runtime, the master orphan scan, the worker watcher) branch on\n * `code`/`status`, NEVER on a message/substring (the same doctrine as `worktree-sync/codes.ts`).\n *\n * The matrix tracks two roles:\n * - `master`: the top-level interactive/direct session (or the root of a launch chain).\n * - `worker`: a session launched with a known parent (`PI_PARENT_PID`/`--parent-pid`), e.g. a\n *   tmux-dispatched agent. A worker knows its parent's pid and winds down gracefully -- never\n *   silently -- when that parent disappears.\n */\n\nimport type { AgentIdentityContract } from \"../orchestration/contracts.ts\";\n\nexport type ProcessRole = \"master\" | \"worker\";\n\n/**\n * - `running` -- normal operation.\n * - `winding_down` -- a lifecycle transition is in progress (parent lost, parent shutdown, or a\n *   cooperative user-requested cleanup); the process is finishing up before exit.\n * - `resumable` -- wound down leaving a payload describing how to pick the task back up.\n * - `adopted` -- claimed by a new parent after the original parent was lost (retained by\n *   `reconcileMatrix` alongside `resumable`, TTL-gated).\n * - `closed` -- terminal; safe to prune.\n */\nexport type ProcessStatus = \"running\" | \"winding_down\" | \"resumable\" | \"adopted\" | \"closed\";\n\nexport type WindDownReason = \"parent_lost\" | \"parent_shutdown\" | \"user_cleanup\";\n\n/** What a wound-down worker leaves behind so its task can be picked back up. */\nexport interface ResumablePayload {\n\tagent: AgentIdentityContract;\n\ttaskRef?: string;\n\ttaskSummary?: string;\n\tlastCode: ProcessStatus;\n}\n\n/** Durable terminal notification outbox for one worker process. */\nexport interface ProcessTerminalHandoff {\n\tcode: number | null;\n\tsignal: string | null;\n\tobservedAt: string;\n\tnotificationDeliveredAt?: string;\n}\n\n/** One process-matrix entry: one file under `state/process-matrix/<entryId>.json` (see `store.ts`). */\nexport interface ProcessMatrixEntry {\n\tentryId: string;\n\trole: ProcessRole;\n\tagent: AgentIdentityContract;\n\tpid: number;\n\thostname: string;\n\tstartedAt: string;\n\theartbeatAt: string;\n\tstatus: ProcessStatus;\n\t/** Worker-only: the pid of the process that launched this one. */\n\tparentPid?: number;\n\tparentSessionId?: string;\n\ttmuxSession?: string;\n\ttmuxPanePid?: number;\n\ttaskRef?: string;\n\ttaskSummary?: string;\n\twindDownReason?: WindDownReason;\n\tresumable?: ResumablePayload;\n\tterminal?: ProcessTerminalHandoff;\n}\n\n/** What a master decides to do about one orphaned worker during the startup scan. */\nexport type CleanupAction = \"adopt\" | \"cleanup\" | \"leave\";\n\n/**\n * What a worker learns by re-reading its OWN fresh matrix entry (a master may have written an\n * adoption or a cooperative-cleanup request into it -- see `docs/process-matrix.md`).\n */\nexport type WorkerDirective = { code: \"adopt\"; parentPid: number } | { code: \"user_cleanup\" } | { code: \"none\" };\n\n/** Outcome of a `reconcileMatrix` pass: which entries survive and which were pruned, and why. */\nexport interface ReconcileMatrixResult {\n\tcode: \"reconciled\";\n\tkept: ProcessMatrixEntry[];\n\tprunedEntryIds: string[];\n\trecoveredEntryIds: string[];\n}\n"]}

package/dist/core/process-matrix/resume-launcher.d.ts

@@ -0,0 +1,26 @@
+import type { ResumablePayload } from "./codes.ts";
+export interface PiSelfLaunchTarget {
+    executable: string;
+    argsPrefix: readonly string[];
+}
+export type ResumablePiAgentLaunchOutcome = {
+    started: true;
+    pid: number;
+    completion: Promise<{
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }>;
+} | {
+    started: false;
+    reason: string;
+};
+export declare function buildResumablePiAgentWakePrompt(payload: ResumablePayload): string;
+/** Launches one exact persisted Pi session; completion is observed only through process events. */
+export declare function launchResumablePiAgent(options: {
+    payload: ResumablePayload;
+    target: PiSelfLaunchTarget;
+    parentPid: number;
+    parentSessionId: string;
+    environment: NodeJS.ProcessEnv;
+}): Promise<ResumablePiAgentLaunchOutcome>;
+//# sourceMappingURL=resume-launcher.d.ts.map

package/dist/core/process-matrix/resume-launcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume-launcher.d.ts","sourceRoot":"","sources":["../../../src/core/process-matrix/resume-launcher.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,MAAM,WAAW,kBAAkB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B;AAED,MAAM,MAAM,6BAA6B,GACtC;IACA,OAAO,EAAE,IAAI,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CAC3E,GACD;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAgBjF;AAED,mGAAmG;AACnG,wBAAsB,sBAAsB,CAAC,OAAO,EAAE;IACrD,OAAO,EAAE,gBAAgB,CAAC;IAC1B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC,UAAU,CAAC;CAC/B,GAAG,OAAO,CAAC,6BAA6B,CAAC,CA4CzC","sourcesContent":["import { spawn } from \"node:child_process\";\nimport { buildPiResumeLaunchSpec } from \"../orchestration/agent-resume.ts\";\nimport type { ResumablePayload } from \"./codes.ts\";\n\nexport interface PiSelfLaunchTarget {\n\texecutable: string;\n\targsPrefix: readonly string[];\n}\n\nexport type ResumablePiAgentLaunchOutcome =\n\t| {\n\t\t\tstarted: true;\n\t\t\tpid: number;\n\t\t\tcompletion: Promise<{ code: number | null; signal: NodeJS.Signals | null }>;\n\t  }\n\t| { started: false; reason: string };\n\nexport function buildResumablePiAgentWakePrompt(payload: ResumablePayload): string {\n\tconst context = payload.agent.resumeContext;\n\tconst taskSummary = payload.taskSummary?.trim().slice(0, 2_000);\n\tconst contextPointers = context.contextPointers\n\t\t.slice(0, 20)\n\t\t.map(\n\t\t\t(pointer) =>\n\t\t\t\t`- ${JSON.stringify({ id: pointer.id, kind: pointer.kind, uri: pointer.uri, readOnly: pointer.readOnly }).slice(0, 1_000)}`,\n\t\t);\n\treturn [\n\t\t\"Resume this interrupted delegated task using the persisted session context and the same logical agent identity.\",\n\t\t...(taskSummary ? [`Task: ${taskSummary}`] : []),\n\t\t...(context.latestCheckpointId ? [`Latest checkpoint: ${context.latestCheckpointId}`] : []),\n\t\t...(contextPointers.length > 0 ? [\"Persisted context pointers:\", ...contextPointers] : []),\n\t\t\"Continue from the persisted transcript and referenced checkpoints or artifacts, then finish with a persisted terminal result.\",\n\t].join(\"\\n\");\n}\n\n/** Launches one exact persisted Pi session; completion is observed only through process events. */\nexport async function launchResumablePiAgent(options: {\n\tpayload: ResumablePayload;\n\ttarget: PiSelfLaunchTarget;\n\tparentPid: number;\n\tparentSessionId: string;\n\tenvironment: NodeJS.ProcessEnv;\n}): Promise<ResumablePiAgentLaunchOutcome> {\n\tconst context = options.payload.agent.resumeContext;\n\tif (!context || context.provider !== \"pi\") {\n\t\treturn { started: false, reason: \"Pi resume context is unavailable.\" };\n\t}\n\tconst spec = buildPiResumeLaunchSpec(options.payload.agent, {\n\t\texecutable: options.target.executable,\n\t\targsPrefix: options.target.argsPrefix,\n\t\tparentPid: options.parentPid,\n\t\tparentSessionId: options.parentSessionId,\n\t\ttaskRef: options.payload.taskRef,\n\t\twakePrompt: buildResumablePiAgentWakePrompt(options.payload),\n\t});\n\tif ([spec.executable, spec.cwd, ...spec.args].some((value) => value.includes(\"\\0\"))) {\n\t\treturn { started: false, reason: \"Resume launch data contains a null byte.\" };\n\t}\n\ttry {\n\t\tconst child = spawn(spec.executable, spec.args, {\n\t\t\tcwd: spec.cwd,\n\t\t\tdetached: true,\n\t\t\tstdio: \"ignore\",\n\t\t\tenv: { ...options.environment, ...spec.env },\n\t\t});\n\t\treturn await new Promise<ResumablePiAgentLaunchOutcome>((resolve) => {\n\t\t\tchild.once(\"error\", (error) => resolve({ started: false, reason: error.message }));\n\t\t\tchild.once(\"spawn\", () => {\n\t\t\t\tconst childPid = child.pid;\n\t\t\t\tif (childPid === undefined || !Number.isSafeInteger(childPid) || childPid <= 0) {\n\t\t\t\t\tresolve({ started: false, reason: \"Resume process started without a valid pid.\" });\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tconst completion = new Promise<{ code: number | null; signal: NodeJS.Signals | null }>(\n\t\t\t\t\t(resolveCompletion, rejectCompletion) => {\n\t\t\t\t\t\tchild.once(\"exit\", (code, signal) => resolveCompletion({ code, signal }));\n\t\t\t\t\t\tchild.once(\"error\", rejectCompletion);\n\t\t\t\t\t},\n\t\t\t\t);\n\t\t\t\tchild.unref();\n\t\t\t\tresolve({ started: true, pid: childPid, completion });\n\t\t\t});\n\t\t});\n\t} catch (error) {\n\t\treturn { started: false, reason: error instanceof Error ? error.message : String(error) };\n\t}\n}\n"]}