@awebai/oats 0.22.12 → 0.22.16

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

@@ -0,0 +1,53 @@
+# OATS v0.22.16
+
+The same reviewed content as the unpublished v0.22.15 tag, whose hosted
+run failed in frozen test data (retirement goldens still carrying the
+removed `harvested` field, and a Desktop harvest fixture predating the
+operations gate) before anything was published; only tests changed.
+
+Souls and capabilities become something you inspect and manage, through
+one kernel contract, and knowledge providers declare what they can do.
+
+## Provider operations and inspection (kernel)
+
+`oats inspect --json` answers everything a GUI needs in one envelope for a
+scope, a selected soul or a running home: souls with runtime defaults,
+editability and instructions; installed capabilities with health from the
+package engine, separately from their effective activation, provenance and
+settings; effective layer bindings; and the operations each provider
+declares, with availability and the reason when unavailable. For a home the
+answer is its captured bindings (with current manifests and trust), the live
+config beside it, and the drift between them. Same-named souls in member
+repositories are addressed by name plus agents root; a home selects its own
+soul under its own root.
+
+`oats operation run <layer>:<name>` resolves the provider that fills a layer
+for a home or a soul, checks declaration, trust and host requirements, runs
+the provider's own command in the right place with the right identity, and
+relays its receipt; a view answers labeled documents. Unconfirmed outcomes
+carry what was observed and a scheduled operation keeps its slot until
+reconciled. Manifests declare `operations`. Schedules gain kind
+`operation`. `oats use --json` answers receipts and `--inherit` returns a
+level to inheritance; `oats soul set` edits an editable soul's defaults and
+instructions in place. All four route to a registered server through the
+saved route; the probe advertises `operations` and `operationsApi: 1`. The
+retire receipt no longer implies a harvest. See
+docs/design/operations-contract.md.
+
+## oats.okf 1.6.0
+
+The official knowledge provider declares `inspect` (a view of STATE.md,
+log.md and pending notes) and `harvest` (the existing action); the catalog
+pins v1.6.0. Existing scopes keep their locked 1.5.2 until their owners
+update them; the GUI then shows no operations for those providers, which is
+the truthful state.
+
+## Desktop
+
+Souls & capabilities replaces the launch-centric roster: select a soul to
+inspect it, Launch and Schedule are explicit, defaults and instructions are
+editable where the kernel says so, installed capabilities are shown apart
+from activation with enable, disable and inherit at an exact scope, an
+instance's menu opens Knowledge & capabilities, provider views render as
+text, and schedules run declared provider operations. See
+docs/design/2026-09-07-desktop-souls-capabilities.md.

package/docs/schedules.md

@@ -56,6 +56,15 @@ and no queue.
   home is started again only at due minutes, never every minute, so a
   harness that keeps exiting is not restarted in a loop. A job holds at most
   one pending delivery: a due minute while one is pending adds nothing.
+- **operation** `{id, enabled, cron, tz, kind: "operation", operation, home}`
+  — runs a provider operation such as `knowledge:harvest` in the instance at
+  `home` through `oats operation run <layer>:<name> --home <home>`. The
+  provider is whatever fills that layer for the home when the job runs (its
+  snapshot), not something stored in the job, so the job stays valid across
+  provider changes and a GUI can list and edit it without parsing argv.
+  Admission, tracking and reconciliation are those of a command job: a
+  launch receipt the provider answers (a harvester it spawned) is followed
+  until that home is gone; the source home is never treated as a launch.
   Unobservable or still starting: skipped with the reason, delivery kept
   pending. Whether a running harness is busy cannot be seen from the
   terminal: delivery is terminal input (bracketed paste plus Enter), never an

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/core.mjs

@@ -987,9 +987,45 @@ function loadManifestAt(idir, origin) {
     if (hookDeclaration(value)?.required && hook !== "spawn") throw new Error(`capability ${id} hook "${hook}" cannot be required — only the spawn hook is enforced (retire and soul-scaffold run outside a spawn transaction)`);
   }
   if (m.agents !== undefined && (!Array.isArray(m.agents) || m.agents.some((a) => typeof a !== "string"))) throw new Error(`capability ${id} "agents" must be an array of package-relative soul directories`);
+  validateManifestOperations(m, id);
   return { ...m, _dir: idir, _origin: origin };
 }
 
+/** `operations`: what a capability offers a GUI or scheduler by name, each
+ *  delegating to one of its own `commands`. kind "action" runs something;
+ *  kind "view" answers { documents: [...] } for presentation (a knowledge
+ *  provider's own view of an instance's working knowledge). context "home"
+ *  runs in an instance home; "scope" runs in the config scope. */
+const OPERATION_NAME_RE = /^[a-z][a-z0-9-]*$/;
+function validateManifestOperations(m, id) {
+  if (m.operations === undefined) return;
+  if (!m.operations || typeof m.operations !== "object" || Array.isArray(m.operations)) throw new Error(`capability ${id} "operations" must be an object map`);
+  for (const [name, op] of Object.entries(m.operations)) {
+    if (!OPERATION_NAME_RE.test(name)) throw new Error(`capability ${id} operation "${name}": name must match ${OPERATION_NAME_RE.source}`);
+    if (!op || typeof op !== "object" || Array.isArray(op)) throw new Error(`capability ${id} operation "${name}" must be an object`);
+    if (typeof op.command !== "string" || !Object.prototype.hasOwnProperty.call(m.commands || {}, op.command)) throw new Error(`capability ${id} operation "${name}": "command" must name one of the manifest's commands`);
+    if (op.kind !== undefined && !["action", "view"].includes(op.kind)) throw new Error(`capability ${id} operation "${name}": "kind" must be action or view`);
+    if (op.context !== undefined && !["home", "scope"].includes(op.context)) throw new Error(`capability ${id} operation "${name}": "context" must be home or scope`);
+    if (op.description !== undefined && typeof op.description !== "string") throw new Error(`capability ${id} operation "${name}": "description" must be a string`);
+    if (op.args !== undefined) {
+      if (!Array.isArray(op.args)) throw new Error(`capability ${id} operation "${name}": "args" must be an array`);
+      for (const a of op.args) {
+        if (!a || typeof a !== "object" || typeof a.name !== "string" || !OPERATION_NAME_RE.test(a.name)) throw new Error(`capability ${id} operation "${name}": each arg needs a name matching ${OPERATION_NAME_RE.source}`);
+        if (a.flag !== undefined && (typeof a.flag !== "string" || !/^--[a-z][a-z0-9-]*$/.test(a.flag))) throw new Error(`capability ${id} operation "${name}" arg "${a.name}": "flag" must look like --name`);
+        if (a.required !== undefined && typeof a.required !== "boolean") throw new Error(`capability ${id} operation "${name}" arg "${a.name}": "required" must be a boolean`);
+      }
+    }
+  }
+}
+/** The normalized operations a manifest declares (empty when none). */
+export function manifestOperations(manifest) {
+  return Object.entries(manifest?.operations || {}).map(([name, op]) => ({
+    name, kind: op.kind || "action", command: op.command, context: op.context || "home",
+    description: op.description || null,
+    args: (op.args || []).map((a) => ({ name: a.name, flag: a.flag || `--${a.name}`, required: !!a.required, description: a.description || null })),
+  }));
+}
+
 /** Discover capability manifests. Later sources take precedence: outer scopes < inner scopes; installed < owned within one scope. Duplicates inside one source layer are errors. */
 export function capabilityManifests(startDir) {
   // Capability-id keyed — never answer for `constructor`/`toString`. The ids
@@ -7230,7 +7266,6 @@ export function retireInstance(root, name, o = {}) {
       contextDir: meta.repo, workspaceDir: workspaceOf(root), rootDir: root, resolved, priorMeta: meta.capabilityMeta || {},
     });
   }
-  const harvested = hookResults?.meta?.["oats.okf"]?.harvested || [];
 
   // ORDINARY retirement must not delete a home whose cleanup did not finish.
   // The failures were already collected above; until now they were read ONLY on
@@ -7439,7 +7474,7 @@ export function retireInstance(root, name, o = {}) {
   }
 
 
-  const result = { retired: name, agent: found.agent.name, workRecovery, workRecoveries: workRecoveries.length > 1 ? workRecoveries : undefined, worktreeRemoved: isWorktree, branchDeleted: !!(o.deleteBranch && meta.branch) || quarantineBranchDeleted, removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, harvested, relinked: relinked.length ? relinked : undefined, capabilityMeta: hookResults?.meta, warnings: hookResults?.warnings?.length ? hookResults.warnings : undefined };
+  const result = { retired: name, agent: found.agent.name, workRecovery, workRecoveries: workRecoveries.length > 1 ? workRecoveries : undefined, worktreeRemoved: isWorktree, branchDeleted: !!(o.deleteBranch && meta.branch) || quarantineBranchDeleted, removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, relinked: relinked.length ? relinked : undefined, capabilityMeta: hookResults?.meta, warnings: hookResults?.warnings?.length ? hookResults.warnings : undefined };
   if (self) {
     // The caller is the instance: its process lives in the window we are about to
     // kill. Detach the kill so this function can return and the caller can report

package/lib/schedule.mjs

@@ -40,11 +40,12 @@ export function scheduleError(code, message, extra) { return Object.assign(new E
  *  is never observed or executed, and is reported invalid on that job only. */
 export function shapeError(def) {
   if (!def || typeof def !== "object" || Array.isArray(def)) return "definition is not an object";
-  if (!["spawn", "command", "wake"].includes(def.kind)) return `kind ${JSON.stringify(def.kind)} is not spawn, command or wake`;
+  if (!["spawn", "command", "wake", "operation"].includes(def.kind)) return `kind ${JSON.stringify(def.kind)} is not spawn, command, wake or operation`;
   if (typeof def.cron !== "string" || typeof def.tz !== "string") return "cron and tz must be strings";
   if (def.kind === "spawn" && typeof def.agent !== "string") return "agent must be a string";
   if (def.kind === "command" && (typeof def.cwd !== "string" || !Array.isArray(def.argv))) return "cwd and argv are required";
   if (def.kind === "wake" && (typeof def.home !== "string" || typeof def.message !== "string")) return "home and message are required";
+  if (def.kind === "operation" && (typeof def.operation !== "string" || typeof def.home !== "string")) return "operation and home are required";
   return null;
 }
 
@@ -229,7 +230,14 @@ export function validateDefinition(ws, def, { checkAgent = true } = {}) {
     if (typeof def.home !== "string" || !isAbsolute(def.home) || !inside(ws, def.home) || !existsSync(join(def.home, "instance.json"))) throw scheduleError("E_SCHEDULE_INVALID", "home: an existing instance home inside the scope", { field: "home" });
     validateMessage(def.message, "message");
     out.home = resolve(def.home); out.message = def.message;
-  } else throw scheduleError("E_SCHEDULE_INVALID", "kind: spawn, command or wake", { field: "kind" });
+  } else if (def.kind === "operation") {
+    // A provider operation in a running home, resolved when the job runs
+    // (oats operation run <layer>:<name> --home): the provider is whatever
+    // fills that layer for the home then; nothing about it is stored here.
+    if (typeof def.operation !== "string" || !/^(knowledge|messaging|tasks):[a-z][a-z0-9-]*$/.test(def.operation)) throw scheduleError("E_SCHEDULE_INVALID", "operation: <layer>:<name>, e.g. knowledge:harvest", { field: "operation" });
+    if (typeof def.home !== "string" || !isAbsolute(def.home) || !inside(ws, def.home) || !existsSync(join(def.home, "instance.json"))) throw scheduleError("E_SCHEDULE_INVALID", "home: an existing instance home inside the scope", { field: "home" });
+    out.operation = def.operation; out.home = resolve(def.home);
+  } else throw scheduleError("E_SCHEDULE_INVALID", "kind: spawn, command, wake or operation", { field: "kind" });
   return out;
 }
 
@@ -320,6 +328,13 @@ function launchSpawn(ws, def, minute, io) {
   }
   return run;
 }
+/** The command job an operation job becomes when it runs: the kernel's own
+ *  operation runner in the home, which resolves the provider at that moment
+ *  and reports a launch receipt (instance/home) only for what the provider
+ *  launched, never for the source home. */
+export function operationAsCommand(def) {
+  return { ...def, kind: "command", cwd: def.home, argv: ["oats", "operation", "run", def.operation, "--home", def.home] };
+}
 /** Parse a command's stdout as one JSON document (remote output can be
  *  multi-line); fall back to the last {...} block; null when nothing parses. */
 export function parseEnvelopeText(text) {
@@ -355,9 +370,16 @@ function launchCommand(ws, def, io) {
   if (instance && !home) { const found = findHomesInScope(ws, instance); if (found.length === 1) home = found[0]; }
   if (envelope.ok && instance && !home) return { kind: "command", launched: true, instance, unconfirmed: true, error: `the envelope names instance ${instance} but no home for it is in this scope's roster; run oats schedule reconcile once it appears` };
   // A valid ok:false answer that reports an incomplete rollback (a harvest
-  // spawn whose compensation could not stop or remove everything) is not a
-  // confirmed failure either.
-  if (!envelope.ok && reportsRetainedEffects(envelope.error?.message)) return { kind: "command", launched: false, unconfirmed: true, ...(instance ? { instance } : {}), error: `command failed with retained effects: ${envelope.error?.message}`, errorCode: envelope.error?.code };
+  // spawn whose compensation could not stop or remove everything), or an
+  // operation runner's unconfirmed outcome (timeout, no valid receipt, a
+  // receipt contradicted by the exit status), is not a confirmed failure.
+  // Whatever name the provider managed to answer travels in error.details
+  // so reconcile can adopt it.
+  if (!envelope.ok && (UNCONFIRMED_ERROR_CODES.has(envelope.error?.code) || envelope.error?.details?.unconfirmed === true || reportsRetainedEffects(envelope.error?.message))) {
+    const partial = envelope.error?.details?.envelope?.result;
+    const named = instance || (partial && typeof partial.instance === "string" ? partial.instance : undefined);
+    return { kind: "command", launched: false, unconfirmed: true, ...(named ? { instance: named } : {}), error: `command outcome unconfirmed: ${envelope.error?.message}`, errorCode: envelope.error?.code };
+  }
   return { kind: "command", launched: envelope.ok === true, ...(instance ? { instance } : {}), ...(home ? { home } : {}), ...(envelope.ok ? {} : { error: envelope.error?.message || "command failed", errorCode: envelope.error?.code }) };
 }
 /** One wake. `startIfStopped` false between due minutes (a harness that
@@ -367,6 +389,8 @@ function launchCommand(ws, def, io) {
  *  confirm (spawn compensation's "rollback INCOMPLETE", a quarantined or
  *  retained home): the launch's effects are unconfirmed, never a confirmed
  *  failure. Shared by caught spawn errors and ok:false command envelopes. */
+/** Error codes whose meaning is "the effects are unconfirmed" by contract. */
+const UNCONFIRMED_ERROR_CODES = new Set(["E_OPERATION_TIMEOUT", "E_OPERATION_RESULT"]);
 export function reportsRetainedEffects(message) { return /INCOMPLETE|quarantin|retain|could not (?:be )?(?:verif|confirm)/i.test(String(message || "")); }
 function performWake(def, io, { startIfStopped = true, canStart = true, reserve } = {}) {
   const seen = observeHome(def.home, io);
@@ -498,7 +522,7 @@ export function tickWorkspace(ws, { now = new Date(), io, reg, wsList, dryRun =
     js.lastLaunchedAt = now.toISOString();
     writeState(ws, st);
     let run;
-    try { run = def.kind === "command" ? launchCommand(ws, def, io) : launchSpawn(ws, def, minute, io); }
+    try { run = def.kind === "spawn" ? launchSpawn(ws, def, minute, io) : launchCommand(ws, def.kind === "operation" ? operationAsCommand(def) : def, io); }
     catch (e) {
       // spawnInstance compensates its own failures, but its rollback can be
       // INCOMPLETE (a pane it could not stop, a quarantined home it kept):
@@ -595,7 +619,7 @@ export function reconcile(ws, id, { io, now = new Date(), clear = false } = {})
       const homes = findHomesInScope(ws, `${def.agent}-${purpose}`);
       if (homes.length === 1) adopted = { instance: `${def.agent}-${purpose}`, home: homes[0] };
       else if (homes.length > 1) ambiguous = `${homes.length} homes named ${def.agent}-${purpose}: ${homes.join(", ")}`;
-    } else if (def.kind === "command") {
+    } else if (def.kind === "command" || def.kind === "operation") {
       const named = js.lastRun?.instance ? findHomesInScope(ws, js.lastRun.instance).map((home) => ({ instance: js.lastRun.instance, home })) : [];
       if (named.length === 1) adopted = named[0];
       else if (named.length > 1) ambiguous = `${named.length} homes named ${js.lastRun.instance}: ${named.map((c) => c.home).join(", ")}`;
@@ -651,7 +675,7 @@ export function updateSchedule(ws, id, spec, io) {
   return withHostLock(() => withScopeLock(ws, () => {
     const defs = readDefinitions(ws);
     if (!defs.jobs[id]) throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}`);
-    const identity = (d) => JSON.stringify([d.kind, d.agent, d.agentsRoot, d.repo, d.purpose, d.home, d.cwd, d.argv]);
+    const identity = (d) => JSON.stringify([d.kind, d.agent, d.agentsRoot, d.repo, d.purpose, d.home, d.cwd, d.argv, d.operation]);
     const busy = !!jobLockInfo(ws, id) || !!readState(ws).jobs[id]?.attempt;
     if (busy && identity(defs.jobs[id]) !== identity(def)) throw scheduleError("E_SCHEDULE_RUNNING", `schedule ${id} is running or has an unresolved attempt; its kind, agent, agentsRoot, repo, purpose, home, cwd and argv cannot change until it ends (cron, tz, task, message, runtime, model and enabled can)`);
     defs.jobs[id] = { ...def, createdAt: defs.jobs[id].createdAt, updatedAt: new Date().toISOString() };

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 || "");
@@ -230,6 +232,7 @@ export function checkRemote(target, io = {}) {
     launchOptions: list("launchOptions", []),
     remote: list("remote", []),
     features: list("features", []),
+    operationsApi: probe.operationsApi === 1 ? 1 : null,
     advertised: Array.isArray(probe.runtimes),
   };
 }
@@ -477,7 +480,34 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
     const { envelope, stderr } = runRemote(target, json(withScope(["status", ...oatsArgs])), io);
     return { envelope: envelope.ok ? { ...envelope, result: { ...envelope.result, server: serverId, target, snapshots: listSnapshots(serverId) } } : envelope, stderr };
   }
-  throw serverError("E_USAGE", `--server routes spawn, retire, status, session and okf harvest only (not ${cmd})`);
+  if (OPERATIONS_COMMANDS.has(cmd)) {
+    // The operations contract (inspect, operation run, use, soul set): the
+    // remote must advertise it before anything is sent. An explicit --dir is
+    // the exact member context the caller chose and travels as is; without
+    // one, a --home selection is left to the host (the home is its own
+    // context) and anything else runs in the registered workspace.
+    // An exact remote home (or a saved instance name) resolves through its
+    // FROZEN route exactly as session attach does: the snapshot's target,
+    // and a home/name disagreement is refused; the registration's target is
+    // used only for scope requests, which get its workspace as --dir.
+    let args = [...oatsArgs];
+    const valueOf = (name) => { const i = args.indexOf(name); return i >= 0 && args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : undefined; };
+    let route;
+    if (valueOf("--home") !== undefined || valueOf("--instance") !== undefined) {
+      route = resolveRoute(serverId, { instance: valueOf("--instance"), home: valueOf("--home") }, cmd);
+      target = route.target;
+      const ii = args.indexOf("--instance");
+      if (ii >= 0) { args.splice(ii, 2); if (valueOf("--home") === undefined) args.push("--home", route.home); }
+    }
+    const remote = checkRemote(target, io);
+    if (!Array.isArray(remote.features) || !remote.features.includes("operations") || remote.operationsApi !== 1) {
+      throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost} does not advertise the operations contract (kernels from ${OPERATIONS_REMOTE_VERSION} do); upgrade it there; nothing was sent`);
+    }
+    const scoped = args.includes("--dir") || args.includes("--home") ? args : [...args, "--dir", target.workspace];
+    const { envelope, stderr } = runRemote(target, json([cmd, ...scoped]), io);
+    return { envelope: envelope.result && typeof envelope.result === "object" ? { ...envelope, result: { ...envelope.result, server: serverId, ...(route ? { route: { home: route.home, instance: route.snapshot?.instance || null, frozen: !!route.snapshot } } : {}) } } : envelope, stderr };
+  }
+  throw serverError("E_USAGE", `--server routes spawn, retire, status, session, okf harvest, schedule, inspect, operation, use and soul only (not ${cmd})`);
 }
 
 // ------------------------------------------------------------------- roster
@@ -619,6 +649,9 @@ export function inspectRemote(serverId, { instance, home } = {}, io = {}) {
 /** The kernel version whose probe first advertises the `session-start`
  *  feature; the probe's features list is the actual check. */
 export const SESSION_START_REMOTE_VERSION = "0.22.9";
+/** The kernel version whose probe first advertises the operations contract. */
+export const OPERATIONS_REMOTE_VERSION = "0.22.16";
+const OPERATIONS_COMMANDS = new Set(["inspect", "operation", "use", "soul"]);
 
 /** `session start` on the execution host for a remote instance: the same
  *  route resolution as inspect, refused before any mutation when the remote

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-catalog.json

@@ -2,7 +2,7 @@
   "packages": {
     "oats.okf": {
       "url": "https://github.com/awebai/oats-okf.git",
-      "ref": "v1.5.2",
+      "ref": "v1.6.0",
       "path": "oats-package"
     },
     "oats.aweb": {
@@ -33,12 +33,33 @@
   },
   "capabilities": {
     "oats.review": "oats.dev",
-    "oas.okf": { "package": "oats.okf", "capability": "oats.okf" },
-    "oas.aweb": { "package": "oats.aweb", "capability": "oats.aweb" },
-    "oas.jira": { "package": "oats.jira", "capability": "oats.jira" },
-    "oas.linear": { "package": "oats.linear", "capability": "oats.linear" },
-    "oas.authoring": { "package": "oats.authoring", "capability": "oats.authoring" },
-    "oas.dev": { "package": "oats.dev", "capability": "oats.dev" },
-    "oas.review": { "package": "oats.dev", "capability": "oats.review" }
+    "oas.okf": {
+      "package": "oats.okf",
+      "capability": "oats.okf"
+    },
+    "oas.aweb": {
+      "package": "oats.aweb",
+      "capability": "oats.aweb"
+    },
+    "oas.jira": {
+      "package": "oats.jira",
+      "capability": "oats.jira"
+    },
+    "oas.linear": {
+      "package": "oats.linear",
+      "capability": "oats.linear"
+    },
+    "oas.authoring": {
+      "package": "oats.authoring",
+      "capability": "oats.authoring"
+    },
+    "oas.dev": {
+      "package": "oats.dev",
+      "capability": "oats.dev"
+    },
+    "oas.review": {
+      "package": "oats.dev",
+      "capability": "oats.review"
+    }
   }
 }

package/package.json

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