@awebai/oats 0.22.12 → 0.22.14

package/bin/oats.mjs

@@ -43,6 +43,7 @@ import { attachArgv, checkRemote, forgetSnapshot, getServer, inspectRemote, star
 import { spawnSync as spawnSyncProc } from "node:child_process";
 import { scheduleScopeOf, listSchedules, describe as describeSchedule, addSchedule, updateSchedule, setEnabled as setScheduleEnabled, removeSchedule, runNow as runScheduleNow, reconcile as reconcileSchedule, tickHost, tickWorkspace, registerWorkspace, unregisterWorkspace, readRegistry, schedulerStatus, saveWakeForHome, removeWakeForHome, wakeFromFlags, withHostLock, scheduleError, SCHEDULE_API } from "../lib/schedule.mjs";
 import { hostUnitStatus, installHostUnit, uninstallHostUnit } from "../lib/schedule-host.mjs";
+import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } from "../lib/attachments.mjs";
 
 const args = process.argv.slice(2);
 const cmd = args[0];
@@ -2960,7 +2961,19 @@ async function sessionCmd() {
       if (file === true) throw Object.assign(new Error("--text-file needs a path"), { code: "E_BAD_ARGS" });
       if (!file && process.stdin.isTTY) throw Object.assign(new Error("provide --text-file or pipe input on stdin"), { code: "E_BAD_ARGS" });
       result = inputInstanceSession(home, readFileSync(file || 0, "utf8"));
-    } else throw Object.assign(new Error("usage: oats session inspect|input|attach|start --home /absolute/home [--text-file path] [--model id] [--json]"), { code: "E_BAD_ARGS" });
+    } else if (args[1] === "receive") {
+      // Bytes arrive on stdin (the routed upload pipes them through ssh),
+      // collected event-driven and bounded before anything is written.
+      const name = flag("name");
+      if (!name || name === true) throw Object.assign(new Error("session receive needs --name <file name>"), { code: "E_BAD_ARGS" });
+      if (!home || home === true) throw Object.assign(new Error("session receive needs --home </absolute/instance>"), { code: "E_BAD_ARGS" });
+      if (process.stdin.isTTY) throw Object.assign(new Error("session receive reads the attachment bytes from stdin"), { code: "E_BAD_ARGS" });
+      result = receiveAttachment(home, name, await readStreamBounded(process.stdin, MAX_ATTACHMENT_BYTES));
+    } else if (args[1] === "upload") {
+      const file = flag("file");
+      if (!file || file === true) throw Object.assign(new Error("session upload needs --file <local path>"), { code: "E_BAD_ARGS" });
+      result = uploadAttachment({ file, home: home === true ? undefined : home });
+    } else throw Object.assign(new Error("usage: oats session inspect|input|attach|start|receive|upload --home /absolute/home [--text-file path] [--model id] [--name file] [--file path] [--json]"), { code: "E_BAD_ARGS" });
     if (JSON_MODE) jsonOk(result); else console.log(JSON.stringify(result, null, 2));
   } catch (e) { cmdFail(e.code || "E_SESSION_FAILED", e.message); }
 }
@@ -3255,7 +3268,7 @@ function versionCmd() {
     // on it (an older CLI without the surface must fail closed with a
     // reason, not an argument error). `features`: kernel abilities a peer
     // must see before relying on them (retire-home: retire --home).
-    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, runtimes: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "roster", "harvest", "schedule"], features: ["retire-home", "session-start", "schedule"], scheduleApi: SCHEDULE_API }));
+    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, runtimes: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "roster", "harvest", "schedule", "session-upload"], features: ["retire-home", "session-start", "schedule", "session-upload"], scheduleApi: SCHEDULE_API }));
     return;
   }
   console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -3462,7 +3475,19 @@ function serverRouteCmd() {
       console.log(`Started ${r.instance || r.home} on ${id} (${r.backend}${r.model ? `, model ${r.model}` : ""}, ${r.reused === "pane" ? "in its existing pane" : r.reused === "adopted" ? "adopted the pending session" : "new window"})`);
       return;
     }
-    if (args[1] !== "attach") bail("E_USAGE", "--server routes `session inspect`, `session start` and `session attach`; input runs on the execution host (the wake broker calls it there)");
+    if (args[1] === "upload") {
+      // Bytes stream to `session receive` on the execution host over the
+      // same route as attach; the answer's checksum is verified here.
+      const file = flag("file");
+      if (!file || file === true) bail("E_BAD_ARGS", "session upload needs --file <local path>");
+      let r;
+      try { r = uploadAttachment({ file, server: id, ...addr }); } catch (e) { bail(e.code || "E_UPLOAD_FAILED", e.message); }
+      if (r.stderr) process.stderr.write(r.stderr + "\n");
+      if (JSON_MODE) { jsonOk(r); return; }
+      console.log(`Uploaded ${r.name} (${r.bytes} bytes) to ${r.instance || r.home} on ${id}: ${r.path}`);
+      return;
+    }
+    if (args[1] !== "attach") bail("E_USAGE", "--server routes `session inspect`, `session start`, `session upload` and `session attach`; input runs on the execution host (the wake broker calls it there)");
     let route;
     try { route = attachArgv(id, addr, { skipVersionCheck: args.includes("--print") }); }
     catch (e) { bail(e.code || "E_BAD_ARGS", e.message); }
@@ -3664,6 +3689,10 @@ Usage:
   oats session start --server <id>           start a stopped remote instance in its existing home
       --instance <name> | --home <abs>       over its saved route; the server must advertise
       [--model <m>] [--json]                 session-start (oats 0.22.9 or later)
+  oats session upload --server <id>          copy a local file into a remote instance's private
+      --instance <name> | --home <abs>       attachments over its saved route (bytes stream on
+      --file <path> [--json]                 ssh stdin; sha256 verified); the server must
+                                            advertise session-upload (oats 0.22.13 or later)
   oats create <name> [--local]               create an agent soul; --local = full
       [--description <d>] [--repo <r>]      soul under local-agents/ (uncommitted,
       [--work <mode>] [--runtime pi|claude|codex] gitignored; same memory + lifecycle)
@@ -3676,6 +3705,11 @@ Usage:
                                                 routes to that host's workspace
   oats spawn ... --wake-file <json> | --wake-every <N> --wake-message <text>  save a wake schedule
                                                 bound to the new instance's home (docs/schedules.md)
+  oats session upload --file <path>          store a copy of a local file as a private attachment
+      --home <absolute-home> [--json]         in the instance home (.oats-attachments/); answers
+                                            {path, bytes, sha256}; never types into the session
+  oats session receive --home <abs> --name   store attachment bytes read from stdin (the routed
+      <file> [--json]                       upload's remote half)
   oats session start --home <absolute-home>  start a STOPPED instance again in its existing home
       [--model <m>] [--json]                 (same identity, worktree, notes and launch env; no
                                             spawn hooks); --model replaces the recorded model

package/docs/design/2026-09-07-architecture-reassessment.md

@@ -0,0 +1,131 @@
+# Architecture reassessment: usable agents with replaceable services
+
+Assessment of main `76c0ea4`, September 7, 2026. Requested by Juan after
+operating the Desktop; incorporates Pepe's terminal, shortcut, split and soul
+management feedback. This records the direction and implementation gaps, not a
+claim that every item below has shipped.
+
+The requirements authority for this assessment is Juan's September 3
+“Architecture simplification and generlization” in his OATS project KB:
+souls carry instructions and capabilities; a harvester converts ephemeral
+state into knowledge accessible through the selected knowledge capability;
+packages distribute souls and capabilities; OATS constructs and operates
+instances across runtimes and platforms. The private Bookshelf README points
+to September 1's adoption/sovereignty strategy. Its relevant constraint is that
+changing a runtime or service provider must not erase the team's relationships
+or working knowledge. The older August proposals about genomes, clothes and
+turn-record experiments are background, not reasons to expand this release.
+
+## Decision
+
+Keep the existing package and capability-layer mechanism. Correct the places
+where the CLI and GUI bypass it. The architecture is broadly right; the
+operator experience and some service boundaries are incomplete. More
+abstractions will not fix a terminal that cannot accept a screenshot.
+
+| Component | Owns | Must not assume |
+|---|---|---|
+| OATS kernel | Soul/instance construction, configuration, lifecycle, host placement, scheduling, capability resolution | A particular knowledge provider, messaging service, or GUI |
+| Session backend | Durable terminal, attach/detach, resize, literal input, observation | OATS soul/package semantics or task success |
+| Knowledge capability | Knowledge access and representation; its harvester and promotion policy | Every installation uses OKF or stores memory in the same files |
+| Messaging capability / aweb | Durable messages, identities, event subscriptions and delivery policy | A particular model harness or an open Desktop window |
+| Task capability | Durable work and task semantics | A particular terminal backend |
+| Desktop | Inspect effective configuration; explicit operator actions; terminal input, files, layout | Provider names, SSH commands, or a second lifecycle implementation |
+
+Scheduling belongs to OATS, and a scheduled harvest is one use of scheduling.
+Harvesting behavior belongs to the knowledge capability. Starting an agent,
+writing a prompt, and producing reviewed knowledge are different outcomes.
+The UI must retain those distinctions.
+
+## What already fits, and what does not
+
+`lib/core.mjs` already selects exclusive knowledge/messaging/tasks layers by
+manifest, resolves scoped capability settings, dispatches lifecycle hooks, and
+materializes runtime instructions. Jira and Linear demonstrate that a layer
+can have alternative implementations. OKF's harvester is already an exported
+capability agent. There is no reason to replace this machinery.
+
+The remaining coupling is concrete:
+
+- The retire receipt reads `hookResults.meta["oats.okf"].harvested`, although
+  current OKF does not supply a retire hook. Remove the dead provider-specific
+  inference; do not invent successful harvesting at retirement.
+- Remote capability routing recognizes `okf harvest` specifically in
+  `bin/oats.mjs` and `lib/servers.mjs`.
+- Desktop harvest actions and scheduled-harvest definitions construct
+  `oats okf harvest`; the editor recognizes that exact argv.
+- The “brain” view presents `STATE.md`, `log.md` and `notes/` as universal
+  knowledge structure. These are conventions of the current setup.
+
+The next service contract should expose the **effective knowledge provider and
+its supported operations for a specific soul/home**. Discovering a capability
+command namespace alone is insufficient: it does not promise a `harvest` verb
+or a shared file layout. A provider may offer harvest, different operations,
+or read-only access. Desktop must show only declared operations and route
+execution through the selected CLI capability. The same resolution must apply
+locally, remotely, and when a scheduled operation runs.
+
+Keep that change small: explicit operation metadata, scoped discovery, and one
+invocation route using the existing capability engine. Do not add a plugin
+framework, generic workflow language, or a second knowledge store. Demonstrate
+replaceability with a tiny alternative-provider fixture that uses a different
+command and storage layout; a full second product is unnecessary.
+
+## tmux and Herdr
+
+The current kernel defaults to a shared tmux session (`pi-agents`) with a
+window per instance. An agent does not require another tmux server. The GUI
+creates a temporary session linking only the selected window. That isolates
+viewers: switching a terminal elsewhere cannot redirect a GUI tab to another
+agent, and an agent exiting cannot silently expose a sibling under its label.
+The `oatsdesk-*` name in Juan's screenshot is this viewer. Its status bar can
+be hidden with a viewer-local setting. Do not alter global tmux settings or
+merge/move live agent sessions to solve a display defect.
+
+Herdr 0.8.2 is a separate terminal runtime, not a tmux-compatible superset.
+Its documented direct terminal attachment, socket API, events and SSH support
+are useful. Its semantic agent state comes from detection and/or integrations;
+it is richer evidence, not proof that a particular message was consumed.
+The [socket API](https://herdr.dev/docs/socket-api/) explicitly distinguishes
+agent-state waits from arbitrary command completion. The
+[remote documentation](https://herdr.dev/docs/persistence-remote/) also
+separates a local thin client from running a client entirely on the server;
+only the former can directly bridge the local desktop clipboard.
+
+Keep one OATS session contract and both existing adapters for now. Do not add
+another supervisor above them. Qualify Herdr's actual literal multi-line
+input, exact occupant checks, detach, resize, process exit and remote behavior
+before selecting it as the default for new instances. Inspect `pane run`
+implementation before replacing it merely because its name sounds like shell
+execution. Removing tmux is a later deployment choice, not a prerequisite for
+consistent UI or remote agents. Existing tmux agents stay where they are.
+
+## Desktop correction sequence
+
+1. **Terminal essentials.** Hide viewer chrome, accept dropped files and pasted
+   images without pressing Enter, upload remote files to the execution host,
+   preserve the destination tab across async work, and show transfer failures.
+   Keep a single GUI and bounded viewers. This is the immediate implementation.
+2. **Keyboard and splits.** Restore Ctrl+Tab navigation inside Mac terminals;
+   let an already-open terminal fill an empty split without a second attach;
+   expose draggable and keyboard-operable separators. Follow up specific
+   keyboard reports with real input tests, especially terminal editing keys
+   and non-US layouts. App shortcuts must not silently steal terminal edits.
+3. **Souls & capabilities.** Replace the launch-centric roster with a management
+   surface showing souls, installed capabilities, effective layer providers,
+   source/version, scoped activation and runtime defaults. Inspect and launch
+   are distinct actions. Edits use existing CLI operations with the exact scope
+   visible; installing a capability must not silently activate it. This is not
+   a marketplace or Team Builder project.
+4. **Provider-neutral operations.** Introduce the scoped operation contract
+   above, then use it for manual harvest, schedules and knowledge inspection.
+   No second hardcoded default is accepted as a generalization.
+5. **Operating rollout.** Enable schedules per team with the owner's learning
+   policy. Capture-lock recovery is a separate reliability issue affecting
+   unattended harvesting; it does not block arbitrary scheduled wakes.
+
+Acceptance must include real Electron file objects, actual terminal bytes,
+remote transfer hashes, split focus/resize without extra PTYs, and a provider
+replacement fixture. Unit tests of mocked argv alone do not establish these
+boundaries. Reuse the existing agents and GUI sparingly; no model is needed to
+exercise attachment transport or terminal layout.

package/docs/desktop.md

@@ -211,3 +211,19 @@ certificate auto-discovery disabled) and
 marked build-verify mode (inventory + strict codesign verification +
 node-pty ABI, no GUI launch); a local
 interactive run may also exercise the launch phase.
+
+### Attach files and screenshots
+
+Drop a file onto an agent terminal to insert its path into that agent's draft.
+Pasting an image from the clipboard uses the same attachment path. Neither
+operation presses Enter. Text paste continues to use the terminal's normal
+paste behavior. A drop targets the pane under the pointer, including a visible
+pane in a split.
+
+Local files are referenced in place. Clipboard images are saved privately in
+Desktop's application-data `attachments` directory and retained so an agent can
+read them later. For remote terminals, Desktop calls the installed CLI's
+`session upload` operation; it inserts the returned path only after the file
+has reached the execution host. Both CLI installations must advertise
+`session-upload`. A failed transfer leaves the draft unchanged and shows an
+error in the terminal. Each drop/paste accepts up to 16 files totaling 25 MB.

package/docs/execution-targets.md

@@ -181,6 +181,27 @@ pane in that exact window. Herdr additionally verifies the original terminal ID.
 The broker owns busy/approval policy and must not interpret `submitted` as
 processing acknowledgement.
 
+### Attachments
+
+A viewer that drops a file or pastes an image gives the agent a path, never
+terminal input. `oats session upload --file <local> --home <abs>` stores a
+copy as a private file under `<home>/.oats-attachments/` (directory 0700,
+file 0600, `name-2` on collision) and answers `{path, bytes, sha256}`; the
+caller pastes `path` into the still-live session itself. With `--server <id>`
+and `--instance <name>` (or `--home`), the same saved route as attach is
+resolved, the remote must list `session-upload` in both its `remote` and
+`features` probe arrays, and the bytes travel on ssh stdin into `oats session
+receive --home <abs> --name <file>` on the execution host. Each side holds
+the whole file in memory up to the 64 MiB kernel bound (this is a bounded
+transfer, not end-to-end streaming); the receiver reads stdin event-driven,
+refuses above the bound before writing, and allocates the destination
+exclusively (`name-2`, `name-3` when taken), so simultaneous uploads of one
+name never overwrite each other and a planted symlink is never followed. The
+attachments directory must be a real directory inside the home. The local
+side refuses the result unless the remote's size and sha256 equal the local
+file's. A remote file is never a local path over SSH. Attachments live and
+die with the home.
+
 Capability spawn hooks register a pending home before runtime allocation;
 inspection becomes available once its receipt is persisted. Retire hooks
 unregister after quiescence. The broker must tolerate this lifecycle order and

package/docs/release-notes/v0.22.13.md

@@ -0,0 +1,44 @@
+# OATS v0.22.13
+
+Terminal essentials for the Desktop and one kernel operation behind them:
+attachments reach the agent as a path, never as typed input.
+
+## Attachments (kernel)
+
+`oats session upload --file <local> --home <abs>` copies a file into the
+instance home's private `.oats-attachments/` directory (0700, file 0600,
+`name-2` when the name is taken) and answers `{path, bytes, sha256}`. With
+`--server <id> --instance <name>` (or `--home`), the same saved route as
+`session attach` is resolved, the remote must advertise the new
+`session-upload` feature, and the bytes travel on ssh stdin into
+`oats session receive --home <abs> --name <file>` on the execution host,
+which reads stdin event-driven, enforces the 64 MiB kernel bound before
+writing anything, allocates the destination exclusively so simultaneous
+uploads never overwrite each other, refuses a symlinked or redirected
+attachments directory, and reports the path only after the bytes are
+synced. The local side refuses the answer unless size and sha256 equal the
+local file's. Each side buffers the whole file up to the bound; a remote
+file is never a local path over SSH. Upload never sends terminal input.
+`oats version --json` lists `session-upload` in `remote` and `features`.
+The CLI's temporary tmux viewer session hides its status line; the agents'
+session and the operator's tmux settings are untouched.
+
+## Desktop
+
+Drop files or paste clipboard images onto an agent terminal: the paths are
+inserted into the draft with bracketed paste and no Enter, local files in
+place, clipboard images saved privately under the app's data directory, and
+remote terminals uploaded through the installed CLI first (both CLIs must
+advertise `session-upload`; a failed transfer leaves the draft unchanged and
+never inserts a local path). Up to 16 files and 25 MB per drop. The viewer's
+tmux status bar is hidden. Ctrl+Tab stays tab navigation inside terminals
+on macOS while other Ctrl chords stay with the program. An already-open
+terminal fills an empty split without a second attach; separators resize by
+pointer or keyboard. Guide: docs/desktop.md, "Attach files and screenshots".
+
+## Design
+
+docs/design/2026-09-07-architecture-reassessment.md records the direction:
+keep the package and capability-layer machinery, fix the places where the
+CLI and GUI bypass it, one session contract with both tmux and Herdr
+adapters until Herdr is qualified, and the Desktop correction sequence.

package/docs/release-notes/v0.22.14.md

@@ -0,0 +1,48 @@
+# OATS v0.22.14
+
+The same reviewed content as the unpublished v0.22.13 tag, whose hosted
+run failed in one Desktop test pin before anything was published; the
+test now checks the behaviour instead of the source text.
+
+Terminal essentials for the Desktop and one kernel operation behind them:
+attachments reach the agent as a path, never as typed input.
+
+## Attachments (kernel)
+
+`oats session upload --file <local> --home <abs>` copies a file into the
+instance home's private `.oats-attachments/` directory (0700, file 0600,
+`name-2` when the name is taken) and answers `{path, bytes, sha256}`. With
+`--server <id> --instance <name>` (or `--home`), the same saved route as
+`session attach` is resolved, the remote must advertise the new
+`session-upload` feature, and the bytes travel on ssh stdin into
+`oats session receive --home <abs> --name <file>` on the execution host,
+which reads stdin event-driven, enforces the 64 MiB kernel bound before
+writing anything, allocates the destination exclusively so simultaneous
+uploads never overwrite each other, refuses a symlinked or redirected
+attachments directory, and reports the path only after the bytes are
+synced. The local side refuses the answer unless size and sha256 equal the
+local file's. Each side buffers the whole file up to the bound; a remote
+file is never a local path over SSH. Upload never sends terminal input.
+`oats version --json` lists `session-upload` in `remote` and `features`.
+The CLI's temporary tmux viewer session hides its status line; the agents'
+session and the operator's tmux settings are untouched.
+
+## Desktop
+
+Drop files or paste clipboard images onto an agent terminal: the paths are
+inserted into the draft with bracketed paste and no Enter, local files in
+place, clipboard images saved privately under the app's data directory, and
+remote terminals uploaded through the installed CLI first (both CLIs must
+advertise `session-upload`; a failed transfer leaves the draft unchanged and
+never inserts a local path). Up to 16 files and 25 MB per drop. The viewer's
+tmux status bar is hidden. Ctrl+Tab stays tab navigation inside terminals
+on macOS while other Ctrl chords stay with the program. An already-open
+terminal fills an empty split without a second attach; separators resize by
+pointer or keyboard. Guide: docs/desktop.md, "Attach files and screenshots".
+
+## Design
+
+docs/design/2026-09-07-architecture-reassessment.md records the direction:
+keep the package and capability-layer machinery, fix the places where the
+CLI and GUI bypass it, one session contract with both tmux and Herdr
+adapters until Herdr is qualified, and the Desktop correction sequence.

package/lib/attachments.mjs

@@ -0,0 +1,164 @@
+/** Instance attachments: bytes a viewer drops or pastes for an agent, kept as
+ *  private files INSIDE the instance home so the agent can read them by path.
+ *  Upload never touches the terminal; the caller pastes the returned path.
+ *  Remote uploads stream through the same ssh transport as every routed
+ *  command, into `oats session receive` on the execution host. */
+import { createHash } from "node:crypto";
+import { closeSync, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readSync, rmSync, statSync, writeSync, realpathSync } from "node:fs";
+import { basename, extname, isAbsolute, join, resolve, sep } from "node:path";
+import { checkRemote, resolveRoute, runRemote, serverError } from "./servers.mjs";
+
+export const ATTACHMENTS_DIRNAME = ".oats-attachments";
+/** Kernel bound per file; a GUI imposes its own stricter interaction bound. */
+export const MAX_ATTACHMENT_BYTES = 64 * 1024 * 1024;
+/** The kernel version whose probe first advertises session-upload. */
+export const SESSION_UPLOAD_REMOTE_VERSION = "0.22.13";
+
+const err = (code, message, extra) => Object.assign(new Error(message), { code, ...(extra || {}) });
+
+/** A file name as it will exist in the attachments directory: one path
+ *  segment, printable, never a dot name, at most 200 bytes. */
+export function attachmentName(name) {
+  if (typeof name !== "string" || !name.trim()) throw err("E_BAD_ARGS", "attachment name must be a non-empty file name");
+  if (name.includes("/") || name.includes("\\") || name.includes("\0")) throw err("E_BAD_ARGS", "attachment name must be a single path segment without slashes or NUL");
+  if (/[\x00-\x1f\x7f]/.test(name)) throw err("E_BAD_ARGS", "attachment name must not contain control characters");
+  if (name === "." || name === "..") throw err("E_BAD_ARGS", "attachment name may not be a dot name");
+  // Deliberate: a name starting with a dash would read as an option on the
+  // remote command line; the caller renames the file (screenshots never
+  // start with one).
+  if (name.startsWith("-")) throw err("E_BAD_ARGS", `attachment name ${JSON.stringify(name)} starts with a dash; rename the file before attaching it`);
+  if (Buffer.byteLength(name) > 200) throw err("E_BAD_ARGS", "attachment name is longer than 200 bytes");
+  return name;
+}
+
+export function sha256Hex(bytes) { return createHash("sha256").update(bytes).digest("hex"); }
+
+/** Read a REGULAR file descriptor to its end, refusing once more than
+ *  `maxBytes` arrive. Regular files never answer EAGAIN; pipes must use
+ *  readStreamBounded, which waits for data instead of spinning. */
+export function readBounded(fd, maxBytes = MAX_ATTACHMENT_BYTES) {
+  const chunks = [];
+  let total = 0;
+  const buf = Buffer.allocUnsafe(1024 * 1024);
+  for (;;) {
+    const n = readSync(fd, buf, 0, buf.length, null);
+    if (n === 0) break;
+    total += n;
+    if (total > maxBytes) throw err("E_UPLOAD_TOO_LARGE", `attachment exceeds the kernel bound of ${maxBytes} bytes`);
+    chunks.push(Buffer.from(buf.subarray(0, n)));
+  }
+  return Buffer.concat(chunks, total);
+}
+
+/** Collect a readable stream (stdin from ssh) into memory, bounded: the
+ *  read is event-driven, so a slow or stalled sender costs no CPU, and the
+ *  bound is checked as chunks arrive, before anything is written. The whole
+ *  file is buffered on both sides (up to the bound); this is not end-to-end
+ *  streaming. */
+export async function readStreamBounded(stream, maxBytes = MAX_ATTACHMENT_BYTES) {
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of stream) {
+    const b = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    total += b.length;
+    if (total > maxBytes) { stream.destroy?.(); throw err("E_UPLOAD_TOO_LARGE", `attachment exceeds the kernel bound of ${maxBytes} bytes`); }
+    chunks.push(b);
+  }
+  return Buffer.concat(chunks, total);
+}
+
+function instanceHomeOf(home) {
+  if (typeof home !== "string" || !isAbsolute(home)) throw err("E_BAD_ARGS", "attachments need an absolute instance home");
+  if (!existsSync(join(home, "instance.json"))) throw err("E_SESSION_UNKNOWN", `${home} is not an OATS instance home (no instance.json); nothing was written`);
+  return realpathSync(home);
+}
+
+/** The attachments directory must be a real directory inside the home: a
+ *  symlink planted there (or a file) must not turn a receive into a write
+ *  somewhere else. Created 0700 when absent. */
+function attachmentsDir(realHome) {
+  const dir = join(realHome, ATTACHMENTS_DIRNAME);
+  let st;
+  try { st = lstatSync(dir); }
+  catch (e) {
+    if (e.code !== "ENOENT") throw e;
+    // Two first uploads may both see ENOENT: the loser's mkdir answers
+    // EEXIST and it validates what the winner (or a planted entry) put there.
+    try { mkdirSync(dir, { mode: 0o700 }); } catch (m) { if (m.code !== "EEXIST") throw m; }
+    st = lstatSync(dir);
+  }
+  if (st.isSymbolicLink() || !st.isDirectory()) throw err("E_UPLOAD_FAILED", `${dir} is not a real directory inside the instance home; nothing was written`);
+  const real = realpathSync(dir);
+  if (real !== dir && !real.startsWith(realHome + sep)) throw err("E_UPLOAD_FAILED", `${dir} resolves outside the instance home; nothing was written`);
+  return dir;
+}
+
+/** Store `bytes` as a private file under <home>/.oats-attachments/<name>,
+ *  taking name-2, name-3 ... when the name is taken. The destination is
+ *  allocated exclusively (O_CREAT|O_EXCL, 0600): two simultaneous uploads
+ *  of the same name get two files and neither clobbers the other, and a
+ *  symlink planted under a candidate name is skipped, never followed. The
+ *  path is reported only after the bytes are written and synced. */
+export function receiveAttachment(home, name, bytes, { maxBytes = MAX_ATTACHMENT_BYTES } = {}) {
+  const realHome = instanceHomeOf(home);
+  const safe = attachmentName(name);
+  if (!Buffer.isBuffer(bytes)) throw err("E_BAD_ARGS", "attachment bytes must be a Buffer");
+  if (bytes.length > maxBytes) throw err("E_UPLOAD_TOO_LARGE", `attachment exceeds the kernel bound of ${maxBytes} bytes`);
+  const dir = attachmentsDir(realHome);
+  const ext = extname(safe), stem = safe.slice(0, safe.length - ext.length);
+  for (let i = 1; i <= 10000; i++) {
+    const path = i === 1 ? join(dir, safe) : join(dir, `${stem}-${i}${ext}`);
+    let fd;
+    try { fd = openSync(path, "wx", 0o600); }
+    catch (e) { if (e.code === "EEXIST") continue; throw e; }
+    try {
+      let off = 0;
+      while (off < bytes.length) off += writeSync(fd, bytes, off, bytes.length - off);
+      fsyncSync(fd);
+    } catch (e) { closeSync(fd); rmSync(path, { force: true }); throw e; }
+    closeSync(fd);
+    return { path, bytes: bytes.length, sha256: sha256Hex(bytes) };
+  }
+  throw err("E_UPLOAD_FAILED", `no free name for ${safe} under ${dir}`);
+}
+
+function readLocalFile(file, maxBytes) {
+  if (typeof file !== "string" || !file) throw err("E_BAD_ARGS", "--file needs a path");
+  const abs = resolve(file);
+  let st;
+  try { st = statSync(abs); } catch { throw err("E_BAD_ARGS", `no such file: ${abs}`); }
+  if (!st.isFile()) throw err("E_BAD_ARGS", `${abs} is not a regular file`);
+  if (st.size > maxBytes) throw err("E_UPLOAD_TOO_LARGE", `${abs} is ${st.size} bytes; the kernel bound is ${maxBytes}`);
+  const fd = openSync(abs, "r");
+  try { if (fstatSync(fd).size !== st.size) throw err("E_UPLOAD_FAILED", `${abs} changed while being read`); return { abs, bytes: readBounded(fd, maxBytes) }; }
+  finally { closeSync(fd); }
+}
+
+/** Upload a local file into an instance's attachments: locally by home, or
+ *  on the execution host of a registered server through its saved route
+ *  (the same resolution as session attach). The remote answer's sha256 and
+ *  size must equal the local file's before the path is reported. */
+export function uploadAttachment({ file, home, server, instance }, io = {}) {
+  const maxBytes = io.maxBytes || MAX_ATTACHMENT_BYTES;
+  const { abs, bytes } = readLocalFile(file, maxBytes);
+  const name = basename(abs);
+  const sha256 = sha256Hex(bytes);
+  if (!server) {
+    if (!home) throw err("E_BAD_ARGS", "session upload needs --home </absolute/instance> or --server <id> with --instance <name> or --home");
+    return { ...receiveAttachment(home, name, bytes, { maxBytes }), name, home: realpathSync(home), source: abs };
+  }
+  const route = resolveRoute(server, { instance, home }, "session upload");
+  const remote = checkRemote(route.target, io);
+  // Both lists must carry the token; a probe without the arrays is an old kernel.
+  const advertises = (list) => Array.isArray(list) && list.includes("session-upload");
+  if (!advertises(remote.remote) || !advertises(remote.features)) {
+    throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${route.target.sshHost} does not advertise session-upload (kernels from ${SESSION_UPLOAD_REMOTE_VERSION} do); upgrade it there; nothing was sent`);
+  }
+  const { envelope, stderr } = runRemote(route.target, ["session", "receive", "--home", route.home, "--name", name, "--json"], { ...io, input: bytes, timeoutMs: io.timeoutMs || 600000 });
+  if (!envelope.ok) throw serverError(envelope.error?.code || "E_UPLOAD_FAILED", `${server}: ${envelope.error?.message || "receive failed"}`);
+  const r = envelope.result || {};
+  if (r.sha256 !== sha256 || r.bytes !== bytes.length || typeof r.path !== "string" || !r.path.startsWith("/")) {
+    throw serverError("E_UPLOAD_FAILED", `${server} stored ${r.bytes ?? "?"} bytes with sha256 ${r.sha256 ?? "?"} at ${r.path || "?"}, but the local file is ${bytes.length} bytes with sha256 ${sha256}; the remote file is left for inspection`);
+  }
+  return { path: r.path, bytes: r.bytes, sha256: r.sha256, name, home: route.home, server, instance: instance || route.snapshot?.instance, source: abs, ...(stderr?.trim() ? { stderr: stderr.trim() } : {}) };
+}

package/lib/servers.mjs

@@ -185,7 +185,9 @@ export function runRemote(target, oatsArgs, io = {}) {
   let stderr = "";
   let status = 0;
   try {
-    stdout = exec(bin, argv, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 16 * 1024 * 1024, timeout: io.timeoutMs || 300000 });
+    // `io.input` (a Buffer) streams to the remote command's stdin: the only
+    // way bytes reach a host, as a quoted argument never could.
+    stdout = exec(bin, argv, { encoding: "utf8", stdio: [io.input === undefined ? "ignore" : "pipe", "pipe", "pipe"], ...(io.input === undefined ? {} : { input: io.input }), maxBuffer: 16 * 1024 * 1024, timeout: io.timeoutMs || 300000 });
   } catch (e) {
     stdout = String(e.stdout || "");
     stderr = String(e.stderr || e.message || "");

package/lib/session-viewer.mjs

@@ -26,6 +26,10 @@ export function prepareSessionViewer(target, { exec = execFileSync } = {}) {
     // when this agent retires. Disable window navigation in the viewer only.
     for (const name of ["prefix", "prefix2"]) run(["set-option", "-t", viewer, name, "None"]);
     run(["set-option", "-t", viewer, "key-table", "oatsview-locked"]);
+    // The viewer shows one agent; its status line only repeats that name.
+    // Session-scoped on the temporary viewer: the agents' own session and
+    // the operator's tmux settings are untouched.
+    run(["set-option", "-t", viewer, "status", "off"]);
     run(["unbind-key", "-a", "-q", "-T", "oatsview-locked"]);
     run(["bind-key", "-T", "oatsview-locked", "WheelUpPane", "if-shell", "-F", "#{||:#{pane_in_mode},#{mouse_any_flag}}", "send-keys -M", "copy-mode -e; send-keys -M"]);
     run(["set-option", "-t", viewer, "mouse", "on"]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.22.12",
+  "version": "0.22.14",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",