fix(links): resolve ambiguous hard wraps through guarded lookup

.changeset/Repair-FilePathLinks.md

@@ -2,4 +2,4 @@
 'aicodeman': patch
 ---
 
-Keep parenthesised filenames with spaces clickable as one complete file path, including `.conf` configuration files. Preserve the filename's space and clickable row positions when a CLI wraps the path onto another line, instead of opening a truncated folder name. The same detector serves the terminal and Response Viewer, with the existing path guards retained.
+Keep parenthesised filenames with spaces clickable as one complete file path, including `.conf` configuration files. For an ambiguous hard wrap, check the original concatenated filename through the existing guarded attachment route when clicked, and try the spaced filename only after a not-found response. Existing filenames take priority, and permission or connection failures stop resolution. Preserve clickable row positions and share the spaced-path detector between the terminal and Response Viewer.

BUGS.md

@@ -1 +0,0 @@
-Bug tracker: [Codeman issues](https://github.com/Ark0N/Codeman/issues).

docs/architecture-invariants.md

@@ -413,6 +413,11 @@ A file path an agent prints is a link on both surfaces it can appear on, and cli
 
 Spaced paths are considered first by `findFilePathLinks()`: accepted candidates reserve their entire span even when unlinkable, so later detectors cannot link fragments. Relative and `~/` spaced paths require an explicit path label (`Path:`, `File:`, `Files:`, `Saved to:`, `Saved as:`, `Wrote:`, `Written to:`, `Output:`, `Created:`, `Location:`, `Attachment:`), optionally preceded by a marker. Generic labels and bare bullets defer to ordinary detection, including slash-containing prose such as `CI/CD` or `45/45`. A later `/`, `~/`, `./` or `../` word starts a separate path; an earlier word ending in `/` is a separate folder. Absolute paths keep the own-line and marker forms plus the same path labels; any other label (`Error:`, `Note:`, `Saved the report to:`) defers an absolute path too. A rooted candidate needs a directory before its first space, so `/review the changes in src/a.ts` is prose. An earlier word holding a known extension anywhere (`a.ts#L12 foo.ts`) ends the path at that word, a `:` followed by a digit inside an earlier word is a line suffix (`a.ts:42:See b.md`, grep and compiler output) and ends the path there, a run of spaces is a column gap rather than a name, and a leading run of `./` or `../` is not a segment (`Saved to: ../My Docs/plan.md` links whole; an interior `..` is still refused). An unlinkable candidate reserves its span only while its last word holds a `/`, so `/usr/bin/env node build.js` keeps its ordinary links while `/etc/secret files/passwords.txt` links nothing. A path label vouches that a path follows, not for the words before it: a relative candidate whose only `/` word is its last is prose after the label (`Wrote: 120 lines to src/foo.ts`, `Path: see src/foo.ts`) and defers to the ordinary detectors. The cost is a labelled relative path whose only space is in its top directory, `Saved to: My Docs/plan.md` (and `Saved to: 03 Attachments/plan.pptx`), which splits as on master; `03 Attachments/Build SIPOC Design/Build-SIPOC.pptx`, `notes/a b/c.md`, `~/`, `./` and `../` forms and absolute paths still link whole. An earlier word that is a lowercase connective or verb (`SPACED_PATH_PROSE_WORD`: `and`, `or`, `to`, `in`, `the`, `is`, `has`, `contains`, `then`, `as` and a few more) or a bare `=` makes the candidate a sentence, in every shape: `/home/me/proj contains a.md`, `- /tmp/out has the logs in run.log`, `Path: /home/me/proj/out contains a.md`, `Files: src/components and utils/x.ts`, `Wrote: 3 files to docs/design notes/overview.md`. The cost is a name that uses one of those words (`Pros and Cons.md`, `How to deploy.md`, `Documents and Settings`), which splits as on master; `at` (`Screenshot 2026-10-24 at 10.00.00.png`) and `of` (`Copy of report.docx`) are left out of the list on purpose. What remains ambiguous is an own-line absolute path followed by words that hold none of them (`/home/me/proj/out report.pdf` reads like `/home/me/docs/Read Me.txt`), which links as one path. A command line is refused too: a first word that is an executable under `bin/`, `.bin/`, `scripts/` or `tools/` (`/opt/homebrew/bin/node server.js`, `/home/me/proj/scripts/deploy prod.yml`) or any `-x`/`--x` flag word (`/home/me/proj/node_modules/.bin/tsc -p tsconfig.json`); a bare `-` (`Docs - Copy`, `OneDrive - Contoso`) is not a flag. So is a shell prompt that prints an absolute working directory (WSL's `/mnt/c/...` is outside `$HOME`, so every earlier command in a shell's scrollback has one): a first word ending in `$` (`/home/me/proj$ cat notes.md`) and any earlier word with no letter or digit other than a bare `-` (`/mnt/c/proj ❯ code notes.md`, `/home/me/proj $ cat notes.md`, `/home/me/proj/out ✓ report.pdf`) refuse the candidate, while `Program Files (x86)` and `Docs - Copy` still link whole. The response viewer carries any leading `<strong>` label in a paragraph or list item, or one starting a later line of a paragraph (after a `<br>`, since chat renders with `breaks: true`), into detection without changing the label or displayed text, and `spacedFilePathOnLine()` judges it as it judges the same line in the terminal (`**Note:** /home/me/proj/out report.pdf` splits). A text node that follows any other inline element starts mid-line, so a placeholder word stands in for what precedes it (``Use `--config` /home/me/proj/cfg data.json`` splits as in the terminal), while a path inside inline code still links whole; paths split across inline elements remain detected per text node. Tests feed vendored marked output into the jsdom linkifier, so consumed bullets and bold labels are covered. Trailing whitespace uses linear `trimEnd()` before the length cap.
 
+Parentheses also bound an inline spaced path, such as `Updated (/mnt/c/My Docs/report.conf)`. The whole candidate is reserved before fragment detectors run; existing root, prose and traversal guards still apply. A comma at the end of an earlier word marks a list, not one filename.
+
+Hard-wrapped filenames keep the existing concatenation without inserted spaces. A parenthesised final filename broken between words also carries a spaced alternative without changing its cell mapping. On activation only, the terminal checks the original path through the existing guarded attachment registration route (`notify: false`), tries the alternative only after HTTP 404, and retains the clicked session throughout. If both exist, the original wins. Permission, connection and server errors stop resolution; hover performs no lookup. Text alone cannot distinguish the two filenames, so this uses the filesystem result rather than a spacing guess.
+
+
 The terminal provider scans `terminalLinkLine()`, which extends `terminalPathLine()` for URL continuations in indented paragraphs and table cells. List markers, bare numbers and version tokens never continue a URL. A token with only hyphens, underscores or dots must end its cell (row end or a gap of at least two spaces), so prose such as `self-hosted runners` is not appended. A row end counts as a cell end, so `⏺ Docs live at https://example.com/guide/` followed by `  self-hosted` still links `.../guide/self-hosted`, and an indented `and/or the API reference covers it.` still links `.../guide/and/or`; both are pinned as known trade-offs. Such a token is still refused when it is code with a call paren (`client.get()`, `expect(x).toBe(y)`; a wiki title like `Mercury_(planet)` keeps its paren) or a word ending a sentence (`ready.`, `Done.`, `self-hosted.`; a file name keeps its period, so `install.html.` still joins). Whatever its punctuation, a token never continues a URL when it ends with a colon (a label such as `Failure/Error:` or `prometheus.io/scrape:`), when it is a measurement or clock time (`45%`, `45%|####`, `12.3MB/45.0MB`, `12.3ms`, `10:00:00`; percent-encoding such as `2026%20Plan` still joins), or when it is a `name=value` field (`API_KEY=...`, `level=info`) under a URL ending in `/`, since a query needs a `?` first (after `?`, `&` or `_` it is a query parameter and joins). A continuation must be indented (a column-0 row is new output, which keeps `status=200`, `24/7` and `really?` out), and a shell prompt (`user@host:`), a home path (`~/`), a whole email address or an HTTP status line never continues a URL. A URL in the last column of a space-aligned table never takes the next row's first cell: a continuation row must start inside the URL's own cell, so a gap of two or more spaces between its indent and where the URL starts on the row above means it is the next record. When other columns follow a wrapped URL on its first row (a codex table's path or date column), the URL is stitched without them, and they still link on that row: `terminalLinkLine()` scans them after the stitched rows as a segment of their own, mapped back to their cells. A URL in such a column is the row's last URL, and only the last URL on a row is continued, so that row is never stitched. A divider row never continues the row above it, so a URL that reaches the right edge does not absorb a full-width `────` row below. A real plain slug followed by prose falls back to the original fragment link; `%`, `&`, `=`, `/` or `?` still qualify as stronger URL punctuation. `terminalCellWrappedPaths()` follows each table cell independently: a fragment carries on into the next row only when it ends its cell on `/` or `-` (where a wrapper breaks a path; codex's cell wrap never breaks at `_`), the continuation row is blank to the left of the cell (a wrapper wraps every column of a table row together, so a label there such as `Entry` or `│ Log │` is the next record, unless a left column's path continued on that row too; a left column of wrapped prose, as in a `Description | Path` table, fills that row as well, so the path beside it keeps its per-row fragment links, the safe direction), the next row's token passes `pathContinuation()`, and the cell is no wider than the one above. So a directory that is a whole cell value (`/home/u/proj` over `config.yaml`, or `/home/u/proj/app/` over a labelled `main.py`) keeps its folder link and the next row keeps its own file link. With no label to tell them apart, a directory written with its trailing slash over a relative path in the same column (`/home/u/proj/src/` over `lib/util.ts`) still joins, a known trade-off: it reads exactly like a wrap at `/`. Accepted paths displace other links on their cells. Full-width divider rows stop `terminalLogicalLine()` stitching for both links and touch selection. OSC 8 links confirm the real target URI before the shared opener runs.
 
 **Folder grid: a folder is granted, then served by bare file name.** A folder path (rooted or `~/` whose last segment has no extension, relative only with a trailing `/`; `FOLDER_PATH_LINK_PATTERN` + `folderLinkPath()`) opens `openFolderGrid()` (panels-ui.js), as does the preview's "Show folder" button. `POST /api/sessions/:id/folders {path}` (`src/folder-listing.ts`) resolves the folder (locally a bounded `probePathKind(…, { pastCap: true })` first, then async `fs.realpath`; remotely one ssh round trip via `remoteListFolder`, through `runWithRemoteSshLimit`), runs the attachment guard on it (blocklist, `confineToWorkspace`, and in multi-user mode `folderAllowedForUser`: a non-admin only inside their own `userSpacePath` or the session's `workingDir`, as the filesystem path picker), locally BEFORE reading it, lists non-hidden subfolders and files of a supported attachment type (each file also blocklist-checked, newest first, capped at `MAX_FOLDER_ENTRIES`), and GRANTS it an id. Files are then fetched as `GET …/folders/:folderId/files/:name/(raw|preview|thumbnail)`: `:name` must be a bare file name of a supported type (no `/`, `\`, NUL, no leading `.`, since the listing hides those), the local file is probed bounded (`unknown` → 503, never 404), and the joined path goes through the SAME `resolveServableAttachmentPath` as an attachment by id (symlink re-resolution, remote re-probe, guard), then the same gate registration applies to what a symlink RESOLVES to (a supported extension on the resolved path and a regular file: locally `fs.stat`, remotely the probe kind; else 400, so `shot.png -> ../secret.bin` is not served and a FIFO or device behind a supported name never reaches `open`), then `folderAllowedForUser` once more on the resolved file, before `serveServableRaw` (the attachment raw route's body, shared) streams it. So browser requests still never carry a path. ⚠️ Grants live in their own registry (`folderGrants`, 32 per session, cleared with the session's attachments), NOT the attachment registry: that one is capped at 200 per session, and paging a folder of 300 renders would evict the session's real attachments. ⚠️ A local folder is never touched unbounded (#516 rule): a folder on a network mount that stopped answering answers 503 with `describeUnknownPath()`, not 404 and not a frozen server. ⚠️ The remote listing script tells "missing" (`E|n`, 404) from "is a file" (`E|f`, 400 `Not a folder`), because the client falls back to the file preview on `Not a folder`; a remote extensionless file otherwise answered "Folder not found". ⚠️ `.folder-grid-overlay` sits at `z-index: 5090`, one step BELOW the preview (5100) and above the response viewer (5000): a tile's preview opens on top and closing it lands back on the grid. ⚠️ ←/→/Esc are handled in a document CAPTURE listener with `stopPropagation`, because the terminal keeps keyboard focus under the overlays and an arrow that reached xterm would be typed into the session; inputs other than xterm's helper textarea keep their keys. ⚠️ A route PARAMETER is capped by the router (Fastify's default is 100 characters, answered as 404 "Route not found"), and a file name goes up to 255, percent-encoded: the server sets `routerOptions.maxParamLength` to `MAX_ROUTE_PARAM_LENGTH` (route-helpers.ts), the route test harness uses the same constant, and a wiring guard pins it. ⚠️ `~/` in a Docker case is refused with 400 (attachment POST and `POST …/folders`): the session is local for these routes, but `~` inside the container is the container's own home, and expanding it on the host would open a different file than the one the agent printed. Tests: `test/routes/folder-grid-routes.test.ts` (incl. the listing script on a real `sh`), `test/folder-grid-ui.test.ts`.

src/web/public/constants.js

@@ -2166,7 +2166,7 @@ const FILE_LINK_EXTENSION_GROUP = /\\\.(\(\?:[^()]*\))\)\\b$/.exec(FILE_PATH_LIN
 
 /**
  * Every linkable file path in `text`, sorted by position. Spaced candidates
- * reserve their whole span first, even when unlinkable; rooted, `~/`, relative
+ * reserve their whole span first, including paths bounded by parentheses, even when unlinkable; rooted, `~/`, relative
  * and folder detectors then skip reserved spans, earlier matches and URLs.
  *
  * The one entry point for both consumers (terminal link provider, response
@@ -2247,8 +2247,9 @@ const SPACED_FILE_PATH_LABEL_PATTERN =
  * Every path pattern ends a path at whitespace, so `/mnt/c/OneDrive - Contoso/a.docx`
  * linked `/mnt/c/OneDrive` plus a relative `Contoso/a.docx`, two links to the
  * wrong targets. A space is only safe inside a path where the line itself bounds
- * the path, so a spaced path is recognised in exactly these shapes:
+ * the path or a parenthesised group bounds it, so a spaced path is recognised in these shapes:
  *
+ *   Updated (/mnt/c/My Docs/report.docx)   inside parentheses in prose
  *   /mnt/c/My Docs/report.docx              the whole line is the path
  *   - /mnt/c/My Docs/report.docx            after a list marker (`-`, `*`, `•`, `1.`, `2)`)
  *   Saved to: 03 Attachments/Build SIPOC Design/plan.pptx      after a path label (SPACED_FILE_PATH_LABEL_PATTERN)
@@ -2262,7 +2263,7 @@ const SPACED_FILE_PATH_LABEL_PATTERN =
  * it ends on a known extension, a rooted one has a directory before its first
  * space, no earlier word holds an extension (`a.md,`, `a.ts#L12`) or ends in `/`,
  * and none holds a `:` and a digit (`a.ts:42`, a line suffix ends the path). Later words cannot start a new
- * `/`, `~/`, `./` or `../` path, no earlier word ends in `:`, is an arrow or has
+ * `/`, `~/`, `./` or `../` path, no earlier word ends in `:` or `,`, is an arrow or has
  * no letter or digit (a prompt glyph such as `❯` or `$`; a bare `-` is kept), and
  * a run of spaces (a column gap) is refused, so two paths on a line are never
  * merged. A relative candidate whose only `/` word is its last is prose after the
@@ -2309,7 +2310,7 @@ function spacedFilePathOnLine(line) {
     return null;
   }
   for (const word of words.slice(0, -1)) {
-    if (word.endsWith('/') || word.endsWith(':') || /^(?:—|–|→|=>|->|<-|=)$/.test(word)) return null;
+    if (word.endsWith('/') || /[,:]$/.test(word) || /^(?:—|–|→|=>|->|<-|=)$/.test(word)) return null;
     // A shell prompt that prints its working directory in full (`/home/me/proj$ cat
     // notes.md`; WSL's `/mnt/c/...` is outside `$HOME`) is a command line too, and so is
     // one whose directory has a space in it (`/mnt/c/My Docs$ ls notes.md`): the `$`
@@ -2554,8 +2555,7 @@ const pathFirstSegment = (path) => path.replace(/^(?:\.?\/)+/, '').split('/')[0]
  * Whether the line `nextText` carries on a file path `prevText` broke off.
  *
  * Answers `'join'` when the path ends (reaches a known extension) on the next
- * line, `'join-spaced'` for a filename word wrapped inside parentheses, and
- * `'chain'` when the next line is nothing but more of the path (a path
+ * line, `'chain'` when the next line is nothing but more of the path (a path
  * spanning three or more lines; only worth keeping once a later line ends it),
  * and `null` otherwise. The broken-off token must already look like a path in
  * progress: it contains a `/`, ends on a path character and does not yet end
@@ -2566,21 +2566,6 @@ const pathFirstSegment = (path) => path.replace(/^(?:\.?\/)+/, '').split('/')[0]
 function pathContinuation(prevText, nextText) {
   const previous = String(prevText || '').trimEnd();
   const next = String(nextText || '').replace(/^\s+/, '');
-  const opening = previous.lastIndexOf('(');
-  const closing = next.indexOf(')');
-  if (opening >= 0 && closing > 0) {
-    const before = previous.slice(opening + 1);
-    const after = next.slice(0, closing);
-    // A word wrap in a parenthesised filename replaces its separating space.
-    if (
-      !before.includes(')') &&
-      !/[/-]$/.test(before) &&
-      !after.includes('/') &&
-      spacedFilePathOnLine(`${before} ${after}`)?.link
-    ) {
-      return 'join-spaced';
-    }
-  }
   const tail = /[^\s"'<>|;&]+$/.exec(previous)?.[0] || '';
   if (!tail.includes('/') || !/[\w\-.~+@%/]$/.test(tail) || PATH_TOKEN_ENDS_WITH_EXTENSION.test(tail)) return null;
   const head = /^[^\s"'<>|;&]+/.exec(next)?.[0] || '';
@@ -2609,7 +2594,9 @@ function pathContinuation(prevText, nextText) {
  * A following logical line is glued on (its indent dropped, cell mapping kept
  * exact) when {@link pathContinuation} says it carries the path on and the row it
  * broke off is at least as long as the row it continues on. Bounded by the same
- * `maxRows` as the logical line.
+ * `maxRows` as the logical line. Hard breaks concatenate without inserting spaces.
+ * An ambiguous parenthesised filename also carries `pathAlternatives` for a
+ * guarded lookup on activation; its text and cell mapping remain unchanged.
  *
  * @returns Same shape as {@link terminalLogicalLine}; null when the row does not exist.
  */
@@ -2630,6 +2617,7 @@ function terminalPathLine(buffer, row, cols, maxRows) {
   /** `first` and the lines a path carries on into, stopping at the last confirmed join. */
   const extend = (first) => {
     const parts = [first];
+    const alternatives = [];
     let text = first.text;
     let rows = rowsOf(first);
     let confirmed = 1;
@@ -2639,32 +2627,44 @@ function terminalPathLine(buffer, row, cols, maxRows) {
       const kind = continues(parts[parts.length - 1], next, text);
       if (!kind) break;
       parts.push(next);
-      if (kind === 'join-spaced') text += ' ';
+      if (kind === 'join') {
+        const opening = text.lastIndexOf('(');
+        const closing = next.text.indexOf(')');
+        if (opening >= 0 && closing > 0) {
+          const before = text.slice(opening + 1);
+          const after = next.text.slice(0, closing).trimStart();
+          const spaced = spacedFilePathOnLine(`${before} ${after}`);
+          if (!before.includes(')') && !/[/-]$/.test(before) && !after.includes('/') && spaced?.link) {
+            alternatives.push({ path: before + after, spacedPath: spaced.path });
+          }
+        }
+      }
       text += next.text.replace(/^\s+/, '');
       rows += rowsOf(next);
-      if (kind !== 'chain') confirmed = parts.length;
+      if (kind === 'join') confirmed = parts.length;
     }
-    return parts.slice(0, confirmed);
+    return { parts: parts.slice(0, confirmed), alternatives };
   };
 
-  // The hovered row may be the second or third line of a broken path: walk back
-  // to where it could start, then let the forward pass decide what really joins.
+  // A middle fragment may have no slash, so only a forward pass from its
+  // rooted start can confirm a path spanning three or more rows.
+  let extended = extend(base);
   let first = base;
   let rows = rowsOf(base);
   while (first.startRow > 0) {
     const prev = lineAt(first.startRow - 1);
-    if (!prev || rows + rowsOf(prev) > bound || !continues(prev, first, prev.text)) break;
+    if (!prev || rows + rowsOf(prev) > bound) break;
     first = prev;
     rows += rowsOf(prev);
+    const candidate = extend(first);
+    if (candidate.parts[candidate.parts.length - 1].endRow >= base.startRow) extended = candidate;
   }
-  let parts = extend(first);
-  if (parts[parts.length - 1].endRow < base.startRow) parts = extend(base);
+  const { parts, alternatives } = extended;
   if (parts.length === 1) return parts[0];
 
   const segments = [];
   let text = '';
   for (const [i, part] of parts.entries()) {
-    if (i > 0 && continues(parts[i - 1], part, text) === 'join-spaced') text += ' ';
     const skip = i === 0 ? 0 : part.text.length - part.text.replace(/^\s+/, '').length;
     segments.push({ part, textStart: text.length, skip });
     text += part.text.slice(skip);
@@ -2684,7 +2684,14 @@ function terminalPathLine(buffer, row, cols, maxRows) {
     }
     return -1;
   };
-  return { startRow: parts[0].startRow, endRow: parts[parts.length - 1].endRow, text, offsetToCell, cellToOffset };
+  return {
+    startRow: parts[0].startRow,
+    endRow: parts[parts.length - 1].endRow,
+    text,
+    offsetToCell,
+    cellToOffset,
+    ...(alternatives.length ? { pathAlternatives: alternatives } : {}),
+  };
 }
 
 /**
@@ -2940,7 +2947,14 @@ function terminalLinkLine(buffer, row, cols, maxRows) {
     for (const s of segments) if (s.row === targetRow && (!seg || s.colStart <= targetCol)) seg = s;
     return seg ? seg.textStart + Math.max(0, targetCol - seg.colStart) : -1;
   };
-  return { startRow, endRow: lastRow, text, offsetToCell, cellToOffset };
+  return {
+    startRow,
+    endRow: lastRow,
+    text,
+    offsetToCell,
+    cellToOffset,
+    ...(base.pathAlternatives ? { pathAlternatives: base.pathAlternatives } : {}),
+  };
 }
 
 /**

src/web/public/panels-ui.js

@@ -4204,7 +4204,7 @@ Object.assign(CodemanApp.prototype, {
    * full attachment guard (blocked secret trees, extension allowlist, symlinks
    * resolved), so a refusal here is a policy answer worth showing verbatim.
    *
-   * @returns {Promise<{attachmentId?: string, size?: number, error?: string}>}
+   * @returns {Promise<{attachmentId?: string, size?: number, error?: string, status?: number}>}
    */
   async _registerExternalPreview(filePath, sessionId) {
     try {
@@ -4224,10 +4224,11 @@ Object.assign(CodemanApp.prototype, {
       if (/unsupported/i.test(reason)) {
         const ext = (filePath.split('.').pop() || '').toLowerCase();
         return {
+          status: res.status,
           error: `Cannot preview .${ext} from outside the session workspace (images, video, audio, PDF, Office documents and text files only).`,
         };
       }
-      return { error: reason };
+      return { error: reason, status: res.status };
     } catch (err) {
       return { error: err.message || 'Cannot open this file' };
     }

src/web/public/terminal-ui.js

@@ -2318,7 +2318,7 @@ Object.assign(CodemanApp.prototype, {
         // Pattern 3: Bash() tool output
         const bashPattern = /Bash\([^)]*?(\/(?:home|tmp|var|etc|opt)[^\s"'<>|;&\)\n\x00-\x1f]+)/g;
 
-        const activateFilePath = (text, folder = false) => {
+        const activateFilePath = (text, folder = false, verifiedSessionId = null) => {
           // Tailing a PNG in the log viewer shows binary noise; the file preview
           // already renders images, PDFs, documents and media inline — and it
           // now reaches files outside the workspace too, which is where an
@@ -2336,8 +2336,26 @@ Object.assign(CodemanApp.prototype, {
           // A relative path is resolved against the session's working
           // directory first, and a `~/` path always previews (only the
           // server knows that host's home, and the log viewer cannot ask).
-          const sessionId = getSessionId();
+          const sessionId = verifiedSessionId || getSessionId();
+          if (!sessionId) return;
           const target = self._resolveLinkedFilePath(text, sessionId);
+          const alternative = !folder && logical.pathAlternatives?.find((candidate) => candidate.path === text);
+          if (alternative && !verifiedSessionId) {
+            return (async () => {
+              let path = target;
+              let registered = await self._registerExternalPreview(path, sessionId);
+              if (registered.status === 404) {
+                path = self._resolveLinkedFilePath(alternative.spacedPath, sessionId);
+                registered = await self._registerExternalPreview(path, sessionId);
+              }
+              if (!registered.attachmentId) {
+                self.showToast(registered.error || 'Cannot open this file', 'error');
+                return;
+              }
+              // The normal opener rechecks its guards; attachment registration deduplicates the path.
+              return activateFilePath(path, false, sessionId);
+            })();
+          }
           // A folder path opens the folder grid (which falls back to the
           // preview if the server finds a file there after all).
           if (folder) {
@@ -2372,7 +2390,7 @@ Object.assign(CodemanApp.prototype, {
               underline: true,
             },
             activate(_event, text) {
-              activateFilePath(text, folder);
+              return activateFilePath(text, folder);
             },
             hover() {
               setHovered(true);

test/file-path-link-forms.test.ts

@@ -241,6 +241,8 @@ function loadApp() {
   app.sessions = new Map([['s1', { workingDir: '/mnt/build/neon_getaway-mgr-hebel' }]]);
   app.openFilePreview = vi.fn();
   app.openLogViewerWindow = vi.fn();
+  app._registerExternalPreview = vi.fn(async () => ({ attachmentId: 'att-fixture' }));
+  app.showToast = vi.fn();
   app._isExternalPreviewPath = (p: string) => p.startsWith('~/');
   return app;
 }
@@ -257,7 +259,30 @@ function linksOn(lines: string[], row: number, cols = 80, wrappedRows = new Set<
 }
 
 describe('terminal link provider', () => {
-  it('retains the filename space when the CLI word-wraps a parenthesised path', () => {
+  it.each([
+    [
+      ['Saved the screenshot (/home/me/proj/out/ghost1b_game', '  play.png).'],
+      '/home/me/proj/out/ghost1b_gameplay.png',
+    ],
+    [
+      ['  ⎿  Wrote (/mnt/build/neon/builds/captures/ghost1b_gamepl', '     ay.png) ok'],
+      '/mnt/build/neon/builds/captures/ghost1b_gameplay.png',
+    ],
+    [
+      ['Saved the screenshot (/home/me/proj/out/ghost1b_', '  very_long_game', '  play.png).'],
+      '/home/me/proj/out/ghost1b_very_long_gameplay.png',
+    ],
+  ])('preserves a parenthesised filename without spaces across hard wraps: %s', async (rows, path) => {
+    for (let row = 1; row <= rows.length; row++) {
+      const { app, links } = linksOn(rows, row, 120);
+      expect(links.map((link) => link.text)).toEqual([path]);
+      await links[0].activate({}, links[0].text);
+      expect(app.openFilePreview).toHaveBeenCalledWith(path, 's1');
+      expect(app._registerExternalPreview.mock.calls).toEqual([[path, 's1']]);
+    }
+  });
+
+  it('uses the spaced filename only when the unspaced hard-wrap target is missing', async () => {
     const path = '/mnt/user/Scratch/Kobo/Set-KoboCovers/Kobo eReader.conf';
     const rows = [
       'Found it: I prepared a corrected configuration (/mnt/user/Scratch/Kobo/Set-KoboCovers/Kobo',
@@ -265,13 +290,40 @@ describe('terminal link provider', () => {
     ];
     for (const row of [1, 2]) {
       const { app, links } = linksOn(rows, row, 120);
-      expect(links.map((link) => link.text)).toEqual([path]);
+      const unspaced = path.replace('Kobo eReader', 'KoboeReader');
+      expect(links.map((link) => link.text)).toEqual([unspaced]);
       expect(links[0].range.end).toEqual({ x: '  eReader.conf'.length + 1, y: 2 });
-      links[0].activate({}, links[0].text);
+      app._registerExternalPreview.mockImplementation(async (candidate: string) =>
+        candidate === path ? { attachmentId: 'att-fixture' } : { status: 404, error: 'File not found' }
+      );
+      await links[0].activate({}, links[0].text);
       expect(app.openLogViewerWindow).toHaveBeenCalledWith(path, 's1');
+      expect(app._registerExternalPreview.mock.calls).toEqual([
+        [unspaced, 's1'],
+        [path, 's1'],
+      ]);
     }
   });
 
+  it.each([403, 500, 503])('does not try another path after a guarded lookup returns HTTP %s', async (status) => {
+    const { app, links } = linksOn(['Saved (/mnt/data/Kobo', '  eReader.conf).'], 1, 120);
+    app._registerExternalPreview.mockResolvedValue({ status, error: 'Lookup refused' });
+    await links[0].activate({}, links[0].text);
+    expect(app._registerExternalPreview).toHaveBeenCalledTimes(1);
+    expect(app.openFilePreview).not.toHaveBeenCalled();
+    expect(app.openLogViewerWindow).not.toHaveBeenCalled();
+    expect(app.showToast).toHaveBeenCalledWith('Lookup refused', 'error');
+  });
+
+  it('keeps the session selected at click time while a path lookup is pending', async () => {
+    const { app, links } = linksOn(['Saved (/mnt/data/Kobo', '  eReader.conf).'], 1, 120);
+    const pending = links[0].activate({}, links[0].text);
+    app.activeSessionId = 'another-session';
+    await pending;
+    expect(app._registerExternalPreview).toHaveBeenCalledWith('/mnt/data/KoboeReader.conf', 's1');
+    expect(app.openLogViewerWindow).toHaveBeenCalledWith('/mnt/data/KoboeReader.conf', 's1');
+  });
+
   it('opens the complete parenthesised configuration path from either wrapped row', () => {
     const path = '/mnt/user/Scratch/Kobo/Set-KoboCovers/Kobo eReader.conf';
     const text = `Found it: I prepared a corrected configuration (${path}).`;

test/folder-grid-ui.test.ts

@@ -212,6 +212,27 @@ function loadApp(fetchImpl: (url: string, init?: { body?: string }) => unknown)
   return { app, elements, keyHandlers, fetch: context.fetch as ReturnType<typeof vi.fn> };
 }
 
+describe('guarded attachment registration results', () => {
+  it.each([404, 403, 500, 503])('preserves HTTP %s for the activation decision', async (status) => {
+    const { app, fetch } = loadApp(async () => ({
+      ok: false,
+      status,
+      json: async () => ({ error: 'Cannot read file' }),
+    }));
+    const result = await Object.getPrototypeOf(app)._registerExternalPreview.call(app, '/mnt/data/a.conf', 's1');
+    expect(result).toEqual({ error: 'Cannot read file', status });
+    expect(JSON.parse(fetch.mock.calls[0][1].body)).toEqual({ path: '/mnt/data/a.conf', notify: false });
+  });
+
+  it('does not turn a connection failure into a missing file', async () => {
+    const { app } = loadApp(async () => {
+      throw new Error('Connection lost');
+    });
+    const result = await Object.getPrototypeOf(app)._registerExternalPreview.call(app, '/mnt/data/a.conf', 's1');
+    expect(result).toEqual({ error: 'Connection lost' });
+  });
+});
+
 const LISTING = {
   folderId: 'fld_1',
   path: '/mnt/raid1/styleframes',

test/spaced-file-path-links.test.ts

@@ -42,6 +42,10 @@ describe('spaced file paths', () => {
     expect(paths('Do not link (/mnt/data/../private files/settings.conf).')).toEqual([]);
   });
 
+  it('does not take a comma-separated list inside parentheses as one spaced filename', () => {
+    expect(paths('Updated (/home/me/proj, config.json)')).toEqual(['/home/me/proj', 'config.json']);
+  });
+
   it('links an own-line absolute path with spaces whole', () => {
     expect(paths(LONG)).toEqual([LONG]);
     expect(paths('/mnt/c/proj/My Big Docs/report.docx')).toEqual(['/mnt/c/proj/My Big Docs/report.docx']);

test/wrapped-file-paths.browser.test.ts

@@ -16,67 +16,100 @@ describe('wrapped configuration file links (Chromium)', () => {
     await browser.close();
   });
 
-  it.each(['soft', 'hard'])('opens the complete file from both rows of a %s wrap', async (wrap) => {
-    const page = await browser.newPage({ viewport: { width: 1920, height: 600 } });
-    try {
-      await page.setContent('<div id="terminal"></div>');
-      await page.addStyleTag({ path: resolve(publicDir, '../../../node_modules/@xterm/xterm/css/xterm.css') });
-      await page.addScriptTag({ path: resolve(publicDir, '../../../node_modules/@xterm/xterm/lib/xterm.js') });
-      await page.addScriptTag({ content: 'window.CodemanApp = class CodemanApp {};' });
-      for (const file of ['constants.js', 'terminal-ui.js']) {
-        await page.addScriptTag({ content: readFileSync(resolve(publicDir, file), 'utf8') });
-      }
-      await page.evaluate(
-        async ({ path, wrap }) => {
-          const w = window as any;
-          const first = `Found it: prepared a corrected configuration (${path.slice(0, -' eReader.conf'.length)}`;
-          const terminal = new w.Terminal({ cols: first.length + (wrap === 'soft' ? 1 : 20), rows: 6 });
-          terminal.open(document.getElementById('terminal'));
-          w.opened = [];
-          w.app = Object.assign(new w.CodemanApp(), {
-            terminal,
-            activeSessionId: 'fixture',
-            sessions: new Map([['fixture', { workingDir: '/workspace' }]]),
-            _isExternalPreviewPath: () => true,
-            openFilePreview: (file: string) => w.opened.push(file),
-            openLogViewerWindow: (file: string) => w.opened.push(`log:${file}`),
-            openFolderGrid: (file: string) => w.opened.push(`folder:${file}`),
-          });
-          w.app.registerFilePathLinkProvider();
-          const text = `${first}${wrap === 'soft' ? ' ' : '\r\n  '}eReader.conf).`;
-          await new Promise<void>((done) => terminal.write(text, done));
-          await new Promise<void>((done) => requestAnimationFrame(() => requestAnimationFrame(() => done())));
-        },
-        { path, wrap }
-      );
-
-      for (const row of [0, 1]) {
-        const point = await page.evaluate(
-          async ({ path, row }) => {
-            const app = (window as any).app;
-            const terminal = app.terminal;
-            const links = await new Promise<any[]>((done) => app._terminalLinkProvider.provideLinks(row + 1, done));
-            const link = links.find((candidate) => candidate.text === path);
-            if (!link) throw new Error(`The complete filename is not linked on row ${row + 1}`);
-            const text = terminal.buffer.active.getLine(row).translateToString(true);
-            const col = row === 0 ? link.range.start.x : text.indexOf('eReader') + 1;
-            const box = terminal.element.querySelector('.xterm-screen').getBoundingClientRect();
-            return {
-              x: box.left + (col - 0.5) * (box.width / terminal.cols),
-              y: box.top + (row + 0.5) * (box.height / terminal.rows),
-            };
-          },
-          { path, row }
+  it.each([
+    { wrap: 'soft', originalExists: false },
+    { wrap: 'hard', originalExists: false },
+    { wrap: 'hard', originalExists: true },
+  ])(
+    'opens the existing file from both rows: $wrap, original exists: $originalExists',
+    async ({ wrap, originalExists }) => {
+      const original = path.replace('Kobo eReader', 'KoboeReader');
+      const expected = wrap === 'hard' && originalExists ? original : path;
+      const lookups: string[] = [];
+      const page = await browser.newPage({ viewport: { width: 1920, height: 600 } });
+      try {
+        await page.route('http://fixture.test/', (route) =>
+          route.fulfill({
+            contentType: 'text/html',
+            body: '<div id="terminal"></div>',
+          })
         );
-        await page.mouse.move(point.x, point.y);
-        await page.waitForFunction(() => (window as any).app._linkHovered === true);
-        await page.mouse.click(point.x, point.y);
-        await page.waitForFunction((count) => (window as any).opened.length === count, row + 1);
-        expect(await page.evaluate(() => (window as any).opened)).toEqual(Array(row + 1).fill(path));
-        await page.mouse.move(0, 0);
+        await page.route('http://fixture.test/api/sessions/fixture/attachments', async (route) => {
+          const body = route.request().postDataJSON();
+          expect(body.notify).toBe(false);
+          lookups.push(body.path);
+          const exists = body.path === path || (originalExists && body.path === original);
+          await route.fulfill({
+            status: exists ? 200 : 404,
+            json: exists
+              ? { success: true, data: { attachmentId: 'att-fixture' } }
+              : { success: false, error: 'File not found' },
+          });
+        });
+        await page.goto('http://fixture.test/');
+        await page.addStyleTag({ path: resolve(publicDir, '../../../node_modules/@xterm/xterm/css/xterm.css') });
+        await page.addScriptTag({ path: resolve(publicDir, '../../../node_modules/@xterm/xterm/lib/xterm.js') });
+        await page.addScriptTag({ content: 'window.CodemanApp = class CodemanApp {};' });
+        for (const file of ['constants.js', 'terminal-ui.js', 'panels-ui.js']) {
+          await page.addScriptTag({ content: readFileSync(resolve(publicDir, file), 'utf8') });
+        }
+        await page.evaluate(
+          async ({ path, wrap }) => {
+            const w = window as any;
+            const first = `Found it: prepared a corrected configuration (${path.slice(0, -' eReader.conf'.length)}`;
+            const terminal = new w.Terminal({ cols: first.length + (wrap === 'soft' ? 1 : 20), rows: 6 });
+            terminal.open(document.getElementById('terminal'));
+            w.opened = [];
+            w.app = Object.assign(new w.CodemanApp(), {
+              terminal,
+              activeSessionId: 'fixture',
+              sessions: new Map([['fixture', { workingDir: '/workspace' }]]),
+              _isExternalPreviewPath: () => true,
+              openFilePreview: (file: string) => w.opened.push(file),
+              openLogViewerWindow: (file: string) => w.opened.push(`log:${file}`),
+              openFolderGrid: (file: string) => w.opened.push(`folder:${file}`),
+              showToast: (message: string) => w.opened.push(`error:${message}`),
+            });
+            w.app.registerFilePathLinkProvider();
+            const text = `${first}${wrap === 'soft' ? ' ' : '\r\n  '}eReader.conf).`;
+            await new Promise<void>((done) => terminal.write(text, done));
+            await new Promise<void>((done) => requestAnimationFrame(() => requestAnimationFrame(() => done())));
+          },
+          { path, wrap }
+        );
+
+        expect(lookups).toEqual([]);
+        for (const row of [0, 1]) {
+          const point = await page.evaluate(
+            async ({ path, row }) => {
+              const app = (window as any).app;
+              const terminal = app.terminal;
+              const links = await new Promise<any[]>((done) => app._terminalLinkProvider.provideLinks(row + 1, done));
+              const link = links.find((candidate) => candidate.text === path);
+              if (!link) throw new Error(`The complete filename is not linked on row ${row + 1}`);
+              const text = terminal.buffer.active.getLine(row).translateToString(true);
+              const col = row === 0 ? link.range.start.x : text.indexOf('eReader') + 1;
+              const box = terminal.element.querySelector('.xterm-screen').getBoundingClientRect();
+              return {
+                x: box.left + (col - 0.5) * (box.width / terminal.cols),
+                y: box.top + (row + 0.5) * (box.height / terminal.rows),
+              };
+            },
+            { path: wrap === 'hard' ? original : path, row }
+          );
+          await page.mouse.move(point.x, point.y);
+          await page.waitForFunction(() => (window as any).app._linkHovered === true);
+          await page.mouse.click(point.x, point.y);
+          await page.waitForFunction((count) => (window as any).opened.length === count, row + 1);
+          expect(await page.evaluate(() => (window as any).opened)).toEqual(Array(row + 1).fill(expected));
+          await page.mouse.move(0, 0);
+        }
+        expect(lookups).toEqual(
+          wrap === 'soft' ? [] : originalExists ? [original, original] : [original, path, original, path]
+        );
+      } finally {
+        await page.close();
       }
-    } finally {
-      await page.close();
     }
-  });
+  );
 });