@abelxiaoxing/cadence 2.0.24 → 2.0.26
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.
- package/README.md +4 -1
- package/docs/conversation-mode.md +1 -1
- package/docs/remote-access.md +1 -1
- package/docs/service-management.md +62 -128
- package/package.json +3 -2
- package/src/agent-panel-model.ts +362 -122
- package/src/agent-panel.ts +142 -49
- package/src/cadence-mode.ts +18 -7
- package/src/native-build.ts +1 -1
- package/src/native-client.ts +1 -1
- package/src/operator-cli.mjs +80 -8
- package/src/service/checkout-lock.ts +7 -0
- package/src/service/coordination.ts +56 -364
- package/src/service/liveness.ts +238 -0
- package/src/service-cli.mjs +1582 -2828
- package/src/service-host.mjs +16984 -15885
- package/web/dist/assets/cadence.css +1 -1
- package/web/dist/assets/cadence.js +16 -16
- package/web/dist/manifest.json +7 -7
package/README.md
CHANGED
|
@@ -89,12 +89,15 @@ cadence server status
|
|
|
89
89
|
cadence server restart # after an upgrade or a .env / models.json change
|
|
90
90
|
cadence server stop # stays registered and starts again at the next boot or login
|
|
91
91
|
cadence server uninstall # run before npm uninstall -g
|
|
92
|
+
cadence doctor # what is left over or recently recovered; --fix for the rest
|
|
92
93
|
```
|
|
93
94
|
|
|
95
|
+
A power loss, shutdown or crash needs no cleanup: the next start recovers automatically, marks interrupted work as interrupted and says what it did.
|
|
96
|
+
|
|
94
97
|
Upgrade with `npm install -g @abelxiaoxing/cadence@latest`, then `cadence server restart`.
|
|
95
98
|
Restart, stop and uninstall stop running work in order rather than leaving it detached.
|
|
96
99
|
Uninstall removes only the service definition; projects, history and Pi settings stay.
|
|
97
|
-
Linux root and named services, remote HTTPS access and recovery are covered in [service management](docs/service-management.md) and [remote access](docs/remote-access.md).
|
|
100
|
+
Linux root and named services, remote HTTPS access and automatic recovery are covered in [service management](docs/service-management.md) and [remote access](docs/remote-access.md).
|
|
98
101
|
|
|
99
102
|
## Development
|
|
100
103
|
|
|
@@ -90,7 +90,7 @@ Automatic review is never recorded as human review.
|
|
|
90
90
|
|
|
91
91
|
To request orderly closure, ask Cadence to cancel in Pi, or use **Cancel workflow — request stop** in the browser (the browser coordinator cannot cancel).
|
|
92
92
|
A pending or unknown cancellation is not reported as stopped.
|
|
93
|
-
Failures, timeouts and unknown process/auth/storage outcomes remain distinct; unknown
|
|
93
|
+
Failures, timeouts and unknown process/auth/storage outcomes remain distinct; an owner that cannot settle unknown work restarts itself and recovers automatically.
|
|
94
94
|
|
|
95
95
|
## Service and compatibility
|
|
96
96
|
|
package/docs/remote-access.md
CHANGED
|
@@ -57,7 +57,7 @@ Never put provider credentials in a browser or URL.
|
|
|
57
57
|
`token-rotate` invalidates old links/cookies, pending grants, authenticated sockets and incomplete downloads without canceling admitted tasks.
|
|
58
58
|
Environment-backed tokens require explicit Stop/restart with changed environment instead; an `.env` token's rotation rewrites only its `CADENCE_TOKEN` line.
|
|
59
59
|
Links may already exist in clipboard/history or external logs; redirecting cannot retract disclosure.
|
|
60
|
-
Use [management and recovery](service-management.md) for Stop,
|
|
60
|
+
Use [management and automatic recovery](service-management.md) for Stop, recovery and `cadence doctor`.
|
|
61
61
|
Loopback HTTPS/viewport tests are not physical-device or second-machine deployment qualification.
|
|
62
62
|
|
|
63
63
|
## Unified workbench entry
|
|
@@ -23,8 +23,7 @@ Defaults are loopback `127.0.0.1:17423`, normal Pi agent configuration, and deta
|
|
|
23
23
|
An explicit port0 selects and persists a positive port once; restart uses the selected configuration, not a fallback endpoint.
|
|
24
24
|
Missing/corrupt existing setup is preserved, not filled in or reset.
|
|
25
25
|
Commands without `--workspace` address the unified workbench, which has no execution cwd and never creates `~/cadence`.
|
|
26
|
-
Use `cadence workbench start|status|diagnose|stop|token-link|token-rotate
|
|
27
|
-
`recover` without `--workspace` also addresses account/workbench state, never the current directory; project-owner recovery requires an explicit `--workspace`.
|
|
26
|
+
Use `cadence workbench start|status|diagnose|stop|token-link|token-rotate` to name that target explicitly; `cadence doctor` covers the account, the workbench and every registered project (see [Automatic recovery](#automatic-recovery)).
|
|
28
27
|
Its start accepts `--foreground`, `--state-home`, `--agent-dir`, `--server-config` and a private `--config` containing an `HttpPolicy` object (the schema used below for project HTTP policy).
|
|
29
28
|
The configuration's port/token come from the `.env`; a selected HTTP policy is retained across orderly restarts.
|
|
30
29
|
A project root containing the private state home is refused, with no alternate directory creation; native `/cadence` also requires a real project selection.
|
|
@@ -60,7 +59,7 @@ The private account state stores bounded project references and opening receipts
|
|
|
60
59
|
Private coordination/Pi credential directories and foreign-owned project selections are refused.
|
|
61
60
|
Direct project entry links remain available as a compatibility route; that route alone still uses separate loopback project entries.
|
|
62
61
|
Git subdirectories and aliases resolve to the same checkout, while overlapping parent/child owners still refuse.
|
|
63
|
-
An unknown
|
|
62
|
+
An unknown or inaccessible selection is never treated as a new project or recovered by choosing another state home.
|
|
64
63
|
|
|
65
64
|
When run as root, Git observation requires a repository Git recognizes as root-owned: Cadence clears `safe.directory` exceptions per command, removes inherited `SUDO_UID` and disables fsmonitor.
|
|
66
65
|
A foreign-owned repository refuses even if a global `safe.directory=*` would allow it; selecting a path is not consent to execute its configured clean/process filters.
|
|
@@ -94,11 +93,12 @@ A reinstall without `--workspace` explicitly selects the unified entry after ord
|
|
|
94
93
|
A plain `restart` retains the definition's existing target, including an older explicit project service, rather than silently migrating it.
|
|
95
94
|
The `.env` [port and token](#port-and-token) select the endpoint (17423 by default) and the token; an occupied endpoint fails instead of falling back.
|
|
96
95
|
Install and restart print the private entry link once the owner answers; the JSON result on stdout never carries the token.
|
|
97
|
-
A successful manager start request is not owner readiness: an unready owner reports `quarantined` or `unconfirmed`, retains the separate `managerStatus`, exits nonzero and names
|
|
98
|
-
Status also retains the manager's `active`/`activating`/`failed` observation separately
|
|
96
|
+
A successful manager start request is not owner readiness: an unready owner reports `quarantined` or `unconfirmed`, retains the separate `managerStatus`, exits nonzero and names `cadence doctor`.
|
|
97
|
+
Status also retains the manager's `active`/`activating`/`failed` observation separately.
|
|
98
|
+
A definition whose project directory was removed gets a readable refusal (exit78, so the unit does not restart in a loop); `cadence server install` switches it to the workbench.
|
|
99
99
|
`restart` rewrites an existing definition with the current Node and package paths, keeping its workspace and the user's disable choices, and starts it; run it after an npm upgrade, a Node change or a `models.json` edit.
|
|
100
100
|
`stop` joins the workbench's accepted openings and associated exact-epoch project owners, then closes the entry; unrelated project owners stay independent.
|
|
101
|
-
|
|
101
|
+
An associated owner that is not running (or whose directory is gone) has nothing to stop; one whose Stop is unconfirmed keeps its own state, and the workbench still stops.
|
|
102
102
|
Project-specific `stop --workspace <path>` remains scoped to that owner.
|
|
103
103
|
The generated registration stays for the next boot or login.
|
|
104
104
|
`uninstall` stops it orderly and deletes only what Cadence generated; workspace, state home, history, linger and Pi sources stay.
|
|
@@ -107,7 +107,7 @@ A definition Cadence did not generate is left unchanged (`foreign`), and `status
|
|
|
107
107
|
|
|
108
108
|
Pi's installer omits peers, so the standalone owner and workers load the Pi SDK (`pi-coding-agent`, `pi-ai`) from exact 0.84.3 optional dependencies.
|
|
109
109
|
Package files may be hard links into the package manager's store (Bun's default install); Cadence binds their exact content, not their link count.
|
|
110
|
-
Missing or unusable Pi sources refuse before an owner registers;
|
|
110
|
+
Missing or unusable Pi sources refuse before an owner registers; an owner that cannot load the SDK refuses at stage `pi-runtime` and exits.
|
|
111
111
|
The no-project workbench starts without either an SDK runtime or Pi authentication; missing sources are reported only when a project is explicitly opened.
|
|
112
112
|
For an explicit single-project definition, the older guards remain: no SDK means no definition, and missing `auth.json` means registered but waiting for Pi login.
|
|
113
113
|
|
|
@@ -152,7 +152,7 @@ It refuses without any effect when that token was edited since the start, so a p
|
|
|
152
152
|
A stopped workspace selected earlier with a generated, environment or file token, or another port, is reselected to the file at its next `start --server-config`.
|
|
153
153
|
Under the new owner reservation Cadence retires the previous token with a new access generation and replaces the selected port and token source; the history and every other selected setting stay.
|
|
154
154
|
A different agent directory, host or proxy still conflicts, and a running owner refuses until it has stopped.
|
|
155
|
-
An interrupted replacement
|
|
155
|
+
An interrupted replacement is recovered by the next start like any interrupted start.
|
|
156
156
|
|
|
157
157
|
### Linux systemd system/root unit (no linger)
|
|
158
158
|
|
|
@@ -180,7 +180,7 @@ An old but inactive unit does not own a subsequently detached owner: install, re
|
|
|
180
180
|
An unconfirmed or quarantined Stop, changed generated file, changed HOME/XDG state selection, a mask or a foreign unit prevents replacement/adoption.
|
|
181
181
|
`restart`, `stop` and `uninstall` await the authenticated original owner Stop before invoking systemctl, so manager timeouts are never used as proof of settlement.
|
|
182
182
|
Restart keeps disablement and does not unmask anything; uninstall removes only the generated definition, never data or linger.
|
|
183
|
-
Direct systemctl shutdown still has the unit's ExecStop and timeout behavior described below
|
|
183
|
+
Direct systemctl shutdown still has the unit's ExecStop and timeout behavior described below.
|
|
184
184
|
|
|
185
185
|
### Independent named Linux services
|
|
186
186
|
|
|
@@ -196,7 +196,7 @@ A named service uses `~/.pi/agent/cadence/servers/<name>.env` under its effectiv
|
|
|
196
196
|
A new named configuration requires `--port`; existing port/token lines are preserved, and a conflicting `--port` refuses instead of rewriting them.
|
|
197
197
|
Edit the selected named file explicitly and restart that same `--name` to change its port.
|
|
198
198
|
An occupied port still refuses rather than silently falling back; use `project open` when an automatically selected detached port is preferable.
|
|
199
|
-
All projects still share one coordination state home for their account, retaining canonical overlap checks
|
|
199
|
+
All projects still share one coordination state home for their account, retaining canonical overlap checks.
|
|
200
200
|
|
|
201
201
|
### Linux systemd user unit
|
|
202
202
|
|
|
@@ -212,10 +212,11 @@ It carries `ConditionPathExists=` for the CLI; explicit single-project definitio
|
|
|
212
212
|
`restart` stops an active unit with its loaded definition, rewrites the file and starts it, without enabling a disabled unit; a masked unit is never enabled or started.
|
|
213
213
|
`ExecStop` is the authenticated orderly Stop, so admitted work is stopped, not detached; `stop` and `uninstall` (`disable --now`) use it too.
|
|
214
214
|
`KillMode=mixed` sends systemd's SIGTERM only to the management client.
|
|
215
|
-
An owner still settling after `TimeoutStopSec=90`
|
|
215
|
+
An owner still settling after `TimeoutStopSec=90` is SIGKILLed, which is not orderly Stop; the next start recovers what it leaves.
|
|
216
216
|
`Restart=on-failure` is bounded to three starts in five minutes.
|
|
217
217
|
Deterministic foreground startup refusals exit78 (`EX_CONFIG`), and newly generated units use `RestartPreventExitStatus=78` so these refusals do not loop.
|
|
218
|
-
Ordinary unexpected process failures retain the bounded restart policy
|
|
218
|
+
Ordinary unexpected process failures retain the bounded restart policy, and every restart first recovers what the failed owner left.
|
|
219
|
+
An owner that hits a runtime fault stops its own workers and exits 75; its unit restarts it after `RestartSec=10`.
|
|
219
220
|
Existing generated units get this setting on the next successful explicit install/restart, not by package installation or recovery.
|
|
220
221
|
Without linger, user units start at login and stop at logout through the same Stop.
|
|
221
222
|
Linger starts the user manager, with every enabled user unit, at boot and keeps it running after logout.
|
|
@@ -229,9 +230,9 @@ It bakes the same PATH, LANG/LC_ALL, XDG_STATE_HOME and PI_CODING_AGENT_DIR as t
|
|
|
229
230
|
For an explicit single-project service, missing `auth.json` leaves the agent written but not loaded; the project-less workbench can start without Pi login.
|
|
230
231
|
Because launchd stops a job only by signaling it, `restart`, `stop`, `uninstall` and a reinstall first stop the owner through the authenticated orderly Stop, and change nothing when that Stop is `unconfirmed`, `quarantined` or `unavailable`.
|
|
231
232
|
Only then does Cadence unload (`bootout`) or replace the agent; `stop` leaves it loaded, and the finished job starts again at the next login.
|
|
232
|
-
There is no `KeepAlive`:
|
|
233
|
+
There is no `KeepAlive`: a failed owner stays down until the next login or `cadence server restart`, which recovers it; an owner that faults at runtime starts its own replacement.
|
|
233
234
|
`restart` keeps a `launchctl disable` and reports `disabled` without loading.
|
|
234
|
-
At logout or shutdown launchd signals the job, which is not orderly Stop
|
|
235
|
+
At logout or shutdown launchd signals the job, which is not orderly Stop: running work is interrupted, and the next start recovers the owner automatically.
|
|
235
236
|
|
|
236
237
|
### Windows login Run entry
|
|
237
238
|
|
|
@@ -242,7 +243,7 @@ It bakes only a custom PI_CODING_AGENT_DIR, because the login environment alread
|
|
|
242
243
|
For an explicit single-project service, missing `auth.json` leaves the entry registered but starts nothing; the project-less workbench can start without Pi login.
|
|
243
244
|
Nothing supervises the detached owner, so a failed owner is not restarted, and every `restart`, `stop`, `uninstall` and reinstall first runs the authenticated orderly Stop and changes nothing unless it is confirmed; Cadence never kills a process.
|
|
244
245
|
A `Cadence` Run value without Cadence's launcher is `foreign` and left unchanged; registry values are only tested for presence, because `reg.exe` prints them in the console code page.
|
|
245
|
-
At sign-out or shutdown Windows ends the owner without orderly Stop
|
|
246
|
+
At sign-out or shutdown Windows ends the owner without orderly Stop: running work is interrupted, and the next start recovers the owner automatically.
|
|
246
247
|
|
|
247
248
|
## Status, departure and Stop
|
|
248
249
|
|
|
@@ -255,10 +256,10 @@ At sign-out or shutdown Windows ends the owner without orderly Stop, which can l
|
|
|
255
256
|
Checks, native process outcomes and human review remain separate facts.
|
|
256
257
|
- `unconfirmed` means startup/Stop acknowledgment or settlement was not established within its reporting bound.
|
|
257
258
|
It is not permission to restart, kill a guessed PID or remove a lock.
|
|
258
|
-
`quarantined`
|
|
259
|
+
`quarantined` means the owner could not settle some process/auth/storage work: it refuses new work, lets the original work settle, stops its own workers and restarts itself (recovered automatically).
|
|
259
260
|
- A host that refuses during `start` reports `{"status":"refused","error":<code>,"stage":<stage>}` and exits without registering an owner.
|
|
260
261
|
Stages are `package` (installed web assets or Agent profiles), `pi-agent-directory`, `pi-auth`, `pi-models` and `service`; stderr names the selected Pi source to fix.
|
|
261
|
-
`quarantined` with stage `pi-runtime` or `service` means the owner registered first; it
|
|
262
|
+
`quarantined` with stage `pi-runtime` or `service` means the owner registered first; it exits, and the next start recovers its registration.
|
|
262
263
|
Reports carry fixed codes and stages only, never paths, configuration bytes or OS error text.
|
|
263
264
|
- The selected Pi agent directory must be a real directory (not a symlink) owned by you; `auth.json` and `models.json` must be your own single-link regular files.
|
|
264
265
|
Their mode bits are not checked: Pi creates its agent directory with your umask (0755, or 0775 under umask 002), and Cadence's own state stays 0700 regardless.
|
|
@@ -271,17 +272,17 @@ At sign-out or shutdown Windows ends the owner without orderly Stop, which can l
|
|
|
271
272
|
The owner loads `models.json` once at start: after it changes, the model catalog, the chosen model and the workspace view refuse as `stale` (credential changes in `auth.json` are read fresh).
|
|
272
273
|
Restart the service to reload it (`cadence server restart`, or `stop` then `start`), then choose the owner model again.
|
|
273
274
|
- A foreground owner can be managed from another terminal.
|
|
274
|
-
Ctrl-C, SIGTERM, machine crash or terminal destruction is **not** the authenticated orderly Stop route and
|
|
275
|
-
A recovered `stopped` registration
|
|
275
|
+
Ctrl-C, SIGTERM, machine crash or terminal destruction is **not** the authenticated orderly Stop route: running work is interrupted, and the next start recovers the owner automatically.
|
|
276
|
+
A recovered `stopped` registration records that the old owner was proven gone, not that its interrupted work completed.
|
|
276
277
|
|
|
277
|
-
`diagnose` reports fixed pending/recording facts and `proxyAuth: direct|validated-proxy` when the owner is reachable; a
|
|
278
|
+
`diagnose` reports fixed pending/recording facts and `proxyAuth: direct|validated-proxy` when the owner is reachable; a busy global registry instead reports its fixed lock reason and names `cadence doctor`.
|
|
278
279
|
No normal status/diagnosis prints access secrets, provider credentials or outbound proxy URLs.
|
|
279
280
|
Keep the explicitly revealed token link private.
|
|
280
281
|
Browser entry redirects to a token-free URL and uses an HttpOnly cookie; that does not retract a link already copied into history, a clipboard or external logs.
|
|
281
282
|
File/generated token rotation invalidates old access and pending confirmations, not admitted work.
|
|
282
283
|
Environment-token replacement requires explicit Stop/restart with changed environment.
|
|
283
284
|
Inbound remote access still requires the selected same-host HTTPS reverse-proxy policy; outbound proxy routing below is independent.
|
|
284
|
-
Browser access, even with a valid token, cannot perform local management
|
|
285
|
+
Browser access, even with a valid token, cannot perform local management, `cadence doctor --fix` or arbitrary manual shell checks.
|
|
285
286
|
The native client's local capability uses an owned direct loopback dispatcher, never the Pi process's provider proxy.
|
|
286
287
|
Detach joins that client's original dispatcher closure without changing the parent's global dispatcher or canceling service work.
|
|
287
288
|
|
|
@@ -309,121 +310,54 @@ Checks inherit the owner's frozen ordinary launch environment (including the can
|
|
|
309
310
|
Resolved model auth is never merged into checks.
|
|
310
311
|
Local fabricated-provider plain/gzip routing tests are not paid-provider, all-adapter, Node22 or other-platform qualification.
|
|
311
312
|
|
|
312
|
-
##
|
|
313
|
+
## Automatic recovery
|
|
313
314
|
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
cadence recover inspect --workspace /absolute/project
|
|
320
|
-
cadence recover resolve --workspace /absolute/project
|
|
315
|
+
Cadence is built for unclean endings: power loss, shutdown or logout while it runs, a crash, `kill -9`, or a supervisor's forced stop.
|
|
316
|
+
The next start (`cadence start`, `cadence project open`, the workbench, the background service, or native `/cadence`) recovers by itself and prints one line, for example:
|
|
317
|
+
|
|
318
|
+
```text
|
|
319
|
+
Cadence recovered project /home/me/app automatically: the machine restarted while Cadence was running; released its locks, continued its history after the last complete entry.
|
|
321
320
|
```
|
|
322
321
|
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
A recovery refusal reports a fixed code/stage or `blocked-preserve-state`, never raw state/configuration bytes.
|
|
326
|
-
Do not delete state files or move to a different state home to bypass a refusal.
|
|
322
|
+
The WebUI shows the same recovery once at the top of the page.
|
|
323
|
+
Nothing is asked of you unless Cadence cannot prove the old process is gone.
|
|
327
324
|
|
|
328
|
-
|
|
325
|
+
What a start does, in order:
|
|
329
326
|
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
327
|
+
- It proves the previous owner gone: new locks record the machine's boot identity and the process's start identity, so a restart of the machine, an absent process or a reused process ID is certain.
|
|
328
|
+
- It stops worker processes the dead owner left running on the same boot, by their exact recorded identity; after a machine restart none can remain.
|
|
329
|
+
- It releases the dead owner's registration and locks, and every other dead reservation in the account (including one whose project directory was removed).
|
|
330
|
+
- It continues the history after the last complete entry (a batch cut short by the crash stays where it is, untouched).
|
|
331
|
+
- Private files that a crash left half-written are moved to `<state-home>/cadence-assistant-v1/recovery-archive-v1/` and the affected part starts afresh; archived files are deleted after 30 days (or sooner beyond 2 GiB).
|
|
334
332
|
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
cadence recover resolve --workspace /absolute/project --state-home /absolute/state-home
|
|
338
|
-
```
|
|
333
|
+
Work that was running is marked interrupted (its outcome stays unknown and is never guessed); nothing is replayed, and worktrees and partial edits are kept.
|
|
334
|
+
Start an interrupted run or message again when you want it.
|
|
339
335
|
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
The holder must be on this host and its PID probe must specifically report absence; age, a remote host, permission denial or a reused live PID never authorizes release.
|
|
345
|
-
|
|
346
|
-
Recovery validates the registry and checks that unreserved project selections have no remaining owner/checkout fences.
|
|
347
|
-
A normally stopped project whose working directory was later removed is checked through its retained private metadata; recovery neither requires nor reconstructs that directory.
|
|
348
|
-
A still-reserved project whose working directory was removed also remains a valid retained reservation: canonical existing ancestors and overlap/endpoint constraints are checked without requiring the missing tail.
|
|
349
|
-
Its reservation, owner/checkout locks and history remain fenced and unchanged; releasing the global lock only restores access to independent projects.
|
|
350
|
-
Dangling/rebound aliases, permission errors and corrupt entries are not treated as absent directories.
|
|
351
|
-
An interrupted reservation remains reserved even when its project initialization is incomplete: unrelated projects can reopen, but that project's uncertain resources are not repaired.
|
|
352
|
-
An older release interrupted after removing a reservation but before releasing its project locks is unsafe and remains blocked, as do corrupt/partial registry bytes, linked files and changed resources.
|
|
353
|
-
Inspection reports `blocked-preserve-state` when it cannot establish those conditions; preserve that state for manual diagnosis rather than deleting locks.
|
|
354
|
-
|
|
355
|
-
Before releasing only `registry.lock`, the resolver exclusively creates, flushes and closes a private receipt under `service-registry-v1/recovery-v1/<lock-incarnation>/<attempt>.json`, retaining the original lock bytes and acknowledged digest.
|
|
356
|
-
It then rechecks the lock incarnation, registry, unreserved project selections, receipt and terminal authority.
|
|
357
|
-
Concurrent resolvers cannot release a successor lock.
|
|
358
|
-
If a resolver dies after the receipt but before release, a new inspection and fresh terminal confirmation may append the next attempt after that resolver's same-host PID is absent; neither receipt nor lock is silently reclaimed.
|
|
359
|
-
Torn or unsafe receipts remain preserved and refused.
|
|
360
|
-
Inspection is bounded to 1024 namespace entries and 128 attempts for one lock incarnation; it never evicts evidence to make space.
|
|
361
|
-
|
|
362
|
-
All project reservations, owner locks, checkout locks, capabilities, history and unknown outcomes remain unchanged.
|
|
363
|
-
No Open/Start is replayed, no process is signaled, and no service is installed or started by recovery.
|
|
364
|
-
After success, explicitly open the desired project again.
|
|
365
|
-
If its own owner is still fenced, run `recover inspect` again and follow project-owner recovery separately; restoring global registry access does not certify or release that owner's work.
|
|
366
|
-
|
|
367
|
-
### Workbench recovery
|
|
368
|
-
|
|
369
|
-
After a crash or failed Stop, an `alive`, `stopping` or `quarantined` registration may outlive its gateway process.
|
|
370
|
-
Do not keep restarting it or delete `workbenches-v1`; inspect the exact selection instead:
|
|
336
|
+
An owner that hits a fault while running (for example a worker that will not exit, or a history write that failed) stops accepting work, lets its work settle, stops its own workers and restarts itself; the restart recovers as above.
|
|
337
|
+
It restarts itself at most three times in a row.
|
|
338
|
+
|
|
339
|
+
### cadence doctor
|
|
371
340
|
|
|
372
341
|
```sh
|
|
373
|
-
cadence
|
|
374
|
-
cadence
|
|
342
|
+
cadence doctor # readonly: what is left over and what recovered recently
|
|
343
|
+
cadence doctor --fix # also handle the cases below, after one confirmation
|
|
344
|
+
cadence doctor --fix --yes # the same without the prompt, for scripts
|
|
345
|
+
cadence doctor --workspace /absolute/project --state-home /absolute/state-home
|
|
375
346
|
```
|
|
376
347
|
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
Partial/corrupt receipts remain preserved; there are at most128attempts per lock incarnation, with no evidence eviction.
|
|
394
|
-
|
|
395
|
-
Recovery also acknowledges and retires the gateway's **exact old project associations**, recorded by their reference-file incarnations in that receipt.
|
|
396
|
-
It does not delete those recent-project references or settle/stop their owners: all project registrations, reservations, locks, opening receipts and history remain unchanged, including unknown outcomes and unfinished Open operations.
|
|
397
|
-
This prevents a deleted old project from immediately quarantining the recovered workbench again on its next Stop.
|
|
398
|
-
Old references require a new explicit **Open** before proxy access or whole-workbench Stop associates them again; merely restarting, viewing the recent list or recovering never replays an Open.
|
|
399
|
-
After recovery, explicitly start/restart the workbench.
|
|
400
|
-
Separately inspect/recover any still-fenced project owner before opening it.
|
|
401
|
-
The receipt is operator acknowledgment, not proof of native process closure or credential/storage correctness.
|
|
402
|
-
|
|
403
|
-
### Project-owner recovery
|
|
404
|
-
|
|
405
|
-
With no registry lock present, inspection displays the epoch, exact coordination/history digests, owner PID/host observation and independent process/credential/storage uncertainty.
|
|
406
|
-
Those digests identify preserved resources, not successful work or credential validity.
|
|
407
|
-
A journal with no unmatched intent does not prove every escaped descendant or external credential writer stopped.
|
|
408
|
-
|
|
409
|
-
Before resolve, independently inspect and stop old processes externally, inspect the selected Pi credential file and SDK locks, and inspect retained storage/history.
|
|
410
|
-
Cadence does not signal arbitrary processes, reclaim SDK locks, repair credentials, truncate damaged history, migrate old formats or delete old resources.
|
|
411
|
-
Resolve requires a native local TTY, four fresh typed responses within120seconds and the same unchanged resources: separate process/escaped-descendant, credential/writeback and storage acknowledgments, then the exact displayed epoch.
|
|
412
|
-
There is no `--yes`, piped-input confirmation, browser body boolean, HTTP recovery endpoint or pasted multiline authorization.
|
|
413
|
-
An SSH terminal executes locally on the owner host; this is an operator interaction boundary, not proof of a physical human's identity.
|
|
414
|
-
|
|
415
|
-
Only a same-host owner whose PID probe specifically reports absence is eligible; live, remote, ambiguous, refreshed or partial resources refuse.
|
|
416
|
-
Absence alone never clears anything.
|
|
417
|
-
The original durable append/flush/close of a new fenced recovery fact completes first.
|
|
418
|
-
Then exact registration and registry state are updated, and the exact capability, owner lock and associated v1 lock are released in order, rechecking remaining resources, history and local authority before every effect.
|
|
419
|
-
Other workspace reservations remain untouched.
|
|
420
|
-
The v1 lock is last.
|
|
421
|
-
An unrelated legacy lock is never eligible.
|
|
422
|
-
|
|
423
|
-
Recovery preserves old unknown outcomes and damaged bytes.
|
|
424
|
-
Its result is **operator acknowledgment, not certification**; restart chooses a new epoch and never replays queues/auth work.
|
|
425
|
-
New work requires fresh plan/action consent.
|
|
426
|
-
Failure/crash between append and release can leave a durable bridge and partial fences.
|
|
427
|
-
A refused command is not proof of no effects.
|
|
428
|
-
Reinspect and preserve that state; reading/restart does not repair it, and automatic retry/reset is not a safe resolution.
|
|
429
|
-
Recognized old history formats stay readonly and are not migrated to enable recovery.
|
|
348
|
+
`cadence recover inspect|resolve` remain as aliases of `doctor` and `doctor --fix`.
|
|
349
|
+
Use the same account and state home as the service.
|
|
350
|
+
|
|
351
|
+
Only these cases wait for you, each named with one sentence and the next step:
|
|
352
|
+
|
|
353
|
+
- **Running but not responding**: the owner process exists and is Cadence's own (its start identity matches) but does not answer.
|
|
354
|
+
`--fix` stops it (TERM, then KILL) and recovers.
|
|
355
|
+
An interactive `cadence start` asks the same question.
|
|
356
|
+
- **Another machine**: the state names a different host (a shared or copied state home).
|
|
357
|
+
Cadence cannot observe that process; `--fix` takes the state over without touching any process.
|
|
358
|
+
Confirm only if that machine no longer runs Cadence with this state.
|
|
359
|
+
- **Unidentifiable process**: a process with the recorded ID exists and Cadence cannot tell whether it is the old owner (older locks on some platforms).
|
|
360
|
+
If no Cadence is running, `--fix` takes the state over.
|
|
361
|
+
- **Workers that did not stop**: leftover workers ignored TERM and KILL; stop them yourself (or restart the machine) and start again.
|
|
362
|
+
|
|
363
|
+
Doctor never deletes a project, its history or anything outside Cadence's private state; damaged private files go to the archive, and the doctor report names it.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@abelxiaoxing/cadence",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.26",
|
|
4
4
|
"description": "Conversation-driven Pi workspace: persistent native and WebUI workflows, explicit plan approval, checks and local delivery.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -78,7 +78,8 @@
|
|
|
78
78
|
"src/coordinator-tools.mjs",
|
|
79
79
|
"src/workspace.ts",
|
|
80
80
|
"src/data-shapes.ts",
|
|
81
|
-
"src/service/checkout-lock.ts"
|
|
81
|
+
"src/service/checkout-lock.ts",
|
|
82
|
+
"src/service/liveness.ts"
|
|
82
83
|
],
|
|
83
84
|
"pi": {
|
|
84
85
|
"extensions": [
|