@awebai/oats 0.22.17 → 0.22.19

package/lib/servers.mjs

@@ -252,7 +252,8 @@ export function checkRemoteSupport(remote, target, oatsArgs, roster) {
   // capability-defined agent, or one with no live instance) has no default
   // this side can establish: the remote kernel validates its own default at
   // spawn, and nothing is asserted here about it.
-  const runtime = flagOf("--runtime") || soul?.runtime;
+  const namedConfig = oatsArgs.includes("--launch-config");
+  const runtime = flagOf("--runtime") || (namedConfig ? undefined : soul?.runtime);
   // What the message may claim depends on what was established: an
   // advertising remote said what it supports; a silent one (before 0.22.2)
   // said nothing, and only pi and claude are assumed of it.
@@ -260,6 +261,7 @@ export function checkRemoteSupport(remote, target, oatsArgs, roster) {
     ? `it advertises runtimes ${remote.runtimes.join(", ")}${remote.sessionBackends.length ? `, session backends ${remote.sessionBackends.join(", ")}` : ", no session backend choice"}${remote.launchOptions.length ? `, launch options ${remote.launchOptions.join(", ")}` : ", no launch options"}`
     : `it does not advertise what it supports (kernels before 0.22.2 do not), so only pi and claude on tmux with no launch options are assumed of it; upgrade it there to use more`;
   const refuse = (what) => { throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost}: ${what} was not established as supported there (${supports})`); };
+  if (namedConfig && !remote.features.includes("launch-config")) refuse("a named launch configuration (the host must advertise launch-config)");
   if (runtime && !remote.runtimes.includes(runtime)) refuse(`runtime ${runtime}${flagOf("--runtime") ? "" : ` (the default of soul ${agent} there)`}`);
   // A wake schedule at spawn is saved by the host: it must advertise schedules.
   if (["--wake-json", "--wake-every", "--wake-cron"].some((f) => oatsArgs.includes(f)) && !remote.features.includes("schedule")) refuse("a wake schedule at spawn (the host must advertise the schedule feature)");
@@ -656,17 +658,100 @@ 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
  *  kernel does not advertise session-start, the envelope relayed as is. */
-export function startRemote(serverId, { instance, home, model } = {}, io = {}) {
-  const route = resolveRoute(serverId, { instance, home }, "session start");
+export function startRemote(serverId, choices = {}, io = {}) {
+  return launchRemoteSession(serverId, "start", choices, io);
+}
+
+export function restartRemote(serverId, choices = {}, io = {}) {
+  return launchRemoteSession(serverId, "restart", choices, io);
+}
+
+function remoteLaunchArgs({ launchConfig, runtime, model, yolo } = {}) {
+  const args = [];
+  if (launchConfig !== undefined) {
+    if (typeof launchConfig !== "string" || !/^[a-z0-9][a-z0-9._-]{0,63}$/i.test(launchConfig)) throw serverError("E_BAD_ARGS", "invalid launch configuration name");
+    args.push("--launch-config", launchConfig);
+  }
+  if (runtime !== undefined) {
+    if (!["pi", "claude", "codex"].includes(runtime)) throw serverError("E_BAD_ARGS", "runtime must be pi, claude or codex");
+    args.push("--runtime", runtime);
+  }
+  if (model !== undefined && model !== null && model !== "") {
+    if (typeof model !== "string" || model.startsWith("-") || model.includes("\0")) throw serverError("E_BAD_ARGS", "invalid model name");
+    args.push("--model", model);
+  }
+  if (yolo !== undefined) {
+    if (typeof yolo !== "boolean") throw serverError("E_BAD_ARGS", "yolo must be true or false");
+    args.push(yolo ? "--yolo" : "--no-yolo");
+  }
+  return args;
+}
+
+function requireRemoteFeature(remote, target, feature) {
+  if (!remote.features.includes(feature)) throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost} does not advertise ${feature}; upgrade it there; nothing was sent`);
+}
+
+function launchRemoteSession(serverId, action, choices, io) {
+  const { instance, home, launchConfig, runtime, yolo } = choices;
+  const choiceArgs = remoteLaunchArgs(choices);
+  const route = resolveRoute(serverId, { instance, home }, `session ${action}`);
   const remote = requireSessionRemote(route.target, io);
   if (!remote.features.includes("session-start")) {
     throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${route.target.sshHost} does not advertise session-start (kernels from ${SESSION_START_REMOTE_VERSION} do); upgrade it there, or start the instance on that host`);
   }
-  const args = ["session", "start", "--home", route.home, ...(model ? ["--model", String(model)] : []), "--json"];
+  if (action === "restart") requireRemoteFeature(remote, route.target, "session-restart");
+  if (launchConfig !== undefined || runtime !== undefined || yolo !== undefined) requireRemoteFeature(remote, route.target, "launch-config");
+  const args = ["session", action, "--home", route.home, ...choiceArgs, "--json"];
   const { envelope, stderr } = runRemote(route.target, args, io);
   return { envelope: envelope.ok ? { ...envelope, result: { ...envelope.result, server: serverId, instance: instance || route.snapshot?.instance || envelope.result.instance } } : envelope, stderr, route };
 }
 
+/** Scope operations follow the registration; existing-home operations follow
+ * its saved route. Definitions travel on stdin, never as remote file paths or
+ * shell arguments. The host resolves environment references and validates the
+ * definition; this client never substitutes its own environment. */
+export function launchConfigRemote(serverId, options = {}, io = {}) {
+  const { action, name, context, instance, home, soul, agentsRoot, definition, keepEnv } = options;
+  if (!["list", "set", "remove", "preview"].includes(action)) throw serverError("E_BAD_ARGS", "unknown launch configuration action");
+  const write = action === "set" || action === "remove";
+  const homeSelected = home !== undefined || instance !== undefined;
+  if (homeSelected && (context !== undefined || soul !== undefined || agentsRoot !== undefined)) throw serverError("E_BAD_ARGS", "select one home or configuration scope");
+  if (write && (homeSelected || soul !== undefined || agentsRoot !== undefined)) throw serverError("E_BAD_ARGS", "edit a launch configuration with --dir, not a home or soul");
+  if (action === "preview" && !homeSelected && !soul) throw serverError("E_BAD_ARGS", "select a home or soul to preview");
+  const args = ["launch-config", action];
+  if (write) {
+    if (typeof name !== "string" || !/^[a-z0-9][a-z0-9._-]{0,63}$/i.test(name)) throw serverError("E_BAD_ARGS", "invalid launch configuration name");
+    args.push(name);
+  }
+  let input;
+  if (action === "set") {
+    if (!definition || typeof definition !== "object" || Array.isArray(definition)) throw serverError("E_BAD_ARGS", "specify a launch configuration object");
+    if (keepEnv !== undefined && typeof keepEnv !== "boolean") throw serverError("E_BAD_ARGS", "keepEnv must be true or false");
+    if (keepEnv && Object.hasOwn(definition, "env")) throw serverError("E_BAD_ARGS", "omit env when preserving the saved environment");
+    input = Buffer.from(JSON.stringify(definition));
+    args.push("--file", "-");
+    if (keepEnv) args.push("--keep-env");
+  }
+  const add = (flag, value, absolute = false) => {
+    if (typeof value !== "string" || !value || value.startsWith("-") || value.includes("\0") || (absolute && !value.startsWith("/"))) throw serverError("E_BAD_ARGS", `invalid ${flag}`);
+    args.push(flag, value);
+  };
+  // Validate explicit selectors before even probing the host.
+  if (context !== undefined) add("--dir", context, true);
+  if (soul !== undefined) add("--soul", soul);
+  if (agentsRoot !== undefined) add("--agents-root", agentsRoot, true);
+  if (action === "preview") args.push(...remoteLaunchArgs(options));
+  const route = homeSelected ? resolveRoute(serverId, { instance, home }, "launch-config") : undefined;
+  const target = route?.target || targetOf(io.server || getServer(serverId));
+  if (route) add("--home", route.home, true);
+  else if (context === undefined) args.push("--dir", target.workspace);
+  // stdin belongs only to the set operation, never its preceding version probe.
+  const remote = checkRemote(target, { ...io, input: undefined });
+  requireRemoteFeature(remote, target, "launch-config");
+  const { envelope, stderr } = runRemote(target, [...args, "--json"], { ...io, input });
+  return { envelope, stderr, target, ...(route ? { route } : {}) };
+}
+
 /** `oats schedule ...` on the execution host: schedules are host-owned, so
  *  every subcommand runs in the server's registered workspace; refused
  *  before any remote mutation when the remote kernel does not advertise

package/package.json

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

package/packages/record/bin/capture.mjs

@@ -160,9 +160,30 @@ function log(...parts) {
 
 /** Take the root's single-run lock, or say who holds it. A hook-triggered
  *  pass that finds it held exits 0: the holder's pass, or the next one,
- *  reconciles the same sessions. */
+ *  reconciles the same sessions.
+ *
+ *  `fn` must return or throw, never call process.exit: the lock is released
+ *  in the finally, and a release that did not happen is said so on stderr
+ *  with the operator recovery and a nonzero exit status. Likewise an owner
+ *  record that could not be written: the lock never silently outlives the
+ *  pass that created it. */
 function withCaptureLock(fn) {
-  const lock = acquireCaptureLock(root);
+  let lock;
+  try {
+    lock = acquireCaptureLock(root);
+  } catch (err) {
+    if (err.lockCleanup) {
+      const c = err.lockCleanup;
+      const outcome = c.removed ? "the initializing lock was removed"
+        : c.reason === "gone" ? "the initializing lock was already gone (removed by another party)"
+        : c.reason === "replaced" ? (c.owner
+          ? `the lock now belongs to pid ${c.owner.pid} (started ${c.owner.startedAt || "?"}) and was left alone`
+          : "the lock directory changed or its identity could not be verified, no owner record was readable, and it was left alone")
+        : `the initializing lock could NOT be removed${c.error ? ` (${c.error})` : ""}; ${c.recovery}`;
+      console.error(`capture: could not write the owner record of ${c.path}: ${err.message}; ${outcome}`);
+    }
+    throw err;
+  }
   if (lock.held) {
     // Never quiet: a stale lock after a killed pass needs the operator, and
     // the line says exactly what to check and what to remove.
@@ -170,13 +191,29 @@ function withCaptureLock(fn) {
     if (lock.held.liveness === "alive") log(line); else console.error(line);
     return { appended: 0, skipped: true };
   }
-  try { return fn(); } finally { lock.release(); }
+  try {
+    return fn();
+  } finally {
+    const r = lock.release();
+    if (!r.released) {
+      // Say what was observed: gone, unreadable (unknown), another owner, or
+      // our own lock that would not go away; never a guess about liveness.
+      const detail = r.reason === "gone" ? "it was already removed by another party (an operator recovery?); nothing to release"
+        : r.reason === "not-owner" ? `it now belongs to pid ${r.owner.pid} (started ${r.owner.startedAt || "?"}); left alone`
+        : r.reason === "unknown-owner" ? `its owner record is missing or unreadable, so it may be an operator removal in progress or a newer pass initializing; left alone; ${r.recovery}`
+        : `${r.error ? `${r.error}; ` : ""}${r.recovery}`;
+      console.error(`capture: did not release ${lock.path} (${r.reason}): ${detail}`);
+      process.exitCode = 1;
+    }
+  }
 }
 
 function pass() {
+  // The privacy loader fails closed by exiting; it runs before the lock is
+  // taken so that exit never leaves the lock behind.
+  const ignore = loadIgnoreOrExit(root);
   return withCaptureLock(() => {
   const out = { appended: 0 };
-  const ignore = loadIgnoreOrExit(root);
   if (!args["aw-only"]) {
     for (const r of captureAllSessions(store, { owner, ignore })) {
       out.appended += r.appended;
@@ -307,11 +344,17 @@ if (args.home) {
     });
   }
   console.log(JSON.stringify({ home: args.home, owner, appended, sessions, ...(unattributed.length ? { unattributed } : {}) }, null, 2));
-  process.exit(0);
+  process.exit(process.exitCode ?? 0); // nonzero when the lock release had to be reported
 }
 
 warnOnStrangerOwner();
-pass();
+try {
+  pass();
+} catch (err) {
+  // The lock's finally has run by now; one line, then the status.
+  console.error(`capture pass failed: ${err.message}`);
+  process.exit(1);
+}
 
 if (args.watch) {
   const roots = [

package/packages/record/lib/capture-lock.mjs

@@ -12,7 +12,8 @@
 // message says exactly that. (A reclaim protocol was reviewed and rejected:
 // rename is not compare-and-swap, and stealing from a stalled live
 // initializer under memory pressure is the failure we are preventing.)
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
 import { join } from "node:path";
 
 export function captureLockPath(root) { return join(root, ".capture.lock"); }
@@ -41,8 +42,28 @@ export function recoveryInstruction(dir, owner, liveness) {
 
 /** Try to take the root's capture lock. Returns { path, release } when
  *  taken, or { path, held: { pid, startedAt, liveness, recovery } } when any
- *  lock exists. Never removes a lock it did not create. */
-export function acquireCaptureLock(root, { now = Date.now, pid = process.pid, liveness = holderLiveness } = {}) {
+ *  lock exists. Never removes a lock it did not create.
+ *
+ *  Two failure points are reported rather than left behind. If the owner
+ *  record cannot be written after THIS call created the directory (a full
+ *  disk, say), the directory is removed only while it is still the very
+ *  directory this call created (same inode) and carries no other owner's
+ *  record; a replacement that appeared meanwhile (operator recovery, then a
+ *  newer pass) is left alone. The original error is rethrown with
+ *  `lockCleanup: { path, removed, reason?, owner?, error?, recovery? }`
+ *  saying what happened. And `release()` never throws: it answers
+ *  `{ released: true }` only when the lock is verifiably gone, otherwise
+ *  `{ released: false, reason: "gone" | "unknown-owner" | "not-owner" |
+ *  "remove-failed", ... }` with the actual observation, never a guess.
+ *
+ *  The owner record carries a per-acquisition nonce, so a release kept from
+ *  an earlier acquisition cannot erase a later one by the same pid (an
+ *  operator recovery followed by a new pass in the same long-lived process).
+ *  That is ownership checking; no lock is ever reclaimed.
+ *
+ *  `io` exists for fault injection in tests only. */
+export function acquireCaptureLock(root, { now = Date.now, pid = process.pid, liveness = holderLiveness, io = {} } = {}) {
+  const fs = { writeFileSync, rmSync, openSync, closeSync, ...io };
   const dir = captureLockPath(root);
   mkdirSync(root, { recursive: true }); // the store creates the root lazily; the lock may come first
   try {
@@ -53,12 +74,54 @@ export function acquireCaptureLock(root, { now = Date.now, pid = process.pid, li
     const live = owner ? (owner.pid === pid ? "alive" : liveness(owner.pid)) : "unknown";
     return { path: dir, held: { pid: owner?.pid, startedAt: owner?.startedAt, liveness: live, recovery: recoveryInstruction(dir, owner, live) } };
   }
-  writeFileSync(join(dir, "owner.json"), JSON.stringify({ pid, startedAt: new Date(now()).toISOString() }));
+  const nonce = randomBytes(8).toString("hex");
+  let directoryFd, identity;
+  try {
+    // Keep the directory alive until initialization or its cleanup finishes.
+    // Otherwise Linux can reuse its inode immediately after an unlink, making
+    // a record-less replacement look like the directory we created.
+    directoryFd = fs.openSync(dir, "r");
+    identity = fstatSync(directoryFd);
+    fs.writeFileSync(join(dir, "owner.json"), JSON.stringify({ pid, nonce, startedAt: new Date(now()).toISOString() }));
+  } catch (err) {
+    // Ownership was proven by the mkdir, not by the moment of cleanup: the
+    // directory is removed only if it is still ours (same inode) and holds
+    // no other pass's record. Anything else is reported, not deleted.
+    let cleanupError, reason;
+    const cur = readOwner(dir);
+    const same = (() => { try { const current = lstatSync(dir); return identity && current.dev === identity.dev && current.ino === identity.ino; } catch { return false; } })();
+    if (!existsSync(dir)) reason = "gone";
+    else if (!identity) reason = "unverified";
+    else if (!same || (cur && (cur.pid !== pid || cur.nonce !== nonce))) reason = "replaced";
+    else { try { fs.rmSync(dir, { recursive: true, force: true }); } catch (e2) { cleanupError = e2; } }
+    const removed = reason === undefined && !existsSync(dir);
+    err.lockCleanup = {
+      path: dir,
+      removed,
+      ...(reason ? { reason } : {}),
+      ...(reason === "replaced" && cur ? { owner: cur } : {}),
+      ...(cleanupError ? { error: cleanupError.message } : {}),
+      ...(removed || reason === "gone" || reason === "replaced" ? {} : { recovery: recoveryInstruction(dir, undefined, "unknown") }),
+    };
+    throw err;
+  } finally {
+    if (directoryFd !== undefined) fs.closeSync(directoryFd);
+  }
   return {
     path: dir,
     release: () => {
+      if (!existsSync(dir)) return { released: false, reason: "gone" };
       const cur = readOwner(dir);
-      if (cur && cur.pid === pid) { try { rmSync(dir, { recursive: true, force: true }); } catch { /* already gone */ } }
+      if (!cur) return { released: false, reason: "unknown-owner", recovery: recoveryInstruction(dir, undefined, "unknown") };
+      if (cur.pid !== pid || cur.nonce !== nonce) return { released: false, reason: "not-owner", owner: cur };
+      let error;
+      try { fs.rmSync(dir, { recursive: true, force: true }); } catch (e) { error = e; }
+      if (!existsSync(dir)) return { released: true };
+      // Our own lock could not be removed. We are the holder and, as far as
+      // this process can tell, alive; the operator gets a conditional line.
+      const live = pid === process.pid ? "alive" : liveness(pid);
+      const recovery = `${dir} is still held by pid ${pid} (this pass, ${live} when it reported this); its removal failed${error ? ` (${error.message})` : ""}; once that process has exited (ps -p ${pid}), remove the lock with: rm -r -- ${shellQuote(dir)}  and rerun`;
+      return { released: false, reason: "remove-failed", liveness: live, ...(error ? { error: error.message } : {}), recovery };
     },
   };
 }