@akagilnc/pi-workflow-roles 0.1.4444 → 0.1.4503

package/dist/public-cli/invocation.js

@@ -4,7 +4,8 @@
  */
 import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { lstat, readFile, realpath, rename, writeFile, } from "node:fs/promises";
+import { lstat, mkdtemp, readFile, realpath, rename, rm, writeFile, } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { activationBookDirectory, ensureRealDirectoryTree, homeFromRunDirectory, pathContainedIn, resolveActivationLedgerHome, } from "../activation-ledger-topology.js";
 import { resolveBookKeyFromGit } from "../activation-ledger-git.js";
@@ -36,7 +37,8 @@ export function issueAdmissionPlacement(authority, request) {
         runId: request.runId,
         role: request.role,
     });
-    ensureRoleRunPlacement(ledgerHome, placement);
+    if (request.materialize !== false)
+        ensureRoleRunPlacement(ledgerHome, placement);
     return {
         principal: authority.seal(placement),
         ...placement,
@@ -172,6 +174,27 @@ export async function bindAdmittedTicketNumber(admitted, ticketNumber) {
     await bindTicketNumberOnRunDirectory(admitted.runDirectory, ticketNumber);
     admitted.ticketNumber = ticketNumber;
 }
+/** Persist each direct caller observed while a retained run is resumed. */
+export async function recordAdmittedCorrelation(admitted, correlationId) {
+    const current = JSON.parse(await readFile(admitted.admittedRequestPath, "utf8"));
+    const prior = [
+        ...(Array.isArray(current.correlationIds)
+            ? current.correlationIds.filter((value) => typeof value === "string" && value.trim() !== "")
+            : []),
+        ...(typeof current.correlationId === "string" && current.correlationId.trim() !== ""
+            ? [current.correlationId]
+            : []),
+    ];
+    const correlationIds = [...new Set([...prior, correlationId])];
+    await writeFile(admitted.admittedRequestPath, `${JSON.stringify({ ...current, correlationId, correlationIds }, null, 2)}\n`, "utf8");
+    await mergeInvocationIdentityPage(admitted.runDirectory, {
+        correlationId,
+        correlationIds,
+    });
+    const mutable = admitted;
+    mutable.correlationId = correlationId;
+    mutable.correlationIds = correlationIds;
+}
 /**
  * #871: persist the typed co-review set as a countersign run fact (admitted-request +
  * invocation.json). Whole-set replace — never union with a prior set. Main ticket
@@ -584,7 +607,7 @@ export function parseFixerArgv(args) {
         ...(project === undefined ? {} : { project }),
     };
 }
-async function freezeRegularFileAttachment(sourcePath, destinationDir, index) {
+async function readRegularFileAttachment(sourcePath) {
     const absolute = isAbsolute(sourcePath) ? sourcePath : resolve(sourcePath);
     let st;
     try {
@@ -596,18 +619,66 @@ async function freezeRegularFileAttachment(sourcePath, destinationDir, index) {
     if (!st.isFile() || st.isSymbolicLink()) {
         throw new CliUsageError(`attachment must be a regular file (not a directory or symlink): ${sourcePath}`);
     }
-    const bytes = await readFile(absolute);
-    const name = `${String(index).padStart(2, "0")}-${basename(absolute)}`;
-    const frozenPath = join(destinationDir, name);
+    try {
+        return { absolute, bytes: await readFile(absolute) };
+    }
+    catch (error) {
+        throw new CliUsageError(`attachment is not a readable regular file: ${sourcePath}`, { cause: error });
+    }
+}
+/**
+ * Snapshot deferred inputs sequentially before identity side effects. The staging
+ * files keep aggregate attachment bytes off heap until their final run is known.
+ */
+async function removePreparedAttachmentDirectory(stagingDirectory) {
+    await rm(stagingDirectory, { recursive: true, force: true });
+}
+/** Own the complete deferred-snapshot lifetime without masking either failure. */
+export async function withPreparedAttachments(attachmentPaths, use) {
+    if (attachmentPaths.length === 0)
+        return await use([]);
+    const stagingDirectory = await mkdtemp(join(tmpdir(), "ak-role-attachments-"));
+    const prepared = [];
+    let result;
+    try {
+        for (let index = 0; index < attachmentPaths.length; index += 1) {
+            const { absolute, bytes } = await readRegularFileAttachment(attachmentPaths[index]);
+            const snapshotPath = join(stagingDirectory, String(index).padStart(6, "0"));
+            await writeFile(snapshotPath, bytes);
+            prepared.push({ absolute, snapshotPath });
+        }
+        result = await use(prepared);
+    }
+    catch (primary) {
+        try {
+            await removePreparedAttachmentDirectory(stagingDirectory);
+        }
+        catch (cleanup) {
+            throw new AggregateError([primary, cleanup], "attachment snapshot operation failed and cleanup also failed", { cause: primary });
+        }
+        throw primary;
+    }
+    await removePreparedAttachmentDirectory(stagingDirectory);
+    return result;
+}
+async function freezeAttachmentBytes(provenancePath, bytes, destinationDir, index) {
+    const frozenPath = join(destinationDir, `${String(index).padStart(2, "0")}-${basename(provenancePath)}`);
     await writeFile(frozenPath, bytes);
     return {
-        attachment: {
-            provenancePath: absolute,
-            frozenPath,
-            byteLength: bytes.byteLength,
-            sha256: sha256Hex(bytes),
-            mediaKind: "regular-file",
-        },
+        provenancePath,
+        frozenPath,
+        byteLength: bytes.byteLength,
+        sha256: sha256Hex(bytes),
+        mediaKind: "regular-file",
+    };
+}
+async function freezePreparedAttachment(prepared, destinationDir, index) {
+    return freezeAttachmentBytes(prepared.absolute, await readFile(prepared.snapshotPath), destinationDir, index);
+}
+async function freezeRegularFileAttachment(sourcePath, destinationDir, index) {
+    const { absolute, bytes } = await readRegularFileAttachment(sourcePath);
+    return {
+        attachment: await freezeAttachmentBytes(absolute, bytes, destinationDir, index),
         body: bytes,
     };
 }
@@ -633,6 +704,21 @@ export async function freezeAttachmentsIntoRun(attachmentPaths, runDirectory, su
     ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
     return freezeAttachments(attachmentPaths, attachmentsDirectory);
 }
+/** Freeze prepared bytes and metadata through one path for birth or retained runs. */
+export async function freezePreparedAttachmentsIntoRun(prepared, runDirectory, summonsKey) {
+    if (prepared.length === 0)
+        return [];
+    const ledgerHome = resolveActivationLedgerHome(homeFromRunDirectory(runDirectory));
+    const attachmentsDirectory = summonsKey === undefined
+        ? join(runDirectory, "attachments")
+        : join(runDirectory, "attachments", summonsKey);
+    ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
+    const attachments = [];
+    for (let index = 0; index < prepared.length; index += 1) {
+        attachments.push(await freezePreparedAttachment(prepared[index], attachmentsDirectory, index));
+    }
+    return attachments;
+}
 function ticketAdmissionFields(ticketNumber) {
     if (ticketNumber === undefined)
         return {};
@@ -776,8 +862,8 @@ export function buildInspectorTransportPrompt(admitted, engineMaterial) {
     return buildInstructionTransportPrompt(admitted, engineMaterial);
 }
 /**
- * Atomically admit a Countersign Role run: freeze Attachments, persist the
- * request, write the invocation ledger (#572 / ADR 0074).
+ * Admit a Countersign run immediately, or reserve its coordinates for deferred
+ * materialization after identity lookup (#572 / ADR 0074 / #863).
  */
 export async function admitCountersignInvocation(options) {
     // Same shared freeze/coordinate body as judge but role: "countersign" so
@@ -793,8 +879,11 @@ export async function admitCountersignInvocation(options) {
         role: "countersign",
         subject: { unbound: true },
         home: options.home,
+        materialize: options.deferPersistence !== true,
     });
-    const attachments = await freezeAttachments(options.attachmentPaths, attachmentsDirectory);
+    const attachments = options.deferPersistence === true
+        ? []
+        : await freezeAttachments(options.attachmentPaths, attachmentsDirectory);
     // Ticket binding is LLM-only post-admission (#635); admission stays unbound.
     const instruction = options.instruction;
     const instructionEmpty = instruction.trim() === "";
@@ -817,11 +906,13 @@ export async function admitCountersignInvocation(options) {
         })),
     };
     const admittedRequestPath = join(runDirectory, "admitted-request.json");
-    await writeAdmittedRequestPersistence(admittedRequestPath, admitted, {
-        sessionDirectory,
-        sessionFile,
-    });
-    await writeRoleInvocationLedger({ ...admitted, sessionDirectory, sessionFile }, admitted.role, options.model);
+    if (options.deferPersistence !== true) {
+        await writeAdmittedRequestPersistence(admittedRequestPath, admitted, {
+            sessionDirectory,
+            sessionFile,
+        });
+        await writeRoleInvocationLedger({ ...admitted, sessionDirectory, sessionFile }, admitted.role, options.model);
+    }
     return {
         role: "countersign",
         runId,
@@ -836,6 +927,23 @@ export async function admitCountersignInvocation(options) {
         ...(options.correlationId === undefined ? {} : { correlationId: options.correlationId }),
     };
 }
+/** Persist a deferred Countersign admission after same-ticket lookup found no retained run. */
+export async function materializeCountersignInvocation(admitted, options) {
+    const placement = issueAdmissionPlacement(options.principalAuthority, {
+        cwd: admitted.projectRoot,
+        runId: admitted.runId,
+        role: "countersign",
+        subject: { unbound: true },
+        home: options.home,
+    });
+    const attachments = await freezePreparedAttachmentsIntoRun(options.preparedAttachments, admitted.runDirectory);
+    admitted.attachments = attachments;
+    await writeAdmittedRequestPersistence(admitted.admittedRequestPath, admitted, {
+        sessionDirectory: placement.sessionDirectory,
+        sessionFile: placement.sessionFile,
+    });
+    await writeRoleInvocationLedger({ ...admitted, sessionDirectory: placement.sessionDirectory, sessionFile: placement.sessionFile }, admitted.role, options.model);
+}
 /** Build the Pi prompt transport for an admitted Countersign request. */
 export function buildCountersignTransportPrompt(admitted, engineMaterial) {
     return buildInstructionTransportPrompt(admitted, engineMaterial);