pm-swarm 0.0.0-stage → 2026.10.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/LICENSE +21 -0
  3. package/README.md +397 -2
  4. package/dist/index.d.ts +40 -0
  5. package/dist/index.d.ts.map +1 -0
  6. package/dist/index.js +27 -0
  7. package/dist/index.js.map +1 -0
  8. package/dist/scripts/main-invocation.d.ts +33 -0
  9. package/dist/scripts/main-invocation.d.ts.map +1 -0
  10. package/dist/scripts/main-invocation.js +40 -0
  11. package/dist/scripts/main-invocation.js.map +1 -0
  12. package/dist/src/commands.d.ts +6 -0
  13. package/dist/src/commands.d.ts.map +1 -0
  14. package/dist/src/commands.js +169 -0
  15. package/dist/src/commands.js.map +1 -0
  16. package/dist/src/fair-scheduling.d.ts +129 -0
  17. package/dist/src/fair-scheduling.d.ts.map +1 -0
  18. package/dist/src/fair-scheduling.js +114 -0
  19. package/dist/src/fair-scheduling.js.map +1 -0
  20. package/dist/src/git-environment.d.ts +3 -0
  21. package/dist/src/git-environment.d.ts.map +1 -0
  22. package/dist/src/git-environment.js +8 -0
  23. package/dist/src/git-environment.js.map +1 -0
  24. package/dist/src/git.d.ts +16 -0
  25. package/dist/src/git.d.ts.map +1 -0
  26. package/dist/src/git.js +60 -0
  27. package/dist/src/git.js.map +1 -0
  28. package/dist/src/lease.d.ts +52 -0
  29. package/dist/src/lease.d.ts.map +1 -0
  30. package/dist/src/lease.js +205 -0
  31. package/dist/src/lease.js.map +1 -0
  32. package/dist/src/order.d.ts +8 -0
  33. package/dist/src/order.d.ts.map +1 -0
  34. package/dist/src/order.js +45 -0
  35. package/dist/src/order.js.map +1 -0
  36. package/dist/src/planner.d.ts +28 -0
  37. package/dist/src/planner.d.ts.map +1 -0
  38. package/dist/src/planner.js +61 -0
  39. package/dist/src/planner.js.map +1 -0
  40. package/dist/src/progress.d.ts +96 -0
  41. package/dist/src/progress.d.ts.map +1 -0
  42. package/dist/src/progress.js +154 -0
  43. package/dist/src/progress.js.map +1 -0
  44. package/dist/src/reap.d.ts +3 -0
  45. package/dist/src/reap.d.ts.map +1 -0
  46. package/dist/src/reap.js +28 -0
  47. package/dist/src/reap.js.map +1 -0
  48. package/dist/src/recovery.d.ts +3 -0
  49. package/dist/src/recovery.d.ts.map +1 -0
  50. package/dist/src/recovery.js +5 -0
  51. package/dist/src/recovery.js.map +1 -0
  52. package/dist/src/resource-tracker.d.ts +9 -0
  53. package/dist/src/resource-tracker.d.ts.map +1 -0
  54. package/dist/src/resource-tracker.js +45 -0
  55. package/dist/src/resource-tracker.js.map +1 -0
  56. package/dist/src/resources.d.ts +66 -0
  57. package/dist/src/resources.d.ts.map +1 -0
  58. package/dist/src/resources.js +87 -0
  59. package/dist/src/resources.js.map +1 -0
  60. package/dist/src/selection.d.ts +49 -0
  61. package/dist/src/selection.d.ts.map +1 -0
  62. package/dist/src/selection.js +33 -0
  63. package/dist/src/selection.js.map +1 -0
  64. package/dist/src/settings.d.ts +4 -0
  65. package/dist/src/settings.d.ts.map +1 -0
  66. package/dist/src/settings.js +14 -0
  67. package/dist/src/settings.js.map +1 -0
  68. package/dist/src/shared-tracker.d.ts +229 -0
  69. package/dist/src/shared-tracker.d.ts.map +1 -0
  70. package/dist/src/shared-tracker.js +320 -0
  71. package/dist/src/shared-tracker.js.map +1 -0
  72. package/dist/src/swarm.d.ts +171 -0
  73. package/dist/src/swarm.d.ts.map +1 -0
  74. package/dist/src/swarm.js +358 -0
  75. package/dist/src/swarm.js.map +1 -0
  76. package/dist/src/test-runner.d.ts +4 -0
  77. package/dist/src/test-runner.d.ts.map +1 -0
  78. package/dist/src/test-runner.js +17 -0
  79. package/dist/src/test-runner.js.map +1 -0
  80. package/dist/src/types.d.ts +42 -0
  81. package/dist/src/types.d.ts.map +1 -0
  82. package/dist/src/types.js +2 -0
  83. package/dist/src/types.js.map +1 -0
  84. package/dist/src/watch.d.ts +19 -0
  85. package/dist/src/watch.d.ts.map +1 -0
  86. package/dist/src/watch.js +90 -0
  87. package/dist/src/watch.js.map +1 -0
  88. package/dist/src/workspace.d.ts +3 -0
  89. package/dist/src/workspace.d.ts.map +1 -0
  90. package/dist/src/workspace.js +42 -0
  91. package/dist/src/workspace.js.map +1 -0
  92. package/manifest.json +14 -0
  93. package/package.json +139 -4
package/CHANGELOG.md ADDED
@@ -0,0 +1,25 @@
1
+ # Changelog
2
+
3
+ ## 2026.10.28 - 2026-10-28
4
+
5
+ ### Added
6
+
7
+ - Select ready work fairly using skills, age and handoff costs ([pm-swarm-fair-scheduling](https://github.com/unbraind/pm-swarm/blob/main/.agents/pm/features/pm-swarm-fair-scheduling.toon))
8
+ - Aggregate revision-bound shared plan progress witnesses ([pm-swarm-plan-progress](https://github.com/unbraind/pm-swarm/blob/main/.agents/pm/features/pm-swarm-plan-progress.toon))
9
+ - Coordinate parallel agents on a shared tracker without git ([pm-swarm-shared-tracker](https://github.com/unbraind/pm-swarm/blob/main/.agents/pm/features/pm-swarm-shared-tracker.toon))
10
+ - Reserve explicit shared resources with fenced tracker leases ([pm-swarm-resource-reservations](https://github.com/unbraind/pm-swarm/blob/main/.agents/pm/features/pm-swarm-resource-reservations.toon))
11
+ - Partition ready work by footprints and dependencies ([pm-swarm-9kio](https://github.com/unbraind/pm-swarm/blob/main/.agents/pm/features/pm-swarm-9kio.toon))
12
+ - Synchronize linked file footprints ([pm-swarm-cm86](https://github.com/unbraind/pm-swarm/blob/main/.agents/pm/features/pm-swarm-cm86.toon))
13
+ - Pick and start safe ready work automatically ([pm-swarm-next](https://github.com/unbraind/pm-swarm/blob/main/.agents/pm/features/pm-swarm-next.toon))
14
+ - Warn or refuse overlapping lane starts ([pm-swarm-overlap](https://github.com/unbraind/pm-swarm/blob/main/.agents/pm/features/pm-swarm-overlap.toon))
15
+ - Watch live lane status changes ([pm-swarm-watch](https://github.com/unbraind/pm-swarm/blob/main/.agents/pm/features/pm-swarm-watch.toon))
16
+ - Predict conflicts from real git merges ([pm-swarm-4343](https://github.com/unbraind/pm-swarm/blob/main/.agents/pm/features/pm-swarm-4343.toon))
17
+ - Retire only merged terminal lanes ([pm-swarm-dbn3](https://github.com/unbraind/pm-swarm/blob/main/.agents/pm/features/pm-swarm-dbn3.toon))
18
+
19
+ ### Changed
20
+
21
+ - Adopt pm-github 2026.10.16: default-branch-safe gated sync and daily gated closeout PRs ([pm-swarm-lux2](https://github.com/unbraind/pm-swarm/blob/main/.agents/pm/chores/pm-swarm-lux2.toon))
22
+
23
+ ### Other
24
+
25
+ - Release readiness behind PM_RELEASE_APPROVED ([pm-swarm-release-gate](https://github.com/unbraind/pm-swarm/blob/main/.agents/pm/chores/pm-swarm-release-gate.toon))
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 unbraind
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,398 @@
1
- # Temporary Holding Version
1
+ # pm-swarm
2
2
 
3
- 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.
3
+ Coordinate dozens of agents on one pm tracker, with renewed heartbeats, fenced ownership, dead-agent recovery and context handoff. pm-swarm uses SDK readiness, dependencies and declared file footprints to choose parallel work and show overlaps. Agents can share a plain directory and the same tracker. Git worktree lanes add optional branch isolation and merge prediction when the workspace is a Git worktree. It never pushes.
4
+
5
+ Install with PM CLI/SDK 2026.10.23 or later (Node 22.18 or later). Git lanes additionally require Git with `merge-tree --write-tree`. Automated GitHub releases require the repository variable `PM_RELEASE_APPROVED=true`. After publication:
6
+
7
+ ```sh
8
+ pm install pm-swarm --project
9
+ npm install pm-swarm @unbrained/pm-cli
10
+ bun add pm-swarm @unbrained/pm-cli
11
+ npx pm install pm-swarm --project
12
+ bunx --bun pm install pm-swarm --project
13
+ ```
14
+
15
+ For local review, build and pack this checkout, then `pm install ./pm-swarm-2026.10.15.tgz --project` in a scratch pm project, with or without Git. npm and Bun dependencies alone do not activate project extensions; use `pm install` to register it.
16
+
17
+ | Command | Example | Behavior |
18
+ | --- | --- | --- |
19
+ | plan | `pm swarm plan --parent project-id --limit 3` | Certified full corpus, SDK readiness and claim view, safe parallel waves |
20
+ | next | `pm swarm next --agent worker --parent project-id` | Pick the best safe ready item and claim its lane; `--dry-run` previews the choice and makes no changes |
21
+ | start | `pm swarm start task-id --agent worker --base main --root ../lanes` | Claim a shared lane; in Git, also create a worktree and branch; warn on overlaps, or refuse with `--strict` |
22
+ | status | `pm swarm status` | Assigned lanes and declared overlaps without Git; in Git, conflicting pairs and clean pair count; `--full` includes every SHA/tree; active branches, ahead/behind current target, changed files, drift, pair and base-tip predictions |
23
+ | status --watch | `pm swarm status --watch --interval 2 --json` | Stream lane and conflict changes as JSON lines (TOON blocks by default); stop with Ctrl-C |
24
+ | sync | `pm swarm sync task-id --files src/a.ts,src/b.ts --dry-run` | Preview explicit changed-file links, or derive them from Git; `--apply` writes through the SDK |
25
+ | heartbeat | `pm swarm heartbeat --agent worker` | Renew agent liveness; optional item ID plus `--token` verifies a held generation |
26
+ | reclaim | `pm swarm reclaim --stale-after 120 --to recovery-worker` | Atomically return stale claims to the open pool (omit `--to`) or transfer them with recovery evidence |
27
+ | handoff | `pm swarm handoff task-id --agent worker --token 1 --to reviewer --note "Tests linked; review parser"` | Atomically transfer ownership and compact context; shared-tracker receiver obtains it from `next` |
28
+ | close | `pm swarm close task-id --agent worker --token 1 --note "Tests pass"` | Fence, finish and release a shared claim in one mutation |
29
+ | progress | `pm swarm progress PLAN_ID --orchestrator coordinator` | Read revision-bound claimed, produced, reviewed and accepted Plan evidence; explicit witness writes use `--apply` |
30
+ | resource | `pm swarm resource resource-id --action reserve --ttl 300 --agent worker` | Exclusive non-file resource lease; status, renew, publish and release share the same tracker fence |
31
+ | land | `pm swarm land` | Search real sequential merges; `--execute` runs linked tests and merges locally |
32
+ | reap | `pm swarm reap --dry-run` | Preview terminal claim release; in Git, also remove merged terminal lanes |
33
+ | settings | `pm swarm settings --base main --root ../lanes --branch-prefix swarm/ --limit 4 --apply` | Preview or apply the `swarm` settings section through the SDK |
34
+
35
+ ## Install and release approval
36
+
37
+ The first npm release is pending the maintainer's interactive bootstrap. After
38
+ that first publish, the maintainer configures npm trusted publishing for
39
+ `release.yml` and sets the repository variable `PM_RELEASE_APPROVED` to `true`.
40
+ The daily workflow and manual dispatch both require this variable and `main`.
41
+ Publishing uses OIDC with provenance; no stored npm token is needed.
42
+
43
+ Once published, install the package and compatible pm host, then activate the
44
+ extension in an initialized pm project:
45
+
46
+ ```sh
47
+ npm install pm-swarm @unbrained/pm-cli
48
+ npx --no-install pm package install ./node_modules/pm-swarm
49
+
50
+ bun add pm-swarm @unbrained/pm-cli
51
+ bunx --bun --no-install pm package install ./node_modules/pm-swarm
52
+
53
+ pm package install npm:pm-swarm
54
+ pm swarm --help
55
+ ```
56
+
57
+ The package exports its SDK through `main` and `types` and registers commands
58
+ with pm. It has no standalone `bin`: use `npx pm` or `bunx --bun pm` through
59
+ the installed host. npm/Bun dependency installation alone does not activate it.
60
+
61
+ ## Without git
62
+
63
+ Plan progress reads and witness declarations, plus resource status, reservation, renewal, publication and release work in plain trackers and never invoke Git, including when Git is absent from PATH. Git worktree planning and branch landing require Git. See the resource example below for an independent resource loop alongside item claims.
64
+
65
+ The primary agent loop is `next` → heartbeat while working → `sync --files --token` → `close --token`. Run `pm init` in a plain directory and install the extension there. Mode is detected once per invocation; non-Git workspaces return `mode: shared-tracker`. `settings` works without repository detection. The tracker commands do not start Git in this mode, including when Git is absent from PATH.
66
+
67
+ ```sh
68
+ pm swarm plan
69
+ pm swarm next --agent worker --dry-run
70
+ pm swarm next --agent worker --json
71
+ # Retain selected and token from this response. The token below is illustrative.
72
+ pm swarm heartbeat task-id --agent worker --token 1
73
+ # Edit and test in the shared workspace.
74
+ pm swarm sync task-id --agent worker --token 1 --files src/a.ts,test/a.test.ts --apply
75
+ pm swarm status --watch --interval 2
76
+ pm swarm close task-id --agent worker --token 1 --note "Tests pass"
77
+ pm swarm reap --agent worker --dry-run
78
+ pm swarm reap --agent worker
79
+ ```
80
+
81
+ Shared lanes are all items with a nonblank assignee, including items with SDK claims made inside or outside swarm, except items tagged `swarm-resource`. Assigned-only items also block overlapping selection. `start` records fenced ownership and the linked footprint through the SDK, without branch or base fields. Selection and shared writes enter an ordered request queue and hold a tracker-local operation pin, with a 30-second lease renewed every five seconds during long mutations. Expiry refuses a resumed writer before its next SDK mutation. The pin is never stolen from a live process during an awaited SDK write; a killed process releases it through the next caller's recovery check. Contention retries use jittered backoff, bounded at five minutes, and exhausted contention fails explicitly. A hung but live process blocks other mutations until it finishes or is terminated.
82
+
83
+ Each shared claim persists a monotonically increasing decimal `swarm_token` and claim timestamp atomically with its assignee. `next` and `start` return `token`; keep that exact string and pass `--token` to shared `sync --apply`, `handoff` and `close`. A stale or missing token is refused with typed `StaleFenceError` / CLI code `swarm_stale_fence` before changing item data. Reusing an author ID after a takeover does not make its old token valid. Embedded `SharedTracker` instances remember the tokens they issue; separate CLI invocations require the explicit token. Legacy claims without a swarm token retain ordinary SDK ownership checks. Plan excludes candidates overlapping active assigned items and places unknown footprints in solitary waves; unknown work is deferred when active lanes prevent a safe planning recommendation. `next` retains its explicit unknown-footprint fallback. Claims made by tools outside swarm do not participate in its multi-item footprint lease; recheck status before editing.
84
+
85
+ `status` lists nonterminal assigned items with their agent, linked files, claim timestamp and age in seconds. Assignments without valid claim provenance have null age. It shows declared overlaps, including unknown footprints, and a one-line note explaining that Git ahead/behind and merge predictions are unavailable. Watch adds `overlap_detected`, `overlap_changed` and `overlap_resolved` events. Age advancing alone emits no change.
86
+
87
+ `sync` requires `--files a,b` without Git. Paths must be relative to the project; `--apply` links them through the SDK and `--dry-run` always previews. `reap` releases terminal claims belonging to the invoking principal; it reports foreign terminal claims with guidance to use their `--agent` principal. Active claims are preserved. `land` exits 2 and explains that it merges Git branches; shared-tracker work already lives on the shared tracker. The dedicated `npm run test:scale` proof installs the built package into one non-Git tracker and runs 50 real process agents through next/heartbeat/sync/close loops, kills 13 of 50 mid-run, reclaims their items and checks every write plus full strict health. Git is absent from PATH. See [fenced lease verification](docs/fenced-leases-verification.md) for measured timings. Hosted Postgres/MCP coordination is not certified by that local-process test.
88
+
89
+ ## Exclusive resources
90
+
91
+ Use one canonical tracker item per physical resource: a test database, port,
92
+ dataset, test environment or deployment slot. Provision it once with the
93
+ `swarm-resource` tag and distribute its ID to every worker. Different IDs are
94
+ different resources even if their titles match. Resource items are excluded from
95
+ work selection, item start/sync/close/handoff and stale-agent reclaim. Ordinary
96
+ work claims and resource reservations remain independent; acquire the resource
97
+ before using it and release it in cleanup. Acquisition is exclusive even for the
98
+ same principal; use renew to extend a reservation you already hold.
99
+
100
+ ```sh
101
+ pm create --type Task --id test-db --title "Integration test database" --tags swarm-resource
102
+ # Use the actual resource ID returned by create, including its project prefix.
103
+ pm swarm resource project-test-db --action reserve --agent worker --ttl 300 --json
104
+ # Retain the returned token string; this example assumes generation 1.
105
+ pm swarm resource project-test-db --action renew --agent worker --token 1 --ttl 600
106
+ pm swarm resource project-test-db --action publish --agent worker --token 1 --note "Integration checks passed"
107
+ pm swarm resource project-test-db --action release --agent worker --token 1
108
+ pm swarm resource project-test-db
109
+ ```
110
+
111
+ TTL defaults to 300 seconds and accepts integers from 1 through 86400. Renew
112
+ before expiry; an agent heartbeat does not extend a resource reservation. Expired
113
+ owners cannot renew, release or publish. A successor reserve increments the
114
+ durable decimal `swarm_token`; release also increments it, preventing same-author
115
+ ABA. No background reaper is required. Retain resource items and their append-only
116
+ histories rather than deleting/recreating them, which would reset their identity.
117
+
118
+ Every command returns only `id`, `resource`, `token`, `owner`, `expires_at` and
119
+ `held`, in native TOON or JSON. Status preserves the recorded expired owner while
120
+ reporting `held: false`. Publication appends a note of at most 4096 characters in
121
+ one atomic tracker update; it retains the reservation until release or expiry.
122
+ `ResourceRefusal` exposes `code` and `remedy`; CLI exit 2 preserves the code and
123
+ includes the remedy in its diagnostic. `resource_busy` means wait or ask the owner
124
+ to release; `resource_stale_fence` means discard the token/result, reserve and
125
+ recompute; `resource_invalid` means inspect the tagged item or fix input;
126
+ `resource_backend_refused` means configure a backend with shared fencing.
127
+
128
+ The built-in `trackerResourceBackend(engine)` reuses #12's local tracker operation
129
+ lease, holding its live writer pin through SDK commit and writing assignee,
130
+ generation, expiry and publication evidence together. It conservatively refuses
131
+ extensions declaring services (or missing/empty capability declarations), since their
132
+ storage ownership cannot be established by this adapter. It never switches to
133
+ local coordination after a provider refusal. The generic `ResourceBackend`
134
+ contract lets a hosted provider supply tracker-wide serialization and atomic
135
+ writes without changing the resource model; a provider must implement its lease
136
+ and commit guarantees explicitly. Hosted Postgres/MCP providers are not certified
137
+ by the filesystem adapter's tests. Direct core writes bypass the swarm protocol;
138
+ all cooperating agents must use this resource API. Tokens guard publication to
139
+ the tracker, not arbitrary external database/deployment writes: those sinks must
140
+ also validate fencing if they allow delayed writes after resource expiry.
141
+
142
+ For the typed SDK example, see [resource reservations](docs/resource-reservations.md).
143
+
144
+ ## Heartbeats, takeover and handoff
145
+
146
+ While editing or running tools outside swarm, run `pm swarm heartbeat --agent worker` regularly. Awaited swarm mutations renew the operation lease and the invoking principal's heartbeat automatically. Synchronous Git subprocesses block those timers; Git mode retains its live process pin across such calls and checks both pin and operation generations before each write, without treating heartbeat age alone as lost ownership. Shared-tracker mode also enforces the heartbeat expiry check. Runtime liveness records stay in the tracker's ignored runtime directory; deleting those records discards recent liveness evidence, so preserve them while agents are active. A new claim or transfer grants a fresh heartbeat interval even if the receiver last ran long ago.
147
+
148
+ Operation owners and queued requests include a hashed host boot and PID namespace identity. Automatic dead-process recovery uses PID probes only when that locality matches. A missing, different or unverifiable locality is preserved as potentially live, including legacy records, another container's PID namespace and unavailable locality probes. Unverifiable ownership can therefore return `swarm_busy` until its owner finishes or an operator inspects abandoned records. Clear only confirmed abandoned pin/request records in the ignored `runtime/swarm` directory after all writers sharing the tracker are stopped. Automatic recovery is certified for the same Linux host boot and PID namespace; this does not certify cross-host coordination.
149
+
150
+ `pm swarm reclaim --stale-after 120 --parent project-id --dry-run` previews stale swarm assignments among direct children without writing item history, ownership or heartbeat records. Remove `--dry-run` to apply; omit `--parent` to scan the tracker. The invoking principal's own assignments are preserved in both preview and apply. Only assignments marked by `swarm_token`, `swarm_claimed_at` or `swarm_branch` are eligible, so ordinary human and SDK assignments are preserved. Only the configured open and in-progress statuses can return to the configured open status; blocked, review, draft and other workflow states are preserved and reported in `refused`. Add `--to recovery-worker` to assign them directly. Each item transition bumps the token and appends a comment with the previous owner, last heartbeat, previous token and destination in the same SDK update. Reclaim uses the newest valid claim or heartbeat timestamp. Before transfer it checks a fresh item against the corpus snapshot and re-reads the owner's heartbeat; observed item changes or fresh heartbeats preserve the item. Core SDK writes and agent-wide heartbeats after that final check can still race with recovery; they do not participate in the swarm pin. Terminal reap also revalidates its item snapshot before release or Git cleanup. Items with neither valid timestamp are preserved and reported in `refused` with guidance to repair their liveness evidence. A `swarm_token` that is not a decimal generation is also preserved and reported in `refused`, and reclaim continues with the other items; `start`, `next`, `handoff` and `close` name that item and refuse before writing. Reclaim does not return a Git lane (`swarm_branch` set) to the pool, because Git `next` skips it and Git `start` reports that the lane already exists. Pass `--to` to keep that lane assigned; explicit reassignment preserves `swarm_branch`. Terminal work is left alone. Choose a threshold longer than your external heartbeat interval.
151
+
152
+ `pm swarm handoff task-id --agent worker --token 1 --to reviewer --note "Tests linked; inspect edge cases"` transfers owner, token, note and receiver packet in one item transaction. `pm swarm next --agent reviewer` returns that assigned item before selecting new work, with its new token and `context`: item state, up to 50 linked files, the last three comments (up to 1024 characters each), sender and note. `files_omitted` reports any file truncation. The full item remains available through `pm show`. A returned handoff remains available until finished or handed on. Malformed handoff JSON, null/primitive/array contexts, and missing, non-decimal or mismatched context tokens are refused as `swarm_stale_fence` in both preview and claim modes, without changing item history.
153
+
154
+ Shared `sync --apply`, `handoff` and `close` consume fencing tokens; reclaim and terminal reap follow their administrative recovery policies. Git `sync --apply` also checks current ownership under the tracker lease and requires `--token` when the item has a swarm token, including after a round-trip handoff. A supplied stale token is refused even when there are no new paths. Core pm commands and external SDK clients do not supply swarm tokens and can bypass this protocol; use the swarm writer commands for the fenced loop. This package does not change the host SDK. Agent principals are caller-selected identities, not an authentication system. Other optional Git worktree commands retain their existing SDK ownership contract.
155
+
156
+ ## Optional Git worktree lanes
157
+
158
+ Inside a Git worktree, existing lane behavior is retained. Use `next` → work and commit in the printed worktree → `sync --apply` → `status` → `land`. Git-specific settings and flags control this optional isolation layer.
159
+
160
+ ```sh
161
+ pm swarm next --agent worker --parent project-id
162
+ pm swarm sync task-id --agent worker --apply
163
+ pm swarm status --watch --interval 2
164
+ pm swarm land --json
165
+ pm swarm land --execute
166
+ ```
167
+
168
+ `next` uses the same certified corpus and SDK dependency readiness as `plan`, excluding existing lanes and both own and foreign claims. It selects known footprints that do not intersect any nonterminal lane's declared footprint or actual changed paths, measured with Git from the current target's merge base. Priority sorts ascending (0 first), then creation time ascending (oldest first), then item ID. A lower priority safe item beats a higher priority overlapping item. Output includes the selection reason and skipped candidates with overlapping lane IDs and paths. `--parent` selects direct children. Both modes serialize through the tracker process pin; Git operations acquire the repository lease inside it. Git retains that pin across synchronous subprocesses that can outlast the heartbeat interval; ownership generations remain checked before writes. Git selection also checks assigned items without a local branch, including assigned-only items; the SDK claim is the final ownership check.
169
+
170
+ Unknown candidate footprints are deferred until no known safe item exists, then started with an explicit warning. An active lane with neither linked nor changed paths cannot establish safety and blocks known candidates conservatively. When no eligible item remains, `selected` is null and no lane is created. `--dry-run` makes no claim, item/history edit, branch, worktree, or local Git configuration change. Normal host SDK read caches may still be refreshed. `next` uses the configured base, root and branch prefix, just as `start` does.
171
+
172
+ `start` includes `overlap_warnings`, naming each active lane and the candidate and lane paths. The default still starts successfully; `pm swarm start task-id --strict` refuses overlaps before claiming or creating a worktree. These checks prevent obvious overlapping edits; real merge predictions remain available through `status` and `land`.
173
+
174
+ `status --watch` emits initial lanes/conflicts as additions, then only changes: `lane_added`, `lane_changed`, `lane_removed`, `conflict_predicted`, `conflict_changed`, and `conflict_resolved`. Ahead/behind counts, changed files and footprint drift participate in lane comparisons. Repeated identical polls emit nothing. The default interval is two seconds; smaller positive requests are clamped to two seconds, and values above 86400 seconds or nonfinite/nonpositive values are rejected. `--interval` requires `--watch`. Ctrl-C exits successfully and clears the pending timer. Watch reads local refs without fetching; fetch remote work explicitly when needed. TOON blocks are separated by blank lines; `--json` emits one event per line. Watch uses the host-pinned SDK codec, keeping the package free of runtime dependencies.
175
+
176
+ Each planning wave contains mutually compatible items. The first wave is the suggested start set. Every incompatible pair carries its separation reasons: equal or containing paths, dependencies, or an unknown footprint. Missing file links always mean `footprint: unknown`, with a solitary wave. Capacity is enforced independently by `--limit`. The SDK excludes blocked work and unfinished containers; only open and unclaimed items start in a plan. `--parent` selects direct children. Readiness is advisory: the SDK claim is the atomic ownership check when starting.
177
+
178
+ `start` registers `swarm_branch`, `swarm_base` (the original commit SHA), and `swarm_base_ref` (the moving target ref). Defaults are base `main`, worktree root `../.pm-swarm`, branch prefix `swarm/`, lane limit 4. Flags override settings. Planning supports limits 1–8; landing searches up to eight active lanes exhaustively and refuses larger batches explicitly.
179
+
180
+ Absolute worktree paths live only in repository-local Git config (`swarm.lane.<id>`). Never put machine paths into tracker fields, comments, or settings. A persisted root setting must be relative; an absolute `start --root` override remains local. Worktree paths may appear in command output. If the lane root is inside the repository, ignore that directory before landing so the base worktree stays clean. Existing absolute linked paths are rejected so sync cannot persist them. Keep `.agents/pm/extensions/` ignored: the host package installer records local tarball provenance there.
181
+
182
+ All package Git operations strip inherited Git location variables (`GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, `GIT_OBJECT_DIRECTORY`, `GIT_ALTERNATE_OBJECT_DIRECTORIES`, `GIT_COMMON_DIR`, `GIT_NAMESPACE`, and `GIT_PREFIX`). The explicit repository directory determines the target, including linked worktrees; hook environment variables cannot redirect operations to a parent or unrelated repository. Other Git configuration and identity variables remain available.
183
+
184
+ Git simulations use configured repository merge drivers; `missing_merge_drivers` reports missing pm configuration, and unresolved tracker paths remain visible in `tracker_conflicts`. Run predictions only in repositories you trust.
185
+
186
+ Status compares each lane with its current target tip and each other lane. Each prediction includes `left_id`, `left_branch`, `right_id`, `right_branch`, conflicting files, an explicit `clean` result from Git's exit status, and informational `messages`; the current target is identified as `base`. Conflicts with no individual paths remain visible with their messages. Default output shows conflicting pairs plus `clean_pairs`; `pm swarm status --full` includes all pairs, commit SHAs, and merge trees. Changed files are measured from the merge base of the current target tip and lane tip, so inherited base updates do not become agent footprints. The recorded starting SHA preserves lane provenance. Drift means a changed path has no linked equal or containing footprint. Git simulations write unreferenced objects, without changing branches, index, or worktree files.
187
+
188
+ Landing backtracks through simulated merge commits, preserving ancestry at each step. If no complete order succeeds, `order` is the largest clean landable subset, with sorted item IDs breaking ties deterministically. `conflicting_set` remains a minimum-cardinality unlandable subset against the base. `blocked` names each remaining lane, conflicting files, Git messages, peers, and a suggested next step such as `rebase swarm/task-b after swarm/task-a lands`. `pm swarm land --execute` merges only the clean order and leaves blocked branches and worktrees untouched; partial results still exit 1. Execution requires the configured base checked out and clean, all lane targets equal to that base, unchanged refs, nonempty linked tests, and every SDK linked-test result passing. Tests run on each simulated merged tree in a temporary worktree through the host's normal trust and sandbox policy. The pinned host uses `GITHUB_HEAD_REF`, then `GITHUB_REF_NAME`, before the local Git branch when deciding source-ref trust; CI flags alone do not grant trust. Foreign-ref commands require explicit clone-local acknowledgement. Tests explicitly exercise refused, acknowledged, and matching hosted-ref states. Refused, skipped, or empty tests block landing. No automatic dependency installation occurs in verification worktrees. All tests are preflighted before the first local merge; unexpected Git failures can still leave earlier merges committed. Inspect and resume explicitly. There is no push. Under `bunx --bun`, Bun supplies the `node` shim; author Bun suites as `bun test`, or provide the intended Node executable in the linked command.
189
+
190
+ Reaping requires the item to have a closed or canceled status, or an SDK terminal status. Branch ancestry must also prove it is merged into its target. Dirty worktrees, mismatched worktree registrations, active items, and unmerged branches are preserved. `start`, `sync`, and `reap` accept `--agent` to select the invoking principal. Only the invoking principal's stale claim is released; foreign claims remain intact. Reaping detects missing lane directories and removes only their stale registrations, preserving unrelated worktree records. A leftover directory is removed only at its expected location inside the configured swarm root, with a worktree marker pointing to a missing registration in this repository. Arbitrary directories, symlink redirections, locked worktrees, and paths outside that root are refused and preserved. The result reports `cleanup` actions and `refused` reasons; dry runs preview these actions. A local `start --root` override must match the configured root before reaping. Reaping does not delete tracker items.
191
+
192
+ Successful commands exit 0. An unlandable set exits 1. Invalid input, ownership refusal, failed Git operations, or failed linked tests use the host's expected-error exit (normally 2). Host rendering supports TOON by default and `--json`. Plans always certify complete SDK reads and fail closed. Default output omits `complete_list` and `read_output`; use `pm swarm plan --full` or `pm swarm plan --json` to retain those receipts and their token estimate. Status and land also accept `--full` for detailed output.
193
+
194
+ For CI, install dependencies and register the extension, then inspect predictions without executing merges:
195
+
196
+ ```sh
197
+ pm swarm plan
198
+ pm swarm plan --full
199
+ pm swarm status
200
+ pm swarm status --full
201
+ pm swarm land --json
202
+ ```
203
+
204
+ `status` reports conflicts without failing the process; `land` supplies the conflict exit gate. For package development, run `npm run release:check` and `bun run release:check` with isolated HOME and Git configuration. CI verifies tracker health, commit identity, TypeScript, lint, duplication, docstrings, four 100% coverage dimensions, production audit, package allowlist, generated changelog, release attestation and packed npm/native Bun consumers. Packed acceptance also installs the tarball into a non-Git tracker and runs the shared loop. Git acceptance extracts `npm pack`, installs the directory with `pm install <dir> --project` into fresh Git repositories and trackers, and checks real host commands through Node, npx, Bun and bunx, including TOON/JSON watch shutdown. A built artifact import check rejects dependencies outside Node built-ins and the pm SDK. Release has only a manual trigger plus an approval variable; scheduled publication stays disabled.
205
+
206
+ ## Shared plan progress witnesses
207
+
208
+ `pm swarm progress PLAN_ID` aggregates each core Plan step's owner and declared
209
+ production evidence into one content revision. It works on one shared tracker,
210
+ including a plain directory with no Git executable. It does not land branches,
211
+ execute linked evidence, or create another task tracker. Requires PM CLI/SDK
212
+ 2026.10.23 or newer for concurrent mutation lease fencing and writer deadlines.
213
+
214
+ Configure the accepting principal once through the tracker's audited settings
215
+ operation. Acceptance commands cannot appoint their own orchestrator:
216
+
217
+ ```sh
218
+ pm swarm settings --progress-orchestrator coordinator --apply
219
+ pm swarm progress delivery-plan --json
220
+ pm swarm progress delivery-plan --offset 20 --limit 20 --revision REVISION
221
+ ```
222
+
223
+ `swarm.progress_orchestrator` is the authority for both reads and writes. Without
224
+ it, accepted counts remain zero and acceptance is refused. `--orchestrator` is
225
+ an optional assertion that must match this setting; it never selects authority.
226
+ `--agent` must match the SDK-recorded mutation author from `PM_AUTHOR`, the global
227
+ SDK author option, or the configured SDK default. A disagreement produces a
228
+ `progress_role` refusal with a remedy before any witness is written.
229
+
230
+ The default TOON and JSON projections include exact counts, up to 20 compact
231
+ step rows, `omitted` and `next_offset`; the maximum page size is 100. Continue with
232
+ `--revision` to refuse changed Plan inputs or approval authority. Evidence bodies
233
+ and raw comments stay in `pm show PLAN_ID --full`. The view distinguishes:
234
+
235
+ | Level | Required evidence |
236
+ | --- | --- |
237
+ | claimed | A core Plan step has an owner. |
238
+ | produced | That owned step is completed with nonempty core `stepEvidence`. |
239
+ | reviewed | A reviewer whose SDK-recorded author differs from the worker explicitly witnesses the revision. |
240
+ | accepted | The configured orchestrator's SDK-recorded author differs from both worker and reviewers and accepts the reviewed revision. |
241
+
242
+ Core `pm plan approve`, a completed status, ordinary comments and worker
243
+ self-reports do not establish orchestrator acceptance. Witness actors are the
244
+ SDK mutation authors also written to item history. Flags cannot override that
245
+ attribution. The receipt includes the resolved `actor`; regression tests verify
246
+ it against both comment authors and the corresponding history entry authors.
247
+
248
+ Identities in pm are asserted. This prevents accidental or casual self-approval
249
+ by one agent changing progress flags. Changing `PM_AUTHOR`, an SDK author option,
250
+ or tracker settings remains an asserted identity/configuration change, not proof
251
+ of a distinct person or process. Adversarial settings need **signed provenance**
252
+ and stronger authorization. These witnesses are not signed and do not provide
253
+ that boundary; protect tracker configuration and write access accordingly.
254
+
255
+ A SHA-256 content revision covers the Plan title, description, body, acceptance
256
+ criteria, readiness definition, all `plan_*` metadata (including step bodies,
257
+ owners, evidence, links and validation), item artifact/dependency links, and the
258
+ configured orchestrator. Any such change invalidates existing review and
259
+ acceptance. Unchanged comments do not invalidate witnesses. This is a content
260
+ revision, not a Git commit or wall-clock version: restoring identical inputs
261
+ restores the same revision. Witnesses refer to declared evidence, not
262
+ independently verified artifact bytes.
263
+
264
+ Reads and declarations are read-only by default. Only `--apply` appends an
265
+ attributed, idempotent `swarm-progress/v2` SDK comment. Previous v1 comments are
266
+ excluded because their actors could have been selected by progress flags;
267
+ re-evaluate and submit new review/acceptance witnesses. Existing core Plan
268
+ commands remain the source of steps, owners and production evidence. SDK atomic
269
+ comments preserve concurrent writers on the same tracker. A criterion or
270
+ configured-authority edit racing a witness append leaves an old-revision
271
+ witness that the new view excludes. Provider failures propagate without a
272
+ filesystem fallback.
273
+
274
+ ```sh
275
+ pm plan create --title 'Parallel delivery' --step 'Implement parser' --step 'Document API'
276
+ pm plan update-step PLAN_ID STEP_ID --step-owner worker
277
+ pm plan complete-step PLAN_ID STEP_ID --step-evidence 'Parser regression passed'
278
+ pm swarm progress PLAN_ID --json
279
+ # Copy the returned revision; the first declaration below is only a preview.
280
+ PM_AUTHOR=reviewer pm swarm progress PLAN_ID --agent reviewer --stage reviewed \
281
+ --step STEP_ID --revision REVISION --evidence 'Inspected parser and regression'
282
+ PM_AUTHOR=reviewer pm swarm progress PLAN_ID --agent reviewer --stage reviewed \
283
+ --step STEP_ID --revision REVISION --evidence 'Inspected parser and regression' --apply
284
+ PM_AUTHOR=coordinator pm swarm progress PLAN_ID --agent coordinator \
285
+ --stage accepted --step STEP_ID --revision REVISION \
286
+ --evidence 'Review and criterion verified' --apply
287
+ pm swarm progress PLAN_ID --json
288
+ ```
289
+
290
+ The typed SDK binds the same options used by its owned pm client. The actor is
291
+ never a separate positional identity that can disagree with that client:
292
+
293
+ ```ts
294
+ import { PlanProgress } from 'pm-swarm';
295
+
296
+ const progress = new PlanProgress({ cwd: '.', pmRoot: '.agents/pm', author: 'coordinator' });
297
+ const view = await progress.view('delivery-plan', { limit: 20 });
298
+ // Preview by default; supply apply: true after evaluating this exact revision.
299
+ await progress.witness(view.id, {
300
+ step: view.steps[0].id, revision: view.revision, stage: 'accepted',
301
+ evidence: 'Independent review verified',
302
+ });
303
+ ```
304
+
305
+ `ProgressRefusal` provides `code` and `remedy`. CLI expected errors retain both
306
+ as structured context. `progress_stale` requires a fresh read and re-evaluation;
307
+ `progress_role` requires matching SDK attribution, independent principals and
308
+ tracker-configured authority; `progress_prerequisite` requires production and
309
+ then review; `progress_invalid` identifies invalid settings, a Plan, step, page
310
+ or witness. Malformed current-version comments fail closed; ordinary comments
311
+ remain ordinary discussion.
312
+
313
+ ## Fair assignment by skills, age and handoff cost
314
+
315
+ `pm swarm schedule` is an opt-in policy over the same certified SDK readiness,
316
+ dependencies, ownership and footprint checks as `next`. It assigns work and never
317
+ launches an agent. It works without Git, including with no Git executable on PATH;
318
+ inside Git it retains measured changed-path checks and optional worktree lanes.
319
+
320
+ Declare hard item requirements with `skill:<name>` tags. Names are case sensitive,
321
+ 1–64 letters, digits, underscores, dots or dashes; an agent may declare up to 64.
322
+ Every required skill must match. Untagged work requires no skills. Optionally set
323
+ `swarm_preferred_agent` and `swarm_handoff_cost` through the extension's registered
324
+ fields. Cost is a nonnegative integer up to 1000000, default 1; it is zero when
325
+ there is no preferred agent or the caller matches that agent. It is a ranking
326
+ unit, not a measured duration or a model's inferred ability.
327
+
328
+ ```sh
329
+ pm create --type Task --title 'Extend parser' --tags skill:typescript \
330
+ --file path=src/parser.ts --field swarm_preferred_agent=parser-worker \
331
+ --field swarm_handoff_cost=5
332
+ pm swarm schedule --agent parser-worker --skills typescript,testing --dry-run
333
+ pm swarm schedule --agent parser-worker --skills typescript,testing --json
334
+ # Retain selected and token, then use the existing heartbeat/sync/close loop.
335
+ ```
336
+
337
+ Below `--max-wait` (default 86400 seconds, range 1–31536000), selection orders by
338
+ priority, lower handoff cost, oldest creation timestamp, then ID. At the threshold,
339
+ qualified work moves ahead of fresh work regardless of priority or transfer cost;
340
+ aged work orders by oldest creation timestamp then ID. With equal input and clock,
341
+ selection is deterministic, including when corpus enumeration changes. Creation
342
+ age is the starvation baseline, not time since becoming ready. Future timestamps
343
+ have age zero. Hard skills, dependency readiness and active conflicts are never
344
+ waived: aging cannot make unsafe or unqualified work runnable. Once those
345
+ constraints clear, an aged item precedes newer arrivals. Unknown footprints may
346
+ start only with no active lanes; in that case aging and the same rank apply to
347
+ them too. This is stricter than `next`'s unknown fallback.
348
+
349
+ Assigned shared-tracker handoffs still take precedence and return the existing
350
+ bounded receiver context and fencing token. Their required skills are checked;
351
+ an unqualified receiver gets `schedule_skills` and must use a qualified receiver.
352
+ An explicit handoff is already assigned, so it adds no ready-candidate rows.
353
+ The scheduler does not reassign someone else's work to reduce a cost.
354
+
355
+ Both TOON and JSON return `selected`, `agent`, `token` when claimed, `reason`, a
356
+ frozen `now`, exact `counts`, and at most 20 compact `decisions` (set `--limit`
357
+ 1–100). The selected row comes first, followed by IDs. `omitted` counts hidden
358
+ rows; decisions distinguish skills, conflicts, lower rank and unknown footprints.
359
+ No corpus, full item bodies or histories are included. `--parent` scopes direct
360
+ children. `--dry-run` writes no claim or history and cannot reserve a later result.
361
+ Real selections hold the existing swarm tracker operation lease across reading,
362
+ ranking and the SDK claim mutation, serializing `schedule`, `next` and `start`
363
+ on the same tracker. External core writers can bypass swarm's footprint protocol;
364
+ all cooperating selectors must use swarm. Local coordination conservatively
365
+ refuses storage-service extensions; hosted Postgres/MCP scheduling is not certified.
366
+
367
+ ```ts
368
+ import { SharedTracker, Swarm, SchedulingRefusal } from 'pm-swarm';
369
+ import { PmClient } from '@unbrained/pm-cli/sdk';
370
+
371
+ const client = new PmClient({ cwd: '.', pmRoot: '.agents/pm', author: 'parser-worker' });
372
+ const tracker = new SharedTracker(new Swarm('.', '.agents/pm', client, 'parser-worker'));
373
+ try {
374
+ const choice = await tracker.schedule({
375
+ skills: ['typescript', 'testing'], maxWaitSeconds: 3600, dryRun: true,
376
+ // Optional SDK clock for repeatable policy evaluation:
377
+ now: '2026-10-23T12:00:00.000Z',
378
+ });
379
+ console.log(choice.selected, choice.reason, choice.counts);
380
+ } catch (error) {
381
+ if (error instanceof SchedulingRefusal) console.error(error.code, error.remedy);
382
+ else throw error;
383
+ }
384
+ ```
385
+
386
+ `Swarm.schedule` exposes the same typed options and receipt for optional Git lanes.
387
+ `SchedulingRefusal` codes are `schedule_invalid` (fix options, skill tags or item
388
+ metadata), `schedule_skills` (declare the required skills or hand off to a qualified
389
+ receiver), and `schedule_backend_refused` (use supported tracker-wide coordination).
390
+ The CLI exits 2 with the code and remedy. An empty eligible set is a successful
391
+ receipt with `selected: null`, not an ownership transfer.
392
+
393
+ Every workflow job granted write permissions, including CodeQL, Dependabot and
394
+ reusable workflow calls, requires the exact repository `unbraind/pm-swarm`.
395
+ The approval variable controls GitHub releases; it does not impose a local npm
396
+ publishing hold. Maintainers run the prepublish checks and authenticate with npm
397
+ for local publication. The first local publish uses `--provenance=false`; daily
398
+ GitHub OIDC releases keep provenance enabled.
@@ -0,0 +1,40 @@
1
+ /** Expose opt-in fair assignment options, compact decisions and actionable refusals. */
2
+ export { SchedulingRefusal } from './src/fair-scheduling.ts';
3
+ /** Typed policy inputs and bounded scheduling receipts. */
4
+ export type { ScheduleOptions, ScheduleReceipt, SchedulingDecision, SchedulingRefusalCode } from './src/fair-scheduling.ts';
5
+ /** Expose revision-bound parallel Plan progress and typed recovery instructions. */
6
+ export { PlanProgress, ProgressRefusal, PROGRESS_PREFIX } from './src/progress.ts';
7
+ /** Expose portable witness, declaration and compact progress contracts. */
8
+ export type { ProgressWitness, ProgressStage, ProgressView, ProgressStep, ProgressOptions, ProgressDeclaration, ProgressRefusalCode } from './src/progress.ts';
9
+ import { register } from './src/commands.ts';
10
+ /** Expose the same tracker-bound engine used by host commands. */
11
+ export { Swarm } from './src/swarm.ts';
12
+ /** Expose claim coordination for trackers without Git worktree lanes. */
13
+ export { SharedTracker } from './src/shared-tracker.ts';
14
+ /** Expose backend-neutral exclusive resource coordination and typed remedies. */
15
+ export { ResourceReservations, ResourceRefusal, RESOURCE_TAG } from './src/resources.ts';
16
+ /** Expose the adapter reusing the existing shared-tracker operation lease. */
17
+ export { trackerResourceBackend } from './src/resource-tracker.ts';
18
+ /** Expose portable backend and compact resource receipt contracts. */
19
+ export type { ResourceBackend, ResourceRecord, ResourceChange, ResourceReceipt, ResourceRefusalCode } from './src/resources.ts';
20
+ /** Expose typed stale-token refusals for embedded workers. */
21
+ export { StaleFenceError } from './src/lease.ts';
22
+ /** Expose conservative footprint and wave planning primitives. */
23
+ export { partition, separation, overlaps, footprintPath } from './src/planner.ts';
24
+ /** Expose the real Git merge predictor for embedded tools. */
25
+ export { predict } from './src/git.ts';
26
+ /** Expose exhaustive sequential merge ordering and minimal conflict analysis. */
27
+ export { cleanOrder, minimalConflict } from './src/order.ts';
28
+ /** Expose SDK-backed package settings resolution. */
29
+ export { settings } from './src/settings.ts';
30
+ /** Expose portable lane contracts. */
31
+ export type { Candidate, Lane, Prediction, Separation, SwarmSettings } from './src/types.ts';
32
+ /** Activate the swarm command family and its extension fields. */
33
+ declare const _default: {
34
+ name: string;
35
+ version: string;
36
+ description: string;
37
+ activate: typeof register;
38
+ };
39
+ export default _default;
40
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,2DAA2D;AAC3D,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAC5H,oFAAoF;AACpF,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACnF,2EAA2E;AAC3E,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE/J,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,kEAAkE;AAClE,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,yEAAyE;AACzE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,iFAAiF;AACjF,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACzF,8EAA8E;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACnE,sEAAsE;AACtE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,cAAc,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAChI,8DAA8D;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,kEAAkE;AAClE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAClF,8DAA8D;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,iFAAiF;AACjF,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC7D,qDAAqD;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,sCAAsC;AACtC,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC7F,kEAAkE"}
package/dist/index.js ADDED
@@ -0,0 +1,27 @@
1
+ /** Expose opt-in fair assignment options, compact decisions and actionable refusals. */
2
+ export { SchedulingRefusal } from './src/fair-scheduling.js';
3
+ /** Expose revision-bound parallel Plan progress and typed recovery instructions. */
4
+ export { PlanProgress, ProgressRefusal, PROGRESS_PREFIX } from './src/progress.js';
5
+ import { defineExtension } from '@unbrained/pm-cli/sdk/authoring';
6
+ import { register } from './src/commands.js';
7
+ /** Expose the same tracker-bound engine used by host commands. */
8
+ export { Swarm } from './src/swarm.js';
9
+ /** Expose claim coordination for trackers without Git worktree lanes. */
10
+ export { SharedTracker } from './src/shared-tracker.js';
11
+ /** Expose backend-neutral exclusive resource coordination and typed remedies. */
12
+ export { ResourceReservations, ResourceRefusal, RESOURCE_TAG } from './src/resources.js';
13
+ /** Expose the adapter reusing the existing shared-tracker operation lease. */
14
+ export { trackerResourceBackend } from './src/resource-tracker.js';
15
+ /** Expose typed stale-token refusals for embedded workers. */
16
+ export { StaleFenceError } from './src/lease.js';
17
+ /** Expose conservative footprint and wave planning primitives. */
18
+ export { partition, separation, overlaps, footprintPath } from './src/planner.js';
19
+ /** Expose the real Git merge predictor for embedded tools. */
20
+ export { predict } from './src/git.js';
21
+ /** Expose exhaustive sequential merge ordering and minimal conflict analysis. */
22
+ export { cleanOrder, minimalConflict } from './src/order.js';
23
+ /** Expose SDK-backed package settings resolution. */
24
+ export { settings } from './src/settings.js';
25
+ /** Activate the swarm command family and its extension fields. */
26
+ export default defineExtension({ name: 'pm-swarm', version: "2026.10.28", description: 'Many agents on one tracker with fenced claims and context handoff; Git lanes optional', activate: register });
27
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAG7D,oFAAoF;AACpF,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGnF,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,kEAAkE;AAClE,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,yEAAyE;AACzE,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,iFAAiF;AACjF,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACzF,8EAA8E;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAGnE,8DAA8D;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,kEAAkE;AAClE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAClF,8DAA8D;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,iFAAiF;AACjF,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC7D,qDAAqD;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAG7C,kEAAkE;AAClE,eAAe,eAAe,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,uFAAuF,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC"}
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Shared entry-point guard for this package's executable scripts.
3
+ *
4
+ * The coverage gate and the docstring gate must behave identically when their
5
+ * suites import them versus when a developer or CI executes them as `main`, so
6
+ * the comparison lives in exactly one measured module instead of drifting
7
+ * between per-script copies.
8
+ */
9
+ /**
10
+ * Decide whether the running process was started for this module rather than
11
+ * importing it for measurement.
12
+ *
13
+ * Both sides are canonicalised through `realpathSync` before comparison. A
14
+ * launcher reached through a symlink (an npm bin shim, a linked workspace)
15
+ * would otherwise compare unequal and skip its gate silently, and under
16
+ * `--preserve-symlinks-main` the entry path stays un-resolved while
17
+ * `import.meta.url` is already real, which would invert the answer on a direct
18
+ * invocation. Canonicalising both sides removes the dependence on how Node was
19
+ * started.
20
+ *
21
+ * An `argv[1]` that no longer resolves propagates the error instead of
22
+ * answering false: a false answer lets a release check exit 0 having scanned
23
+ * nothing, which is the silent skip this guard exists to prevent, while a
24
+ * thrown error turns the same situation into a loud non-zero exit. A genuinely
25
+ * different entry path still returns false, which is how a test import
26
+ * declines to run main wiring.
27
+ *
28
+ * @param argv - The process argv to inspect; `argv[1]` names the entry script.
29
+ * @param moduleUrl - The `import.meta.url` of the module that might be main.
30
+ * @returns True when the entry and this module canonicalise to one path.
31
+ */
32
+ export declare function isMainInvocation(argv: readonly string[], moduleUrl: string): boolean;
33
+ //# sourceMappingURL=main-invocation.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"main-invocation.d.ts","sourceRoot":"","sources":["../../scripts/main-invocation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAIpF"}
@@ -0,0 +1,40 @@
1
+ /**
2
+ * Shared entry-point guard for this package's executable scripts.
3
+ *
4
+ * The coverage gate and the docstring gate must behave identically when their
5
+ * suites import them versus when a developer or CI executes them as `main`, so
6
+ * the comparison lives in exactly one measured module instead of drifting
7
+ * between per-script copies.
8
+ */
9
+ import { realpathSync } from "node:fs";
10
+ import { fileURLToPath } from "node:url";
11
+ /**
12
+ * Decide whether the running process was started for this module rather than
13
+ * importing it for measurement.
14
+ *
15
+ * Both sides are canonicalised through `realpathSync` before comparison. A
16
+ * launcher reached through a symlink (an npm bin shim, a linked workspace)
17
+ * would otherwise compare unequal and skip its gate silently, and under
18
+ * `--preserve-symlinks-main` the entry path stays un-resolved while
19
+ * `import.meta.url` is already real, which would invert the answer on a direct
20
+ * invocation. Canonicalising both sides removes the dependence on how Node was
21
+ * started.
22
+ *
23
+ * An `argv[1]` that no longer resolves propagates the error instead of
24
+ * answering false: a false answer lets a release check exit 0 having scanned
25
+ * nothing, which is the silent skip this guard exists to prevent, while a
26
+ * thrown error turns the same situation into a loud non-zero exit. A genuinely
27
+ * different entry path still returns false, which is how a test import
28
+ * declines to run main wiring.
29
+ *
30
+ * @param argv - The process argv to inspect; `argv[1]` names the entry script.
31
+ * @param moduleUrl - The `import.meta.url` of the module that might be main.
32
+ * @returns True when the entry and this module canonicalise to one path.
33
+ */
34
+ export function isMainInvocation(argv, moduleUrl) {
35
+ const entry = argv[1];
36
+ if (entry === undefined)
37
+ return false;
38
+ return realpathSync(entry) === realpathSync(fileURLToPath(moduleUrl));
39
+ }
40
+ //# sourceMappingURL=main-invocation.js.map