johns-harness 2026.9.8 → 2026.9.11

package/README.md

@@ -8,7 +8,17 @@
 
 ![A collective of AI agents working one codebase together](docs/images/swarm-collective.png)
 
-John's Harness is a production agent harness for engineers who run more than one coding agent at a time. Agents work the same repositories at once, coordinate through a durable board keyed by git origin, message each other while they run, and ship only through an exact-head push gate with per-commit production authority. Memory persists across sessions and compaction and is shared by every agent in the swarm.
+John's Harness is a production agent harness for engineers who run more than one coding agent at a time. Agents work the same repositories at once, coordinate through a durable board keyed by git origin, message each other while they run, and ship only through an exact-head push gate with per-commit production authority. Memory persists across sessions and compaction and is shared by every agent in the swarm. Launching a swarm takes one command and a number; the members divide the work among themselves.
+
+## Migrating from OpenClaw
+Bring your agents, memory, credentials, and scheduled jobs into John's Harness.
+```sh
+npm i -g johns-harness && johnness migrate
+```
+The command backs up your state, creates `~/.johnness`, rewrites settings, and checks the result.
+If your gateway is running, it shows the exact stop command before making changes.
+Review any script updates, then follow the printed commands to start the new gateway.
+Your original installation stays intact. Preview with `johnness migrate --dry-run`; undo with `johnness migrate --rollback`.
 
 ## Quick start
 
@@ -17,12 +27,12 @@ Requires Node 22.12 or newer.
 ```bash
 npm install -g johns-harness
 johnness onboard
-johnness config set plugins.entries.mr-memory.config.key "mk_your_key"
+johnness memory mk_your_key
 ```
 
 The package is `johns-harness`; the command it installs is `johnness`.
 
-The wizard sets up credentials, workspace, gateway, and channels. The third line stores a MemoryRouter API key from [memoryrouter.ai](https://memoryrouter.ai); until it is set, the harness still runs and prints one setup line saying where to put it.
+The wizard sets up credentials, workspace, gateway, and channels. It asks for your MemoryRouter API key and links to [signup](https://app.memoryrouter.ai/signup), free to start. If you skip memory in the wizard, the third line stores the key later.
 
 ### First run
 
@@ -30,11 +40,17 @@ The wizard sets up credentials, workspace, gateway, and channels. The third line
 | --- | --- | --- |
 | Install | `npm install -g johns-harness` | Installs the CLI, the runtime, and the default memory plugin. A postinstall step applies the patched dependency files. |
 | Configure | `johnness onboard` | Interactive wizard for gateway, workspace, and skills. `johnness configure` reopens it later. |
-| Memory | `johnness config set plugins.entries.mr-memory.config.key "mk_..."` | Turns on persistent memory. The plugin is already installed and enabled. |
+| Memory | `johnness memory mk_your_key` | Turns on persistent memory. The plugin is already installed and enabled. |
 | Start | `johnness gateway start` | Starts the gateway as a background service. `johnness gateway run` keeps it in the foreground. |
 | Connect | `johnness channels add --channel telegram --token "<bot token>"` | Connects a chat channel. Discord, Slack, WhatsApp, Signal, iMessage, Matrix, and more are supported. |
 | Check | `johnness doctor` | Health checks and quick fixes for the gateway and channels. |
 
+### Signing in from chat
+Owners and allowlisted senders can send `/login` (or `/relogin`) in Telegram, Discord, or another chat channel.
+Open the link, enter the device code, and sign in to ChatGPT; the harness reconnects automatically.
+For headless installs, run `johnness models auth login --device`; no browser or localhost callback needed.
+Expired ChatGPT credentials trigger an owner notice with the `/login` recovery command.
+
 ### From source
 
 ```bash
@@ -46,21 +62,54 @@ node johnness.mjs --help
 ### Verify
 
 ```bash
-npm test                        # 529 tests against the installed dependency tree
-bash scripts/verify-patches.sh  # 182 checks across every patch family
+npm test                        # 701 tests against the installed dependency tree
+bash scripts/verify-patches.sh  # 258 checks across every patch family
+```
+
+## Launch a swarm with one command
+
+One call, one number. The orchestrator writes a single directive and chooses how many agents should work it. The members decide everything else.
+
+```
+swarm_spawn({
+  directive: "<the whole briefing: goal, scope, forbidden files, push rules, author identity>",
+  count: 12,
+  coord: { root: "/abs/path/to/repo", branch: "main", prodAuthorized: false },
+  model: "anthropic/claude-fable-5-1"      // optional, applies to every member
+})
 ```
 
+![One command launches a hundred agents that fan out over a codebase and pick up work from a shared board](docs/images/swarm-spawn.png)
+
+Every member receives the same directive plus a short runtime preamble that carries the protocol. Nobody hands out work.
+
+The lowest-numbered live member decomposes the directive into work items on the shared board. The post is a compare-and-swap, so exactly one plan exists no matter how many members arrive at the same moment; the rest wait for it rather than poll.
+
+Each member claims one open item atomically, works it, pushes, marks it done or failed, and claims the next. A claim is exactly one winner, even under concurrent attempts.
+
+Claims carry a 15 minute lease that heartbeats extend. A lease that lapses reopens the item the moment anyone looks at the board, so a dead member never strands its work.
+
+When work reveals more items, any member appends them to the plan and the addition wakes the others through their inboxes. Members message each other directly only for a real dependency, and each records how the swarm coordinated so the next one starts smarter.
+
+The preamble also carries the operating protocol as defaults with named exceptions: the planner declares the shape of the work, one integrator merges parallel branches and builds and pushes once so parallel work flows into a single sequential step, one gateway or a shared budget fronts each rate-limited host, and done means done. Members ask a service holder with a durable request and wait on the answer without polling.
+
+Per-member announces are suppressed. When the last member finishes, one `swarm finished` rollup arrives with every item, its owner, its pushed head, and its summary.
+
+`count` runs from 2 to 100. Members beyond the concurrency limit are queued and start as slots free, and `swarm_status` reads a swarm's progress without interrupting anyone. Members are ordinary agents: same depth rules, same push preflight, same per-commit production authority, no force pushes.
+
+Full guide, including the preamble members receive and the work item state machine: [`docs/SWARM.md`](docs/SWARM.md).
+
 ## The problem
 
 Coding agents today run as isolated processes. Two agents on the same repository have no shared state, no way to talk to each other mid-task, and no gate between a dirty local branch and production. Once a context window compacts, whatever the agent knew is gone.
 
 ## What makes it different
 
-- **A swarm, not a pile of agents.** One coordination board per repository, direct agent-to-agent messages delivered inside a busy agent's run, exclusive claims on shared areas, and a push preflight that blocks stale, forced, broad, and unauthorized pushes.
+- **A swarm, not a pile of agents.** One coordination board per repository, direct agent-to-agent messages delivered inside a busy agent's run, exclusive claims on shared areas, a push preflight that blocks stale, forced, broad, and unauthorized pushes, and `swarm_spawn`, which launches up to 100 agents from one directive in a single call.
 - **Memory built for production.** Tiered recall that traces from consolidated reflections down to the verbatim record, surviving compaction and shared across the swarm. Installed and enabled by default.
 - **Production authority per commit.** Promotion is granted to an exact SHA, never to a branch name, so one worker's authorization never covers another worker's commits.
 - **An append-only action log.** Agents record every consequential action to `ACTION_LOG.md` and read it before acting.
-- **A fixed runtime surface.** The core does not grow on a schedule. New mechanisms enter only to solve a demonstrated production failure, one narrow, tested, reversible patch at a time: 54 patch families, each with a regression test and a rollback path.
+- **A fixed runtime surface.** The core does not grow on a schedule. New mechanisms enter only to solve a demonstrated production failure, one narrow, tested, reversible patch at a time: 59 patch families, each with a regression test and a rollback path.
 - **Reliability with a definition.** Bounded retries, explicit failure states, exact-once continuation, context-pressure recovery, durable delivery, and supervised gateway recovery.
 - **Coding first, phone optional.** Direct the work at a high level from a chat channel while agents plan, implement, test, coordinate, and stage releases unattended.
 - **Local voice.** Optional native Whisper transcription of inbound audio, entirely on your machine. Off by default. [Setup](docs/NATIVE-WHISPER-MUSE.md).
@@ -92,8 +141,12 @@ Agents sharing a filesystem are not a swarm. A swarm knows who owns which work,
 
 **Production authority belongs to a commit.** Never to a branch name or a timestamp.
 
+**One directive, one number.** `swarm_spawn` launches up to 100 members from the same briefing and they divide the work themselves. See the launch section near the top of this page and the [swarm guide](docs/SWARM.md).
+
 ## Memory
 
+Run `johnness memory mk_your_key` to set your MemoryRouter API key and start persistent memory, or enter it during onboarding.
+
 The future of AI is not smarter models. It is models with the right context: what is happening, what happened before, and what matters now.
 
 An agent in this harness remembers what it was told yesterday, the decision it made last Tuesday, the fix it tried that did not work, and why. That context persists across sessions and survives compaction. It does not live and die inside one context window.
@@ -123,7 +176,7 @@ The log is a [`RULES.md`](RULES.md) workspace convention enforced through the ac
 
 ## Patch families
 
-The runtime carries 54 patch families. Each is a production fix applied at the source with a regression test, a durable patch marker, and a rollback path. A verifier runs 182 checks against the package tree and installed dependencies, and 529 tests run against the installed dependency tree.
+The runtime carries 59 patch families. Each is a production fix applied at the source with a regression test, a durable patch marker, and a rollback path. A verifier runs 258 checks against the package tree and installed dependencies, and 701 tests run against the installed dependency tree.
 
 Every family follows the same six steps: reproduce the failure, trace the exact runtime path, make the smallest source-level change that restores the invariant, add a regression test and a patch marker, run the verifier, and retain rollback artifacts. The full index: [`docs/PATCHES.md`](docs/PATCHES.md).
 
@@ -140,7 +193,7 @@ Every family follows the same six steps: reproduce the failure, trace the exact
 ## Documentation
 
 - [`docs/index.md`](docs/index.md): runtime docs, from gateway and channels to plugins, nodes, and CLI reference.
-- [`docs/PATCHES.md`](docs/PATCHES.md): the 54 patch families, one record each.
+- [`docs/PATCHES.md`](docs/PATCHES.md): the 59 patch families, one record each.
 - [`docs/NATIVE-WHISPER-MUSE.md`](docs/NATIVE-WHISPER-MUSE.md): local Whisper transcription setup.
 - [`RULES.md`](RULES.md): the default operating rules, including Rule Zero on production authorization.
 

package/dist/auth-choice-Ck7FJ_PD.js

@@ -206,7 +206,7 @@ async function applyNonInteractiveAuthChoice(params) {
 			provider,
 			name: ""
 		});
-		upsertAuthProfile({
+		await upsertAuthProfile({
 			profileId,
 			credential: {
 				type: "token",

package/dist/auth-choice-CtvmIf50.js

@@ -62,7 +62,7 @@ async function applyAuthChoiceAnthropic(params) {
 			provider,
 			name: String(profileNameRaw ?? "")
 		});
-		upsertAuthProfile({
+		await upsertAuthProfile({
 			profileId: namedProfileId,
 			agentDir: params.agentDir,
 			credential: {
@@ -813,7 +813,7 @@ async function applyAuthChoicePluginProvider(params, options) {
 	});
 	if (result.configPatch) nextConfig = mergeConfigPatch(nextConfig, result.configPatch);
 	for (const profile of result.profiles) {
-		upsertAuthProfile({
+		await upsertAuthProfile({
 			profileId: profile.profileId,
 			credential: profile.credential,
 			agentDir

package/dist/auth-choice-DYEtgk1X.js

@@ -62,7 +62,7 @@ async function applyAuthChoiceAnthropic(params) {
 			provider,
 			name: String(profileNameRaw ?? "")
 		});
-		upsertAuthProfile({
+		await upsertAuthProfile({
 			profileId: namedProfileId,
 			agentDir: params.agentDir,
 			credential: {
@@ -813,7 +813,7 @@ async function applyAuthChoicePluginProvider(params, options) {
 	});
 	if (result.configPatch) nextConfig = mergeConfigPatch(nextConfig, result.configPatch);
 	for (const profile of result.profiles) {
-		upsertAuthProfile({
+		await upsertAuthProfile({
 			profileId: profile.profileId,
 			credential: profile.credential,
 			agentDir

package/dist/auth-choice-DtQ1-QBl.js

@@ -206,7 +206,7 @@ async function applyNonInteractiveAuthChoice(params) {
 			provider,
 			name: ""
 		});
-		upsertAuthProfile({
+		await upsertAuthProfile({
 			profileId,
 			credential: {
 				type: "token",