faberun 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felipe Broering
+
+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

@@ -0,0 +1,131 @@
+# skills
+
+Personal catalog of reusable agent skills, installable into any repository
+with a single command.
+
+All skills live under [`skills/`](skills/). Each skill is one folder
+with a `SKILL.md`; scripts, references, and templates live inside the skill so
+it stays a single copyable unit.
+
+## Install
+
+```bash
+npx github:feliperun/faberun             # every `mine` skill → .claude/skills/ of the current repo
+npx github:feliperun/faberun faberun # one named skill
+npx github:feliperun/faberun list        # show the catalog
+npx github:feliperun/faberun --global    # install into ~/.claude/skills/ instead
+npx github:feliperun/faberun --force     # replace skills that already exist
+```
+
+`npx` needs the repository to be reachable (public, or private with git
+credentials). Without npx, copy or symlink a skill folder into
+`~/.claude/skills/` or `.claude/skills/`:
+
+```bash
+cp -r skills/faberun ~/.claude/skills/faberun
+ln -s "$(pwd)/skills/init-agentkit" ~/.claude/skills/init-agentkit
+```
+
+## Skills
+
+### faberun
+
+Executes large implementation plans as observable multi-model DAGs outside the
+orchestrator's context: declarative routing (Claude or Codex workers, including
+DeepSeek through Codex custom providers), closed task packets, structured
+cross-model quality gates, bounded revisions, campaign journaling with
+`HANDOFF.md`, and a built-in `supervise` watchdog that keeps resuming a dead
+controller until the run is terminal — from any host scheduler (launchd, cron,
+CI, or another agent), with no dependency on the orchestrator's runtime.
+
+Release 1 makes a long campaign cheap to watch and cheap to finish. Liveness is
+rendered ambiently from a bounded heartbeat at zero token cost, and the control
+session pulls campaign events on its own cursor instead of being woken by
+progress. Every Definition of Done item now declares how it is proven, so a
+mechanically provable node spends no judge at all, while contract-level
+`finalVerification` keeps a phase from closing on partial proof. An interrupted
+run is continued in place by `resume`, never re-authored, and the factory rides
+out provider exhaustion, quota resets, dead leases, and flaky networks
+deterministically. `metrics` reports effectiveness and efficiency of a
+campaign together, from what the runs recorded. Detail:
+[references/release-1.md](skills/faberun/references/release-1.md).
+
+Quickstart, in the repository that will receive the implementation:
+
+```bash
+FABERUN=/path/to/faberun/src/cli.mjs
+TARGET=/path/to/target-repository
+
+rg -qxF '.runs/' "$TARGET/.gitignore" || printf '\n.runs/\n' >> "$TARGET/.gitignore"
+node "$FABERUN" campaign init feature-42 --cwd "$TARGET" --goal "Deliver feature 42"
+node "$FABERUN" campaign attach feature-42 --cwd "$TARGET" --tool codex --session-id <session-id> --no-transcript
+```
+
+Inspect the target once, write the contract and its task packets, then:
+
+```bash
+node "$FABERUN" validate contract.json
+node "$FABERUN" preflight contract.json
+node "$FABERUN" run --detach contract.json
+node "$FABERUN" supervise --detach "$TARGET/.runs/<run-id>"   # unattended resume
+```
+
+| Goal | Command |
+| --- | --- |
+| Find the active campaign | `campaign list --cwd <repo>` |
+| Pull unseen campaign events | `campaign sync <id> --cwd <repo> --session-id <s>` |
+| Advance the session cursor | `campaign ack <id> --cwd <repo> --session-id <s> --event-id <e>` |
+| Validate a contract | `validate <contract.json>` |
+| Check credentials, models, binaries | `preflight <contract.json>` / `doctor [--cwd <dir>]` |
+| Start without blocking the session | `run --detach <contract.json>` |
+| Read current state | `status <run-dir>` / `status --json <run-dir>` |
+| Name the next action per campaign | `next [--cwd <dir>] [--json]` |
+| View attempts and tokens | `report <run-dir>` |
+| Read what a stopped node needs: gate findings and blocking questions | `findings <run-dir>` |
+| Read the campaign indicators | `metrics <campaign-id> --cwd <repo>` |
+| Stop a run and terminate its providers | `cancel <run-dir>` |
+| Resume an interrupted run | `resume --detach <run-dir>` |
+| Keep finishing a run whose controller died | `supervise --detach <run-dir> [--interval 30]` |
+
+Operational detail: [SKILL.md](skills/faberun/SKILL.md) and the
+[contract reference](skills/faberun/references/contract.md).
+
+### init-agentkit
+
+Bootstraps the agent kit into a repository: canonical `AGENTS.md` with
+`CLAUDE.md`/`GEMINI.md`/`CURSOR.md`/`AGENT.md` symlinks, base docs (VISION,
+ARCHITECTURE, ABSTRACTIONS, GETTING-STARTED), ADRs with template and index, the
+Sentrux structural quality gate, a `create-adr` slash command, and githooks.
+Always ask which compatibility rule applies before running it — see
+[SKILL.md](skills/init-agentkit/SKILL.md).
+
+### Session continuity
+
+Long sessions stay cheap across usage-limit resets: a curated handoff is saved
+to `.claude/session-handoff.md` while the session is warm, and this
+repository's [SessionStart hook](.claude/hooks/session-start.mjs) injects a
+fresh handoff into every new session automatically. The save/resume protocol
+lives inside faberun as
+[references/session-memory.md](skills/faberun/references/session-memory.md).
+
+## Development
+
+- Node.js 22 or newer; the runtime is plain ESM `.mjs` with no runtime
+  dependencies. TypeScript is a development-only check (`checkJs`/`noEmit`).
+- `npm run check` — syntax; `npm run typecheck` — static types; `npm test` — the suite.
+- The skills of this repository stay active inside it through symlinks in
+  `.claude/skills/`.
+- [AGENTS.md](AGENTS.md) is the canonical guidance; the other agent files are
+  symlinks to it — never edit them.
+
+## Inspiration
+
+The memory-layer split (session handoff / campaign handoff / standing memory)
+draws on [ai-memory](https://github.com/akitaonrails/ai-memory) by Akita on
+Rails. Most other patterns here — compile-not-retrieve summaries,
+start-of-session handoff injection, cross-harness workstreams — converged
+independently.
+
+## License
+
+[MIT](LICENSE).

package/bin/faberun.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * The faberun executable.
+ *
+ * It calls `runCli()` and nothing else. A bin wrapper that parses, validates or
+ * decides is a second CLI with no tests. The call has to be explicit because
+ * `src/cli.mjs` guards its own dispatch on `process.argv[1]` being itself --
+ * which, invoked through here, it is not.
+ *
+ * Usage, from a repository with a `.runs/` directory:
+ *   faberun preflight <contract.json>
+ *   faberun run <contract.json> [--detach]
+ *   faberun resume <run-dir> [--node <id>] [--detach]
+ *   faberun status|report|findings <run-dir> [--json]
+ *   faberun doctor [--cwd <dir>] [--discover] [--json]
+ *   faberun models [--probe] [--json]
+ *   faberun campaign <subcommand> ...
+ *   faberun metrics <campaign-id> [--json]
+ *
+ * `src/web/server.mjs` is the browser surface and is launched directly, not
+ * through here.
+ */
+import { runCli } from "../src/cli.mjs";
+
+await runCli();

package/integrations/claude-code/statusline-bench.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Bench the Claude Code status-line script: 20 runs over a fixture heartbeat,
+# then print the median wall time in milliseconds. Exits 1 when the median is
+# 50 ms or more.
+set -euo pipefail
+
+here=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+script="$here/claude-code.sh"
+
+tmp=$(mktemp -d "${TMPDIR:-/tmp}/if-statusline-bench.XXXXXX")
+trap 'rm -rf "$tmp"' EXIT
+
+mkdir -p "$tmp/.runs/campaigns/if-bench"
+cat >"$tmp/.runs/campaigns/if-bench/heartbeat.json" <<'JSON'
+{"activeNode":"bench-node","attention":null,"campaignId":"if-bench","checkpoints":{"done":2,"total":5},"generatedAt":1756742580,"lastProgressAt":1756742400,"phase":"P1","runtime":"codex","schemaVersion":1,"state":"running","weightedUsed":1200000,"weightedCap":6000000}
+JSON
+
+escaped=${tmp//\\/\\\\}
+escaped=${escaped//\"/\\\"}
+input="{\"cwd\":\"$escaped\",\"workspace\":{\"current_dir\":\"$escaped\"}}"
+
+times=()
+for ((i = 0; i < 20; i++)); do
+  elapsed=$( { TIMEFORMAT='%R'; time "$script" <<<"$input" >/dev/null; } 2>&1 )
+  ms=$(awk -v s="$elapsed" 'BEGIN { printf "%d", s * 1000 + 0.5 }')
+  times+=("$ms")
+done
+
+median=$(printf '%s\n' "${times[@]}" | sort -n | awk '
+  { samples[NR] = $1 }
+  END {
+    if (NR % 2 == 1) value = samples[(NR + 1) / 2]
+    else value = (samples[NR / 2] + samples[NR / 2 + 1]) / 2
+    printf "%d", value + 0.5
+  }')
+
+printf 'median %d ms\n' "$median"
+if [ "$median" -ge 50 ]; then
+  printf 'statusline too slow: median %d ms >= 50 ms\n' "$median" >&2
+  exit 1
+fi
+exit 0

package/integrations/claude-code/statusline.sh

@@ -0,0 +1,80 @@
+#!/bin/sh
+# Claude Code statusLine renderer for faberun ambient liveness. Reads
+# the session JSON on stdin, reads that repo's .runs/status.json pointer
+# (rewritten every controller tick), and prints one line:
+#   <run-id> · <state> · <node> <elapsed> · $<usd> · needs you: <n>
+# elapsedSec, costUsd and needsYou are precomputed by the controller, so this
+# never touches a clock or a node process, only formats. No pointer, an
+# unreadable file, or one over the 1 KiB cap prints an empty line, exit 0.
+# jq is used when present; otherwise sed/grep pull the flat top-level fields.
+#
+# Allowance guard. The same session JSON carries rate_limits.five_hour
+# (used_percentage plus a reset instant); the script otherwise reads stdin only
+# for cwd. At ALLOWANCE_WARN_PCT or above, the line appends the warning and the
+# command to switch the seat, so the operator moves harness before the credit
+# is gone rather than after. jq reads the nested field directly, and the
+# grep/sed fallback reaches it as well by flattening the JSON to one line
+# first, so the warning is not silently jq-only. Operator harnesses other than
+# claude carry no ambient rate signal at all: their exhaustion arrives as an
+# invocation failure the engine classifies as quota_exhausted, and this script
+# adds no second classifier for them.
+
+set -u
+
+# Percent of the five-hour allowance at which the line warns. A named number,
+# not a policy: the threshold is also printed in the line the operator reads.
+ALLOWANCE_WARN_PCT=85
+
+session=$(cat)
+repo=$(printf '%s' "$session" | sed -n 's/.*"cwd":"\([^"]*\)".*/\1/p;s/.*"current_dir":"\([^"]*\)".*/\1/p' | head -n 1)
+pointer="$repo/.runs/status.json"
+
+# The nested five_hour.used_percentage. jq when present; otherwise flatten the
+# session JSON and pull the field out of the five_hour object with sed. The
+# fallback matches a compact nested object, which is what the harness emits.
+used_pct=
+if command -v jq >/dev/null 2>&1; then
+  used_pct=$(printf '%s' "$session" | jq -r '.rate_limits.five_hour.used_percentage // empty' 2>/dev/null) || used_pct=
+else
+  flat=$(printf '%s' "$session" | tr -d '\n')
+  used_pct=$(printf '%s' "$flat" | sed -n 's/.*"five_hour"[[:space:]]*:[[:space:]]*{[^}]*"used_percentage"[[:space:]]*:[[:space:]]*\([0-9][0-9.]*\).*/\1/p')
+fi
+# Integer compare: a fraction never decides crossing a whole threshold.
+whole_pct=${used_pct%%.*}
+warning=
+if [ -n "$used_pct" ] && [ -n "$whole_pct" ] && [ "$whole_pct" -ge "$ALLOWANCE_WARN_PCT" ] 2>/dev/null; then
+  warning="[warn] claude 5h ${used_pct}% >=${ALLOWANCE_WARN_PCT}% · faberun seat switch --harness <id>"
+fi
+
+line=
+if [ -n "$repo" ] && [ -f "$pointer" ] && [ "$(wc -c <"$pointer" | tr -d ' ')" -le 1024 ]; then
+  if command -v jq >/dev/null 2>&1; then
+    out=$(jq -r '[.runId,.state,(.activeNode//"-"),(.elapsedSec//"-"),(.costUsd//"-"),(.needsYou//0)]|@tsv' "$pointer" 2>/dev/null) || out=
+    set -f; IFS='	'; set -- $out; IFS=' '; set +f
+    runId=${1:-}; state=${2:-}; node=${3:-}; elapsedSec=${4:-}; costUsd=${5:-}; needsYou=${6:-}
+  else
+    field() { grep -o "\"$1\":\"[^\"]*\"\|\"$1\":[0-9.null-]*" "$pointer" | head -n 1 | sed "s/.*://;s/\"//g"; }
+    runId=$(field runId); state=$(field state); node=$(field activeNode)
+    elapsedSec=$(field elapsedSec); costUsd=$(field costUsd); needsYou=$(field needsYou)
+  fi
+  if [ -n "$runId" ] && [ -n "$state" ]; then
+    [ -n "$node" ] && [ "$node" != "null" ] || node=-
+    [ -n "$needsYou" ] && [ "$needsYou" != "null" ] || needsYou=0
+    elapsed=-
+    if [ -n "${elapsedSec:-}" ] && [ "$elapsedSec" != "null" ] && [ "$elapsedSec" != "-" ]; then
+      h=$((elapsedSec / 3600)); m=$(((elapsedSec % 3600) / 60)); s=$((elapsedSec % 60))
+      if [ "$h" -gt 0 ]; then elapsed="${h}h$(printf '%02d' "$m")m"
+      elif [ "$m" -gt 0 ]; then elapsed="${m}m$(printf '%02d' "$s")s"
+      else elapsed="${s}s"
+      fi
+    fi
+    usd=-
+    [ -n "${costUsd:-}" ] && [ "$costUsd" != "null" ] && [ "$costUsd" != "-" ] && usd="\$$costUsd"
+    line="$runId · $state · $node $elapsed · $usd · needs you: $needsYou"
+  fi
+fi
+
+if [ -n "$warning" ]; then
+  if [ -n "$line" ]; then line="$line · $warning"; else line="$warning"; fi
+fi
+printf '%s\n' "$line"

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "faberun",
+  "version": "0.3.0",
+  "description": "Faberun is a development orchestration system that turns intent into verified software: harness- and model-agnostic, it keeps the intent, coordinates the work, verifies the result and decides what happens next.",
+  "type": "module",
+  "bin": {
+    "faberun": "bin/faberun.mjs"
+  },
+  "repository": "github:feliperun/faberun",
+  "homepage": "https://github.com/feliperun/faberun",
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "integrations"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "check": "for f in bin/*.mjs .claude/hooks/*.mjs src/*.mjs src/*/*.mjs src/*/*/*.mjs evals/*.mjs test/*.mjs test/*/*.mjs; do node --check \"$f\" || exit 1; done",
+    "typecheck": "tsc",
+    "test": "node --test test/*.test.mjs test/*/*.test.mjs",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
+    "@types/node": "^22.10.0",
+    "husky": "^9.1.7",
+    "typescript": "^5.7.0"
+  }
+}

package/skills/faberun/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: faberun
+description: Faberun: a harness- and model-agnostic development orchestrator that turns plans into verified software changes.
+---
+
+# Faberun
+
+Run a plan outside the main context, this session as the control plane.
+Read [rules](references/rules.md) first.
+
+| Action | Read |
+| --- | --- |
+| Author a contract (fallback) | [contract](references/contract.md), [engineering](references/engineering.md) |
+| Launch, resume, integrate | [workflow](references/workflow.md), [operations](references/operations.md) |
+| Dispatch a node | [handoffs](references/handoffs.md) |
+| Supervise, answer attention | [operations](references/operations.md), [handoffs](references/handoffs.md) |
+| Verify, judge, settle | [engineering](references/engineering.md), [handoffs](references/handoffs.md) |
+
+Watchdog re-invocations:
+
+    node src/cli.mjs supervise <run-dir>
+    node src/cli.mjs supervise campaign <id> [--allow-main]
+
+launchd: `StartInterval 300`; `launchctl load -w ~/Library/LaunchAgents/faberun.plist`.