@staix/agent-hub 0.21.0 → 0.23.0

package/src/rooms/boundary.ts

@@ -4,7 +4,7 @@ import { HUB, DIGEST, MAX_HOP, USER, sanitize, type Envelope } from "../hub/enve
 import { mentionsPrivatePath } from "../hub/memory-policy.ts";
 import { detectSignals, type Routing } from "../hub/routing.ts";
 import type { PiiVerdict } from "../hub/inference.ts";
-import { encodeRoomMessage, isRoomLocalPeerId, parseRemotePeerId, type RoomChatEnvelope } from "./application.ts";
+import { encodeRoomMessage, isRoomLocalPeerId, parseRemotePeerId, type RoomChatEnvelope, type RoomInvocationPayload, type RoomInvocationKind, encodeRoomInvocationBody, decodeRoomInvocationBody } from "./application.ts";
 
 export interface RoomBoundaryContext {
   cwd: string; target: string; current: () => boolean;
@@ -15,6 +15,8 @@ export interface RoomBoundaryContext {
   modelScreenOn: () => boolean;
   /** The existing host-bound screenPii port owns device/campus admission, deadlines and fixed models. */
   screen?: (text: string) => Promise<PiiVerdict>;
+  /** Host ledger provenance, never a serializable request/peer capability. */
+  invocation?: RoomInvocationAuthorization;
 }
 export type RoomBoundaryCode = "invalid_message" | "not_exposed" | "boundary_refused" | "hop";
 declare const proofBrand: unique symbol;
@@ -25,6 +27,25 @@ const ENVELOPE_FIELDS = new Set(["id", "trace", "hop", "from", "to", "kind", "pr
 const encoder = new TextEncoder();
 const refused = (code: RoomBoundaryCode): RoomBoundaryResult => ({ status: "refused", code });
 
+declare const invocationBrand: unique symbol;
+export interface RoomInvocationAuthorization { readonly [invocationBrand]: true }
+interface AuthorizedInvocation { binding: string; sender: string; kind: RoomInvocationKind; body: string; current: () => boolean }
+const invocations = new WeakMap<RoomInvocationAuthorization, AuthorizedInvocation>();
+/** Host-only construction: the ledger owner supplies the actual caller/callee and exact request/result. */
+export function authorizeRoomInvocation(envelope: Envelope, sender: string, payload: RoomInvocationPayload, current: () => boolean): RoomInvocationAuthorization {
+  if (envelope.from !== HUB || envelope.kind !== "invocation" && envelope.kind !== "invocation_result" || !isRoomLocalPeerId(sender) || sender === USER) throw new Error("room: invocation provenance unavailable");
+  const body = encodeRoomInvocationBody(envelope.kind, payload);
+  const token = Object.freeze({}) as RoomInvocationAuthorization;
+  invocations.set(token, { binding: JSON.stringify(envelope), sender, kind: envelope.kind, body, current });
+  return token;
+}
+function invocationOf(token: RoomInvocationAuthorization | undefined, envelope: Envelope): AuthorizedInvocation | undefined {
+  if (!token || typeof token !== "object") return undefined;
+  const bound = invocations.get(token);
+  try { return bound && bound.kind === envelope.kind && bound.binding === JSON.stringify(envelope) && bound.current() === true ? bound : undefined; }
+  catch { return undefined; }
+}
+
 interface BodyPolicy { routing: Routing; paths: string[]; model: boolean; signature: string }
 function bodyPolicy(context: RoomBoundaryContext): BodyPolicy | undefined {
   try {
@@ -47,10 +68,12 @@ export async function roomBoundary(input: Envelope, ctx: RoomBoundaryContext): P
     const env = structuredClone(input), context: RoomBoundaryContext = { ...ctx };
     const target = parseRemotePeerId(context.target);
     if (!target || !env || typeof env !== "object" || Array.isArray(env) || Object.keys(env).some(key => !ENVELOPE_FIELDS.has(key))) return refused("invalid_message");
-    if (env.from === HUB || env.from === DIGEST || !isRoomLocalPeerId(env.from)) return refused("boundary_refused");
-    if (env.kind !== "chat" && env.kind !== "status" || env.private === true) return refused("boundary_refused");
+    const invocation = invocationOf(context.invocation, env), sender = invocation?.sender ?? env.from;
+    if (env.from === HUB && !invocation || env.from === DIGEST || !isRoomLocalPeerId(sender)) return refused("boundary_refused");
+    if (!invocation && env.kind !== "chat" && env.kind !== "status" || env.private === true) return refused("boundary_refused");
     if (env.private !== undefined && typeof env.private !== "boolean") return refused("invalid_message");
     if (!Array.isArray(env.to) || !env.to.includes(context.target)) return refused("boundary_refused");
+    if (invocation && (env.to.length !== 1 || env.to[0] !== context.target)) return refused("boundary_refused");
     if (env.to.length > 64 || env.to.some(id => !isRoomLocalPeerId(id) && !parseRemotePeerId(id))) return refused("invalid_message");
     if (!Number.isSafeInteger(env.hop) || env.hop < 0 || env.hop > MAX_HOP) return refused("hop");
     if (env.refs !== undefined && (!env.refs || typeof env.refs !== "object" || Array.isArray(env.refs))) return refused("invalid_message");
@@ -62,32 +85,41 @@ export async function roomBoundary(input: Envelope, ctx: RoomBoundaryContext): P
     const authorized = (): RoomBoundaryCode | undefined => {
       try {
         if (context.current() !== true) return "boundary_refused";
-        if (env.from !== USER && context.senderExposed(env.from) !== true) return "not_exposed";
-        if (context.senderPrivate(env.from) !== false || taskId !== undefined && context.taskPrivate(taskId) !== false) return "boundary_refused";
+        if (context.invocation && invocationOf(context.invocation, env) !== invocation) return "boundary_refused";
+        if (sender !== USER && context.senderExposed(sender) !== true) return "not_exposed";
+        if (context.senderPrivate(sender) !== false || taskId !== undefined && context.taskPrivate(taskId) !== false) return "boundary_refused";
         return context.current() === true ? undefined : "boundary_refused";
       } catch { return "boundary_refused"; }
     };
     const initial = authorized(); if (initial) return refused(initial);
-    const envelope: RoomChatEnvelope = { id: env.id, trace: env.trace, hop: env.hop, from: env.from, to: target.peer, kind: env.kind, priority: env.priority === "important" ? "status" : env.priority, body: env.body, ts: env.ts };
+    const envelope: RoomChatEnvelope = { id: env.id, trace: env.trace, hop: env.hop, from: sender, to: target.peer, kind: env.kind as RoomChatEnvelope["kind"], priority: invocation ? "status" : env.priority === "important" ? "status" : env.priority, body: invocation?.body ?? env.body, ts: env.ts };
     encodeRoomMessage({ v: 1, type: "chat", envelope }); // Validate metadata/body budget before any model sees it.
     const policy = bodyPolicy(context);
-    let withheld = !clearBody(env.body, paths, context, policy);
+    const body = envelope.body;
+    let withheld = !clearBody(body, paths, context, policy);
     if (!withheld && policy?.model) {
       const before = authorized(); if (before) return refused(before);
       let verdict: PiiVerdict | undefined;
-      try { verdict = await context.screen?.(env.body); } catch { /* unknown fails closed to the fixed stub */ }
+      try { verdict = await context.screen?.(body); } catch { /* unknown fails closed to the fixed stub */ }
       const after = authorized(); if (after) return refused(after);
       withheld = verdict?.label !== "clear";
       const fresh = bodyPolicy(context);
       if (!fresh || fresh.signature !== policy.signature) return refused("boundary_refused");
-      withheld ||= !clearBody(env.body, paths, context, fresh);
+      withheld ||= !clearBody(body, paths, context, fresh);
     }
     const final = authorized(); if (final) return refused(final);
-    const outgoing = Object.freeze({ ...envelope, body: withheld ? `[room message ${envelope.id} withheld]` : sanitize(envelope.body) });
+    if (invocation?.kind === "invocation" && withheld) return refused("boundary_refused");
+    let outgoingBody = withheld ? `[room message ${envelope.id} withheld]` : sanitize(envelope.body);
+    if (invocation?.kind === "invocation_result") {
+      const result = decodeRoomInvocationBody("invocation_result", body);
+      const hiddenOutcome = result.outcome === "needs_review" || result.outcome === "timeout" ? "needs_review" : result.outcome === "refused" ? "refused" : "withheld";
+      outgoingBody = encodeRoomInvocationBody("invocation_result", withheld ? { ...result, outcome: hiddenOutcome, body: "" } : { ...result, body: sanitize(result.body) });
+    } else if (invocation) outgoingBody = body; // Canonical structured args, sanitized only when the target renders them.
+    const outgoing = Object.freeze({ ...envelope, body: outgoingBody });
     encodeRoomMessage({ v: 1, type: "chat", envelope: outgoing });
     const current = () => authorized() === undefined && (withheld || (() => {
       const latest = bodyPolicy(context);
-      return latest !== undefined && latest.signature === policy?.signature && clearBody(env.body, paths, context, latest);
+      return latest !== undefined && latest.signature === policy?.signature && clearBody(body, paths, context, latest);
     })());
     const proof = Object.freeze({}) as RoomOutboundProof;
     proofs.set(proof, { envelope: outgoing, current });

package/src/rooms/service.ts

@@ -1,6 +1,8 @@
 /** Host integration for X4. Remote identities carry chat, never local control authority. */
 import type { Bus } from "../hub/bus.ts";
 import { USER, MAX_HOP, type Envelope, type PeerState } from "../hub/envelope.ts";
+import type { RoomInvocationAuthorization } from "./boundary.ts";
+import { roomInvocationHash } from "../hub/room-invocations.ts";
 import { Limiter, PROJECT_LIMITS, type LimitsConfig } from "../hub/limits.ts";
 import type { PiiVerdict } from "../hub/inference.ts";
 import type { Routing } from "../hub/routing.ts";
@@ -8,9 +10,14 @@ import { roomMembers } from "./wire.ts";
 import { RoomStore, RoomStoreError, RoomApplicationLimitError, type RoomOutgoing } from "./store.ts";
 import { RoomPolicy } from "./policy.ts";
 import { RemotePeer } from "./remote-peer.ts";
-import { parseRemotePeerId, roomReceiptReasonText, type RoomMessage, type RoomReceiptReason } from "./application.ts";
+import { parseRemotePeerId, roomReceiptReasonText, type RoomMessage, type RoomReceiptReason, type RoomChatEnvelope } from "./application.ts";
 import { RoomApplicationDeferredError, type RoomLink, type RoomLinkApplication, type RoomLinkContext, type RoomLinkState, type RoomPresencePeer } from "./link.ts";
 
+export interface RoomInvocationIdentity { room: string; member: string; epoch: string; current: () => boolean }
+export interface RoomInvocationIngress {
+  envelope: RoomChatEnvelope; room: string; member: string; epoch: string; remotePeer: string; hash: string;
+  current: () => boolean; claim: () => boolean;
+}
 export interface RoomChatOptions {
   bus: Bus; cwd: string; now?: () => number;
   routing: () => Routing; piiPaths: () => readonly string[];
@@ -18,6 +25,8 @@ export interface RoomChatOptions {
   taskPrivate: (id: number) => boolean | undefined;
   modelScreenOn: () => boolean; screen: (text: string) => Promise<PiiVerdict>;
   policyVersion: () => string | number;
+  invocationAuthorization?: (env: Envelope, identity: RoomInvocationIdentity) => RoomInvocationAuthorization | undefined;
+  invocation?: (input: RoomInvocationIngress) => Promise<"admitted" | "refused">;
   roster?: (ids: readonly string[]) => void;
   changed?: () => void;
   limits?: () => LimitsConfig;
@@ -109,6 +118,15 @@ export class RoomChat {
     this.bindings.set(name, binding);
     this.refreshTargets(); this.refreshOutgoing(binding); this.queueChanged();
   }
+  invocationIdentity(id: string, sender?: string): RoomInvocationIdentity | undefined {
+    const target = this.targets.get(id), state = target?.binding.store.get(target.binding.name);
+    if (!target || !state || !this.valid(target.binding) || sender !== undefined && !this.exposed(target.binding, sender)) return undefined;
+    const epoch = state.current.digest, room = state.current.room, member = target.member;
+    return { room, member, epoch, current: () => {
+      const next = this.targets.get(id), current = target.binding.store.get(target.binding.name);
+      return (sender === undefined || this.exposed(target.binding, sender)) && this.valid(target.binding) && next?.binding === target.binding && next.member === member && current?.current.room === room && current.current.digest === epoch;
+    } };
+  }
   private refreshTargets(): void {
     const candidates = new Map<string, Target[]>();
     for (const binding of this.bindings.values()) {
@@ -146,7 +164,9 @@ export class RoomChat {
             const digest = state?.current.digest;
             const current = () => this.valid(binding) && this.targets.get(id)?.binding === binding && this.targets.get(id)?.member === target.member && this.options.policyVersion() === version
               && binding.store.get(binding.name)?.current.digest === digest;
-            return { cwd: this.options.cwd, target: id, current,
+            const identity = this.invocationIdentity(id);
+            const invocation = identity ? this.options.invocationAuthorization?.(env, identity) : undefined;
+            return { cwd: this.options.cwd, target: id, current, ...(invocation ? { invocation } : {}),
               senderExposed: peer => this.exposed(binding, peer), senderPrivate: this.options.senderPrivate,
               taskPrivate: this.options.taskPrivate, routing: this.options.routing, piiPaths: this.options.piiPaths,
               modelScreenOn: this.options.modelScreenOn, screen: this.options.screen };
@@ -299,6 +319,24 @@ export class RoomChat {
     else if (chat.to !== USER && this.options.bus.hushed(env).some(row => row.peer === chat.to)) refusal = "boundary_refused";
     else if (!this.rate(from, incoming.sender, chat.to, chat.body)) refusal = "rate_limited";
     if (refusal) context.store.finishApplication(context.name, input.digest, "failed_safe", refusal, context.current);
+    else if (chat.kind === "invocation" || chat.kind === "invocation_result") {
+      if (!this.options.invocation) context.store.finishApplication(context.name, input.digest, "failed_safe", "boundary_refused", context.current);
+      else {
+        const epoch = state.current.digest;
+        const current = () => context.current() && this.valid(binding) && binding.store.get(binding.name)?.current.digest === epoch
+          && this.sourceUnambiguous(binding, incoming.sender, member!.label) && member!.exposedPeers.includes(chat.from) && this.exposed(binding, chat.to)
+          && !this.options.bus.hushed(env).some(row => row.peer === chat.to);
+        try {
+          const admitted = await this.options.invocation({ envelope: chat, room: state.current.room, member: incoming.sender, epoch, remotePeer: from,
+            hash: roomInvocationHash(chat), current, claim: () => current() && context.store.claimApplication(context.name, input.digest, current) });
+          if (!current()) throw new Error("room: state_changed");
+          context.store.finishApplication(context.name, input.digest, admitted === "admitted" ? "completed" : "failed_safe", admitted === "admitted" ? "admitted" : "boundary_refused", current);
+          if (admitted === "admitted") this.count(binding, "inbound");
+        } catch (error) {
+          context.store.quarantineApplication(context.name, input.digest); this.capacityChanged(); this.options.changed?.(); throw error;
+        }
+      }
+    }
     else if (chat.to === USER) {
       if (!context.current() || !this.valid(binding)) throw new Error("room: state_changed");
       const admission = context.store.admitPersonInbox(context.name, input.digest, context.current);

package/templates/checks/analysis.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// Runs only the explicitly selected program. No shell and no automatic invocation.
+import { constants, closeSync, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+import { resolve } from "node:path";
+import { spawn } from "node:child_process";
+
+const MAX_BYTES = 1024 * 1024, TIMEOUT_MS = 5000;
+function boundedFile(file) {
+  const before = lstatSync(file);
+  if (!before.isFile() || before.isSymbolicLink() || before.size > MAX_BYTES) throw new Error("input refused");
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const opened = fstatSync(fd);
+    if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino || opened.size > MAX_BYTES) throw new Error("input changed");
+    const bytes = Buffer.alloc(opened.size + 1); let size = 0;
+    while (size < bytes.length) { const count = readSync(fd, bytes, size, bytes.length - size, size); if (!count) break; size += count; }
+    const after = fstatSync(fd);
+    if (size !== opened.size || after.size !== opened.size || after.mtimeMs !== opened.mtimeMs || after.ctimeMs !== opened.ctimeMs) throw new Error("input changed");
+    return bytes.subarray(0, size);
+  } finally { closeSync(fd); }
+}
+function run(program, input) {
+  return new Promise(resolveRun => {
+    const group = process.platform !== "win32";
+    const child = spawn(process.execPath, [program, input], { shell: false, detached: group, stdio: ["ignore", "pipe", "ignore"] });
+    const chunks = []; let size = 0, refused = false, settled = false;
+    const kill = () => { refused = true; try { if (group && child.pid) process.kill(-child.pid, "SIGKILL"); else child.kill("SIGKILL"); } catch { /* Already gone. */ } };
+    const timer = setTimeout(kill, TIMEOUT_MS);
+    const finish = (code) => {
+      if (settled) return; settled = true; clearTimeout(timer);
+      // A program may have started descendants; release only this invocation's process group.
+      if (group && child.pid) try { process.kill(-child.pid, "SIGKILL"); } catch { /* Already gone. */ }
+      resolveRun(!refused && code === 0 ? Buffer.concat(chunks, size) : undefined);
+    };
+    child.on("error", () => { kill(); finish(null); });
+    child.stdout.on("data", bytes => {
+      if (refused) return;
+      if (bytes.length > MAX_BYTES - size) { chunks.length = 0; kill(); return; }
+      size += bytes.length; chunks.push(Buffer.from(bytes));
+    });
+    child.on("close", finish);
+  });
+}
+if (process.argv.length !== 5) {
+  console.error("usage: analysis.mjs <program.mjs> <input.json> <expected-output>"); console.log("analysis: FAIL"); process.exitCode = 2;
+} else {
+  let ok = false;
+  try {
+    const program = resolve(process.argv[2]), input = resolve(process.argv[3]), expectedFile = resolve(process.argv[4]);
+    const programBytes = boundedFile(program), inputBytes = boundedFile(input), expected = boundedFile(expectedFile);
+    JSON.parse(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(inputBytes));
+    const unchanged = () => boundedFile(program).equals(programBytes) && boundedFile(input).equals(inputBytes) && boundedFile(expectedFile).equals(expected);
+    const first = await run(program, input);
+    if (first === undefined || !unchanged()) throw new Error("first run refused or declared files changed");
+    const second = await run(program, input);
+    ok = unchanged() && first !== undefined && second !== undefined && first.equals(expected) && second.equals(expected);
+  } catch { /* Refuse without echoing program stderr, private paths, inputs or expected bytes. */ }
+  console.log(`analysis-reproduce: ${ok ? "OK" : "FAIL"}`); console.log(`analysis: ${ok ? "OK" : "FAIL"}`); process.exitCode = ok ? 0 : 1;
+}

package/templates/checks/fixtures/analysis-expected.json

@@ -0,0 +1 @@
+{"count":4,"sum":20}

package/templates/checks/fixtures/analysis-input.json

@@ -0,0 +1 @@
+[2, 4, 6, 8]

package/templates/checks/fixtures/analysis.mjs

@@ -0,0 +1,7 @@
+// Explicit fixture program: node analysis.mjs <input.json>.
+import { readFileSync } from "node:fs";
+const values = JSON.parse(readFileSync(process.argv[2], "utf8"));
+if (!Array.isArray(values) || !values.every(value => typeof value === "number" && Number.isFinite(value))) process.exit(1);
+const sum = values.reduce((total, value) => total + value, 0);
+if (!Number.isFinite(sum)) process.exit(1);
+process.stdout.write(JSON.stringify({ count: values.length, sum }) + "\n");

package/templates/checks/fixtures/ops.json

@@ -0,0 +1,4 @@
+[
+  { "id": "prepare-review", "owner": "project-owner", "due": "2026-11-10", "status": "in_progress" },
+  { "id": "confirm-evidence", "owner": "reviewer", "due": "2026-11-12", "status": "open" }
+]

package/templates/checks/fixtures/writing-rules.json

@@ -0,0 +1,4 @@
+{
+  "requiredTerms": ["evidence", "repeatable check"],
+  "bannedPhrases": ["guaranteed success", "unlimited capacity"]
+}

package/templates/checks/fixtures/writing.json

@@ -0,0 +1,5 @@
+{
+  "title": "Evidence review",
+  "language": "en",
+  "text": "The pilot records evidence from a repeatable check. The next review confirms the measured result."
+}

package/templates/checks/ops.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// Structure only. An empty array does not establish that all required actions were recorded.
+import { constants, closeSync, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+
+const MAX_BYTES = 1024 * 1024;
+function actions(file) {
+  const before = lstatSync(file);
+  if (!before.isFile() || before.isSymbolicLink() || before.size > MAX_BYTES) throw new Error("input refused");
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const opened = fstatSync(fd);
+    if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino || opened.size > MAX_BYTES) throw new Error("input changed");
+    const bytes = Buffer.alloc(opened.size + 1); let size = 0;
+    while (size < bytes.length) { const count = readSync(fd, bytes, size, bytes.length - size, size); if (!count) break; size += count; }
+    const after = fstatSync(fd);
+    if (size !== opened.size || after.size !== opened.size || after.mtimeMs !== opened.mtimeMs || after.ctimeMs !== opened.ctimeMs) throw new Error("input changed");
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes.subarray(0, size)));
+  } finally { closeSync(fd); }
+}
+function date(value) {
+  if (typeof value !== "string" || !/^[0-9]{4}-[0-9]{2}-[0-9]{2}$/.test(value)) return false;
+  const parsed = new Date(`${value}T00:00:00.000Z`);
+  return Number.isFinite(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
+}
+function valid(value) {
+  if (!Array.isArray(value)) return false;
+  const seen = new Set(), keys = ["id", "owner", "due", "status"], statuses = new Set(["open", "in_progress", "blocked", "done"]);
+  return value.every(action => {
+    if (!action || typeof action !== "object" || Array.isArray(action) || Object.keys(action).length !== keys.length || !keys.every(key => Object.hasOwn(action, key))) return false;
+    if (typeof action.id !== "string" || !action.id.trim() || seen.has(action.id) || typeof action.owner !== "string" || !action.owner.trim() || !date(action.due) || !statuses.has(action.status)) return false;
+    seen.add(action.id); return true;
+  });
+}
+if (process.argv.length !== 3) {
+  console.error("usage: ops.mjs <actions.json>"); console.log("ops: FAIL"); process.exitCode = 2;
+} else {
+  let ok = false;
+  try { ok = valid(actions(process.argv[2])); } catch { /* Never echo action content, identifiers or paths. */ }
+  console.log(`ops-records: ${ok ? "OK" : "FAIL"}`); console.log(`ops: ${ok ? "OK" : "FAIL"}`); process.exitCode = ok ? 0 : 1;
+}

package/templates/checks/writing.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// Explicit invocation only: node writing.mjs <document.json> <rules.json>.
+import { constants, closeSync, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+
+const MAX_BYTES = 1024 * 1024;
+function readJSON(file) {
+  const before = lstatSync(file);
+  if (!before.isFile() || before.isSymbolicLink() || before.size > MAX_BYTES) throw new Error("input refused");
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const opened = fstatSync(fd);
+    if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino || opened.size > MAX_BYTES) throw new Error("input changed");
+    const bytes = Buffer.alloc(opened.size + 1); let size = 0;
+    while (size < bytes.length) { const count = readSync(fd, bytes, size, bytes.length - size, size); if (!count) break; size += count; }
+    const after = fstatSync(fd);
+    if (size !== opened.size || after.size !== opened.size || after.mtimeMs !== opened.mtimeMs || after.ctimeMs !== opened.ctimeMs) throw new Error("input changed");
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes.subarray(0, size)));
+  } finally { closeSync(fd); }
+}
+const object = value => !!value && typeof value === "object" && !Array.isArray(value);
+const nonempty = value => typeof value === "string" && value.trim().length > 0;
+const terms = value => Array.isArray(value) && value.every(nonempty);
+function report(results) {
+  for (const [id, ok] of results) console.log(`${id}: ${ok ? "OK" : "FAIL"}`);
+  const ok = results.every(([, passed]) => passed);
+  console.log(`writing: ${ok ? "OK" : "FAIL"}`); process.exitCode = ok ? 0 : 1;
+}
+if (process.argv.length !== 4) {
+  console.error("usage: writing.mjs <document.json> <rules.json>"); console.log("writing: FAIL"); process.exitCode = 2;
+} else {
+  let document, rules;
+  try { document = readJSON(process.argv[2]); } catch { /* Refuse without echoing document bytes or paths. */ }
+  try { rules = readJSON(process.argv[3]); } catch { /* Rule values never become diagnostics or regular expressions. */ }
+  const metadata = object(document) && [document.title, document.language, document.text].every(nonempty);
+  const body = metadata ? `${document.title}\n${document.text}` : "";
+  const literals = metadata && object(rules) && terms(rules.requiredTerms) && terms(rules.bannedPhrases)
+    && rules.requiredTerms.every(term => document.text.includes(term)) && rules.bannedPhrases.every(term => !body.includes(term));
+  const style = metadata && !/\b(?:TODO|TBD)\b/i.test(body) && body.split(/\r\n|\r|\n/).every(line => line === line.trimEnd());
+  report([["writing-metadata", metadata], ["writing-terms", literals], ["writing-style", style]]);
+}

package/templates/packs/analysis.pack.json

@@ -0,0 +1,14 @@
+{
+  "name": "analysis",
+  "profile": "research",
+  "summary": "Reproducible analysis of declared inputs, with separate person review of provenance and method.",
+  "roles": ["analyst"],
+  "rubric": [
+    { "id": "analysis-reproduce", "text": "The local reproduction check compares the declared program and input against the expected output and records its observed result.", "required": true },
+    { "id": "analysis-inputs", "text": "Person review confirms input provenance, selection and limits, with unknowns and missing data stated explicitly.", "required": true },
+    { "id": "analysis-method", "text": "Person review assesses method suitability, assumptions and interpretation; output equality alone does not establish validity.", "required": true }
+  ],
+  "checks": [
+    { "id": "analysis-reproduce", "note": "Manual, advisory example only: bun templates/checks/analysis.mjs <program.mjs> <input.json> <expected-output>. A match proves reproduction, not method validity." }
+  ]
+}

package/templates/packs/ops.pack.json

@@ -0,0 +1,14 @@
+{
+  "name": "ops",
+  "profile": "general",
+  "summary": "Traceable project and meeting action records with explicit ownership, status and human follow-up review.",
+  "roles": ["project-manager", "meeting-actions-owner"],
+  "rubric": [
+    { "id": "ops-records", "text": "Action records pass the local schema, identity, ownership and status checks, with observed results retained.", "required": true },
+    { "id": "ops-coverage", "text": "Person review checks coverage against the source meeting or project record and identifies missing or duplicated actions.", "required": true },
+    { "id": "ops-followup", "text": "Person review confirms assignments and follow-up dates were agreed, or marks them proposed or unknown; completion requires evidence.", "required": true }
+  ],
+  "checks": [
+    { "id": "ops-records", "note": "Manual, advisory example only: bun templates/checks/ops.mjs <actions.json>. A schema pass does not prove meeting coverage or agreement." }
+  ]
+}

package/templates/packs/writing-pack.pack.json

@@ -0,0 +1,14 @@
+{
+  "name": "writing-pack",
+  "profile": "writing",
+  "summary": "Scoped editing and translation with explicit metadata, terminology and style evidence.",
+  "roles": ["editor", "translator", "style-checker", "terminology-checker"],
+  "rubric": [
+    { "id": "writing-metadata", "text": "Required document metadata is present and agrees with the supplied rules.", "required": true },
+    { "id": "writing-terms", "text": "The document passes the supplied terminology rules; unresolved usage decisions are identified for person review.", "required": true },
+    { "id": "writing-style", "text": "The document passes the supplied mechanical style rules; readability and audience fit have a separate reviewer judgment.", "required": true }
+  ],
+  "checks": [
+    { "id": "writing-check", "note": "Manual, advisory example only: bun templates/checks/writing.mjs <document.json> <rules.json>. Output is evidence, not publication approval." }
+  ]
+}

package/templates/roles/NOTICE.md

@@ -1,6 +1,6 @@
 # Role catalog attribution
 
-Selected role guidance is adapted from msitarzewski/agency-agents at f99f6aa910a442b0197b768ce0ea7751e35e2060. Each adapted definition names its upstream path. The other three research definitions are original agent-hub guidance. Upstream persona, code samples and autonomy claims are excluded.
+Selected role guidance is adapted from msitarzewski/agency-agents at f99f6aa910a442b0197b768ce0ea7751e35e2060. Each adapted definition names its upstream path. The other three research definitions and the writing and ops definitions are original agent-hub guidance. Upstream persona, code samples and autonomy claims are excluded.
 
 MIT License
 

package/templates/roles/ops/meeting-actions-owner.md

@@ -0,0 +1,26 @@
+---
+id: meeting-actions-owner
+name: Meeting actions owner
+group: ops
+summary: Extract and maintain traceable action records from a bounded meeting or project record.
+base: implementer
+classes: implement,summarize
+source: original agent-hub guidance
+---
+## Scope
+Create action records from the supplied meeting or project sources. Keep decisions, proposals, assignments, deadlines and unknowns separate, with stable action IDs and source references.
+
+## Not in scope
+Do not infer attendance, acceptance, completion or dates from silence. External follow-up, calendar changes and commitments by others require explicit authorization.
+
+## Deliverables
+Action records with the required fields, source locations, stated owner and date status, plus unresolved questions and a concise change account.
+
+## Hub use
+Use the existing task flow for the assigned base role. Name source and output paths in the plan; report missing records and proposed follow-up before treating it as agreed work.
+
+## Review duties
+Check coverage against the source, duplicate actions, ownership and status consistency. Verify that a completion claim has an actual receipt rather than a planned date.
+
+## Evidence
+Meeting excerpts or decision references and the observed record-check result. Person review establishes source coverage and confirms proposed assignments or follow-up dates.

package/templates/roles/ops/project-manager.md

@@ -0,0 +1,26 @@
+---
+id: project-manager
+name: Project manager
+group: ops
+summary: Define a bounded delivery plan with explicit ownership, dependencies and acceptance evidence.
+base: planner
+classes: plan
+source: original agent-hub guidance
+---
+## Scope
+Turn the authorized objective into scoped tasks, dependencies, proposed owners, milestones and acceptance evidence. Distinguish recorded commitments from planning assumptions.
+
+## Not in scope
+Do not invent progress, assign authority through prose or commit other people to dates. Budget, staffing, external messages and release decisions remain with their authorized actors.
+
+## Deliverables
+Reviewable task plan, dependency and risk notes, owner and date proposals, acceptance criteria, and decisions or missing inputs requiring a person.
+
+## Hub use
+Use the existing planning flow and task board. Reference the source request and affected paths; surface overlap, blockers and scope changes through the established coordination tools.
+
+## Review duties
+Check that each proposed outcome has an owner, a feasible dependency order and observable completion evidence. Keep unknown capacity and unaccepted dates explicit.
+
+## Evidence
+Source requests, recorded decisions, task references and verified progress receipts. A plan or inventory count is not evidence of completed work or available capacity.

package/templates/roles/writing/editor.md

@@ -0,0 +1,26 @@
+---
+id: editor
+name: Editor
+group: writing
+summary: Edit a scoped document for structure, clarity and fidelity to its source material.
+base: implementer
+classes: implement,bulk_edit
+source: original agent-hub guidance
+---
+## Scope
+Edit the assigned document against its audience, purpose, source material and declared style rules. Keep supported meaning and attribution intact.
+
+## Not in scope
+Do not invent facts, quotes or approvals. Publication, external submission and changes to project policy require their own authorized actors.
+
+## Deliverables
+Revised document, a concise account of substantive changes, unresolved questions and references to the exact inputs and rules used.
+
+## Hub use
+Use the existing task flow for the assigned base role. Identify the document paths and proposed edits in the plan; report blockers and changed scope before extending the work.
+
+## Review duties
+Check organization, unsupported claims, ambiguous wording and consistency. Separate a mechanical check result from a person's editorial judgment.
+
+## Evidence
+Versioned source and document references, recorded rule checks, and a clear list of unverified claims or editorial decisions requiring review.

package/templates/roles/writing/style-checker.md

@@ -0,0 +1,26 @@
+---
+id: style-checker
+name: Style checker
+group: writing
+summary: Check a document against supplied style rules and separate mechanical findings from editorial judgment.
+base: verifier,reviewer
+classes: test,review
+source: original agent-hub guidance
+---
+## Scope
+Check the assigned document against the exact supplied style rules. Distinguish deterministic constraints from readability or tone judgments that need human review.
+
+## Not in scope
+Do not invent a style policy, rewrite the whole document or treat a mechanical pass as approval to publish. Verification grants no additional permissions.
+
+## Deliverables
+Findings with rule IDs, document locations, observed text and suggested corrections. Record passed, failed, unrun and human-review items separately.
+
+## Hub use
+Use the existing task or review flow for the assigned base role. Cite the document and rule versions, and bind each finding to a reproducible observation.
+
+## Review duties
+Check declared formatting, consistency and language constraints without changing their thresholds. Identify conflicts or ambiguous rules instead of silently choosing a new standard.
+
+## Evidence
+Observed local check results and source locations support mechanical findings. Readability, audience fit and tone require a stated reviewer judgment.

package/templates/roles/writing/terminology-checker.md

@@ -0,0 +1,26 @@
+---
+id: terminology-checker
+name: Terminology checker
+group: writing
+summary: Verify declared terms, names and translations against a versioned glossary.
+base: verifier,reviewer
+classes: test,review
+source: original agent-hub guidance
+---
+## Scope
+Check the assigned document for the supplied preferred, restricted and language-specific terms. Keep exact glossary rules distinct from context-dependent usage judgments.
+
+## Not in scope
+Do not create institutional names, expand unknown acronyms by guesswork or change the authoritative glossary. A literal match does not prove factual or translation correctness.
+
+## Deliverables
+Term findings with rule IDs, source locations and glossary references; explicit ambiguity and exception requests where context prevents a firm verdict.
+
+## Hub use
+Use the existing task or review flow for the assigned base role. Identify document and glossary paths and versions; report a missing or conflicting glossary before treating terms as verified.
+
+## Review duties
+Check proper nouns, abbreviations and consistent translations. Preserve quoted source text and distinguish a declared exception from an unnoticed mismatch.
+
+## Evidence
+Versioned glossary entries, exact document occurrences and observed checker output. Domain usage and proposed exceptions need a recorded person review.

package/templates/roles/writing/translator.md

@@ -0,0 +1,26 @@
+---
+id: translator
+name: Translator
+group: writing
+summary: Translate a bounded document while preserving meaning, attribution and declared terminology.
+base: implementer
+classes: implement,bulk_edit
+source: original agent-hub guidance
+---
+## Scope
+Translate the assigned source into the requested language and register. Preserve names, quantities, qualifiers, citations and the distinction between completed and proposed activity.
+
+## Not in scope
+Do not supply missing facts, certify a translation or imply publication approval. Leave legal or specialist interpretation and external delivery to their authorized actors.
+
+## Deliverables
+Translated document, source-to-output references, terminology decisions and unresolved ambiguities with their source locations.
+
+## Hub use
+Use the existing task flow for the assigned base role. Name source, output and glossary paths in the plan and completion summary; report unavailable inputs explicitly.
+
+## Review duties
+Compare meaning and coverage against the source. Check omissions, changed certainty, numbers and proper nouns; identify wording that needs a fluent or domain reviewer.
+
+## Evidence
+Exact source and glossary versions, check results and examples of reviewed ambiguities. A terminology match alone does not establish translation fidelity.