@awebai/oats 0.22.0 → 0.22.2

package/packages/record/lib/store.mjs

@@ -19,6 +19,7 @@ import {
   existsSync,
   fsyncSync,
   ftruncateSync,
+  linkSync,
   mkdirSync,
   openSync,
   readdirSync,
@@ -28,8 +29,9 @@ import {
   statSync,
   unlinkSync,
   writeFileSync,
-  writeSync,
 } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { hostname } from "node:os";
 import { join } from "node:path";
 
 import { finishTurn, sha256Hex, verifyTurnId } from "./canonical.mjs";
@@ -141,16 +143,186 @@ export function parseJournal(input) {
   return { turns, validEnd, torn: validEnd < bytes.length };
 }
 
+// ----------------------------------------------------------- stream lock
+//
+// The per-stream lock is an exclusive-create lockfile carrying an OWNER
+// TOKEN: the creating process's pid, its hostname, and a random nonce.
+// Two properties follow from the token that a bare lockfile cannot give:
+//
+//   - staleness is judged against the HOLDER'S LIVENESS, not the lock's
+//     age, so a contender that arrives late against a still-running holder
+//     waits (or times out) instead of stealing a live lock; and
+//   - release unlinks the lock only while it still carries the releaser's
+//     nonce, so a holder whose lock was reclaimed cannot delete the
+//     replacement lock out from under its new owner.
+//
+// Crash recovery is preserved: a lock whose pid is gone from this host is
+// provably stale and is reclaimed at once, without waiting out any age.
+//
+// Age remains the fallback for the two cases where liveness is not
+// knowable here: a lock created on another host (file sync can copy one
+// in) and a lock with no readable token (written by an older version, or
+// by hand).
+
+function newLockToken() {
+  return {
+    pid: process.pid,
+    host: hostname(),
+    nonce: randomBytes(12).toString("hex"),
+    acquiredAt: new Date().toISOString(),
+  };
+}
+
+// Create the lock, or report that someone else holds it. The payload is
+// written to a temp file and hard-linked into place, so the lock never
+// exists with partial or empty content: a contender that can see the file
+// can always read the whole token.
+function createLock(lockPath, dir, token) {
+  const tmp = join(dir, `.lock.tmp-${token.pid}-${token.nonce}`);
+  try {
+    writeFileSync(tmp, JSON.stringify(token) + "\n");
+    try {
+      linkSync(tmp, lockPath);
+      return true;
+    } catch (err) {
+      if (err.code === "EEXIST") return false;
+      throw err;
+    }
+  } finally {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      /* never created, or already gone */
+    }
+  }
+}
+
+// Read the lock as { token, ino, mtimeMs }; token is null when the file
+// holds no readable owner token. Returns null when the lock has vanished.
+function readLock(lockPath) {
+  let st;
+  let raw;
+  try {
+    st = statSync(lockPath);
+    raw = readFileSync(lockPath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null; // vanished: the holder released
+    // Anything else (EACCES, EISDIR, EIO...) is a condition retrying cannot
+    // clear. Swallowing it here is what let the acquire loop spin: it read
+    // as "vanished" forever. Fail with the underlying code and path so the
+    // operator can act on it.
+    throw new StoreError(
+      `cannot read stream lock ${lockPath}: ${err.code ?? "unknown error"} (${err.message})`,
+      { cause: err },
+    );
+  }
+  let token = null;
+  try {
+    const parsed = JSON.parse(raw);
+    if (
+      parsed &&
+      typeof parsed.pid === "number" &&
+      typeof parsed.host === "string" &&
+      typeof parsed.nonce === "string"
+    ) {
+      token = parsed;
+    }
+  } catch {
+    /* no token: an older or hand-written lock, judged by age below */
+  }
+  return { token, ino: st.ino, mtimeMs: st.mtimeMs };
+}
+
+// true / false when the holder's liveness is knowable from this process,
+// null when it is not (the lock was created on another host). EPERM means
+// the process exists and belongs to another user: alive.
+function holderAlive(token) {
+  if (token.host !== hostname()) return null;
+  try {
+    process.kill(token.pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "ESRCH" ? false : true;
+  }
+}
+
+function lockIsProvenStale(held, staleMs) {
+  if (held.token) {
+    const alive = holderAlive(held.token);
+    if (alive === true) return false; // live holder: never stealable, at any age
+    if (alive === false) return true; // dead holder: crash recovery
+  }
+  return Date.now() - held.mtimeMs > staleMs;
+}
+
+// Remove a lock we have proven stale — and only that lock. Re-checking the
+// file's identity immediately before the unlink DETECTS a replacement that
+// landed while we were proving the old lock stale, so the common cascade
+// (reclaiming from whoever reclaimed first) is caught. It is a detection,
+// not an exclusion: a replacement landing between this recheck and the
+// unlink is still removed, and nothing here defends against that window.
+//
+// Returns null when there is nothing to report — the lock was removed, was
+// already gone, or had been replaced since we proved it stale; all three
+// mean "retry". Returns the underlying error when the removal itself keeps
+// failing (a read-only or hostile directory), which the caller reports on
+// timeout rather than retrying silently forever.
+function removeStaleLock(lockPath, held) {
+  let st;
+  try {
+    st = statSync(lockPath);
+  } catch (err) {
+    return err.code === "ENOENT" ? null : err; // already gone
+  }
+  if (st.ino !== held.ino || st.mtimeMs !== held.mtimeMs) return null; // replaced
+  try {
+    unlinkSync(lockPath);
+    return null;
+  } catch (err) {
+    return err.code === "ENOENT" ? null : err; // beaten to it
+  }
+}
+
+// Release: unlink only while the lock still carries our nonce. If it was
+// reclaimed (we ran long enough to be judged dead, or a sync overwrote
+// it), the file now belongs to another holder and is left alone.
+function releaseOwnedLock(lockPath, token) {
+  // Release runs in a finally block: it must not replace the critical
+  // section's own outcome with a lock error. A lock we cannot read is also
+  // a lock whose ownership we cannot prove, so leaving it is the correct
+  // move as well as the safe one — it is reclaimable by liveness once this
+  // process exits.
+  let held;
+  try {
+    held = readLock(lockPath);
+  } catch {
+    return;
+  }
+  if (held === null) return;
+  if (!held.token || held.token.nonce !== token.nonce) return;
+  try {
+    unlinkSync(lockPath);
+  } catch {
+    /* already gone */
+  }
+}
+
+function describeHolder(held) {
+  if (!held || !held.token) return "holder unknown";
+  return `held by pid ${held.token.pid} on ${held.token.host} since ${held.token.acquiredAt}`;
+}
+
 export class RecordStore {
   constructor(root, { owner, lockTimeoutMs = 10000, lockStaleMs = 30000 } = {}) {
     if (!root) throw new StoreError("record root is required");
-    // The lock has no liveness refresh: a holder that outlives lockStaleMs
-    // can be stolen from mid-critical-section. Keeping the waiter timeout
-    // strictly below the stale threshold guarantees a contender errors out
-    // loudly before it could ever steal a live holder's lock.
-    if (lockTimeoutMs >= lockStaleMs) {
-      throw new StoreError("lockTimeoutMs must be < lockStaleMs (stale-steal would race a live holder)");
-    }
+    // lockTimeoutMs is how long a contender waits; lockStaleMs is how old a
+    // lock must be before it is reclaimed WHEN ITS HOLDER'S LIVENESS CANNOT
+    // BE CHECKED (foreign host, no readable token). There is deliberately no
+    // ordering constraint between them: safety against stealing a live
+    // holder's lock comes from the owner token, not from the two thresholds
+    // being ordered — an ordering that never held, because the waiter's
+    // timeout starts when the contender arrives while age is measured from
+    // the lock's creation.
     this.root = root;
     this.owner = owner ?? null;
     this.lockTimeoutMs = lockTimeoutMs;
@@ -166,52 +338,44 @@ export class RecordStore {
   // processes: hooks, watchers and manual passes can all fire close
   // together for the same owner, and an unguarded repair can truncate a
   // concurrent writer's already-fsynced turn. Exclusive-create lockfile
-  // with stale-steal (a crashed holder's lock older than lockStaleMs is
-  // removed).
+  // carrying an owner token; see the stream-lock helpers above for how
+  // staleness is proven and why release is ownership-checked.
   withStreamLock(streamId, fn) {
     const dir = join(this.streamsDir(), streamId);
     mkdirSync(dir, { recursive: true });
     const lockPath = join(dir, ".lock");
+    const token = newLockToken();
     const deadline = Date.now() + this.lockTimeoutMs;
+    // Every iteration that fails to acquire falls through to ONE deadline
+    // check and one sleep — there is deliberately no `continue` above them,
+    // and no branch that retries "for free". An earlier version checked the
+    // deadline only on the readable-and-live branch, so a lock that kept
+    // failing to be read, or kept failing to be removed, or kept reading as
+    // vanished (a dangling symlink does exactly that) retried forever, hot,
+    // with nothing able to stop it. Retrying at once after a reclaim would
+    // buy ~25ms on the crash-recovery path and reopen that hole; it is not
+    // worth it.
     for (;;) {
-      try {
-        const fd = openSync(lockPath, "wx");
-        try {
-          writeSync(fd, String(process.pid));
-        } finally {
-          closeSync(fd);
-        }
-        break;
-      } catch (err) {
-        if (err.code !== "EEXIST") throw err;
-        let stale = false;
-        try {
-          stale = Date.now() - statSync(lockPath).mtimeMs > this.lockStaleMs;
-        } catch {
-          continue; // lock vanished between open and stat: retry now
-        }
-        if (stale) {
-          try {
-            unlinkSync(lockPath);
-          } catch {
-            /* another process stole it first */
-          }
-          continue;
-        }
-        if (Date.now() >= deadline) {
-          throw new StoreError(`timed out waiting for lock on stream ${streamId} (${lockPath})`);
-        }
-        sleepSync(25);
+      if (createLock(lockPath, dir, token)) break;
+      const held = readLock(lockPath); // throws on anything but ENOENT
+      const reclaimError =
+        held !== null && lockIsProvenStale(held, this.lockStaleMs)
+          ? removeStaleLock(lockPath, held)
+          : null;
+      if (Date.now() >= deadline) {
+        throw new StoreError(
+          `timed out waiting for lock on stream ${streamId} (${lockPath}, ${describeHolder(held)})` +
+            (reclaimError
+              ? `; it was judged stale but could not be removed: ${reclaimError.code ?? "unknown error"} (${reclaimError.message})`
+              : ""),
+        );
       }
+      sleepSync(25);
     }
     try {
       return fn();
     } finally {
-      try {
-        unlinkSync(lockPath);
-      } catch {
-        /* already stolen as stale; nothing to release */
-      }
+      releaseOwnedLock(lockPath, token);
     }
   }
 

package/skills/oats/SKILL.md

@@ -98,8 +98,12 @@ soul. Never put secrets, user data, or volatile task details in an instance
 name.
 
 To self-retire, first finish memory/commit/reporting requirements, report final
-status, then run `oats retire <own-instance> --self`. Never retire merely to
-clean up; retirement deletes the instance home.
+status, then run `oats retire <own-instance> --self`. That returns at once and
+a detached completion retires you a few seconds later exactly as an external
+`oats retire` would (quiesce, preserve work, hooks, remove the home). If the
+completion fails, your window stays, the failure shows in `oats status` with
+the retry command, and an operator retries. Never retire merely to clean up;
+retirement deletes the instance home.
 
 ## Canonical versus generated
 

package/capabilities/oats-aweb/package.json

@@ -1,20 +0,0 @@
-{
-  "name": "@awebai/oats-aweb",
-  "version": "0.2.0",
-  "description": "OATS messaging provider: per-instance aweb identities (mint at spawn, self-delete at retire), cross-machine roster, guided setup, and agents-md injection",
-  "keywords": [
-    "pi-package",
-    "oats",
-    "aweb"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/awebai/oats",
-    "directory": "capabilities/oats-aweb"
-  },
-  "license": "MIT",
-  "type": "module",
-  "dependencies": {
-    "@awebai/pi": "^0.2.1"
-  }
-}

package/capabilities/oats-jira/package.json

@@ -1,25 +0,0 @@
-{
-  "name": "@awebai/oats-jira",
-  "version": "0.1.0",
-  "description": "OATS tasks provider: Jira via acli — epic/story/task protocol, agent roster, label-based agent identity, and agents-md injection",
-  "keywords": [
-    "pi-package",
-    "oats",
-    "jira"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/awebai/oats",
-    "directory": "capabilities/oats-jira"
-  },
-  "license": "MIT",
-  "type": "module",
-  "bin": {
-    "oats-jira": "./bin/oats-jira.mjs"
-  },
-  "pi": {
-    "skills": [
-      "./skills"
-    ]
-  }
-}

package/capabilities/oats-linear/README.md

@@ -1,234 +0,0 @@
-# OATS Linear tasks integration
-
-Binds the OATS `tasks` layer to [Linear](https://linear.app). It ships the
-`linear-tasks` skill, a short soul injection, a spawn briefing, and JSON-first
-`oats linear ...` commands for issue work.
-
-## Why GraphQL instead of a Linear CLI?
-
-Linear's official `@linear/cli` only supports interactive issue creation and
-branch checkout. It cannot list queues, read issues, transition workflow
-states, label ownership, or post comments. Third-party CLIs expose different
-and unstable command contracts. This integration therefore calls Linear's
-official GraphQL API directly with Node's built-in `fetch`; it adds no external
-CLI or SDK dependency.
-
-- Endpoint: `https://api.linear.app/graphql`
-- Authentication: personal API key in the `Authorization` header
-- Documentation: <https://linear.app/developers/graphql>
-
-## Setup
-
-1. In Linear, open **Settings → Security & access → API keys** and create a
-   personal API key with access to the workspace used by your OATS agents.
-2. Put the key in your shell or secret manager, never in `oats-config.yaml`:
-
-   ```bash
-   export LINEAR_API_KEY='lin_api_...'
-   ```
-
-   Start/resume agents from an environment that receives this variable. The
-   spawn hook warns when it is absent; API commands fail once with an actionable
-   authentication error rather than attempting login.
-3. Activate the bundled integration at the intended target:
-
-   ```bash
-   oats use oats.linear --global --dir /path/to/workspace
-   ```
-
-4. Add target settings to that binding (team is the Linear issue-prefix key;
-   project is an optional default communicated in each instance briefing):
-
-   ```yaml
-   capabilities:
-     layers:
-       tasks:
-         capability: oats.linear
-         from: bundled
-         settings: { team: ENG, project: Agent Platform }
-   ```
-
-5. Verify resolution and API access (operational commands are available only
-   in an active context):
-
-   ```bash
-   oats doctor /path/to/workspace
-   oats linear auth
-   oats linear teams
-   oats linear states --team ENG
-   oats linear projects --team ENG
-   ```
-
-The API key acts as the human who created it. Agents preserve the human
-assignee, identify themselves with `agent-<instance-name>` labels, and do not
-move issues to terminal states without explicit human authorization.
-
-## Command surface
-
-All successful output is JSON; errors are JSON on stderr and return non-zero.
-Run an incomplete command for usage, or load the `linear-tasks` skill for the
-workflow and exact examples.
-
-```text
-oats linear auth
-oats linear teams
-oats linear states --team <KEY>
-oats linear projects --team <KEY>
-oats linear labels --team <KEY>
-oats linear issue list|get|create|update|comment ...
-```
-
-Agent labels are created team-locally on first use of `--agent`. Other labels
-must already exist. `--description-file` and `--body-file` avoid shell quoting
-problems for multiline Markdown.
-
-## Projects, project documentation, and related issues
-
-### Operating model
-
-Use each Linear object for one kind of durable information:
-
-| Linear object | What belongs there | Who manages it with this integration |
-|---|---|---|
-| Project | Outcome, ownership, lifecycle, target dates, and the container for related issues | Humans in the Linear UI; agents can discover it |
-| Project overview | Intent, scope/non-goals, architecture, constraints, human gates, and success criteria | Humans in the Linear UI |
-| Project documents | Detailed designs, decision records, runbooks, research, and other long-form project context | Humans in the Linear UI |
-| Issue | One bounded deliverable with acceptance criteria | Agents through `oats linear issue ...` |
-| Sub-issue | An independently verifiable part of a larger issue | Agents through `--parent` |
-| Issue comment | Milestones, blockers, handoffs, verification, and PR/branch links | Agents through `issue comment` |
-| Messaging | Conversation and nudges | The configured messaging layer, never the durable task record |
-
-The project overview and documents explain the work; issues execute it. Keep
-project-wide decisions out of an arbitrary issue description, and keep task
-status out of chat. When a project document governs an issue, link that
-document from the issue description or a durable comment.
-
-### Discover projects
-
-The wrapper currently reads project metadata but not project overview/document
-content:
-
-```bash
-oats linear projects --team ENG
-```
-
-The JSON includes project IDs, names, slugs, status, and associated teams. Use
-an exact project name or slug in issue commands. If the configured project is
-missing or ambiguous, stop and ask the human rather than selecting a similar
-name.
-
-### List issues in a project
-
-```bash
-# Open issues in the project
-oats linear issue list --team ENG --project "Agent Platform"
-
-# Open issues claimed by one OATS instance
-oats linear issue list --team ENG --project "Agent Platform" \
-  --agent my-agent-instance
-
-# Include terminal issues when auditing history
-oats linear issue list --team ENG --project "Agent Platform" --all
-```
-
-`issue list` excludes completed, canceled, and duplicate states unless `--all`
-is supplied. Use `issue get` before acting; its JSON includes the issue's
-project and parent context:
-
-```bash
-oats linear issue get ENG-123
-```
-
-### Create issues in a project
-
-Prefer a Markdown file for acceptance criteria:
-
-```bash
-cat > /tmp/issue.md <<'EOF'
-Why this work is needed.
-
-Acceptance:
-- [ ] Observable outcome implemented
-- [ ] Verification evidence recorded
-- [ ] Relevant documentation updated
-EOF
-
-oats linear issue create --team ENG --project "Agent Platform" \
-  --title "Implement token refresh" \
-  --description-file /tmp/issue.md \
-  --agent my-agent-instance
-```
-
-Create a sub-issue only when it is independently verifiable and the parent
-really decomposes into multiple pieces:
-
-```bash
-oats linear issue create --team ENG --parent ENG-123 \
-  --title "Add refresh-token tests" \
-  --description-file /tmp/issue.md \
-  --agent my-agent-instance
-```
-
-Project membership and parentage are independent: `--project` associates an
-issue with a project; `--parent` makes it a sub-issue. Supply both when the
-sub-issue must explicitly carry project membership.
-
-### Work and report within the project
-
-```bash
-oats linear issue update ENG-123 --agent my-agent-instance
-oats linear issue update ENG-123 --state "In Progress"
-oats linear issue comment ENG-123 \
-  --body "[my-agent-instance] milestone: implementation complete; tests pass"
-oats linear issue comment ENG-123 \
-  --body "[my-agent-instance] handoff → reviewer: PR <url>; run npm test"
-```
-
-Use the team's exact workflow names from `oats linear states --team ENG`.
-Agents normally stop at the review state. Terminal transitions require both
-explicit human authorization and `--allow-terminal`.
-
-### Manage project overviews and documents
-
-The current command wrapper does **not** read or mutate project overview
-Markdown or Linear documents. Manage them through the Linear UI:
-
-1. Open the project returned by `oats linear projects --team <KEY>`.
-2. Maintain project intent, scope, non-goals, ownership, gates, architecture,
-   and success criteria in its overview.
-3. Keep detailed designs, decisions, and runbooks in project documents.
-4. Link governing project documents from related issues.
-5. Record implementation progress on issues; use Linear's project updates for
-   human-facing project-level summaries.
-
-An agent that needs unavailable project-document context must ask the human for
-its URL/content. It must not infer missing project policy from issue titles.
-
-## Current support boundary
-
-| Operation | Supported by `oats linear`? | Current path |
-|---|---:|---|
-| Discover teams, workflow states, projects, and labels | Yes | `teams`, `states`, `projects`, `labels` |
-| List/get/create/update/comment on project issues | Yes | `issue ...` commands |
-| Create sub-issues | Yes | `issue create --parent ...` |
-| Create, rename, schedule, change status, or close a project | No | Linear UI; human-owned |
-| Read or edit project overview Markdown | No | Linear UI |
-| List, read, create, or edit project documents | No | Linear UI |
-| Move an existing issue into/out of a project | No | Linear UI |
-| Change an existing issue's parent | No | Linear UI |
-| Publish Linear project status updates | No | Linear UI |
-| Create issue-to-issue relations such as blocks/related | No | Linear UI |
-
-Do not invent GraphQL calls or undocumented command flags to bypass this
-boundary. A future, separately reviewed extension could add commands such as:
-
-```text
-oats linear project get|create|update
-oats linear project issue-add|issue-remove
-oats linear document list|get|create|update
-oats linear project-update create
-oats linear relation create
-```
-
-Before adding those operations, the deployment must decide which project and
-document mutations agents may perform and which remain human-only.

package/capabilities/oats-linear/package.json

@@ -1,29 +0,0 @@
-{
-  "name": "@awebai/oats-linear",
-  "version": "0.1.0",
-  "description": "OATS tasks provider: Linear via its GraphQL API, with JSON-first commands and label-based agent identity",
-  "keywords": [
-    "pi-package",
-    "oats",
-    "linear",
-    "tasks"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/awebai/oats",
-    "directory": "capabilities/oats-linear"
-  },
-  "license": "MIT",
-  "type": "module",
-  "scripts": {
-    "test": "node --test"
-  },
-  "bin": {
-    "oats-linear": "./bin/oats-linear.mjs"
-  },
-  "pi": {
-    "skills": [
-      "./skills"
-    ]
-  }
-}