asylumwarden 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TachikomaGundam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# AsylumWarden
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Status: core + CLI implemented (milestones M1–M2), adapter layer in
+progress. The npm package `asylumwarden@0.0.0` is a name reservation; the
+first functional release will be `0.1.0`.**
+
+AsylumWarden is a local, file-first control plane for multi-seat AI work. It
+keeps the plan, leases, receipts, and ledger on disk. It does not run a daemon,
+require a database, or replace the host's sandbox.
+
+- GitHub: <https://github.com/TachikomaGundam/AsylumWarden>
+- npm: `asylumwarden` (0.0.0 name reservation; functional release `0.1.0`
+  follows the release gate in [`docs/RELEASING.md`](docs/RELEASING.md))
+- License: MIT
+
+## What it is
+
+- A registry of work lines and their writable / read-only / forbidden surfaces.
+- A DAG planner with cycle and dependency checks.
+- Atomic claims with owner, epoch, TTL, and heartbeat.
+- Receipt validation: commands, artifacts, read mentions, and path containment.
+- An append-only, hash-chained ledger that is tamper-evident, not tamper-proof.
+- A thin CLI and optional opencode adapter.
+
+## What it is not
+
+- Not a sandbox. Same-uid processes can still bypass declarations.
+- Not a replacement for PCB's control plane or Abathur's gates.
+- Not a required dependency of Abathur. It is an optional companion.
+- Not a daemon, scheduler service, or task database.
+
+## Design
+
+The approved architecture is in
+[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). Wire formats
+and error codes have a single source: [`docs/CONTRACT.md`](docs/CONTRACT.md)
+with machine-readable schemas in `schemas/`. Security limits are stated
+plainly in [`docs/SECURITY.md`](docs/SECURITY.md). The PCB pilot boundary is
+in [`docs/PILOT-PCB.md`](docs/PILOT-PCB.md). Release rules are in
+[`docs/RELEASING.md`](docs/RELEASING.md).
+
+## Boundary with Abathur
+
+Abathur does not import AsylumWarden and does not install it. AsylumWarden may
+read Abathur data, but the dependency is one-way:
+
+```text
+AsylumWarden  ---reads/obeys--->  versioned contract
+Abathur       ---does not depend on--->  AsylumWarden
+```
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

package/adapters/opencode/index.js

@@ -0,0 +1,282 @@
+// THIN ADAPTER (M3). No business rules here; all validation is core's (fail-closed).
+// Every warden_* handler does exactly one thing: map tool args -> CLI argv, run the
+// core in-process via runCli(), return { output, exit }. No retries, no state
+// access, no defaults, no interpretation of the envelope.
+//
+// PCB pilot boundary (docs/PILOT-PCB.md): this adapter must NEVER be installed into
+// PCB sessions. The PCB pilot is CLI-only and shadow-only; the plugin path is out
+// of bounds for that line.
+//
+// Plugin shape: verified against a real installed plugin on this machine,
+// opencode-wiki-historian@0.6.3 (dist/index.js + dist/tools.js), 2026-11-05:
+//
+//   // dist/index.js (historian):
+//   async function server(input, options) { ... return { tool: buildTools(opts) }; }
+//   const plugin = { id: 'opencode-historian', server };
+//   export default plugin;
+//   // dist/tools/read.js (historian):
+//   import { tool } from '@opencode-ai/plugin';
+//   const s = tool.schema;                       // zod
+//   tool({ description, args: { key: s.string() }, execute: async (raw) => string })
+//
+// The real plugin builds each tool with the SDK's `tool()` helper and zod schemas.
+// This adapter must not import any host SDK (AGENTS.md: adapters never create a
+// path back into core; the zero-dep promise; task constraint), so tool definitions
+// are the same plain objects the helper returns — { description, args, execute } —
+// with `args` declared as JSON Schema instead of zod. If the host-side loader ever
+// needs zod args, that wrapping belongs at install time, not in core and not here.
+// Everything host-facing is duck-typed: no @opencode-ai/* import anywhere, static
+// or dynamic. If the host shape is missing/unexpected we register nothing and log
+// once — never throw at load.
+//
+// Core is imported through the public library entry only (src/index.mjs exports
+// runCli); zero subprocess. Import direction: adapters -> core, never the reverse
+// (enforced by tools/import-gate.mjs).
+
+import { runCli } from "../../src/index.mjs";
+
+// CLI surface per docs/CONTRACT.md §8. `command` = fixed leading argv tokens;
+// positional/value/bool entries map 1:1 onto CLI flags (camelCase tool param ->
+// kebab-case flag, e.g. stateHome -> --state-home). Required-ness is NOT checked
+// here — core fails closed (USAGE, exit 1) on a missing --actor/--epoch/etc.
+const TOOL_SPECS = [
+  {
+    tool: "warden_init",
+    command: ["init"],
+    description: "Initialize the state home (genesis ledger entry + anchor push). " +
+      "With bootstrapRegistry=true, create an absent registry file instead (needs registry, self, root).",
+    positional: [],
+    valueFlags: [
+      { key: "config", flag: "config", desc: "Path to asylumwarden.json" },
+      { key: "stateHome", flag: "state-home", desc: "State home override (test/shadow)" },
+      { key: "registry", flag: "registry", desc: "Registry path (with bootstrapRegistry)" },
+      { key: "self", flag: "self", desc: "Own line name (with bootstrapRegistry)" },
+      { key: "root", flag: "root", desc: "Own writable root (with bootstrapRegistry)" },
+    ],
+    boolFlags: [
+      { key: "force", flag: "force", desc: "Overwrite an existing registry file" },
+      { key: "bootstrapRegistry", flag: "bootstrap-registry", desc: "Bootstrap the registry file" },
+    ],
+  },
+  {
+    tool: "warden_plan",
+    command: ["plan"],
+    description: "Validate a wave manifest and materialize the wave.",
+    positional: [{ key: "manifest", desc: "Path to wave.json" }],
+    valueFlags: [
+      { key: "config", flag: "config", desc: "Path to asylumwarden.json" },
+      { key: "stateHome", flag: "state-home", desc: "State home override" },
+    ],
+    boolFlags: [{ key: "force", flag: "force", desc: "Force re-plan" }],
+  },
+  {
+    tool: "warden_ready",
+    command: ["ready"],
+    description: "List claimable cells of a wave (pending, dependencies done).",
+    positional: [{ key: "wave", desc: "Wave id" }],
+    valueFlags: [
+      { key: "config", flag: "config", desc: "Path to asylumwarden.json" },
+      { key: "stateHome", flag: "state-home", desc: "State home override" },
+    ],
+    boolFlags: [],
+  },
+  {
+    tool: "warden_claim",
+    command: ["claim"],
+    description: "Acquire the lease on a cell (owner, epoch, TTL).",
+    positional: [
+      { key: "wave", desc: "Wave id" },
+      { key: "cell", desc: "Cell id" },
+    ],
+    valueFlags: [
+      { key: "actor", flag: "actor", desc: "Actor name (required by core)" },
+      { key: "ttl", flag: "ttl", desc: "Lease TTL in seconds", type: "number" },
+      { key: "config", flag: "config", desc: "Path to asylumwarden.json" },
+      { key: "stateHome", flag: "state-home", desc: "State home override" },
+    ],
+    boolFlags: [{ key: "steal", flag: "steal", desc: "Steal a live lease (audited)" }],
+  },
+  {
+    tool: "warden_renew",
+    command: ["renew"],
+    description: "Heartbeat: extend the lease of the current epoch.",
+    positional: [
+      { key: "wave", desc: "Wave id" },
+      { key: "cell", desc: "Cell id" },
+    ],
+    valueFlags: [
+      { key: "actor", flag: "actor", desc: "Actor name (required by core)" },
+      { key: "epoch", flag: "epoch", desc: "Lease epoch (required by core)", type: "number" },
+      { key: "ttl", flag: "ttl", desc: "New TTL in seconds", type: "number" },
+      { key: "config", flag: "config", desc: "Path to asylumwarden.json" },
+      { key: "stateHome", flag: "state-home", desc: "State home override" },
+    ],
+    boolFlags: [],
+  },
+  {
+    tool: "warden_release",
+    command: ["release"],
+    description: "Voluntarily release a held lease.",
+    positional: [
+      { key: "wave", desc: "Wave id" },
+      { key: "cell", desc: "Cell id" },
+    ],
+    valueFlags: [
+      { key: "actor", flag: "actor", desc: "Actor name (required by core)" },
+      { key: "epoch", flag: "epoch", desc: "Lease epoch (required by core)", type: "number" },
+      { key: "config", flag: "config", desc: "Path to asylumwarden.json" },
+      { key: "stateHome", flag: "state-home", desc: "State home override" },
+    ],
+    boolFlags: [],
+  },
+  {
+    tool: "warden_requeue",
+    command: ["requeue"],
+    description: "Move a failed cell back to pending.",
+    positional: [
+      { key: "wave", desc: "Wave id" },
+      { key: "cell", desc: "Cell id" },
+    ],
+    valueFlags: [
+      { key: "config", flag: "config", desc: "Path to asylumwarden.json" },
+      { key: "stateHome", flag: "state-home", desc: "State home override" },
+    ],
+    boolFlags: [],
+  },
+  {
+    tool: "warden_done",
+    command: ["done"],
+    description: "Finish a cell as done with a receipt (core validates the receipt).",
+    positional: [
+      { key: "wave", desc: "Wave id" },
+      { key: "cell", desc: "Cell id" },
+    ],
+    valueFlags: [
+      { key: "actor", flag: "actor", desc: "Actor name (required by core)" },
+      { key: "epoch", flag: "epoch", desc: "Lease epoch (required by core)", type: "number" },
+      { key: "receipt", flag: "receipt", desc: "Receipt file path (required by core)" },
+      { key: "config", flag: "config", desc: "Path to asylumwarden.json" },
+      { key: "stateHome", flag: "state-home", desc: "State home override" },
+    ],
+    boolFlags: [],
+  },
+  {
+    tool: "warden_fail",
+    command: ["fail"],
+    description: "Finish a cell as failed with a reason.",
+    positional: [
+      { key: "wave", desc: "Wave id" },
+      { key: "cell", desc: "Cell id" },
+    ],
+    valueFlags: [
+      { key: "actor", flag: "actor", desc: "Actor name (required by core)" },
+      { key: "epoch", flag: "epoch", desc: "Lease epoch (required by core)", type: "number" },
+      { key: "reason", flag: "reason", desc: "Failure reason (required by core)" },
+      { key: "config", flag: "config", desc: "Path to asylumwarden.json" },
+      { key: "stateHome", flag: "state-home", desc: "State home override" },
+    ],
+    boolFlags: [],
+  },
+  {
+    tool: "warden_status",
+    command: ["status"],
+    description: "Status report for one wave or all waves.",
+    positional: [{ key: "wave", desc: "Wave id (omit for all waves)" }],
+    valueFlags: [
+      { key: "config", flag: "config", desc: "Path to asylumwarden.json" },
+      { key: "stateHome", flag: "state-home", desc: "State home override" },
+    ],
+    boolFlags: [],
+  },
+  {
+    tool: "warden_verify",
+    command: ["verify"],
+    description: "Verify the ledger hash chain + anchor + receipt spot-check.",
+    positional: [],
+    valueFlags: [
+      { key: "wave", flag: "wave", desc: "Restrict verification to one wave" },
+      { key: "config", flag: "config", desc: "Path to asylumwarden.json" },
+      { key: "stateHome", flag: "state-home", desc: "State home override" },
+    ],
+    boolFlags: [],
+  },
+  {
+    tool: "warden_registry_check",
+    command: ["registry", "check"],
+    description: "Validate the registry, print its digest and the line table.",
+    positional: [],
+    valueFlags: [
+      { key: "config", flag: "config", desc: "Path to asylumwarden.json" },
+      { key: "stateHome", flag: "state-home", desc: "State home override" },
+    ],
+    boolFlags: [],
+  },
+];
+
+// Pure arg -> argv mapping. Undefined/null params are omitted so core sees
+// exactly what the caller passed (core decides required-ness, fail-closed).
+export function buildArgv(spec, args) {
+  const argv = [...spec.command];
+  for (const p of spec.positional) {
+    if (args[p.key] !== undefined && args[p.key] !== null) argv.push(String(args[p.key]));
+  }
+  for (const f of spec.valueFlags) {
+    if (args[f.key] !== undefined && args[f.key] !== null) argv.push(`--${f.flag}`, String(args[f.key]));
+  }
+  for (const b of spec.boolFlags) {
+    if (args[b.key] === true) argv.push(`--${b.flag}`);
+  }
+  return argv;
+}
+
+function jsonSchemaArgs(spec) {
+  const args = {};
+  for (const p of spec.positional) args[p.key] = { type: "string", description: p.desc };
+  for (const f of spec.valueFlags) args[f.key] = { type: f.type ?? "string", description: f.desc };
+  for (const b of spec.boolFlags) args[b.key] = { type: "boolean", description: b.desc };
+  return args;
+}
+
+function buildTools() {
+  const tools = {};
+  for (const spec of TOOL_SPECS) {
+    tools[spec.tool] = {
+      description: spec.description,
+      args: jsonSchemaArgs(spec),
+      execute: async (rawArgs) => {
+        const argv = buildArgv(spec, rawArgs ?? {});
+        let output = "";
+        const exit = await runCli(argv, { write: (chunk) => { output += chunk; } });
+        return { output, exit };
+      },
+    };
+  }
+  return tools;
+}
+
+let logged = false;
+function logOnce(reason) {
+  if (logged) return;
+  logged = true;
+  console.error(`[asylumwarden-adapter] ${reason} — no warden_* tools registered (the CLI still works).`);
+}
+
+// Same hooks contract the historian plugin ships: server(input, options) resolves
+// hooks whose `tool` field maps tool name -> definition. Degrades to a no-op
+// (empty hooks, one console.error) when the host passes a missing/unexpected
+// shape — registration must never crash host startup.
+async function server(input, _options) {
+  try {
+    if (input === null || typeof input !== "object") {
+      logOnce(`unexpected host API shape: server(input) received ${input === null ? "null" : typeof input}`);
+      return {};
+    }
+    return { tool: buildTools() };
+  } catch (err) {
+    logOnce(`tool registration failed: ${err instanceof Error ? err.message : String(err)}`);
+    return {};
+  }
+}
+
+const plugin = { id: "asylumwarden", server };
+export default plugin;

package/bin/asylumwarden.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { runCli } from "../src/cli/main.mjs";
+
+process.exitCode = await runCli(process.argv.slice(2));

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "asylumwarden",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "private": false,
+  "description": "Local, file-first control plane for multi-seat AI work: registry, DAG, leases, receipts, ledger.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.22.1"
+  },
+  "bin": {
+    "asylumwarden": "bin/asylumwarden.mjs"
+  },
+  "scripts": {
+    "test": "node tools/workfile-gate.mjs && node --test 'test/**/*.test.mjs'",
+    "gate:imports": "node tools/import-gate.mjs",
+    "gate:workfiles": "node tools/workfile-gate.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./server": "./adapters/opencode/index.js"
+  },
+  "files": [
+    "src",
+    "schemas",
+    "bin",
+    "adapters",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TachikomaGundam/AsylumWarden.git"
+  },
+  "homepage": "https://github.com/TachikomaGundam/AsylumWarden",
+  "bugs": {
+    "url": "https://github.com/TachikomaGundam/AsylumWarden/issues"
+  }
+}

package/schemas/config.schema.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "asylumwarden/config.schema.json",
+  "title": "AsylumWarden project config (asylumwarden.json)",
+  "type": "object",
+  "allOf": [
+    {
+      "anyOf": [
+        {
+          "description": "normal mode: shadow keys forbidden",
+          "properties": {
+            "version": { "const": 1 },
+            "registry": { "type": "string", "pattern": "^~?/" },
+            "registry_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+            "self": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" },
+            "state_home": { "type": "string", "pattern": "^~?/" },
+            "mode": { "const": "normal" },
+            "kinds": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "object",
+                "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 4096 } },
+                "required": ["description"],
+                "additionalProperties": false
+              }
+            },
+            "anchor": {
+              "anyOf": [
+                { "type": "null" },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": { "enum": ["command", "remote", "human-checkpoint", "file"] },
+                    "target": { "type": "string", "minLength": 1, "maxLength": 4096 },
+                    "signer": { "type": "string", "minLength": 1, "maxLength": 256 }
+                  },
+                  "required": ["type", "target"],
+                  "additionalProperties": false
+                }
+              ]
+            }
+          },
+          "required": ["version", "registry", "registry_sha256", "self", "state_home", "mode"],
+          "additionalProperties": false
+        },
+        {
+          "description": "shadow mode: shadow_of and shadow_home required",
+          "properties": {
+            "version": { "const": 1 },
+            "registry": { "type": "string", "pattern": "^~?/" },
+            "registry_sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+            "self": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" },
+            "state_home": { "type": "string", "pattern": "^~?/" },
+            "mode": { "const": "shadow" },
+            "shadow_of": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+            "shadow_home": { "type": "string", "pattern": "^/" },
+            "protect": {
+              "type": "array",
+              "maxItems": 64,
+              "items": { "type": "string", "pattern": "^~?/" }
+            },
+            "kinds": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "object",
+                "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 4096 } },
+                "required": ["description"],
+                "additionalProperties": false
+              }
+            },
+            "anchor": {
+              "anyOf": [
+                { "type": "null" },
+                {
+                  "type": "object",
+                  "properties": {
+                    "type": { "enum": ["command", "remote", "human-checkpoint", "file"] },
+                    "target": { "type": "string", "minLength": 1, "maxLength": 4096 },
+                    "signer": { "type": "string", "minLength": 1, "maxLength": 256 }
+                  },
+                  "required": ["type", "target"],
+                  "additionalProperties": false
+                }
+              ]
+            }
+          },
+          "required": ["version", "registry", "registry_sha256", "self", "state_home", "mode", "shadow_of", "shadow_home", "protect"],
+          "additionalProperties": false
+        }
+      ]
+    }
+  ]
+}

package/schemas/ledger.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "asylumwarden/ledger.schema.json",
+  "title": "AsylumWarden ledger entry (one per JSONL line)",
+  "type": "object",
+  "properties": {
+    "seq": { "type": "integer", "minimum": 1 },
+    "ts": { "type": "string", "format": "date-time" },
+    "type": {
+      "enum": ["genesis", "plan", "claim", "renew", "release", "requeue", "steal", "done", "fail", "anchor"]
+    },
+    "wave": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" },
+    "cell": { "type": ["string", "null"], "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" },
+    "actor": { "type": ["string", "null"], "minLength": 1, "maxLength": 256 },
+    "payload": { "type": "object" },
+    "prev": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+    "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+  },
+  "required": ["seq", "ts", "type", "wave", "cell", "actor", "payload", "prev", "hash"],
+  "additionalProperties": false
+}

package/schemas/manifest.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "asylumwarden/manifest.schema.json",
+  "title": "AsylumWarden wave manifest (wave.json)",
+  "type": "object",
+  "properties": {
+    "version": { "const": 1 },
+    "wave": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" },
+    "cells": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 1024,
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" },
+          "kind": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,31}$" },
+          "line": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" },
+          "cwd": { "type": "string", "pattern": "^/" },
+          "allowed_roots": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 64,
+            "items": { "type": "string", "pattern": "^/" }
+          },
+          "read_roots": {
+            "type": "array",
+            "maxItems": 64,
+            "items": { "type": "string", "pattern": "^/" }
+          },
+          "deps": {
+            "type": "array",
+            "maxItems": 1024,
+            "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" }
+          },
+          "role": { "type": "string", "minLength": 1, "maxLength": 256 },
+          "role_file": { "type": "string", "pattern": "^/" },
+          "session_started_at": { "type": "string", "format": "date-time" },
+          "brief": { "type": "string", "maxLength": 4096 },
+          "acceptance": { "type": "string", "maxLength": 4096 }
+        },
+        "required": ["id", "kind", "line", "cwd", "allowed_roots", "deps"],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": ["version", "wave", "cells"],
+  "additionalProperties": false
+}