flowviant 0.111.0 → 0.113.0

package/bin/lib/agentCards.mjs

@@ -38,6 +38,7 @@
 
 import { appendFileSync, readFileSync } from 'node:fs';
 import { CARD_THREAD_RENDER_MAX } from './cardThread.mjs';
+import { CARD_FILES_RENDER_MAX } from './agentFiles.mjs';
 
 /**
  * How many card specs one agent may accumulate.
@@ -56,8 +57,11 @@ export const MAX_STASHED_CARDS = 40;
  *  the card's discussion, so the bound grows by the most a turn's discussion
  *  can render to (`CARD_THREAD_RENDER_MAX`). The discussion is printed LAST,
  *  and a stash that cut it would hand the pre-review a thread missing its
- *  newest words — the ones the agent read most recently. */
-export const MAX_SPEC_CHARS = 8_000 + CARD_THREAD_RENDER_MAX;
+ *  newest words — the ones the agent read most recently. Since 0.112.0 the
+ *  files on that discussion follow it (`CARD_FILES_RENDER_MAX`), and a cut
+ *  there would hand the pre-review a card missing the screenshot its agent
+ *  was shown. */
+export const MAX_SPEC_CHARS = 8_000 + CARD_THREAD_RENDER_MAX + CARD_FILES_RENDER_MAX;
 
 /**
  * Write down the spec this turn is about to hand the agent.

package/bin/lib/agentFiles.mjs

@@ -0,0 +1,68 @@
+/**
+ * A TURN'S FILES, AS THE WIRE HANDS THEM OVER (0.112.0) — the owner,
+ * 2026-09-28: "im unable to paste pictures or add files for the conversations
+ * in working or stuck or review".
+ *
+ * The server hands an agent turn its files on `agentTurnJobs[].attachments`:
+ * `{ id, name, size, from }`, where `from` is `message` (attached to THIS
+ * turn's words — an answer, a send-back) or `card` (attached to notes on the
+ * card the turn is about). Absent is none; the server sends the key only to a
+ * daemon at `DAEMON_AGENT_FILES_MIN` and parks the turn below it, which is why
+ * this release reads it.
+ *
+ * THE WIRE IS NOT TRUSTED, the card thread's rule (cardThread.mjs): the server
+ * capped each origin (`AGENT_FILES_PER_MESSAGE_MAX`, `CARD_FILES_PER_TURN_MAX`
+ * in the app's fieldCaps.ts) and this module applies the SAME numbers again —
+ * copies the release gate holds to the server's (`scripts/check-app-parity.mjs`,
+ * rule 10), because a tighter copy would silently drop a file the person
+ * watched go out. An entry with no id, or from an origin this daemon cannot
+ * place in a prompt, is dropped alone; one file named twice (an answer's
+ * screenshot that is also on the card's thread) is kept once, where it came
+ * first — the person's own message.
+ *
+ * Pure data and pure functions, like cardThread.mjs: prompts imports it.
+ */
+
+/** The server's `AGENT_FILES_PER_MESSAGE_MAX` — one message's files. */
+export const AGENT_FILES_PER_MESSAGE_MAX = 4;
+/** The server's `CARD_FILES_PER_TURN_MAX` — the card's newest files, per turn. */
+export const CARD_FILES_PER_TURN_MAX = 8;
+
+/**
+ * THE LONGEST LINE ONE FILE ADDS TO A PROMPT. A landed file is
+ * `.flowviant/uploads/<name>` with the name at most `SAFE_NAME_MAX` (80) plus
+ * a collision's `-<id6>`; a missed one is its safe name. The renderer cuts at
+ * this regardless, so the bound below holds by construction, not by trust.
+ */
+export const AGENT_FILE_LINE_MAX = 160;
+
+/**
+ * THE MOST THE CARD'S FILES CAN ADD TO A CARD SPEC, rendered — so the spec
+ * stash (agentCards.mjs `MAX_SPEC_CHARS`) holds the note whole beside the
+ * discussion, and the pre-review is handed the files the agent was. A header
+ * line and its blank line, then one line per file. `agentFiles.test.mjs`
+ * renders the worst case against it.
+ */
+export const CARD_FILES_RENDER_MAX = 200 + CARD_FILES_PER_TURN_MAX * (AGENT_FILE_LINE_MAX + 1);
+
+/**
+ * The files off the wire, message files first then the card's, each origin at
+ * its cap, as `{ id, name, size, from }`. Never throws; anything that is not a
+ * list is none.
+ */
+export function readAgentFiles(raw) {
+  if (!Array.isArray(raw)) return [];
+  const seen = new Set();
+  const pick = (from, max) => {
+    const out = [];
+    for (const a of raw) {
+      if (out.length >= max) break;
+      if (!a || typeof a !== 'object' || a.from !== from) continue;
+      if (typeof a.id !== 'string' || !a.id || seen.has(a.id)) continue;
+      seen.add(a.id);
+      out.push({ id: a.id, name: typeof a.name === 'string' ? a.name : '', size: a.size, from });
+    }
+    return out;
+  };
+  return [...pick('message', AGENT_FILES_PER_MESSAGE_MAX), ...pick('card', CARD_FILES_PER_TURN_MAX)];
+}

package/bin/lib/prompts.mjs

@@ -23,6 +23,7 @@ import { AGENT_TASK_TYPES, agentTaskTypeFor, agentTaskTypeOf } from './agentTask
 import { ARTIFACT_CONTRACT_TAIL, SYSTEM_AGENT_DECK, SYSTEM_AGENT_MODEL } from './artifactContracts.mjs';
 import { isLibraryReference } from './knowledgeLibrary.mjs';
 import { readCardThread } from './cardThread.mjs';
+import { AGENT_FILE_LINE_MAX, AGENT_FILES_PER_MESSAGE_MAX, CARD_FILES_PER_TURN_MAX } from './agentFiles.mjs';
 
 // Wiki-gen turn: the local Claude READS the repo (cwd) and writes/maintains the
 // knowledge VAULT — a plain directory of markdown files with [[wikilinks]]
@@ -1093,18 +1094,19 @@ export const AGENT_HANDS_BACK = Object.freeze({
  * files cards in this project, and this turn is about to edit code. The
  * instruction is ours and sits outside the fence. The card's DISCUSSION
  * (`cardThread`, 0.106.0) is printed inside the same fence, as part of the
- * spec (`AGENT_TASK_SPEC`), so the spec stashed for the pre-review carries it.
+ * spec (`AGENT_TASK_SPEC`), so the spec stashed for the pre-review carries it
+ * — and the files on that discussion (`cardFiles`, 0.112.0) with it.
  *
  * The queue POSITION is stated because it changes behaviour: an agent that
  * thinks it is finishing tidies up, writes summaries and stops; one that knows
  * three more cards are coming leaves the ground ready for them.
  */
-export const AGENT_TASK_KICKOFF = ({ agentName, task, cardThread, position, total }) =>
+export const AGENT_TASK_KICKOFF = ({ agentName, task, cardThread, cardFiles, position, total }) =>
   agentTaskKindOf(task?.taskKind) === 'code'
     ? `You are the agent "${safeName(agentName)}", working card ${position} of ${total} ` +
       `on this branch. Everything you commit here is reviewed and merged TOGETHER with ` +
       `the other cards in this run.\n\n` +
-      `${fence('THE CARD', taskBlock(task, cardThread))}\n\n` +
+      `${fence('THE CARD', taskBlock(task, cardThread, cardFiles))}\n\n` +
       `When you commit, put this trailer on the LAST line of each commit message so ` +
       `the card can find its own commits:\n` +
       `Flowviant-Task: ${task?.id ?? ''}\n\n` +
@@ -1116,7 +1118,7 @@ export const AGENT_TASK_KICKOFF = ({ agentName, task, cardThread, position, tota
       `You are the agent "${safeName(agentName)}", working card ${position} of ${total} ` +
       `in this run. This card is ${AGENT_HANDS_BACK[agentTaskKindOf(task?.taskKind)]}, ` +
       `written under .flowviant/artifacts/, and changes nothing in the repository.\n\n` +
-      `${fence('THE CARD', taskBlock(task, cardThread))}\n\n` +
+      `${fence('THE CARD', taskBlock(task, cardThread, cardFiles))}\n\n` +
       `Do it, and end with the JSON object.`;
 
 /**
@@ -1144,7 +1146,7 @@ const safeName = (n) =>
  * renderings of a card that can drift — and the drift would be invisible,
  * because nobody reads both prompts side by side.
  */
-export const AGENT_TASK_SPEC = (task, cardThread) =>
+export const AGENT_TASK_SPEC = (task, cardThread, cardFiles) =>
   `id: ${task?.id ?? ''}\n` +
   `title: ${task?.title ?? ''}\n` +
   // THE KIND, when it is news (0.97.0). A code card's spec stays byte-for-byte
@@ -1174,8 +1176,12 @@ export const AGENT_TASK_SPEC = (task, cardThread) =>
   // LAST, after everything the card asks. Printed only when it names THIS
   // card and holds something, so every spec without a discussion — every
   // stash and every prompt before 0.106.0 — is byte-for-byte what it was.
+  // …and THE FILES ON IT (0.112.0) right after it, under the same rule: the
+  // server sends a card's files with that card's thread, so a thread naming
+  // another card names nothing here, and no files is no line.
   (cardThread && task?.id && String(cardThread.taskId ?? '') === String(task.id)
-    ? prefixed('\n', cardThreadText(readCardThread(cardThread, 'turn')))
+    ? prefixed('\n', cardThreadText(readCardThread(cardThread, 'turn'))) +
+      prefixed('\n', cardFilesText(cardFiles))
     : '');
 
 /** A card's type as the spec prints it, or ''. */
@@ -1211,6 +1217,40 @@ const cardThreadText = (thread, indent = '') => {
 /** `head` before `text`, or '' when there is no text. */
 const prefixed = (head, text) => (text ? `${head}${text}` : '');
 
+/**
+ * A TURN'S FILES AS TEXT (0.112.0) — the Terminal's note, in the Terminal's
+ * shape (workSessionTurns.mjs): a bracketed header saying they are already on
+ * disk, then one relative path per line, so "see the screenshot" is a file
+ * the agent can open. A file that did not arrive is named and given no path
+ * (workAttachments.mjs `fetchAgentFiles` says why it is named at all). ''
+ * when there is nothing, which is what keeps every prompt without files
+ * byte-for-byte what it was. Each origin is cut at the server's cap again
+ * and each line at `AGENT_FILE_LINE_MAX`, so what this adds is bounded here.
+ */
+const filesText = (head, files, max) => {
+  const lines = (Array.isArray(files) ? files : [])
+    .slice(0, max)
+    .map((f) =>
+      typeof f?.path === 'string' && f.path
+        ? oneLine(`- ${f.path}`, AGENT_FILE_LINE_MAX)
+        : typeof f?.missed === 'string' && f.missed
+          ? oneLine(`- could not be fetched: ${f.missed}`, AGENT_FILE_LINE_MAX)
+          : ''
+    )
+    .filter(Boolean);
+  return lines.length ? `[${head}]\n${lines.join('\n')}` : '';
+};
+/** The files a person attached to THIS message — the Terminal's header, with
+ *  "person" for "human" as everywhere else an agent is addressed. */
+const messageFilesText = (files) =>
+  filesText('FILES THE PERSON ATTACHED TO THIS MESSAGE — already on disk in this worktree', files, AGENT_FILES_PER_MESSAGE_MAX);
+/** The files on the card's notes, printed with the card's discussion; ends in
+ *  a newline like every other section of a spec. */
+const cardFilesText = (files) => {
+  const text = filesText("FILES ON THIS CARD'S DISCUSSION — already on disk in this worktree", files, CARD_FILES_PER_TURN_MAX);
+  return text ? `${text}\n` : '';
+};
+
 /** A reference as the server sends it: a library path and its title. Anything
  *  else is not printed — this text is fenced as card content, but a path that
  *  is not a path is not worth handing an agent.
@@ -1240,24 +1280,48 @@ const taskBlock = AGENT_TASK_SPEC;
  * fence of its own, naming the card (a message often carries no `task` to name
  * it by). Never inside THE CARD YOU ARE ON: that block is the spec, as it
  * always was. Absent, nothing is printed, and the prompt is what it was.
+ *
+ * THE TURN'S FILES (0.112.0), each where its origin says: `messageFiles` (the
+ * person attached them to these words) inside WHAT THEY SAID, `cardFiles` (on
+ * the card's notes) at the foot of THE CARD'S DISCUSSION. None, and the prompt
+ * is byte-for-byte what it was.
  */
-export const AGENT_HUMAN_KICKOFF = ({ agentName, message, askedByName, task, cardThread, position, total }) =>
+export const AGENT_HUMAN_KICKOFF = ({ agentName, message, askedByName, task, cardThread, messageFiles, cardFiles, position, total }) =>
   `You are the agent "${safeName(agentName)}"` +
   (task ? `, working card ${position} of ${total} on this branch` : '') +
   `.\n\n` +
   `${fence('WHO IS TALKING', askedByName || 'a member of this project')}\n\n` +
-  `${fence('WHAT THEY SAID', message)}\n\n` +
+  `${fence('WHAT THEY SAID', withMessageFiles(message, messageFiles))}\n\n` +
   (task ? `${fence('THE CARD YOU ARE ON', taskBlock(task))}\n\n` : '') +
-  cardDiscussionBlock(cardThread) +
+  cardDiscussionBlock(cardThread, cardFiles) +
   `Carry on, and end with the JSON object as usual.`;
 
+/**
+ * THE PERSON'S FILES GO WITH THEIR WORDS (0.112.0), after them and inside
+ * WHAT THEY SAID — the Terminal's placement exactly (its note joins the
+ * message before the kickoff fences it). "Like this" and the path to "this"
+ * are one message, read together; a sibling block after the fence would make
+ * the agent join them back up. Inside the fence costs nothing: the lines are
+ * facts about their message, never an instruction of ours, and a person who
+ * types a forged "[FILES …]" line names a path they could already have typed.
+ * No files, and the message is handed through untouched.
+ */
+const withMessageFiles = (message, files) => {
+  const note = messageFilesText(files);
+  return note ? [message, note].filter(Boolean).join('\n\n') : message;
+};
+
 /** A human turn's card discussion, fenced, naming the card — '' when there is
- *  none to print. */
-const cardDiscussionBlock = (cardThread) => {
+ *  none to print. The card's files (0.112.0) close it, after the discussion
+ *  they were attached in; a card with files and no readable thread still gets
+ *  the block, since the files alone are worth naming — but only where the
+ *  thread names a card to hang them on. */
+const cardDiscussionBlock = (cardThread, cardFiles) => {
   const text = cardThreadText(readCardThread(cardThread, 'turn'));
-  if (!text) return '';
+  const files = cardThread?.taskId ? cardFilesText(cardFiles) : '';
+  if (!text && !files) return '';
   const head = `card: ${oneLine(cardThread.taskId, 64)}\ntitle: ${oneLine(cardThread.title, 300)}\n\n`;
-  return `${fence("THE CARD'S DISCUSSION", `${head}${text}`)}\n\n`;
+  return `${fence("THE CARD'S DISCUSSION", `${head}${text}${prefixed(text ? '\n' : '', files)}`)}\n\n`;
 };
 
 /**

package/bin/lib/work.mjs

@@ -36,7 +36,7 @@
  *   workReportQueue.mjs    every settle, held and retried until delivered
  *   workSessionTokens.mjs  the per-session work credential
  *   workNarration.mjs      the tab's live line and the deferral sentence
- *   workAttachments.mjs    files the human attached, brought to disk
+ *   workAttachments.mjs    files the human attached, brought to disk (tabs and agents)
  *   workSessionRuntime.mjs which CLI a tab speaks, which conversation resumes
  *   workAdoptCarry.mjs     adoption's dirty carry
  *   workSessionTurns.mjs   a tab's turn, start to settle
@@ -229,7 +229,7 @@ export function createWorkManager({
   });
   const { workTokens, mintWorkToken } = createWorkSessionTokens({ getLeaseTtl });
   const { makeNarrator, sayTurnDeferred, lastDeferSaid } = createWorkNarration();
-  const { fetchAttachments } = createWorkAttachments();
+  const { fetchAttachments, fetchAgentFiles } = createWorkAttachments();
   const { sessionRuntime, agyRegistryLookup } = createWorkSessionRuntime({ sessionMetaPath });
   const { carryDirtyState } = createAdoptCarry({ sessionMetaPath });
   const { processWorkTurns, workAnswering } = createWorkSessionTurns({
@@ -359,6 +359,7 @@ export function createWorkManager({
     workChildren,
     agentPublished,
     agentRemoteAt,
+    fetchAgentFiles,
   });
 
   const { processAgentMergeJobs, agentMerges } = createWorkAgentMerges({

package/bin/lib/workAgentTurnExecution.mjs

@@ -56,6 +56,7 @@ export function createAgentTurnExecution({
   postAgentTrace,
   postAgentActivity,
   postAgentParked,
+  fetchAgentFiles,
 }) {
   /** How long the final flush may hold the settle. Bounded because the settle
    *  is the turn's contract and the trace is a readout: a wedged uplink costs
@@ -266,6 +267,23 @@ export function createAgentTurnExecution({
         ? Boolean(codexResumeId)
         : rt === 'claude' && Boolean(ranMarker && existsSync(ranMarker));
 
+    /**
+     * THE TURN'S FILES, ON DISK BEFORE THE PROMPT NAMES THEM (0.112.0) — the
+     * Terminal's order: the agent must be able to open what it is told about.
+     * Into this worktree's `.flowviant/uploads/`, which the common exclude
+     * already hides from git, so a screenshot is never committed by the
+     * agent's `git add -A`. After the kind's refusals (a turn refused runs
+     * nothing and needs no files) and before the stash, which names the
+     * card's files beside its discussion so the pre-review — a fresh reader
+     * standing in this same worktree — is pointed at what the agent was.
+     * No key is no call: a turn without files touches nothing here, and its
+     * prompt is byte-for-byte what it was.
+     */
+    const files =
+      Array.isArray(job.attachments) && job.attachments.length > 0
+        ? await fetchAgentFiles(wt, job.attachments)
+        : { message: [], card: [] };
+
     /**
      * WRITE THE CARD DOWN BEFORE HANDING IT OVER — the material the AI
      * pre-review reads at review entry (see agentCards.mjs).
@@ -284,7 +302,8 @@ export function createAgentTurnExecution({
      * ONE SPEC BUILDER (`AGENT_TASK_SPEC`) shared with the kickoff below, so
      * what the reviewer reads is byte-identical to what the agent read — the
      * card's discussion included (0.106.0): both are handed the same
-     * `job.cardThread`, and the builder prints it inside the spec.
+     * `job.cardThread`, and the builder prints it inside the spec — and the
+     * card's files after it (0.112.0), fetched just above.
      * Failure is swallowed inside `stashCard`: a note about a turn may never
      * cost the turn.
      */
@@ -292,7 +311,7 @@ export function createAgentTurnExecution({
       stashCard(
         sessionMetaPath(wt, 'flowviant-agent-cards', agentId),
         job.task.id,
-        AGENT_TASK_SPEC(job.task, job.cardThread)
+        AGENT_TASK_SPEC(job.task, job.cardThread, files.card)
       );
     }
 
@@ -375,8 +394,10 @@ export function createAgentTurnExecution({
                 agentName: job.agentName,
                 task: job.task,
                 // The card's discussion (0.106.0), printed inside THE CARD by
-                // the same builder the stash above wrote down.
+                // the same builder the stash above wrote down — and the files
+                // on it (0.112.0), after it, the same way.
                 cardThread: job.cardThread,
+                cardFiles: files.card,
                 position: job.position ?? 1,
                 total: job.total ?? 1,
               })
@@ -388,6 +409,10 @@ export function createAgentTurnExecution({
                 // The discussion on the one card this message is about, in a
                 // fence of its own after the person's words (0.106.0).
                 cardThread: job.cardThread,
+                // The files (0.112.0): the person's inside their words, the
+                // card's at the foot of its discussion.
+                messageFiles: files.message,
+                cardFiles: files.card,
                 position: job.position ?? 1,
                 total: job.total ?? 1,
               }),

package/bin/lib/workAgentTurns.mjs

@@ -46,6 +46,8 @@ export function createWorkAgentTurns({
   workChildren,
   agentPublished,
   agentRemoteAt,
+  /** The turn's files, fetched into its worktree (workAttachments.mjs, 0.112.0). */
+  fetchAgentFiles,
 }) {
   const {
     postAgentTurn,
@@ -108,6 +110,7 @@ export function createWorkAgentTurns({
     postAgentTrace,
     postAgentActivity,
     postAgentParked,
+    fetchAgentFiles,
   });
 
   /** `releaseSlot` hands back the admission reservation the caller took on this

package/bin/lib/workAttachments.mjs

@@ -3,19 +3,42 @@
  *
  * Split out of work.mjs (2026-09-26, SOLID F037). One trust boundary — a
  * server-sent name becoming a path on somebody's machine — with its caps, its
- * collision rule and its git exclude, reached only from the session lane.
+ * collision rule and its git exclude, reached from the session lane
+ * (`fetchAttachments`) and, since 0.112.0, the agent lane (`fetchAgentFiles`:
+ * the files on an answer, a send-back or the card's notes). ONE download loop
+ * serves both, so the two lanes cannot disagree about what a safe name is.
  * The name rule itself is safeFileName.mjs's.
  */
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { FLEET_URL, FLEET_TOKEN, USER_AGENT } from './config.mjs';
 import { excludeInWorktree } from './git.mjs';
 import { FLOWVIANT_OWN_PATHS } from './knowledgeLibrary.mjs';
 import { safeFileName } from './safeFileName.mjs';
 import { fleetEndpoint } from './fleetWire.mjs';
+import { readAgentFiles } from './agentFiles.mjs';
+
+/**
+ * ONE FILE'S CEILING, for both lanes (0.113.0, the owner 2026-09-29: "20 MB
+ * for every file"). The server's `ATTACHMENT_MAX_BYTES` (the app's
+ * fieldCaps.ts), held equal by the release gate (`scripts/check-app-parity.mjs`,
+ * rule 11): a tighter copy here skips a file the person watched go out — which
+ * is what 0.112.0's 10 MB did to anything bigger, and why the server floors a
+ * file over 10 MB at this release (`DAEMON_LARGE_FILES_MIN`).
+ */
+export const ATTACHMENT_MAX_BYTES = 20 * 1024 * 1024;
 
 export function createWorkAttachments() {
-  const ATTACHMENT_URL = fleetEndpoint('attachment', FLEET_URL);
+  /**
+   * WHERE THE BYTES COME FROM, by lane: the Terminal's `/fleet/attachment/:id`
+   * (a session's uploads) and the agent lane's `/fleet/agent-file/:id` (a
+   * card conversation's, 0.112.0). Same shape — the machine credential, the
+   * bytes streamed, 404/410 when gone — and a different store behind each.
+   */
+  const FILE_URL = {
+    attachment: fleetEndpoint('attachment', FLEET_URL),
+    'agent-file': fleetEndpoint('agent-file', FLEET_URL),
+  };
   /**
    * FILES THE HUMAN ATTACHED, brought to where a CLI can read them.
    *
@@ -30,21 +53,38 @@ export function createWorkAttachments() {
    * doing that check is one deploy away from being zero places.
    */
   const UPLOAD_DIR = '.flowviant/uploads';
-  const ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024;
   // `safeFileName` (bin/lib/safeFileName.mjs — the server's rule, one daemon
   // home): THE EXTENSION SURVIVES A CUT, and it is idempotent over its own
   // output, so re-applying it to what the server already sanitized is a no-op
   // and the two sides never disagree about the cut. An empty name is
   // `attachment`, the server's own fallback.
   const safeUploadName = (raw) => safeFileName(raw, 'attachment');
-  /** @returns relative paths written, in the order the human attached them. */
-  const fetchAttachments = async (wt, attachments) => {
-    if (!Array.isArray(attachments) || attachments.length === 0) return [];
+  /** The file at `path` holds exactly `buf` — read only when the sizes agree. */
+  const holds = (path, buf) => {
+    try {
+      return statSync(path).size === buf.byteLength && readFileSync(path).equals(buf);
+    } catch {
+      return false;
+    }
+  };
+  /**
+   * THE ONE DOWNLOAD LOOP. Each entry's relative path, or null where it did
+   * not land — aligned with `list`, so a caller can say which file is missing.
+   * `endpoint` names the route (`FILE_URL`). `sameBytesKept` is the agent
+   * lane's: a turn about a card is handed the card's files EVERY turn, into
+   * one long-lived worktree, and without it the second turn's copy of
+   * `mock.png` collided with the first's and was renamed `mock-<id6>.png` — one
+   * file under two names, the prompt naming a different one each turn. A name
+   * already holding these exact bytes IS this file. The Terminal's loop never
+   * asks it: a tab's message carries its files once, and its answer stays
+   * what it was.
+   */
+  const landFiles = async (wt, list, endpoint, sameBytesKept) => {
     const dir = join(wt, UPLOAD_DIR);
     try {
       mkdirSync(dir, { recursive: true });
     } catch {
-      return [];
+      return list.map(() => null);
     }
     // "Never committed by us" has to be true for GIT, not just for this code:
     // an untracked `.flowviant/` makes the whole worktree dirty, which refuses
@@ -58,12 +98,13 @@ export function createWorkAttachments() {
     // whole-directory line also hid a repo's own new `.flowviant/check.json`
     // from its agent's `git add -A`.
     excludeInWorktree(wt, FLOWVIANT_OWN_PATHS);
-    const written = [];
-    for (const a of attachments.slice(0, 8)) {
+    const landed = [];
+    for (const a of list) {
+      landed.push(null);
       if (!a?.id || typeof a.id !== 'string' || !/^[0-9a-f-]{8,64}$/i.test(a.id)) continue;
       if (Number(a.size) > ATTACHMENT_MAX_BYTES) continue;
       try {
-        const res = await fetch(`${ATTACHMENT_URL}/${a.id}`, {
+        const res = await fetch(`${FILE_URL[endpoint]}/${a.id}`, {
           headers: { Authorization: `Bearer ${FLEET_TOKEN}`, 'User-Agent': USER_AGENT },
           signal: AbortSignal.timeout(60_000),
         });
@@ -73,21 +114,54 @@ export function createWorkAttachments() {
         // Collisions are real (two screenshots both named Screenshot.png), and
         // silently overwriting one with the other loses a file the human sent.
         let name = safeUploadName(a.name);
-        if (existsSync(join(dir, name))) {
+        let already = sameBytesKept && holds(join(dir, name), buf);
+        if (!already && existsSync(join(dir, name))) {
           const dot = name.lastIndexOf('.');
           const stem = dot > 0 ? name.slice(0, dot) : name;
           const ext = dot > 0 ? name.slice(dot) : '';
           name = `${stem}-${String(a.id).slice(0, 6)}${ext}`;
+          already = sameBytesKept && holds(join(dir, name), buf);
         }
-        writeFileSync(join(dir, name), buf);
-        written.push(`${UPLOAD_DIR}/${name}`);
+        if (!already) writeFileSync(join(dir, name), buf);
+        landed[landed.length - 1] = `${UPLOAD_DIR}/${name}`;
       } catch {
         /* one file failing must not fail the turn — the prompt lists what
            actually arrived, so the agent never chases a path that isn't there */
       }
     }
-    return written;
+    return landed;
+  };
+
+  /** @returns relative paths written, in the order the human attached them. */
+  const fetchAttachments = async (wt, attachments) => {
+    if (!Array.isArray(attachments) || attachments.length === 0) return [];
+    return (await landFiles(wt, attachments.slice(0, 8), 'attachment', false)).filter(Boolean);
+  };
+
+  /**
+   * AN AGENT TURN'S FILES (0.112.0), read off the wire (agentFiles.mjs: each
+   * origin at the server's cap, message files first) and fetched from
+   * `/fleet/agent-file/:id` into the agent's own worktree.
+   *
+   * Split by where the prompt prints them, and each entry says whether it
+   * LANDED: `{ path }` for a file on disk, `{ missed: name }` for one that did
+   * not arrive. Unlike the Terminal, which lists only what arrived, a miss is
+   * NAMED: a tab's person is watching the reply and re-attaches; a person who
+   * answered a parked agent "like this" with a screenshot is not, and an agent
+   * told nothing reads "like this" with no referent and guesses. Told the file
+   * could not be fetched, it can say so in its answer. Never a path for a
+   * miss, so it still never chases one.
+   *
+   * @returns {Promise<{ message: Array<{path: string}|{missed: string}>, card: Array<{path: string}|{missed: string}> }>}
+   */
+  const fetchAgentFiles = async (wt, attachments) => {
+    const out = { message: [], card: [] };
+    const list = readAgentFiles(attachments);
+    if (list.length === 0) return out;
+    const landed = await landFiles(wt, list, 'agent-file', true);
+    list.forEach((a, i) => out[a.from].push(landed[i] ? { path: landed[i] } : { missed: safeUploadName(a.name) }));
+    return out;
   };
 
-  return { fetchAttachments };
+  return { fetchAttachments, fetchAgentFiles };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowviant",
-  "version": "0.111.0",
+  "version": "0.113.0",
   "description": "Run your own coding CLIs as build agents for Flowviant — Claude Code, Codex or Antigravity, on your own credentials. Holds your sessions, keeps a worktree per tab, and ships branches on your word.",
   "type": "module",
   "bin": {