@awebai/oats 0.40.2 → 0.41.0

package/lib/instance-git.mjs

@@ -6,7 +6,7 @@
  * repository's default branch) with "no upstream" ≠ 0/0. Diffs are bounded and
  * addressed by an opaque file id minted with an observation revision; a diff
  * against a tree that has since moved is refused, never served. */
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -44,6 +44,78 @@ function git(cwd, argv, { allowFail = false, input, diffExit = false } = {}) {
 }
 const trim = (s) => (s === null ? null : s.trim());
 
+const BRANCH_REFS = Buffer.from("refs/heads/");
+/** The two reads of HEAD, as bytes. They run like the module's other reads:
+ *  read-only, helper-free, and with the module's own environment (gitEnv),
+ *  which keeps only the caller's PATH and HOME: GIT_DIR, GIT_WORK_TREE,
+ *  GIT_COMMON_DIR, GIT_INDEX_FILE and every other variable of the caller are
+ *  not passed, and no global or system configuration is read, so nothing but
+ *  the work tree named by `-C` decides what is read. `-C` comes first. */
+const readHead = (work, args) => spawnSync("git", ["-C", work, ...READ_ONLY_GIT, ...args], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER, shell: false, timeout: 30_000, env: gitEnv() });
+/** What a failed read of HEAD says, without a line of the output that was not an error. */
+const headReadFailure = (r, command) => String(r.error?.message ?? r.stderr ?? "").trim() || `git ${command} ${r.signal ? `was ended by ${r.signal}` : `exited with ${r.status}`}`;
+
+/** What a work tree's HEAD names → { branch, detached, ref }. The one reader
+ *  of that name: the retire plan and the retire both use it.
+ *
+ *  `ref` is the ref HEAD points at, as the bytes `git symbolic-ref --quiet HEAD`
+ *  prints, without the one line feed that ends them; null when HEAD is
+ *  detached. It is evidence for a comparison and is never serialized. Through a
+ *  chain of symbolic refs it is the last one: the branch the commits go to.
+ *
+ *  `branch` is the name OATS carries for it: the part after `refs/heads/`, when
+ *  that part is valid UTF-8 (it decodes and encodes back to the same bytes).
+ *  Nothing of it is trimmed or replaced: a name may begin or end with a
+ *  character that reads as white space. It is null when HEAD is detached, and
+ *  also for a ref OATS carries no name for: one whose name is not valid UTF-8,
+ *  or one outside `refs/heads/`. So `branch: null, detached: false` means "a
+ *  name OATS does not carry", and two such HEADs are never taken for the same
+ *  one by their missing names: compare `ref`.
+ *
+ *  A read that fails throws E_WORK_INSPECTION_FAILED. Only Git's own quiet
+ *  answer (exit 1, nothing printed) is "detached". */
+export function headName(work) {
+  const r = readHead(work, ["symbolic-ref", "--quiet", "HEAD"]);
+  if (!r.error && r.status === 0 && r.stdout.length > 1) {
+    const ref = Buffer.from(r.stdout[r.stdout.length - 1] === 0x0a ? r.stdout.subarray(0, -1) : r.stdout);
+    let branch = null;
+    if (ref.length > BRANCH_REFS.length && ref.subarray(0, BRANCH_REFS.length).equals(BRANCH_REFS)) {
+      const name = ref.subarray(BRANCH_REFS.length);
+      try {
+        const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(name);
+        if (Buffer.from(text, "utf8").equals(name)) branch = text;
+      } catch { /* not valid UTF-8: a name OATS does not carry */ }
+    }
+    return { branch, detached: false, ref };
+  }
+  if (!r.error && r.status === 1 && !r.stdout.length && !r.stderr.length) return { branch: null, detached: true, ref: null };
+  throw oatsError("E_WORK_INSPECTION_FAILED", `could not read what the worktree at ${work} has checked out: ${headReadFailure(r, "symbolic-ref")}`);
+}
+
+/** A worktree's HEAD for a retire → { commit, branch, detached, ref }: what
+ *  headName gives, and the commit HEAD is at.
+ *
+ *  A HEAD that has no commit (a branch that is not born yet) is a failed read
+ *  here: the retire proves its copy against this commit, and removes a
+ *  worktree only after it has asked which refs reach it, so there is nothing
+ *  it could do without one. That differs from the plan on purpose: the plan
+ *  (observeInstanceGit) reads the commit for itself, and an unborn work tree is
+ *  a value on its wire (`revision: "unborn"`).
+ *
+ *  The name and the commit are two reads, and nothing binds them but what is
+ *  done with them: a copy is proven against `commit`, so a name read at
+ *  another moment than the commit gives a copy that fails its proof. Nothing
+ *  destructive rests on the name. */
+export function worktreeHead(work) {
+  const name = headName(work);
+  const r = readHead(work, ["rev-parse", "--verify", "--quiet", "HEAD^{commit}"]);
+  const commit = !r.error && r.status === 0 ? r.stdout.toString("latin1").replace(/\n$/, "") : "";
+  if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(commit)) {
+    throw oatsError("E_WORK_INSPECTION_FAILED", `the HEAD of the worktree at ${work} has no commit that could be read${r.error || r.stderr?.length ? `: ${headReadFailure(r, "rev-parse")}` : ""}`);
+  }
+  return { commit, ...name };
+}
+
 /** The instance's work tree, from its home. The home's instance.json names
  *  the work mode; the tree is `<home>/work` (a directory or a symlink to the
  *  shared checkout). Missing/retired → attributed refusal, never a crash. */
@@ -169,12 +241,49 @@ function fileId(revision, indexOid, entry) {
   return createHash("sha256").update(`${revision}\0${indexOid}\0${entry.kind}\0${entry.path}\0${entry.origPath ?? ""}`).digest("hex").slice(0, 24);
 }
 
+/** The HEAD of a worktree a retire is about to remove, and whether a ref of
+ *  its repository reaches that commit → { head, unreached }. A ref outlives
+ *  the worktree; HEAD, and refs only the worktree has, do not.
+ *
+ *  One read in the repository that carries no ref name, so a ref whose name is
+ *  not valid UTF-8, or very many refs, cannot make it refuse:
+ *  `git for-each-ref --contains <commit> --count=1 --format=%(objectname)`.
+ *  Exit 0 with a line printed: some ref reaches the commit. Exit 0 with
+ *  nothing printed: none does, and the commit is something to preserve. Any
+ *  other exit throws E_WORK_INSPECTION_FAILED. Standard error is not a failure
+ *  here: a damaged ref prints a warning there with exit 0, and reaches
+ *  nothing. A commit that only another worktree's HEAD reaches counts as not
+ *  reached, which can only add a copy. */
+export function worktreeCommitUnreached(repo, work) {
+  const head = worktreeHead(work);
+  const r = spawnSync("git", ["-C", repo, ...READ_ONLY_GIT, "for-each-ref", "--contains", head.commit, "--count=1", "--format=%(objectname)"], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER, shell: false, timeout: 30_000, env: gitEnv() });
+  if (r.error || r.status !== 0) throw oatsError("E_WORK_INSPECTION_FAILED", `could not read which refs of ${repo} reach the commit the worktree at ${work} has checked out: ${headReadFailure(r, "for-each-ref")}`);
+  return { head, unreached: r.stdout.length === 0 };
+}
+
+/** The check made immediately before a retire removes a worktree: HEAD as it
+ *  is now (`now`, worktreeHead) against HEAD as the final inspection read it
+ *  (`inspected`). Equal when the commits are equal and both are detached or
+ *  both point at a ref with the same bytes. The branch names are not compared:
+ *  for a ref OATS carries no name for they are null on both sides, and null
+ *  equal to null proves nothing. Anything else throws
+ *  E_WORK_PRESERVATION_FAILED, and the worktree is not removed. */
+export function assertSameWorktreeHead(inspected, now) {
+  const same = !!inspected && !!now && inspected.commit === now.commit
+    && (inspected.ref === null || now.ref === null ? inspected.ref === null && now.ref === null && inspected.detached === true && now.detached === true : Buffer.compare(inspected.ref, now.ref) === 0);
+  if (!same) throw oatsError("E_WORK_PRESERVATION_FAILED", "the worktree's HEAD changed after it was inspected, so the worktree was not removed. The home and the worktree are kept, and so is any recovery the retire wrote; retry the retire.");
+}
+
 /** One consistent observation of the tree. Every field is what git said. */
 export function observeInstanceGit(home) {
   const { meta, work, mode } = instanceWorkTree(home);
   const headOid = trim(git(work, ["rev-parse", "--verify", "--quiet", "HEAD"], { allowFail: true }));
   const raw = git(work, ["status", "--porcelain=v2", "-z", "--branch", "--untracked-files=all", "--ignore-submodules=none"]);
   const { branch, entries } = parsePorcelainV2(raw);
+  // The name comes from headName, not from the status header, which prints
+  // "(detached)" and other words where a name would be and is read as text.
+  // The header still gives the upstream and its counts.
+  const head = headName(work);
   // The index state participates in the revision so that a stage/unstage
   // between observation and diff is a moved tree, not a stale-but-served diff.
   // Hashed from the index listing: no `write-tree`, so observing creates no object.
@@ -198,10 +307,10 @@ export function observeInstanceGit(home) {
   return {
     instanceGitApi: INSTANCE_GIT_API,
     instance: meta.instance ?? null, agent: meta.agent ?? null, home, workMode: mode,
-    observation: { revision, indexRevision: indexOid, at, worktree: work, branch: branch.head, detached: branch.head === null && headOid !== null, unborn: headOid === null },
-    recorded: { branch: meta.branch ?? null, repo: meta.repo ?? null, drift: meta.branch !== undefined && meta.branch !== null && branch.head !== meta.branch },
+    observation: { revision, indexRevision: indexOid, at, worktree: work, branch: head.branch, detached: head.detached && headOid !== null, unborn: headOid === null },
+    recorded: { branch: meta.branch ?? null, repo: meta.repo ?? null, drift: meta.branch !== undefined && meta.branch !== null && head.branch !== meta.branch },
     upstream, base: baseComparison,
-    remote: remoteOf(work, branch.head),
+    remote: remoteOf(work, head.branch),
     summary, files,
     notes: [
       ...(upstream.ref === null ? ["no upstream configured: upstream ahead/behind are unknown, not zero"] : []),

package/lib/instance-lifecycle.mjs

@@ -167,7 +167,8 @@ function writeFileSyncAtomic(path, value) {
 /** Facts for Remove (retire): what retirement would touch, with the design's
  *  defaults (retain worktree and branch; never touch a PR). `oats retire`
  *  itself applies them: plain retire re-homes the worktree; --discard-worktree
- *  / --delete-branch are the dialog's opt-ins. */
+ *  is the dialog's opt-in. No retire deletes a branch: `deleteBranch` is
+ *  always false. */
 export function planRetire(ctx, root, name, { home } = {}) {
   const me = resolveInstance(ctx, root, name, { home });
   const kids = descendantsOf(me.root, name);
@@ -183,7 +184,7 @@ export function planRetire(ctx, root, name, { home } = {}) {
   appendEvent(me.home, { kind: "retire-planned", data: { planRevision: planRevision(safety), children: kids.length, dirty: facts.work.observed ? facts.work.changed + facts.work.untracked : null } }, { workspaceOnly: true });
   return { lifecycleApi: LIFECYCLE_API, action: "retire", instance: name, home: me.home, at: new Date().toISOString(), facts, defaults, planRevision: planRevision(safety),
     notes: [
-      ...(facts.work.observed && facts.work.drift ? [`the worktree is on ${facts.work.branch}, not the recorded ${facts.recordedBranch}; branch actions use the worktree's branch`] : []),
+      ...(facts.work.observed && facts.work.drift ? [`the worktree is on ${facts.work.branch ?? (facts.work.detached ? "a detached HEAD" : "a ref OATS carries no branch name for")}, not the recorded ${facts.recordedBranch}`] : []),
       ...(facts.work.observed && facts.work.changed + facts.work.untracked > 0 ? [`${facts.work.changed} changed and ${facts.work.untracked} untracked file(s) would be retained with the worktree`] : []),
       ...(kids.length ? [`${kids.length} recorded child instance(s) are stopped first (bounded SIGTERM, never escalated) and retained (their homes are not removed); a child still running after the grace refuses the retirement`] : []),
       ...((kids.ambiguous || []).length ? [`${kids.ambiguous.length} instance(s) record this name as parent but the name is not unique under this root; they are listed under ambiguous and NOT acted on`] : []),

package/lib/packages.mjs

@@ -2,7 +2,7 @@
  * OATS packages — versions, lock v3 (workspace model v2).
  *
  * Contract: docs/design/2026-09-23-workspace-module-contracts.md §4.
- * Decision: https://github.com/awebai/oats-knowledge/blob/main/knowledge/nodes/oats-expert/decisions/workspace-model-v2.md.
+ * Decision: https://github.com/awebai/oats-knowledge/blob/main/knowledge/nodes/oats-maintainer/decisions/workspace-model-v2.md.
  *
  * A package is a place to fetch from WITH a version attached. Nothing is
  * installed: `resolvePackages` turns each `workspace.packages` entry into an

package/lib/resolve.mjs

@@ -2,7 +2,7 @@
  * lib/resolve.mjs — from a soul to an immutable resolution (module contract §3).
  *
  * Contract: docs/design/2026-09-23-workspace-module-contracts.md §3.
- * Decision: https://github.com/awebai/oats-knowledge/blob/main/knowledge/nodes/oats-expert/decisions/workspace-model-v2.md (6, 12, 14, 16, 19–21).
+ * Decision: https://github.com/awebai/oats-knowledge/blob/main/knowledge/nodes/oats-maintainer/decisions/workspace-model-v2.md (6, 12, 14, 16, 19–21).
  *
  * `resolveSoul(discovery, soulEntry, options)` turns a discovered soul into the
  * exact set of modules an instance will be built from: which capability comes

package/lib/servers.mjs

@@ -25,6 +25,7 @@ import { parseStrictJson } from "./canonical-json.mjs";
 import { noteRuntimeName } from "./deprecation.mjs";
 import { readWaitingClaim } from "./instance-events.mjs";
 import { withDirLock } from "./dir-lock.mjs";
+import { shellWord } from "./core.mjs";
 
 const OATS_HOME_DIR = () => process.env.OATS_HOME_DIR || join(homedir(), ".oats");
 export const SERVERS_FILE = () => join(OATS_HOME_DIR(), "servers.json");
@@ -917,22 +918,29 @@ export function instanceOnHost(serverId, name, io = {}) {
 function requireSessionRemote(target, io, home) {
   const remote = checkRemote(target, io);
   if (!remote.remote.includes("session")) {
-    throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost} does not advertise the \`oats session\` commands (kernels from ${SESSION_REMOTE_VERSION} do); upgrade it there, or attach with ssh -t ${target.sshHost} tmux attach -t ${recordedTmuxTarget(target, io, home)}`);
+    throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost} does not advertise the \`oats session\` commands (kernels from ${SESSION_REMOTE_VERSION} do); upgrade it there, or attach with ${oldKernelAttachHint(target, io, home)}`);
   }
   return remote;
 }
 
-/** Where a kernel without `oats session` put the instance's window: the tmux
- *  session and window its roster records for that home, else its default
- *  session (pi-agents, the default of every kernel before 0.31). */
+/** How to attach by hand to an instance on a kernel without `oats session`: the tmux session and
+ *  window its roster records for that home, else its default session (pi-agents, the default of every
+ *  kernel before 0.31). When the roster row records the server's socket the hint names it, and the
+ *  remote command is ONE quoted word (ssh joins its words for the remote shell, which would split a
+ *  path with a space); a row without a socket is a kernel that only ever used its default server. */
 const OLD_KERNEL_TMUX_SESSION = "pi-agents";
-function recordedTmuxTarget(target, io, home) {
+function oldKernelAttachHint(target, io, home) {
+  let row;
   try {
     const status = runRemote(target, ["status", "--json", "--dir", target.workspace], { ...io, input: undefined }).envelope;
-    const row = (status.ok ? status.result?.agents || [] : []).flatMap((a) => a.instances || []).find((i) => i.home && home && resolve(i.home) === resolve(home));
-    if (row?.tmux?.session) return row.tmux.window ? `${row.tmux.session}:${row.tmux.window}` : row.tmux.session;
+    row = (status.ok ? status.result?.agents || [] : []).flatMap((a) => a.instances || []).find((i) => i.home && home && resolve(i.home) === resolve(home));
   } catch { /* the hint falls back to the default session */ }
-  return OLD_KERNEL_TMUX_SESSION;
+  const tmux = row?.tmux?.session ? row.tmux : null;
+  const recorded = tmux ? (tmux.window ? `${tmux.session}:${tmux.window}` : tmux.session) : OLD_KERNEL_TMUX_SESSION;
+  // The remote command is ONE word for the local shell, with or without a socket: ssh joins its
+  // arguments and the remote shell reads the result again.
+  const server = typeof tmux?.socket === "string" && tmux.socket ? `-S ${shellWord(tmux.socket)} ` : "";
+  return `ssh -t ${target.sshHost} ${shellWord(`tmux ${server}attach -t ${shellWord(recorded)}`)}`;
 }
 
 export function inspectRemote(serverId, { instance, home } = {}, io = {}) {

package/package.json

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