@akagilnc/pi-workflow-roles 0.1.5577 → 0.1.5593

package/dist/public-cli/invocation.js

@@ -1,21 +1,20 @@
 /**
- * Public Invocation request admission: optional opaque instruction, frozen
- * Attachments, project default/override (ADR 0052 / #106).
+ * Public Invocation request admission: optional opaque instruction, caller
+ * attachment paths as-is, project default/override (ADR 0052 / #106 / #1165).
  */
 import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
-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 { readFile, realpath, rename, writeFile, } from "node:fs/promises";
+import { 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";
 import { ensureRoleRunDirectory, ensureRoleRunPlacement, formatRunLeaf, isUnboundRunDirectory, listBookRunDirectories, roleRunPlacement, } from "../role-run-placement.js";
 import { packagedAdmittedSubject, packagedArgvResult, packagedBareToken, packagedBaseIsRevision, packagedEmitsAuthorityRefs, packagedPublicInstructionSubject, packagedRoleMetadata, packagedStoresSourceRunRaw, packagedSubjectChoices, } from "../packaged-role-registry.js";
 import { isSafePositiveTicketNumber, parseTicketNumber, readBoardTicketNumber, requireSafePositiveTicketNumber, } from "../run-ticket-number.js";
-import { rewriteRunDirectoryPathFields, rewriteRunDirectoryPathValue, } from "../role-run-relocation.js";
+import { rewriteRunDirectoryPathFields, } from "../role-run-relocation.js";
 import { readPageSync, renderCurrentSync, updateSectionSync, writeSectionSync } from "../run-dossier.js";
 import { loadDoctorCase, } from "../doctor-evidence.js";
-import { emptyCollectorManifest, loadCollectorManifest, parseCollectorPrNumber, parseCollectorRepository, } from "../collector-config.js";
+import { parseCollectorPrNumber, parseCollectorRepository, } from "../collector-config.js";
 import { ownerRepoFromGitHubRemoteUrl } from "./github-remote.js";
 import { FixerPacketValidationError, parseFixerPrerequisites, } from "../package-contracts/fixer-packet.js";
 import { createProductionMergerGitState } from "../merger-git-state.js";
@@ -25,10 +24,23 @@ import { rehomeUnboundTicketProvenance } from "../ticket-provenance.js";
 import { uuidv7 } from "../uuidv7.js";
 import {} from "../notary-contracts.js";
 import { NotarySourceRunError, resolveNotarySourceRunLocator, } from "../notary-source-run.js";
-import { appendEngineSessionMaterial, } from "../package-resources/engine-material.js";
 import { CliUsageError } from "./cli-errors.js";
 import { REJECTED_PUBLIC_SPELLINGS, createTypedOptionConsumer, evaluateAnalystModeOptionContract, optionsForOwner, resolveAnalystMode, } from "./option-definitions.js";
 import { errorText, isRecord } from "../unknown-value.js";
+/** Normalize admitted attachment records (caller path only; #1165). */
+export function normalizeAdmittedAttachment(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const record = raw;
+    const path = record.path;
+    // Opaque caller path — keep "" / whitespace; only a non-string is absent.
+    if (typeof path === "string")
+        return { path };
+    return undefined;
+}
+function admitCallerAttachments(attachmentPaths) {
+    return attachmentPaths.map((path) => ({ path }));
+}
 /** Issue a principal from the single authoritative role-run placement. */
 export function issueAdmissionPlacement(authority, request) {
     const ledgerHome = resolveActivationLedgerHome(request.home);
@@ -262,12 +274,9 @@ export async function relocateAdmittedRunToTicket(admitted, authority, heldLease
         "taskPath",
         "packetPath",
         "prerequisitesPath",
-        "requestManifestPath",
         "mergerInputPath",
     ], oldRunDirectory, target.runDirectory);
-    for (const attachment of admitted.attachments) {
-        attachment.frozenPath = rewriteRunDirectoryPathValue(attachment.frozenPath, oldRunDirectory, target.runDirectory);
-    }
+    // #1165: caller --attach / --request-manifest paths stay as given; do not rewrite.
     admitted.principal = principal;
     // current.json projects host.original from this run directory. Ownership is
     // already transferred; a refuse still carries the true cause to the caller
@@ -383,7 +392,8 @@ function assignPublicSeatOption(owner, taken, fields) {
     const value = taken.value;
     switch (taken.def.id) {
         case "attach":
-            fields.attachmentPaths.push(requireOptionPath(taken.def.canonical, value));
+            // #1165: file-flag values are opaque; only a missing argument is a usage error.
+            fields.attachmentPaths.push(requireProvidedOptionValue(taken.def.canonical, value));
             return;
         case "project":
             fields.project = requireOptionPath(taken.def.canonical, value);
@@ -427,7 +437,8 @@ function assignPublicSeatOption(owner, taken, fields) {
             fields.repo = parseRepoOption(value);
             return;
         case "request-manifest":
-            fields.requestManifestPath = requireOptionPath(taken.def.canonical, value);
+            // #1165: file-flag values are opaque; only a missing argument is a usage error.
+            fields.requestManifestPath = requireProvidedOptionValue(taken.def.canonical, value);
             return;
         case "issue": {
             if (value === undefined || value.trim() === "") {
@@ -540,6 +551,16 @@ function requireOptionPath(flag, value) {
     }
     return value;
 }
+/**
+ * #1165 file flags (--attach / --request-manifest): keep the provided string
+ * opaque (including spaces and ""). Only a missing argument is a usage error.
+ */
+function requireProvidedOptionValue(flag, value) {
+    if (value === undefined) {
+        throw new CliUsageError(`${flag} requires a path`);
+    }
+    return value;
+}
 /**
  * Shared Skill-arg token rule for caller-controlled values projected into the
  * space-joined Skill invocation line. Rejects blank, whitespace (smuggles the
@@ -625,123 +646,6 @@ export function requireAuthorityRef(value) {
         optionLike: "--authority-ref requires a durable reference, not inline Spec prose",
     });
 }
-async function readRegularFileAttachment(sourcePath) {
-    const absolute = isAbsolute(sourcePath) ? sourcePath : resolve(sourcePath);
-    let st;
-    try {
-        st = await lstat(absolute);
-    }
-    catch (error) {
-        throw new CliUsageError(`attachment is not a readable regular file: ${sourcePath}`, { cause: error });
-    }
-    if (!st.isFile() || st.isSymbolicLink()) {
-        throw new CliUsageError(`attachment must be a regular file (not a directory or symlink): ${sourcePath}`);
-    }
-    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 {
-        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,
-    };
-}
-/** Freeze attachments only — ticket binding is the shared LLM seat path (#635). */
-async function freezeAttachments(ledgerHome, attachmentPaths, attachmentsDirectory) {
-    const attachments = [];
-    // attachments/ appears only when something is frozen; created through the
-    // ledger's symlink-rejecting tree walk, never a plain mkdir.
-    if (attachmentPaths.length > 0) {
-        ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
-    }
-    for (let i = 0; i < attachmentPaths.length; i += 1) {
-        const frozen = await freezeRegularFileAttachment(attachmentPaths[i], attachmentsDirectory, i);
-        attachments.push(frozen.attachment);
-    }
-    return attachments;
-}
-/**
- * Freeze summons attachments into an already-retained run (#637 same-ticket resume).
- * Writes under attachments/summons-<key>/ so prior freeze names stay intact.
- * Manual resume never calls this — birth attachments keep their original semantics.
- */
-export async function freezeAttachmentsIntoRun(attachmentPaths, runDirectory, summonsKey = `s-${Date.now().toString(36)}`) {
-    if (attachmentPaths.length === 0)
-        return [];
-    const ledgerHome = resolveActivationLedgerHome(homeFromRunDirectory(runDirectory));
-    const attachmentsDirectory = join(runDirectory, "attachments", summonsKey);
-    ensureRealDirectoryTree(ledgerHome, attachmentsDirectory);
-    return freezeAttachments(ledgerHome, 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 {};
@@ -892,36 +796,21 @@ export async function admitPublicRole(role, parsed, env, override) {
             else {
                 repository = resolveGitHubRemoteRepository(projectRoot);
             }
-            let manifest = emptyCollectorManifest();
-            let manifestCanonicalJson;
-            if (parsed.requestManifestPath !== undefined) {
-                try {
-                    manifest = await loadCollectorManifest(parsed.requestManifestPath);
-                    manifestCanonicalJson = manifest.canonicalJson;
-                }
-                catch (error) {
-                    throw new CliUsageError(errorText(error), { cause: error });
-                }
-            }
-            const manifestDigest = manifest.digest;
+            // #1165: pass caller path as-is; package does not read, validate, or rewrite.
             const admittedCollector = await admitStandardMaterialInvocation("collector", {
                 ...shared,
                 instruction,
                 attachmentPaths,
                 ...project,
-                placedFields: async (placed) => {
+                placedFields: async () => {
                     // #1088: explicit --pr only. Unbound PR is located by the LLM via host CLI.
-                    let requestManifestPath;
-                    if (manifestCanonicalJson !== undefined) {
-                        requestManifestPath = join(placed.runDirectory, "request-manifest.json");
-                        await writeFile(requestManifestPath, manifestCanonicalJson, "utf8");
-                    }
                     return {
                         ...(explicitPrNumber === undefined ? {} : { prNumber: explicitPrNumber }),
                         repository: repository.canonical,
                         repositoryDisplay: repository.display,
-                        ...(requestManifestPath === undefined ? {} : { requestManifestPath }),
-                        manifestDigest,
+                        ...(parsed.requestManifestPath === undefined
+                            ? {}
+                            : { requestManifestPath: parsed.requestManifestPath }),
                     };
                 },
             });
@@ -932,12 +821,10 @@ export async function admitPublicRole(role, parsed, env, override) {
                 throw new CliUsageError(`doctor --issue must be a positive integer, got ${Number.NaN}`);
             }
             const issueNumber = parsed.issueNumber;
-            let frozenAttachments = [];
-            const admittedDoctor = await admitStandardMaterialInvocation("doctor", {
+            return admitStandardMaterialInvocation("doctor", {
                 ...shared,
                 instruction,
-                attachmentPaths: [],
-                freezeAttachments: false,
+                attachmentPaths,
                 ...project,
                 placedFields: async (placed) => {
                     let caseRunsPath;
@@ -974,16 +861,13 @@ export async function admitPublicRole(role, parsed, env, override) {
                         const detail = errorText(error);
                         throw new CliUsageError(`doctor case could not be constructed from retained evidence: ${detail}`, { cause: error });
                     }
-                    frozenAttachments = await freezeAttachments(placed.ledgerHome, attachmentPaths, placed.attachmentsDirectory);
                     return {
                         issueNumber,
                         caseRunsPath,
                         caseIdentity,
-                        attachments: persistedAttachmentRefs(frozenAttachments),
                     };
                 },
             });
-            return { ...admittedDoctor, attachments: frozenAttachments };
         }
         case "source-locator": {
             const projectRoot = resolve(parsed.project ?? shared.cwd);
@@ -1014,7 +898,7 @@ export async function admitPublicRole(role, parsed, env, override) {
                 instruction: "",
                 attachmentPaths: [],
                 ...project,
-                freezeAttachments: false,
+                recordAttachments: false,
                 admittedFields: {
                     sourceRunPath: sourceRun.runDirectory,
                     sourceRun,
@@ -1031,7 +915,7 @@ export async function admitPublicRole(role, parsed, env, override) {
                 instruction,
                 attachmentPaths: [],
                 ...project,
-                freezeAttachments: false,
+                recordAttachments: false,
                 admittedFields: { baseRevision },
             });
         }
@@ -1129,9 +1013,9 @@ async function placeRoleAdmission(options) {
         home: options.home,
         ...(options.materialize === undefined ? {} : { materialize: options.materialize }),
     });
-    const attachments = options.freezeAttachments === false
+    const attachments = options.recordAttachments === false
         ? []
-        : await freezeAttachments(ledgerHome, options.attachmentPaths, attachmentsDirectory);
+        : admitCallerAttachments(options.attachmentPaths);
     return {
         runId,
         bookKey,
@@ -1147,13 +1031,7 @@ async function placeRoleAdmission(options) {
     };
 }
 function persistedAttachmentRefs(attachments) {
-    return attachments.map((attachment) => ({
-        provenancePath: attachment.provenancePath,
-        frozenPath: attachment.frozenPath,
-        byteLength: attachment.byteLength,
-        sha256: attachment.sha256,
-        mediaKind: attachment.mediaKind,
-    }));
+    return attachments.map((attachment) => ({ path: attachment.path }));
 }
 async function persistPlacedAdmission(admitted, placed, model) {
     writeAdmittedRequestPersistence(placed.runDirectory, admitted, {
@@ -1173,19 +1051,18 @@ async function persistPlacedAdmission(admitted, placed, model) {
  * before materializeCountersignInvocation writes the page.
  * Seats whose extra facts are known before placement pass them as admittedFields.
  * Seats whose extra facts depend on the placed run pass placedFields
- * (coder writes task.md; fixer writes fix-packet.md; collector writes request-manifest.json;
- * doctor resolves the case, then freezes attachments; merger writes merger-input.json).
+ * (coder writes task.md; fixer writes fix-packet.md; merger writes merger-input.json).
  */
 async function admitStandardMaterialInvocation(role, options) {
     const defer = options.deferPersistence === true;
-    const skipFreeze = defer || options.freezeAttachments === false;
+    const skipAttachments = defer || options.recordAttachments === false;
     const placed = await placeRoleAdmission({
         role,
         home: options.home,
         principalAuthority: options.principalAuthority,
         cwd: options.cwd,
         attachmentPaths: options.attachmentPaths,
-        ...(skipFreeze ? { freezeAttachments: false } : {}),
+        ...(skipAttachments ? { recordAttachments: false } : {}),
         ...(defer ? { materialize: false } : {}),
         ...(options.project === undefined ? {} : { project: options.project }),
         ...(options.createRunId === undefined ? {} : { createRunId: options.createRunId }),
@@ -1197,7 +1074,8 @@ async function admitStandardMaterialInvocation(role, options) {
         ? {}
         : { correlationId: options.correlationId };
     const instruction = options.instruction;
-    const instructionEmpty = instruction.trim() === "";
+    // Admitted emptiness is literal absence, not whitespace-only (#1165 J3).
+    const instructionEmpty = instruction.length === 0;
     const placedExtra = options.placedFields === undefined ? undefined : await options.placedFields(placed);
     const admittedFields = {
         ...(options.admittedFields ?? {}),
@@ -1245,25 +1123,28 @@ function admittedTransportPromptKind(admitted) {
 /**
  * One initial prompt transport. The registry `transportPrompt` leaf selects
  * a fixed kickoff, a bound baseline, or frozen skill args. Absent means the
- * caller instruction plus frozen attachment paths.
+ * caller instruction plus caller attachment paths as-is (#1165).
+ * Engine / outsourcing material rides startup readingMaterial (#1167), not here.
  */
-export function buildInstructionTransportPrompt(admitted, engineMaterial) {
+export function buildInstructionTransportPrompt(admitted) {
     const kind = admittedTransportPromptKind(admitted);
     if (kind === "fixed-kickoff") {
         if (admitted.sourceRunPath === undefined || admitted.sourceRunPath.trim() === "") {
             throw new Error("fixed-kickoff transport prompt is missing the source run pointer");
         }
-        return appendEngineSessionMaterial([admitted.sourceRunPath], engineMaterial).join("\n");
+        return admitted.sourceRunPath;
     }
     if (kind === "baseline") {
         if (admitted.baseRevision === undefined) {
             throw new Error("baseline transport prompt is missing the bound revision");
         }
         const lines = [admitted.baseRevision];
-        if (!admitted.instructionEmpty) {
+        // Use raw admitted.instruction — do not gate on instructionEmpty metadata
+        // (old pages may set that flag wrong while still holding whitespace text).
+        if (admitted.instruction.length > 0) {
             lines.push("", admitted.instruction);
         }
-        return appendEngineSessionMaterial(lines, engineMaterial).join("\n");
+        return lines.join("\n");
     }
     if (kind === "skill-args") {
         if (admitted.baseRevision === undefined
@@ -1276,20 +1157,28 @@ export function buildInstructionTransportPrompt(admitted, engineMaterial) {
                 lens: admitted.lens,
                 authorityRefs: admitted.authorityRefs,
             })];
-        if (!admitted.instructionEmpty && admitted.instruction.trim() !== "") {
+        if (admitted.instruction.length > 0) {
             lines.push("", admitted.instruction);
         }
-        return appendEngineSessionMaterial(lines, engineMaterial).join("\n");
+        return lines.join("\n");
     }
-    const lines = [admitted.instructionEmpty ? "" : admitted.instruction];
-    if (admitted.attachments.length > 0) {
+    // #1165 J3: assemble from the admitted instruction bytes themselves.
+    const lines = [admitted.instruction];
+    // #1164/#1165: each caller path keeps its file-flag provenance.
+    const flaggedPaths = [
+        ...admitted.attachments.map((attachment) => `--attach ${attachment.path}`),
+        ...(admitted.requestManifestPath === undefined
+            ? []
+            : [`--request-manifest ${admitted.requestManifestPath}`]),
+    ];
+    if (flaggedPaths.length > 0) {
         lines.push("");
-        lines.push("已受理附件（冻结快照路径）：");
-        for (const attachment of admitted.attachments) {
-            lines.push(`- ${attachment.frozenPath}`);
+        lines.push("已受理附件：");
+        for (const entry of flaggedPaths) {
+            lines.push(`- ${entry}`);
         }
     }
-    return appendEngineSessionMaterial(lines, engineMaterial).join("\n");
+    return lines.join("\n");
 }
 /** Persist a deferred Countersign admission after same-ticket lookup found no retained run. */
 export async function materializeCountersignInvocation(admitted, options) {
@@ -1298,8 +1187,7 @@ export async function materializeCountersignInvocation(admitted, options) {
         home: options.home,
         principalAuthority: options.principalAuthority,
         cwd: admitted.projectRoot,
-        attachmentPaths: [],
-        freezeAttachments: false,
+        attachmentPaths: options.attachmentPaths,
         runId: admitted.runId,
         ...(options.ticketNumber === undefined ? {} : { assertedTicketNumber: options.ticketNumber }),
     });
@@ -1310,8 +1198,7 @@ export async function materializeCountersignInvocation(admitted, options) {
     if (ticketFields.ticketNumber !== undefined) {
         admitted.ticketNumber = ticketFields.ticketNumber;
     }
-    const attachments = await freezePreparedAttachmentsIntoRun(options.preparedAttachments, admitted.runDirectory);
-    admitted.attachments = attachments;
+    admitted.attachments = placement.attachments;
     writeAdmittedRequestPersistence(admitted.runDirectory, admitted, {
         sessionDirectory: placement.sessionDirectory,
         sessionFile: placement.sessionFile,
@@ -1332,10 +1219,13 @@ export async function loadAdmittedJudgeRequest(runDirectory) {
             return undefined;
         if (!Array.isArray(record.attachments))
             return undefined;
+        const attachments = record.attachments
+            .map((item) => normalizeAdmittedAttachment(item))
+            .filter((item) => item !== undefined);
         return {
             instruction: record.instruction,
             instructionEmpty: record.instructionEmpty,
-            attachments: record.attachments,
+            attachments,
         };
     }
     catch {
@@ -1597,7 +1487,7 @@ export function parseAnalystArgv(args) {
                 return;
             }
             if (taken.def.id === "attach") {
-                pushValue("attach", requireOptionPath(taken.def.canonical, taken.value));
+                pushValue("attach", requireProvidedOptionValue(taken.def.canonical, taken.value));
                 return;
             }
             if (taken.def.id === "group-a-label" || taken.def.id === "group-b-label") {