@akagilnc/pi-workflow-roles 0.1.5583 → 0.1.5593

package/src/public-cli/invocation.ts

@@ -1,20 +1,16 @@
 /**
- * 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 { dirname, isAbsolute, join, resolve, sep } from "node:path";
 
 import {
   activationBookDirectory,
@@ -57,7 +53,6 @@ import {
 } from "../run-ticket-number.ts";
 import {
   rewriteRunDirectoryPathFields,
-  rewriteRunDirectoryPathValue,
 } from "../role-run-relocation.ts";
 import { readPageSync, renderCurrentSync, updateSectionSync, writeSectionSync } from "../run-dossier.ts";
 import {
@@ -65,8 +60,6 @@ import {
 } from "../doctor-evidence.ts";
 import type { DoctorCaseIdentity } from "../doctor-contracts.ts";
 import {
-  emptyCollectorManifest,
-  loadCollectorManifest,
   parseCollectorPrNumber,
   parseCollectorRepository,
   type CollectorRepository,
@@ -110,16 +103,27 @@ import type { PublicThinkingLevel } from "./registry.ts";
 
 import { errorText, isRecord } from "../unknown-value.ts";
 
+/** Caller-supplied attachment path recorded as-is (#1165). */
 export type FrozenAttachment = {
-  /** Original caller path retained only as provenance. */
-  readonly provenancePath: string;
-  /** Absolute path of the admitted frozen snapshot bytes. */
-  readonly frozenPath: string;
-  readonly byteLength: number;
-  readonly sha256: string;
-  readonly mediaKind: "regular-file";
+  readonly path: string;
 };
 
+/** Normalize admitted attachment records (caller path only; #1165). */
+export function normalizeAdmittedAttachment(raw: unknown): FrozenAttachment | undefined {
+  if (typeof raw !== "object" || raw === null) return undefined;
+  const record = raw as Record<string, unknown>;
+  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: readonly string[],
+): readonly FrozenAttachment[] {
+  return attachmentPaths.map((path) => ({ path }));
+}
+
 /** Shared admitted Role run identity (#106 common Invocation + #109 Coder). */
 export type AdmittedRoleInvocationBase = {
   readonly runId: string;
@@ -127,7 +131,7 @@ export type AdmittedRoleInvocationBase = {
   readonly projectRoot: string;
   /** Opaque instruction bytes as submitted. */
   readonly instruction: string;
-  /** True when the caller supplied no nonblank instruction. */
+  /** True when the caller supplied a literally empty instruction (length 0). */
   readonly instructionEmpty: boolean;
   readonly attachments: readonly FrozenAttachment[];
   readonly runDirectory: string;
@@ -222,7 +226,6 @@ export type AdmittedCollectorInvocation = AdmittedRoleInvocationBase & {
   readonly prNumber?: number;
   readonly repository: CollectorRepository;
   readonly requestManifestPath?: string;
-  readonly manifestDigest: string;
 };
 
 export type AdmittedDoctorInvocation = AdmittedRoleInvocationBase & {
@@ -622,19 +625,12 @@ export async function relocateAdmittedRunToTicket(
       "taskPath",
       "packetPath",
       "prerequisitesPath",
-      "requestManifestPath",
       "mergerInputPath",
     ],
     oldRunDirectory,
     target.runDirectory,
   );
-  for (const attachment of admitted.attachments) {
-    (attachment as { frozenPath: string }).frozenPath = rewriteRunDirectoryPathValue(
-      attachment.frozenPath,
-      oldRunDirectory,
-      target.runDirectory,
-    ) as string;
-  }
+  // #1165: caller --attach / --request-manifest paths stay as given; do not rewrite.
   (admitted as { principal: DurablePrincipal }).principal = principal;
 
   // current.json projects host.original from this run directory. Ownership is
@@ -842,7 +838,8 @@ function assignPublicSeatOption(
   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);
@@ -888,7 +885,8 @@ function assignPublicSeatOption(
       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() === "") {
@@ -1072,6 +1070,20 @@ function requireOptionPath(
   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: string,
+  value: string | undefined,
+): string {
+  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
@@ -1166,184 +1178,6 @@ export function requireAuthorityRef(value: string | undefined): string {
   });
 }
 
-async function readRegularFileAttachment(
-  sourcePath: string,
-): Promise<{ absolute: string; bytes: Buffer }> {
-  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 },
-    );
-  }
-}
-
-export type PreparedAttachment = {
-  readonly absolute: string;
-  readonly snapshotPath: string;
-};
-
-/**
- * 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: string): Promise<void> {
-  await rm(stagingDirectory, { recursive: true, force: true });
-}
-
-/** Own the complete deferred-snapshot lifetime without masking either failure. */
-export async function withPreparedAttachments<T>(
-  attachmentPaths: readonly string[],
-  use: (prepared: readonly PreparedAttachment[]) => Promise<T>,
-): Promise<T> {
-  if (attachmentPaths.length === 0) return await use([]);
-  const stagingDirectory = await mkdtemp(join(tmpdir(), "ak-role-attachments-"));
-  const prepared: PreparedAttachment[] = [];
-  let result: T;
-  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: string,
-  bytes: Buffer,
-  destinationDir: string,
-  index: number,
-): Promise<FrozenAttachment> {
-  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: PreparedAttachment,
-  destinationDir: string,
-  index: number,
-): Promise<FrozenAttachment> {
-  return freezeAttachmentBytes(
-    prepared.absolute,
-    await readFile(prepared.snapshotPath),
-    destinationDir,
-    index,
-  );
-}
-
-async function freezeRegularFileAttachment(
-  sourcePath: string,
-  destinationDir: string,
-  index: number,
-): Promise<{ attachment: FrozenAttachment; body: Buffer }> {
-  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: string,
-  attachmentPaths: readonly string[],
-  attachmentsDirectory: string,
-): Promise<readonly FrozenAttachment[]> {
-  const attachments: FrozenAttachment[] = [];
-  // 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: readonly string[],
-  runDirectory: string,
-  summonsKey: string = `s-${Date.now().toString(36)}`,
-): Promise<readonly FrozenAttachment[]> {
-  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: readonly PreparedAttachment[],
-  runDirectory: string,
-  summonsKey?: string,
-): Promise<readonly FrozenAttachment[]> {
-  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: FrozenAttachment[] = [];
-  for (let index = 0; index < prepared.length; index += 1) {
-    attachments.push(await freezePreparedAttachment(prepared[index]!, attachmentsDirectory, index));
-  }
-  return attachments;
-}
-
 function ticketAdmissionFields(
   ticketNumber: number | undefined,
 ): { ticketNumber?: number } {
@@ -1573,38 +1407,21 @@ export async function admitPublicRole(
       } else {
         repository = resolveGitHubRemoteRepository(projectRoot);
       }
-      let manifest = emptyCollectorManifest();
-      let manifestCanonicalJson: string | undefined;
-      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: string | undefined;
-          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 }),
           };
         },
       });
@@ -1617,12 +1434,10 @@ export async function admitPublicRole(
         );
       }
       const issueNumber = parsed.issueNumber;
-      let frozenAttachments: readonly FrozenAttachment[] = [];
-      const admittedDoctor = await admitStandardMaterialInvocation("doctor", {
+      return admitStandardMaterialInvocation("doctor", {
         ...shared,
         instruction,
-        attachmentPaths: [],
-        freezeAttachments: false,
+        attachmentPaths,
         ...project,
         placedFields: async (placed) => {
           let caseRunsPath: string;
@@ -1663,16 +1478,13 @@ export async function admitPublicRole(
               { 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);
@@ -1702,7 +1514,7 @@ export async function admitPublicRole(
         instruction: "",
         attachmentPaths: [],
         ...project,
-        freezeAttachments: false,
+        recordAttachments: false,
         admittedFields: {
           sourceRunPath: sourceRun.runDirectory,
           sourceRun,
@@ -1719,7 +1531,7 @@ export async function admitPublicRole(
         instruction,
         attachmentPaths: [],
         ...project,
-        freezeAttachments: false,
+        recordAttachments: false,
         admittedFields: { baseRevision },
       });
     }
@@ -1868,8 +1680,8 @@ async function placeRoleAdmission(options: {
   readonly runId?: string;
   readonly assertedTicketNumber?: number;
   readonly attachmentPaths: readonly string[];
-  /** Gleaner-left admits no caller attachments. */
-  readonly freezeAttachments?: boolean;
+  /** When false, leave attachments empty (deferred countersign / seats without attach). */
+  readonly recordAttachments?: boolean;
   /** Countersign reserves coordinates, then materializes after identity lookup. */
   readonly materialize?: boolean;
 }): Promise<PlacedRoleAdmission> {
@@ -1892,9 +1704,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,
@@ -1912,20 +1724,8 @@ async function placeRoleAdmission(options: {
 
 function persistedAttachmentRefs(
   attachments: readonly FrozenAttachment[],
-): ReadonlyArray<{
-  provenancePath: string;
-  frozenPath: string;
-  byteLength: number;
-  sha256: string;
-  mediaKind: FrozenAttachment["mediaKind"];
-}> {
-  return attachments.map((attachment) => ({
-    provenancePath: attachment.provenancePath,
-    frozenPath: attachment.frozenPath,
-    byteLength: attachment.byteLength,
-    sha256: attachment.sha256,
-    mediaKind: attachment.mediaKind,
-  }));
+): ReadonlyArray<{ path: string }> {
+  return attachments.map((attachment) => ({ path: attachment.path }));
 }
 
 async function persistPlacedAdmission(
@@ -1967,8 +1767,7 @@ async function persistPlacedAdmission(
  * 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<
   R extends PackagedRole,
@@ -1976,10 +1775,10 @@ async function admitStandardMaterialInvocation<
 >(
   role: R,
   options: AdmitInspectorInvocationOptions & {
-    /** Reserve coordinates; skip freeze, placement disk, and admitted section write. */
+    /** Reserve coordinates; skip placement disk and admitted section write. */
     readonly deferPersistence?: boolean;
-    /** Skip attachment freeze. Gleaner-left admits no caller attachments. */
-    readonly freezeAttachments?: boolean;
+    /** Leave attachments empty (gleaner-left / notary / deferred countersign). */
+    readonly recordAttachments?: boolean;
     /** Seat facts already validated by admitPublicRole. */
     readonly admittedFields?: Extra;
     /** Seat facts that exist only after placement. Written before the admitted page. */
@@ -1987,14 +1786,14 @@ async function admitStandardMaterialInvocation<
   },
 ): Promise<AdmittedRoleInvocationBase & { readonly role: R } & Extra> {
   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 }),
@@ -2007,7 +1806,8 @@ async function admitStandardMaterialInvocation<
       ? {}
       : { 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 ?? ({} as Extra)),
@@ -2050,7 +1850,8 @@ type InstructionTransportSource = {
   readonly role?: string;
   readonly instruction: string;
   readonly instructionEmpty: boolean;
-  readonly attachments: readonly { readonly frozenPath: string }[];
+  readonly attachments: readonly { readonly path: string }[];
+  readonly requestManifestPath?: string;
   readonly baseRevision?: string;
   readonly lens?: ReviewerLens;
   readonly authorityRefs?: readonly string[];
@@ -2069,7 +1870,7 @@ function admittedTransportPromptKind(
 /**
  * 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(
@@ -2087,7 +1888,9 @@ export function buildInstructionTransportPrompt(
       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 lines.join("\n");
@@ -2105,17 +1908,25 @@ export function buildInstructionTransportPrompt(
       lens: admitted.lens,
       authorityRefs: admitted.authorityRefs,
     })];
-    if (!admitted.instructionEmpty && admitted.instruction.trim() !== "") {
+    if (admitted.instruction.length > 0) {
       lines.push("", admitted.instruction);
     }
     return lines.join("\n");
   }
-  const lines: string[] = [admitted.instructionEmpty ? "" : admitted.instruction];
-  if (admitted.attachments.length > 0) {
+  // #1165 J3: assemble from the admitted instruction bytes themselves.
+  const lines: string[] = [admitted.instruction];
+  // #1164/#1165: each caller path keeps its file-flag provenance.
+  const flaggedPaths: string[] = [
+    ...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 lines.join("\n");
@@ -2143,7 +1954,7 @@ export type AdmitCountersignInvocationOptions = {
 export async function materializeCountersignInvocation(
   admitted: AdmittedCountersignInvocation,
   options: Pick<AdmitCountersignInvocationOptions, "home" | "principalAuthority" | "model"> & {
-    preparedAttachments: readonly PreparedAttachment[];
+    attachmentPaths: readonly string[];
     /** Typed ticket known before the deferred run is written. */
     ticketNumber?: number;
   },
@@ -2153,8 +1964,7 @@ export async function materializeCountersignInvocation(
     home: options.home,
     principalAuthority: options.principalAuthority,
     cwd: admitted.projectRoot,
-    attachmentPaths: [],
-    freezeAttachments: false,
+    attachmentPaths: options.attachmentPaths,
     runId: admitted.runId,
     ...(options.ticketNumber === undefined ? {} : { assertedTicketNumber: options.ticketNumber }),
   });
@@ -2165,11 +1975,7 @@ export async function materializeCountersignInvocation(
   if (ticketFields.ticketNumber !== undefined) {
     (admitted as { ticketNumber?: number }).ticketNumber = ticketFields.ticketNumber;
   }
-  const attachments = await freezePreparedAttachmentsIntoRun(
-    options.preparedAttachments,
-    admitted.runDirectory,
-  );
-  (admitted as { attachments: readonly FrozenAttachment[] }).attachments = attachments;
+  (admitted as { attachments: readonly FrozenAttachment[] }).attachments = placement.attachments;
   writeAdmittedRequestPersistence(admitted.runDirectory, admitted, {
     sessionDirectory: placement.sessionDirectory,
     sessionFile: placement.sessionFile,
@@ -2196,10 +2002,13 @@ export async function loadAdmittedJudgeRequest(
     if (typeof record.instruction !== "string") return undefined;
     if (typeof record.instructionEmpty !== "boolean") return undefined;
     if (!Array.isArray(record.attachments)) return undefined;
+    const attachments = record.attachments
+      .map((item) => normalizeAdmittedAttachment(item))
+      .filter((item): item is FrozenAttachment => item !== undefined);
     return {
       instruction: record.instruction,
       instructionEmpty: record.instructionEmpty,
-      attachments: record.attachments as FrozenAttachment[],
+      attachments,
     };
   } catch {
     return undefined;
@@ -2596,7 +2405,7 @@ export function parseAnalystArgv(args: readonly string[]): ParseAnalystArgvResul
       if (taken.def.id === "attach") {
         pushValue(
           "attach",
-          requireOptionPath(taken.def.canonical, taken.value),
+          requireProvidedOptionValue(taken.def.canonical, taken.value),
         );
         return;
       }

package/src/public-cli/option-definitions.ts

@@ -344,7 +344,7 @@ const SHARED_PROJECT_SEMANTICS = {
 } as const satisfies Omit<PublicOptionDefinition, "owner">;
 
 /**
- * Immutable shared semantics for the common frozen-file `--attach` face.
+ * Immutable shared semantics for the common `--attach` face (#1165).
  * Role rows bind owner only. Reviewer has no attach face; analyst sweep attach
  * keeps its own modes/selectsMode/description and must not use this binding.
  */
@@ -357,8 +357,8 @@ const SHARED_ATTACH_SEMANTICS = {
   repeatable: true,
   form: "option" as const,
   description: {
-    en: "Attach a regular file; frozen at admission (repeatable).",
-    zh: "附加普通文件；受理即冻结（可重复）。",
+    en: "Caller file path passed as-is to the role (repeatable). Package does not read, copy, or validate; use an absolute path when cwd differs from --project.",
+    zh: "调用方文件路径原样递给衙门（可重复）。包不读、不复制、不校验；调用方当前目录与 --project 不同时请给绝对路径。",
   },
 } as const satisfies Omit<PublicOptionDefinition, "owner">;
 
@@ -556,8 +556,8 @@ const COLLECTOR_OPTIONS = [
     repeatable: false,
     form: "option",
     description: {
-      en: "Optional request manifest JSON path ({requests:[{id,body}]}). Parsed for semantics and passed to the Collector as materials — not a machine collection directive.",
-      zh: "可选 request manifest JSON 路径（{requests:[{id,body}]}）。按语义解析后作为材料递给通进司，不是机器代收 finding 的指令。",
+      en: "Caller path to a request manifest JSON file, passed as-is. Package does not read, copy, or validate; use an absolute path when cwd differs from --project.",
+      zh: "调用方 request manifest JSON 路径，原样传递。包不读、不复制、不校验；调用方当前目录与 --project 不同时请给绝对路径。",
     },
   },
 ] as const satisfies readonly PublicOptionDefinition[];