@moxuli/moremote 0.1.0 → 0.1.2

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.
@@ -14,6 +14,6 @@ Reject alternatives: global npm self-update (permission/package-manager ownershi
14
14
 
15
15
  ## Consequences
16
16
 
17
- More disk is retained; the bootstrap's implementation remains fixed until explicit service maintenance. An update cannot force progress through a hung operation. This is preferable to corrupting authority or reporting false success. Package-manager installation, npm first publication/trusted-publisher setup, OS service acceptance and physical APNs delivery remain distinct gates.
17
+ More disk is retained; the bootstrap's implementation remains fixed until explicit service maintenance. An update cannot force progress through a hung operation. This is preferable to corrupting authority or reporting false success. Package publication, hosted release, OS service acceptance and physical APNs delivery remain distinct gates. Reuse the owner's existing selected-repository publishing secret; do not require new credentials or a web-only trust migration to release.
18
18
 
19
19
  Contracts: [managed updates](../specs/06-managed-updates.md), [release prerequisites](../releasing.md), [plan](../plans/2026-11-10-managed-updates.md).
@@ -19,7 +19,7 @@ Activation queues a verified candidate. The supervisor requests a drain, never f
19
19
  - `src/runtime.ts`: parent-only IPC drain at cycle boundary and readiness, preserve mutation/journal semantics.
20
20
  - `src/cli.ts`: managed run/service/update/status/opt-out integration and installed-version reporting.
21
21
  - `tests/updater.test.ts`: real state/install/handoff processes with synthetic packages, failure/concurrency/opt-out boundaries.
22
- - `.github/workflows/{ci,release}.yml`, `scripts/release.mjs`: frozen Node24.13.0, exact identity/tag validation, deterministic tarball, separate least-privilege release and OIDC publication.
22
+ - `.github/workflows/{ci,release}.yml`, `scripts/release.mjs`: frozen Node24.13.0, exact identity/tag validation, deterministic tarball and a least-privilege publishing step using the already-provisioned organization secret.
23
23
 
24
24
  ## Verification entrypoints (integration owner only)
25
25
 
@@ -0,0 +1,168 @@
1
+ # Native service acceptance — 2026-11-11
2
+
3
+ ## Status and boundary
4
+
5
+ The current compiled source controller has exercised real macOS launchd installation,
6
+ start, status, stop and uninstall against the published0.1.1 managed runtime.
7
+ This is not a new npm release, a published-version upgrade, or Linux/Windows native
8
+ service-manager acceptance. Existing released0.1.1 bytes remain unchanged.
9
+
10
+ The acceptance used an unused per-user service label, an isolated HOME and a short,
11
+ owned state directory. Cloud was disabled, pairings were empty and the official
12
+ endpoint was an unreachable loopback address. No official daemon, real-work session,
13
+ model, enrollment or APNs request was used. Installation was refused unless the
14
+ service label and real-home registration file were initially absent.
15
+
16
+ ## Discovered shutdown race
17
+
18
+ The real service initially installed and started successfully. Stopping it could
19
+ fail with `CONTROL_CONNECTION_CLOSED`: native bootout had already begun graceful
20
+ supervisor/runtime shutdown while the CLI independently requested control shutdown.
21
+ The socket could close before its ownership records had finished retiring.
22
+
23
+ The correction preserves strict generic control transport errors. Only a managed
24
+ shutdown can cross this specific closure window; it must still wait for supervisor
25
+ retirement and confirm that no runtime remains. An empty response alone is never
26
+ success, malformed responses still fail, and an uncertain stop is not replayed
27
+ against a replacement generation. The workflow now lives with supervisor lifecycle
28
+ ownership instead of being duplicated in CLI command wiring.
29
+
30
+ Independent review exposed a second boundary: a final status probe can return null
31
+ for a departed generation while a replacement owner remains alive. Its regression
32
+ also failed before correction. Shutdown now revalidates the current supervisor and
33
+ runtime lock/PID synchronously after the awaited probe, including lock-only startup.
34
+ The replacement must remain intact and shutdown must fail rather than authorizing
35
+ uninstall. The independent follow-up found no remaining blocker in this scope.
36
+ These checks are snapshots; they cannot prevent an independent start afterward.
37
+
38
+ ## Exercised proof
39
+
40
+ - The new owned-socket/supervisor-retirement regression failed before the behavior
41
+ correction. It checks that closure cannot complete shutdown before retirement.
42
+ - 22 focused behavioral checks passed across `managed-shutdown.test.ts`,
43
+ `frontend-lifecycle.test.ts`, `control-response.test.ts` and `cli.test.ts`.
44
+ - `npm run typecheck` and `npm run build` passed.
45
+ - The corrected compiled source controller installed the real launchd registration,
46
+ reached the published runtime's authenticated status endpoint, stopped it and
47
+ removed the registration, plist and isolated state. Final launchd lookup returned
48
+ the platform's explicit missing-service result; no test login service remained.
49
+ - Earlier fixture setup failures were not product acceptance: one used an invalid
50
+ synthetic client identity; another exceeded the Unix-domain socket path limit.
51
+ The final native run used valid configuration and a short isolated path.
52
+
53
+ ## Remaining gates at the preceding checkpoint
54
+
55
+ 1. A separately authorized, immutable next-version release including current source;
56
+ the published0.1.1 package must not be represented as containing this correction.
57
+ 2. Real published-version activation/rollback through an installed native service.
58
+ 3. Equivalent native service-manager acceptance on Linux and Windows.
59
+
60
+ Do not install a test registration over an everyday service. A fake HOME isolates
61
+ registration files, not launchd's per-user label namespace. When that label is in
62
+ use, use a separately owned OS environment rather than stopping another instance.
63
+
64
+ ## Installed upgrade and rollback continuation — 2026-11-12
65
+
66
+ - A fresh anonymous npm download of immutable0.1.1 matches registry SHA512 and
67
+ published SHA256`358574ca750d27c8a116743cd729d7ab830c41fc17045ddfa46ff808ff3bba3b`.
68
+ The retained native service starts those actual published bootstrap bytes.
69
+ - The actual launchd namespace and real-home registration file are required to
70
+ be absent before installation. The service uses an owned temporary HOME/state,
71
+ no pairs, cloud disabled and an unreachable loopback official endpoint.
72
+ - Initial startup did not reach readiness because the fixture omitted the required
73
+ client-identity prefix. A private direct bootstrap diagnostic reports
74
+ `INVALID_CONFIG`; this is not a product startup defect.
75
+ - Failed-run cleanup exposed a real ownership defect: launchd canonicalizes
76
+ `/tmp` to `/private/tmp`, while the controller compared raw strings and rejected
77
+ its own registration. The exact first service was safely removed through the
78
+ normal controller using its independently established canonical definition.
79
+ - The product correction accepts a parent-path alias only when both leaves are
80
+ ordinary non-symlink files, device/inode match and real paths match. Exact
81
+ unchanged paths retain their fast path. Leaf symlinks, different files and
82
+ foreign registration/marker protections remain rejected. The same rule applies
83
+ to systemd's file path; Windows task matching is unchanged.
84
+ - All10focused service-lifecycle consumers, typecheck and build pass. Independent
85
+ OpenCode review reports no blocker. Distinct hard links/bind mounts remain a
86
+ conservative refusal; no general authority over user-writable services is added.
87
+ - The corrected real launchd run passes in181.29seconds: published0.1.1 bootstrap
88
+ → current synthetic9000.0.2 candidate → failed compatible9000.0.3 startup →
89
+ recovered9000.0.2. Authenticated status and durable selection agree; bootstrap/
90
+ previous remain0.1.1. Normal stop/uninstall leaves no registration, plist or
91
+ owned successful-run files.
92
+
93
+ This accepts macOS native activation/rollback with real installed package bytes
94
+ and a deliberately failing unpublished fixture. It is not a new immutable public
95
+ release, public-to-public next-version delivery, Linux/Windows native acceptance,
96
+ cloud activation or any real-work-session operation.
97
+
98
+ ## Linux user-service and Windows encoding continuation — 2026-11-12
99
+
100
+ Actual Linux acceptance uses the existing Ubuntu26.04 user manager, systemd259
101
+ and pinned Node24.13.0. The real unit reaches active/running/enabled and the
102
+ authenticated control reports the installed version. QA0.1.1 activates synthetic
103
+ 9000.0.2, then rejects compatible9000.0.3 before readiness and recovers9000.0.2
104
+ with unchanged bootstrap/previous0.1.1. Normal stop/uninstall leaves
105
+ LoadState=not-found, an empty FragmentPath, absent definition/control and no live
106
+ supervisor/runtime. This is actual user-systemd, not every Linux distribution.
107
+
108
+ The preceding Windows QA implementation identified missing BOM in a UTF-16LE
109
+ task import file. Native COM syntax-only validation of a decoded string did not
110
+ test the file bytes consumed by schtasks. That QA writer emitted FF FE; its
111
+ current reader was corrected to consume one leading U+FEFF while retaining
112
+ ownership/XML checks. This was current/current QA evidence, not retained-version
113
+ compatibility; the later correction below supersedes the persistent-BOM design.
114
+
115
+ That18consumer run covered writer/current-reader consumption, legacy unmarked
116
+ UTF-16 ownership inspection, repeated-BOM, wrong-encoding and foreign-marker
117
+ rejection. Typecheck and build also passed.
118
+
119
+ The final unwrapped native Windows Task Scheduler run passes in168.23seconds.
120
+ It installs/starts QA0.1.1, authenticates status, activates synthetic9000.0.2,
121
+ rejects9000.0.3 before readiness and recovers9000.0.2, then normally stops and
122
+ uninstalls. Independent task/definition/control checks are absent and no live
123
+ supervisor/runtime remains. The exercised QA archive SHA256 is
124
+ `8b5c55ac04edfaf5c93eb7b1708ad07be9eec5b0d288b04ec0b5dbbd81b4df82`.
125
+
126
+ No console-token impersonation, account/policy change, real daemon/cloud
127
+ operation or public release is used. A private fixture's elevated-owner ACL
128
+ mismatch was recorded separately rather than misrepresented as a product login
129
+ requirement. Failed and diagnostic task registrations were normally removed.
130
+ An independent provider review could not run because its read tools were
131
+ refused; no review approval is claimed.
132
+
133
+
134
+ ## Retained public reader correction — 2026-11-12
135
+
136
+ Fresh-context specification review found that unchanged public0.1.1 starts its
137
+ resource reader before runtime readiness and cannot consume persistent BOM-prefixed
138
+ ownership XML. A matching compatibility tuple and synthetic current/current
139
+ native pass did not establish retained-reader compatibility.
140
+
141
+ Persistent `moremote-cli-task.xml` is now BOM-free UTF-16LE. Native `/Create`
142
+ receives a separate BOM-prefixed XML file in an owned private temporary directory
143
+ outside shared state. `finally` removes that copy before `/Run`; registration or
144
+ cleanup failure cannot start the runtime. No schema bump or migration is needed.
145
+
146
+ Two new deterministic regressions first fail, then the20focused lifecycle/resource
147
+ consumers, typecheck and build pass. The frozen public reader is unmodified,
148
+ SHA256`1ee80f6bdab819e15da817038cecf46133b07d1a157663893a64112a2fdca13b`;
149
+ an independent anonymous npm download confirms those module bytes. Fresh-context
150
+ Stage A and Stage B re-review close the blocker, explicitly using the weaker
151
+ same-provider fallback after the unavailable cross-provider attempt.
152
+
153
+ The actual Windows journey starts unchanged npm0.1.1 bootstrap bytes, activates
154
+ the current synthetic9000.0.2, fails9000.0.3 before readiness, recovers9000.0.2
155
+ and normally stops/uninstalls. The native interval is183.86seconds; the enclosing
156
+ fleet job takes202.70seconds. Independent final observations show no task,
157
+ definition, control endpoint or live supervisor/runtime; successful-run runtime
158
+ files are removed. The intentionally unused loopback official target yields
159
+ degraded connection status while authenticated runtime/version checks succeed.
160
+
161
+ Public0.1.1 archive SHA256 is
162
+ `358574ca750d27c8a116743cd729d7ab830c41fc17045ddfa46ff808ff3bba3b`;
163
+ unpublished exercised candidate SHA256 is
164
+ `6dca555348e87dd395aa0564d97aa1499581fbeadc98b78dbb1c9c3c179ff861`.
165
+ No real daemon/cloud/model operation, account/security-policy change, npm
166
+ publication or everyday installed service occurs. Synthetic candidates are
167
+ still not a new immutable public release or public-to-public delivery.
168
+
package/docs/releasing.md CHANGED
@@ -1,38 +1,34 @@
1
1
  # Releasing @moxuli/moremote
2
2
 
3
- Repository: public `moxuli/moremote-cli`; package: public `@moxuli/moremote`; executable: `moremote-cli`. No unscoped npm alias is published. This repository contains no publishing credential and workflows do not read NPM_TOKEN/NODE_AUTH_TOKEN secrets.
3
+ Repository: public `moxuli/moremote-cli`; package: public `@moxuli/moremote`; executable: `moremote-cli`. No unscoped alias is published. Credentials never belong in this repository, release assets or package contents.
4
4
 
5
- ## First publication and trust setup (human prerequisites)
5
+ ## Existing publishing authority
6
6
 
7
- The package must exist before its npm package settings can define a trusted publisher. An npm organization owner/package maintainer must establish an authenticated npm account, confirm the `@moxuli` scope/package authority and2FA policy, and explicitly authorize one **first public publication** of the validated0.1.0 tarball from a trusted workstation. This is an external release, not a CI dry run. Do not assume an org token exists, re-use a stale login, create a token automatically or publish merely to test authentication. If npm adds a pre-publication trusted-publisher reservation flow, use its current documented UI rather than guessing that the existing-package settings work for a404 package.
7
+ The owner already provisioned organization secret `NPM_TOKEN`, restricted to this selected public CLI repository. Reuse that configuration. Do not create another token, require a new login, or block release on a web-only trusted-publisher migration. The workstation's protected publishing credential is separately loaded at point of use; do not echo it or commit an authenticated npm configuration.
8
8
 
9
- After that first package exists, on npmjs.com package Settings → Trusted Publisher, configure:
9
+ The release job uses environment `npm-release`. Only its publish step receives the existing secret as `NODE_AUTH_TOKEN`; checks, dependency installation, builds and package scripts do not receive it. The temporary npm configuration contains the literal environment placeholder, pins both default and `@moxuli` registries to npmjs, has private permissions and is removed after publishing. No authentication file is packaged. Token authority/expiry and required interactive provider checks still apply; never bypass them or claim acceptance from a valid identity read alone.
10
10
 
11
- - provider GitHub Actions, organization `moxuli`, repository `moremote-cli`;
12
- - workflow filename **`release.yml`** (not its full path);
13
- - environment **`npm-release`**;
14
- - permit **direct `npm publish`** (current npm defaults may allow staged publish only).
15
-
16
- Create the matching GitHub environment, restrict it to protected release tags and add required reviewers if desired. Configure tag protection/Rulesets so only authorized maintainers can create release tags. A newly created npm trusted-publisher configuration must complete its first successful publish within the current documented two-day validation window; recreate an expired configuration rather than adding a long-lived secret fallback. For the first OIDC release, bump to a genuinely new version (for example0.1.1); npm versions cannot be overwritten. After successful OIDC publication, require2FA and disallow traditional tokens in npm publishing access, and separately revoke unused automation tokens under owner authorization. Existing organization secrets are not consumed by these workflows.
11
+ Configure the release environment to accept authorized `v*` tags. Branch/tag protection and required reviewers remain owner-governed settings. Token replacement/revocation is a separate account action. npm trusted publishing remains an optional future migration, not an additional prerequisite for the current owner's existing setup.
17
12
 
18
13
  ## Normal release
19
14
 
20
- 1. Keep dependencies pinned and the compatibility tuple unchanged only if storage/wire rollback is genuinely safe. Complete `npm ci --ignore-scripts`, `npm run check`, `npm run smoke:upgrade`, `node scripts/release.mjs validate vX.Y.Z` and `node scripts/release.mjs pack vX.Y.Z` using Node24.13.0. The pack command produces `moxuli-moremote-X.Y.Z.tgz` and `SHA256SUMS` from two byte-identical packs and validates archived identity/required entrypoints. These generated files are release outputs, not source files to commit.
21
- 2. Review public package contents, changelog and external acceptance separately. Update package.json and only the lockfile root versions; do not upgrade dependencies incidentally. Commit through normal review and push the exact stable `vX.Y.Z` tag only after owner release authorization. Prerelease/range/mismatched tags fail closed.
22
- 3. The release workflow revalidates repository/tag/package/lock identity, runs checks/build, packs deterministically, verifies the supported bundled npm version, and publishes that exact tarball with OIDC/public access/provenance. The `npm-release` environment gate applies. GitHub-hosted Ubuntu24.04 and pinned Node24.13.0 are used; no global npm upgrade occurs.
23
- 4. Only after npm publication succeeds does it create the GitHub Release containing the identical tarball and SHA256SUMS. Release concurrency is serialized and never cancels a publishing run. Only this job receives contents:write and id-token:write; ordinary CI has contents:read, checkout credentials are not persisted, and no cache is used in release builds.
24
- 5. If npm publish fails, no successful GitHub Release is created. If npm succeeded but GitHub creation failed, **do not republish/retag** or assume the workflow is transactional across registries. Recover the exact published npm tarball, validate its integrity and identity against the logged build artifact/checksum, and attach those bytes in a separately authorized GitHub Release operation. A rerun will honestly fail npm's immutable-version check; it never substitutes different bytes for the same version.
15
+ 1. Keep dependencies pinned. Preserve the compatibility tuple only when storage/wire rollback is genuinely safe. On Node24.13.0 run `npm ci --ignore-scripts`, `npm run check`, `npm run smoke:upgrade`, `node scripts/release.mjs validate vX.Y.Z` and `node scripts/release.mjs pack vX.Y.Z`.
16
+ 2. Review public contents and changelog. Update package.json and only lockfile root versions, commit through review, then push the exact owner-authorized stable `vX.Y.Z` tag. Prerelease/range/mismatched tags fail closed. Generated tarballs/SHA256SUMS are release outputs, not tracked source.
17
+ 3. The GitHub-hosted Ubuntu24.04 job validates repository/tag/package/lock identity, checks/builds and produces two byte-identical packs. It publishes the exact tested tarball with the existing scoped secret, public access and GitHub provenance. Node24.13.0 is pinned; no global toolchain upgrade occurs.
18
+ 4. Only after npm accepts publication does the job create a GitHub Release with the identical tarball and SHA256SUMS. Release concurrency is serialized and never cancels an in-flight publish. Only this job receives contents:write/id-token:write for release/provenance; ordinary CI is contents:read. Checkout credentials are not persisted and release builds use no cache.
19
+ 5. If npm fails, no successful GitHub Release is created. If npm accepted but GitHub creation failed, **do not republish or retag**: recover the exact published bytes, validate integrity against the accepted build artifact/checksum, and recover the GitHub Release under the owner's release authorization. npm versions are immutable.
20
+ 6. npm can acknowledge submission while processing a new package. Require an independent anonymous registry read and installation of the public exact version before claiming availability. Do not repeatedly republish while processing. Record the receiver result in STATE.
25
21
 
26
- CI also runs portable behavioral checks and an explicit isolated real packaged-upgrade smoke on macOS/Linux/Windows. Native service registration still requires authorized platform acceptance; no CI step installs a real login service. Physical APNs acceptance is independent of npm/release acceptance.
22
+ The first workstation bootstrap publication is0.1.0. Subsequent automated releases must use a genuinely new version; neither workflow reruns nor corrected documentation can replace published0.1.0 bytes.
27
23
 
28
- ## Verified action pins and primary sources
24
+ CI also runs portable behavior and isolated real packaged-upgrade smoke on macOS/Linux/Windows. It never installs a real login service. Native platform managers and physical APNs are separate acceptance gates.
29
25
 
30
- Official tag refs were resolved read-only from each official upstream with `git ls-remote`:
26
+ ## Verified action pins and primary sources
31
27
 
32
- - [`actions/checkout` v6.0.2](https://github.com/actions/checkout/tree/de0fac2e4500dabe0009e67214ff5f5447ce83dd): `de0fac2e4500dabe0009e67214ff5f5447ce83dd`.
33
- - [`actions/setup-node` v6.1.0](https://github.com/actions/setup-node/tree/395ad3262231945c25e8478fd5baf05154b1d79f): `395ad3262231945c25e8478fd5baf05154b1d79f`.
34
- - [npm trusted publishers](https://docs.npmjs.com/trusted-publishers/): npm11.5.1+, supported hosted runners, exact workflow/environment binding, initial configuration expiry, automatic public provenance and token restrictions.
35
- - [GitHub publishing Node packages](https://docs.github.com/en/actions/tutorials/publish-packages/publish-nodejs-packages): package/repository metadata, scoped public publication and provenance. OIDC follows npm's newer instructions, not GitHub's optional token example.
36
- - [GitHub OIDC hardening](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect).
28
+ - [`actions/checkout` v6.0.2](https://github.com/actions/checkout/tree/de0fac2e4500dabe0009e67214ff5f5447ce83dd): resolved official tag.
29
+ - [`actions/setup-node` v6.1.0](https://github.com/actions/setup-node/tree/395ad3262231945c25e8478fd5baf05154b1d79f): resolved official tag.
30
+ - [GitHub publishing Node packages](https://docs.github.com/en/actions/tutorials/publish-packages/publish-nodejs-packages): scoped public publishing, token use and provenance.
31
+ - [npm provenance](https://docs.npmjs.com/generating-provenance-statements): hosted build identity is separate from npm publishing authority.
32
+ - [npm trusted publishers](https://docs.npmjs.com/trusted-publishers/): optional future short-lived authentication migration.
37
33
 
38
- Do not claim a package/trusted publisher/release exists from checked-in workflow source alone. Current observed public availability/authentication and exercised checks belong in STATE.md, with no private account identifiers or credentials.
34
+ Never infer a registry package, hosted workflow result, release or protection setting from checked-in YAML alone. Record only exercised facts, without private accounts or credential values.
@@ -1,6 +1,6 @@
1
1
  # 03 — Relay HTTP API, version 1
2
2
 
3
- **Status:** implementation detail of the owner-approved first notification/scoped-delivery iteration; review against the accepted architecture before coding
3
+ **Status:** living relay-v1 contract. Activity/widget additions below describe unreleased local integration, not published CLI0.1.1 or native/live-cloud acceptance.
4
4
 
5
5
  ## Common rules
6
6
 
@@ -103,7 +103,9 @@ without contacting cloud.
103
103
 
104
104
  ### PUT /pairs/{pairId}/state; GET /pairs/{pairId}/state
105
105
 
106
- Host writes, phone reads. Body/response contains `{envelope}` with `state` channel.
106
+ Host writes, phone reads. PUT accepts strict `{envelope}` or additive
107
+ `{envelope,widgetFingerprint}`; GET returns the envelope only, as specified below.
108
+ Envelope channel is `state`.
107
109
  Only the latest nonexpired snapshot keeps ciphertext, monotonic by issuedAt then
108
110
  immutable ID. Each state ID/digest remains a conflict guard through its own
109
111
  original envelope expiry, including after supersession; no additional24hour
@@ -395,3 +397,121 @@ may contain both original128KiB-bounded payload and a separate8KiB receipt; a
395
397
  host pairing response may contain two bounded proofs. A128KiB response reader
396
398
  would permanently reject valid work and is nonconforming. This larger response
397
399
  budget never raises the128KiB request or64KiB decrypted command-content limits.
400
+
401
+ ## Opt-in task activities and widget reloads
402
+
403
+ These additive routes do not change command, receipt, alert, pairing, service,
404
+ or managed-update identities. Cloud remains disabled by default. Every route
405
+ uses the existing pair bearer; subscription IDs and registration IDs are
406
+ lowercase canonical UUIDs. No pair-level activity-device registration exists.
407
+
408
+ | Route (under `/v1/pairs/{pairId}`) | Role | Exact JSON body | Admission |
409
+ | --- | --- | --- | --- |
410
+ | `PUT /activities/{subscriptionId}` | phone | `{registrationId,token,environment,topic,interest}` | normal |
411
+ | `DELETE /activities/{subscriptionId}` | phone | none | recovery |
412
+ | `GET /activities` | host | none | normal |
413
+ | `PUT /activities/{subscriptionId}/state` | host | `{registrationId,topic,event:"update",envelope}` | normal |
414
+ | `PUT /activities/{subscriptionId}/end` | host | `{registrationId,topic,event:"end",envelope}` | recovery |
415
+ | `PUT /widget-device` | phone | `{registrationId,token,environment}` | normal |
416
+ | `DELETE /widget-device/{registrationId}` | phone | none | recovery |
417
+
418
+ Tokens are even-length hex,1–256 bytes, normalized lowercase. Environment is
419
+ `sandbox|production`; provider configuration must match. The activity `topic`
420
+ is the existing pair-key HMAC `presenceTopic(rootKey,pairId,agentId)` (32 bytes,
421
+ base64url), not an APNs topic or plaintext agent identity. At most8 live
422
+ subscriptions are admitted per pair. GET returns
423
+ `{ok:true,subscriptions:[{id,registrationId,topic,interest,expiresAt}]}`.
424
+ PUT registration returns the same single row as `{ok:true,subscription:...}`.
425
+ Registration replacement uses a fresh registrationId; different bytes under
426
+ the same registrationId conflict. Native renewal must preserve the ActivityKit
427
+ activity's original8-hour ceiling. DELETE removes queued state immediately.
428
+ Retired subscription/registration IDs share a bounded1000-entry token-free guard
429
+ pool with widget registrations. Delayed registration PUTs cannot resurrect or
430
+ roll back retired identities. Widget DELETE is registration-exact; activity DELETE targets the subscription.
431
+ Activity guards retain the original8h ceiling and widget guards the original24h
432
+ expiry, without retry extension. Unknown DELETEs also reserve bounded guards;
433
+ capacity exhaustion fails closed, never evicts live protection.
434
+
435
+ The encrypted `interest` uses additive channel `activityInterest`, envelope.id
436
+ equal to subscriptionId, lifetime at most8h. Exact plaintext:
437
+ `{version:1,subscriptionId,daemonServerId,agentId}`. The companion authenticates
438
+ the envelope, pinned daemon, exact subscription and derived topic before any
439
+ read-only task lookup. This plaintext cannot authorize commands. No timeline
440
+ or chat download is required. Existing snapshot cadence (at least30s) admits
441
+ one bounded interest pass, at most8 exact fallback reads outside the recent list.
442
+ The owned optional lane has a2s deadline,250ms SDK reads and request cancellation.
443
+ Commands/control never await it; drain aborts/joins before SDK/journal close. Missing tasks never imply finish.
444
+
445
+ Activity state uses additive channel `activityState`, fresh envelope UUID and
446
+ at most600s lifetime, capped by subscription expiry. Exact plaintext:
447
+ `{version:1,subscriptionId,daemonServerId,agentId,title,hostName,phase,startedAt,measuredAt,expiresAt,requiresAttention,isTerminal}`.
448
+ Title/hostName are limited to160/80 characters. Phase is
449
+ `running|waiting|finished|error|idle`; permission attention maps to waiting;
450
+ official closed/error or current terminal attention maps to end. A running
451
+ turn supersedes an old terminal attention flag. startedAt is nullable, from
452
+ official activeTurn.startedAt or lastUserMessageAt, never a measurement
453
+ substitute. measuredAt/expiresAt exactly match envelope headers in milliseconds.
454
+ Existing encrypted snapshots also include optional lastUserMessageAt,
455
+ activeTurnStartedAt and bounded cwd per task. Encrypted usage adds genuine
456
+ provider displayName and window/balance label (at most128 characters each),
457
+ preserving absent values as unavailable. No full chats, invented labels or
458
+ synthetic percentages are added.
459
+
460
+ HKDF salt, AES-GCM nonce/tag framing, metadata AAD and existing channels remain
461
+ byte-compatible. Only the new channel name changes HKDF info. Activity state
462
+ serialized envelope is at most3000 UTF-8 bytes. Native ContentState has default
463
+ Codable field `payload`, a canonical JSON string of that envelope (key order
464
+ version,pairId,id,channel,issuedAt,expiresAt,nonce,ciphertext).
465
+ Updates derive directly from real semantic task transitions, independently of
466
+ alert admission/presence suppression. Unchanged measurements normally do not push.
467
+ Acknowledged nonterminal state renews from fresh samples every8minutes (120s before600s expiry).
468
+ Unknown admissions retain identical ciphertext until expiry; semantic changes can supersede progress. Disconnected state expires.
469
+
470
+ Live authenticated interests are cached against the current pair key/daemon. Terminal work precedes optional normal discovery, once per fresh
471
+ snapshot, without GET/state admission; authenticated404/409 invalidates its cache.
472
+ Only exact429 `daily_work_limit`, `x-moremote-budget:normal` and consistent future
473
+ `x-moremote-reset`/Retry-After pauses normal work alone. Missing/malformed hints,
474
+ outages, disable or recovery exhaustion preserve origin-wide pause/cycle fences.
475
+ Recovery still requires server admission; hints never grant operation authority.
476
+
477
+ APNs uses `apns-push-type:liveactivity`, configured main topic plus
478
+ `.push-type.liveactivity`, priority5 update/10 end, collapse-id subscriptionId,
479
+ apns-id envelope.id, expiration floor(expiresAt/1000). Body is
480
+ `{aps:{timestamp,event,"content-state":{payload},"stale-date"}}`; all APNs dates
481
+ are epoch seconds. End additionally sets dismissal-date. There is no apns-event
482
+ header. A512-byte static-attributes reserve and the complete4096-byte provider
483
+ payload limit both apply. End and invalid-token retirement compare the exact
484
+ current registration identity; stale provider failures never remove replacement
485
+ tokens. Provider admission is not proof of rendering.
486
+
487
+ Existing `PUT /state` accepts strict legacy `{envelope}` or additive
488
+ `{envelope,widgetFingerprint}`. GET state remains unchanged. The new fingerprint
489
+ is a pair-keyed HMAC using the presence domain over JSON
490
+ `["widgetSnapshot",meaningfulProjection]`. Projection includes bounded sorted
491
+ task identity/title/status/attention/latest turn/project plus usage values;
492
+ measurement and usage fetchedAt clocks are excluded. Only a changed opaque
493
+ fingerprint for the current widget registration queues a coalesced push.
494
+ Legacy envelope-only publications do not cause widget pushes.
495
+
496
+ Widget registration expires after24h and requires foreground/token renewal
497
+ (native renewal around12h uses a fresh registration ID).
498
+ Native uses the WidgetKit token, not an alert or activity token. Explicit
499
+ `APNS_WIDGET_TOPIC` is the widget extension bundle ID plus `.push-type.widgets`;
500
+ it is never derived from the main app topic. APNs uses push-type widgets,
501
+ priority5 and `{aps:{"content-changed":true}}`, no private identifiers.
502
+ WidgetKit automatically reloads timelines opportunistically on receipt;
503
+ WidgetPushHandler observes token/configuration updates. Timeline providers use
504
+ the existing sealed snapshot and its expiry; reload is not realtime delivery.
505
+ See Apple's [WidgetKit push documentation](https://developer.apple.com/documentation/widgetkit/updating-widgets-with-widgetkit-push-notifications).
506
+
507
+ Activity/widget work shares bounded provider attempts and background batches
508
+ with alerts; no recursive requests, unbounded retries, recovery-budget borrowing
509
+ for progress or changes to endpoint retirement/receipt/updater lifecycle.
510
+
511
+ Every APNs sender requires a synchronous `BeforeSend = () => boolean` fence
512
+ after asynchronous JWT signing and immediately before transport. The durable
513
+ caller rechecks service enabled, active pair, exact current registration and
514
+ publication, and expiry. Signing shares the original10s attempt deadline;
515
+ late signing cannot start transport. Global budgets and kill deadline are unchanged.
516
+ Physical Live Activity/widget behavior and live APNs/cloud delivery for this
517
+ delta remain pending; provider200 never establishes device delivery.
@@ -16,6 +16,12 @@ Readiness observers use the runtime's positive parent IPC acknowledgement after
16
16
 
17
17
  An empty control EOF or reset is `CONTROL_CONNECTION_CLOSED` while the previously validated owner still exists, not a raw JSON parser exception or a successful stop. A malformed/nonobject reply is `CONTROL_INVALID_RESPONSE`. Only observed retirement/replacement of that exact validated record can classify an empty disconnect as not-running. No control or official mutation is retried because of a lost reply.
18
18
 
19
+ Ephemeral control transport compatibility: `managed/runtime-transport.json` is a marked version1, private/no-follow descriptor binding `json-lines-v1` to instanceId, pid, startedAt and SHA256(token). It is durably published before the runtime record. The original strict runtime.lock/runtime.json shapes remain unchanged, so retained0.1.0 readers and crash recovery can still read them; the existing marked managed directory contains the additional descriptor. Cleanup removes only the matching descriptor inode/generation.
20
+
21
+ The controller chooses one transport from that fact before sending: a matching descriptor means bounded4KiB newline frames and a duplex connection; no descriptor or a valid descriptor from another generation means the known0.1.0 EOF/unframed transport on POSIX. Invalid/linked/foreign descriptors are terminal, not an excuse to guess or probe. Ownership and selected framing are revalidated immediately before the single write. There is no timeout-based fallback, second connection or action replay.
22
+
23
+ Historical Windows boundary: unchanged published0.1.0 EOF-only control cannot provide a reliable duplex named-pipe reply. A live such generation reports `LEGACY_WINDOWS_CONTROL_UNAVAILABLE`, never fake status/stopped. It remains an explicit selectable candidate. The retained supervisor's separate child IPC can still drain, roll back or stop it. A managed stop waits for supervisor retirement and positive runtime retirement evidence before reporting success; an unsupervised live historical runtime remains unavailable/unknown. New framed runtimes retain full Windows support. An absent PID or retired record is evidence, not permission to signal an arbitrary PID.
24
+
19
25
  The first installed-package `run` or explicit service installation obtains its exact current version into `managed/versions/<version>/node_modules/@moxuli/moremote`. Lifecycle scripts are disabled. npm network retries are disabled, fetches have a60second limit and installation has a120second process limit. Package name/version, ordinary nonsymlinked build/entry files and directory ownership are verified before an atomic staging rename. Existing version directories are immutable and reverified. Failed installations never change selection. There is no global npm self-overwrite or sudo.
20
26
 
21
27
  ## Durable selection and bounded discovery
@@ -36,14 +42,22 @@ After old exit, candidate readiness requires journal creation and acquired runti
36
42
 
37
43
  Opt-out during drain allows the old cycle to settle, then resumes old active without starting candidate. Opt-out during candidate startup drains it before resuming old active. Explicit stop signals only the owned service/runtime, writes a separate supervisor stop request, and waits for supervisor exit before managed deletion. Stop does not cause an internal respawn. A hung in-flight operation cannot be safely force-killed by an update: activation waits, status retains activating, and explicit operator stop remains separate. A staged package alone is never reported as active.
38
44
 
45
+ On Windows, the persistent ownership XML remains BOM-free UTF-16LE so unchanged
46
+ retained0.1.1 readers can validate shared state during startup and rollback.
47
+ Task Scheduler's file import instead receives an owned private transient copy
48
+ with the required UTF-16LE BOM, outside shared state. Remove that copy on every
49
+ normal success/failure path and before `/Run`; failed cleanup must not start the
50
+ runtime. Native registration acceptance must include unchanged public bootstrap
51
+ bytes, not only current code relabeled as an older QA version.
52
+
39
53
  ## Evidence entrypoints
40
54
 
41
- `npm run check` exercises ordinary regression tests and compiles; `npm run smoke:upgrade` then packs two synthetic versions of the actual compiled package, installs both through real npm into isolated private prefixes, starts the production retained service entry (without registering any OS service), confirms runtime.version advances from9000.0.1 to9000.0.2, retains the old/bootstrap executable and performs a clean stop. It contacts only npm plus an intentionally unavailable localhost official endpoint, never everyday official data or cloud. It is explicit acceptance, not an install hook. CI includes the same smoke on macOS/Linux/Windows. Neither this specification nor test source claims those checks have been exercised.
55
+ `npm run check` exercises ordinary regression tests and compiles; `npm run smoke:upgrade` then packs three synthetic versions of the actual compiled package and installs them through real npm into isolated private prefixes. It starts the production retained service entry without registering an OS service, confirms9000.0.1→9000.0.2, exercises the retained frontend through a path alias, then queues compatible9000.0.3 whose disposable runtime exits before readiness. The supervisor must return to9000.0.2, retain bootstrap/previous, record the failed candidate and clear pending/activating before a clean stop. Only the disposable failed package bytes change. It contacts npm plus an intentionally unavailable localhost endpoint, never everyday official data or cloud. This is explicit acceptance, not an install hook. CI includes this smoke on macOS/Linux/Windows; observed results belong in STATE, not this specification.
42
56
 
43
57
  The packaged smoke explicitly invokes the old frontend through a parent-directory symlink/junction and requires one selected-version response. Every network/subprocess/control/wait stage has a bounded deadline and a named checkpoint. Teardown retains handles to its own spawned processes, signals only their dedicated POSIX process groups or Windows PID subtrees, and awaits exit. Failure keeps the temporary root plus the last stage/selection; it never deletes an unexplained failed fixture or signals a PID discovered from an arbitrary state record.
44
58
 
45
59
  ## Official design references
46
60
 
47
61
  - [Claude Code update behavior and package-manager boundaries](https://code.claude.com/docs/en/setup#update-claude-code): background checks, next-start activation, diagnostic visibility, opt-out; native versus Homebrew/WinGet/OS-package manager boundaries. This project borrows the owned-version/launcher boundary, not Claude's installer or global package-manager upgrade behavior. Our continuously running consumer needs an explicit cycle-safe handoff rather than a silent session restart.
48
- - [npm trusted publishers](https://docs.npmjs.com/trusted-publishers/): short-lived OIDC credentials, GitHub-hosted runner and npm11.5.1+ requirements, public provenance and exact workflow/environment binding.
49
- - [GitHub Node package publication](https://docs.github.com/en/actions/tutorials/publish-packages/publish-nodejs-packages): exact package identity, scoped public access, build-before-publish and provenance. Its token example is not used; npm's OIDC documentation governs authentication here.
62
+ - [npm trusted publishers](https://docs.npmjs.com/trusted-publishers/): an optional future authentication migration, not a prerequisite for the owner's existing organization publishing secret.
63
+ - [GitHub Node package publication](https://docs.github.com/en/actions/tutorials/publish-packages/publish-nodejs-packages): exact identity, scoped public access and build-before-publish/provenance. Existing `NPM_TOKEN` is available only to this selected public repository and exposed as `NODE_AUTH_TOKEN` only during its release publish step.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@moxuli/moremote",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Optional encrypted notification and scoped-action companion for Paseo",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",