@moxuli/moremote 0.1.0 → 0.1.1

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 CHANGED
@@ -70,5 +70,5 @@ Default CLI state uses `LOCALAPPDATA/MoRemoteCLI` on Windows, `~/Library/Applica
70
70
 
71
71
  [Docs](docs/README.md) · [Contributing](CONTRIBUTING.md) · [License](LICENSE) · [Notices](NOTICE)
72
72
 
73
- Public release prerequisites, OIDC trust setup and exact verification commands:
73
+ Public release prerequisites, existing-secret setup and exact verification commands:
74
74
  [releasing](docs/releasing.md). Checked-in workflows are not proof of a published package.
package/dist/cli.js CHANGED
@@ -54,13 +54,30 @@ async function stopRuntime(dir) { if (!await requestControl(dir, 'stop'))
54
54
  if (!await requestControl(dir, 'status'))
55
55
  return;
56
56
  } throw Error('STOP_TIMEOUT'); }
57
- async function stopManaged(dir) { requestSupervisorStop(dir); await stopRuntime(dir); if (readUpdateState(dir))
58
- for (let i = 0; i < 900; i++) {
59
- if (!supervisorRunning(dir))
60
- return;
61
- await sleep(200);
62
- } if (readUpdateState(dir) && supervisorRunning(dir))
63
- throw Error('SUPERVISOR_STOP_TIMEOUT'); }
57
+ async function stopManaged(dir) {
58
+ requestSupervisorStop(dir);
59
+ let legacyUnavailable = false;
60
+ try {
61
+ await stopRuntime(dir);
62
+ }
63
+ catch (error) {
64
+ if (error instanceof Error && error.message === 'LEGACY_WINDOWS_CONTROL_UNAVAILABLE' && readUpdateState(dir))
65
+ legacyUnavailable = true;
66
+ else
67
+ throw error;
68
+ }
69
+ if (readUpdateState(dir))
70
+ for (let i = 0; i < 900; i++) {
71
+ if (!supervisorRunning(dir)) {
72
+ if (legacyUnavailable && await requestControl(dir, 'status'))
73
+ throw Error('STOP_TIMEOUT');
74
+ return;
75
+ }
76
+ await sleep(200);
77
+ }
78
+ if (readUpdateState(dir) && supervisorRunning(dir))
79
+ throw Error('SUPERVISOR_STOP_TIMEOUT');
80
+ }
64
81
  async function stopOwned(dir, definition) { await stopService(definition); await stopManaged(dir); }
65
82
  async function main() {
66
83
  if (args.help || !action) {
@@ -0,0 +1,4 @@
1
+ import { type ResourceIdentity, type RuntimeOwner } from './resources.js';
2
+ export declare function controlFraming(dir: string, owner: RuntimeOwner): 'legacy-eof' | 'json-lines-v1';
3
+ export declare function publishControlTransport(dir: string, owner: RuntimeOwner): Promise<ResourceIdentity>;
4
+ export declare function removeControlTransport(dir: string, identity: ResourceIdentity, owner: RuntimeOwner): boolean;
@@ -0,0 +1,68 @@
1
+ import { join } from 'node:path';
2
+ import { openSync, closeSync, fsyncSync, renameSync } from 'node:fs';
3
+ import { createHash, randomUUID } from 'node:crypto';
4
+ import { privateManagedDirectory } from './config.js';
5
+ import { managedRoot } from './update-state.js';
6
+ import { inspectResource, readPrivateText, createPrivateFile, removeOwnedResource, sameResource } from './resources.js';
7
+ const OWNER = 'MoRemote CLI control transport';
8
+ function readDescriptor(dir) {
9
+ if (!inspectResource(join(dir, 'managed'), 'directory', true))
10
+ return null;
11
+ const root = managedRoot(dir), path = join(root, 'runtime-transport.json');
12
+ if (!inspectResource(path, 'file', true))
13
+ return null;
14
+ const file = readPrivateText(path, 2048);
15
+ let value;
16
+ try {
17
+ value = JSON.parse(file.text);
18
+ }
19
+ catch {
20
+ throw Error('INVALID_CONTROL_TRANSPORT');
21
+ }
22
+ if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length !== 7 || value.owner !== OWNER || value.version !== 1 || value.framing !== 'json-lines-v1' || typeof value.instanceId !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(value.instanceId) || !Number.isSafeInteger(value.pid) || value.pid < 1 || value.pid > 2147483647 || !Number.isSafeInteger(value.startedAt) || value.startedAt < 1 || typeof value.tokenHash !== 'string' || !/^[0-9a-f]{64}$/.test(value.tokenHash))
23
+ throw Error('INVALID_CONTROL_TRANSPORT');
24
+ return { ...file, value };
25
+ }
26
+ function matches(value, owner) { return value.instanceId === owner.instanceId && value.pid === owner.pid && value.startedAt === owner.startedAt && value.tokenHash === createHash('sha256').update(owner.token).digest('hex'); }
27
+ export function controlFraming(dir, owner) {
28
+ const descriptor = readDescriptor(dir);
29
+ return descriptor && matches(descriptor.value, owner) ? 'json-lines-v1' : 'legacy-eof';
30
+ }
31
+ export async function publishControlTransport(dir, owner) {
32
+ // Nested managed resources are understood/ignored by the published 0.1.0
33
+ // root reader; its exact six/seven-key runtime lock/record stays unchanged.
34
+ await privateManagedDirectory(join(dir, 'managed'));
35
+ const root = managedRoot(dir), path = join(root, 'runtime-transport.json'), before = readDescriptor(dir);
36
+ const value = { owner: OWNER, version: 1, framing: 'json-lines-v1', instanceId: owner.instanceId, pid: owner.pid, startedAt: owner.startedAt, tokenHash: createHash('sha256').update(owner.token).digest('hex') };
37
+ const temp = path + '.' + randomUUID() + '.tmp', identity = createPrivateFile(temp, JSON.stringify(value) + '\n');
38
+ try {
39
+ const current = readDescriptor(dir);
40
+ if (before ? (!current || !sameResource(before.identity, current.identity) || before.text !== current.text) : current !== null)
41
+ throw Error('CONTROL_TRANSPORT_CHANGED');
42
+ renameSync(temp, path);
43
+ if (process.platform !== 'win32') {
44
+ const fd = openSync(root, 'r');
45
+ try {
46
+ fsyncSync(fd);
47
+ }
48
+ finally {
49
+ closeSync(fd);
50
+ }
51
+ }
52
+ return identity;
53
+ }
54
+ finally {
55
+ removeOwnedResource(temp, identity);
56
+ }
57
+ }
58
+ export function removeControlTransport(dir, identity, owner) {
59
+ try {
60
+ const current = readDescriptor(dir);
61
+ if (!current || !sameResource(current.identity, identity) || !matches(current.value, owner))
62
+ return false;
63
+ return removeOwnedResource(join(managedRoot(dir), 'runtime-transport.json'), identity);
64
+ }
65
+ catch {
66
+ return false;
67
+ }
68
+ }
package/dist/control.js CHANGED
@@ -3,6 +3,7 @@ import { randomBytes, randomUUID, timingSafeEqual, createHash } from 'node:crypt
3
3
  import { join } from 'node:path';
4
4
  import { chmodSync, renameSync, readdirSync } from 'node:fs';
5
5
  import { assertStateRoot, createPrivateFile, hasCode, inspectResource, inspectRuntime, readRuntimeOwner, readRuntimeRecord, removeOwnedResource, runtimeMatches, RUNTIME_OWNER, sameResource, writePrivateAtomic } from './resources.js';
6
+ import { controlFraming, publishControlTransport, removeControlTransport } from './control-transport.js';
6
7
  export function controlEndpoint(dir) { return process.platform === 'win32' ? '\\\\.\\pipe\\moremote-cli-' + createHash('sha256').update(dir).digest('hex').slice(0, 24) : join(dir, 'runtime.sock'); }
7
8
  function object(value) { return typeof value === 'object' && value !== null && !Array.isArray(value); }
8
9
  function removeRuntimeFile(path, identity, owner, record = false) {
@@ -40,53 +41,95 @@ export async function requestControl(dir, action) {
40
41
  return null;
41
42
  const expectedRecord = resources.record.identity;
42
43
  const record = resources.record.value;
44
+ const framing = controlFraming(dir, record);
45
+ if (framing === 'legacy-eof' && process.platform === 'win32') {
46
+ if (!running(record.pid))
47
+ return null;
48
+ throw Error('LEGACY_WINDOWS_CONTROL_UNAVAILABLE');
49
+ }
43
50
  const ownerEnded = () => { const path = join(dir, 'runtime.json'); if (!inspectResource(path, 'file', true))
44
51
  return true; const current = readRuntimeRecord(path); return !sameResource(current.identity, expectedRecord) || !runtimeMatches(current.value, record); };
45
- const disconnected = () => { try {
52
+ const { promise, resolve, reject } = Promise.withResolvers();
53
+ const socket = createConnection(controlEndpoint(dir));
54
+ let raw = '', settled = false;
55
+ socket.setEncoding('utf8');
56
+ const succeed = (value) => { if (settled)
57
+ return; settled = true; clearTimeout(timer); socket.destroy(); resolve(value); };
58
+ const fail = (error) => { if (settled)
59
+ return; settled = true; clearTimeout(timer); socket.destroy(); reject(error); };
60
+ const disconnected = () => { if (settled)
61
+ return; if (raw) {
62
+ fail(Error('CONTROL_INVALID_RESPONSE'));
63
+ return;
64
+ } try {
46
65
  if (ownerEnded())
47
- resolve(null);
66
+ succeed(null);
48
67
  else
49
- reject(Error('CONTROL_CONNECTION_CLOSED'));
68
+ fail(Error('CONTROL_CONNECTION_CLOSED'));
50
69
  }
51
70
  catch (error) {
52
- reject(error);
71
+ fail(error);
53
72
  } };
54
- const { promise, resolve, reject } = Promise.withResolvers();
55
- const socket = createConnection(controlEndpoint(dir));
56
- let raw = '';
57
- socket.setTimeout(2000);
73
+ const parseResponse = (frame) => { try {
74
+ const value = JSON.parse(frame);
75
+ if (!object(value))
76
+ throw Error('CONTROL_INVALID_RESPONSE');
77
+ succeed(value);
78
+ }
79
+ catch {
80
+ fail(Error('CONTROL_INVALID_RESPONSE'));
81
+ } };
82
+ const timer = setTimeout(() => fail(Error('CONTROL_TIMEOUT')), 2000);
58
83
  socket.on('connect', () => {
59
84
  try {
60
85
  const current = inspectRuntime(dir);
61
86
  if (!current.record || !sameResource(current.record.identity, expectedRecord) || !runtimeMatches(current.record.value, record))
62
87
  throw Error('RUNTIME_RESOURCE_COLLISION');
63
- socket.end(JSON.stringify({ token: record.token, action }) + '\n');
88
+ if (controlFraming(dir, current.record.value) !== framing)
89
+ throw Error('CONTROL_TRANSPORT_CHANGED');
90
+ const payload = JSON.stringify({ token: record.token, action }) + '\n';
91
+ // The owned generation fact selects exactly one exchange, never a timeout
92
+ // probe/replay. Published 0.1.0 uses EOF; new named pipes remain duplex.
93
+ if (framing === 'legacy-eof')
94
+ socket.end(payload);
95
+ else
96
+ socket.write(payload);
64
97
  }
65
98
  catch (error) {
66
- socket.destroy(error instanceof Error ? error : Error('CONTROL_INVALID'));
99
+ fail(error);
67
100
  }
68
101
  });
69
- socket.on('data', chunk => { raw += chunk; if (Buffer.byteLength(raw) > 4096)
70
- socket.destroy(Error('CONTROL_LIMIT')); });
71
- socket.on('end', () => { if (!raw) {
72
- disconnected();
73
- return;
74
- } try {
75
- const value = JSON.parse(raw);
76
- if (!object(value))
77
- throw Error('CONTROL_INVALID_RESPONSE');
78
- resolve(value);
79
- }
80
- catch {
81
- reject(Error('CONTROL_INVALID_RESPONSE'));
82
- } });
83
- socket.on('timeout', () => socket.destroy(Error('CONTROL_TIMEOUT')));
84
- socket.on('error', error => { if (hasCode(error, 'ECONNREFUSED') || hasCode(error, 'ENOENT'))
85
- resolve(null);
102
+ socket.on('data', chunk => {
103
+ if (settled)
104
+ return;
105
+ raw += chunk;
106
+ if (Buffer.byteLength(raw) > 4096) {
107
+ fail(Error('CONTROL_LIMIT'));
108
+ return;
109
+ }
110
+ if (framing === 'legacy-eof')
111
+ return;
112
+ const end = raw.indexOf('\n');
113
+ if (end < 0)
114
+ return;
115
+ if (end !== raw.length - 1) {
116
+ fail(Error('CONTROL_INVALID_RESPONSE'));
117
+ return;
118
+ }
119
+ parseResponse(raw.slice(0, end));
120
+ });
121
+ socket.on('end', () => { if (framing === 'legacy-eof' && raw)
122
+ parseResponse(raw);
123
+ else
124
+ disconnected(); });
125
+ socket.on('close', disconnected);
126
+ socket.on('error', error => { if (settled)
127
+ return; if (hasCode(error, 'ECONNREFUSED') || hasCode(error, 'ENOENT'))
128
+ succeed(null);
86
129
  else if (hasCode(error, 'ECONNRESET') || hasCode(error, 'EPIPE'))
87
130
  disconnected();
88
131
  else
89
- reject(error); });
132
+ fail(error); });
90
133
  return promise;
91
134
  }
92
135
  function closeServer(server) {
@@ -138,36 +181,57 @@ export async function ownRuntime(dir, status, stop) {
138
181
  const lockPath = join(dir, 'runtime.lock'), recordPath = join(dir, 'runtime.json');
139
182
  let lock = createPrivateFile(lockPath, JSON.stringify(owner) + '\n');
140
183
  const staging = process.platform === 'win32' ? endpoint : join(dir, 's.' + owner.instanceId.slice(0, 8));
141
- let socketIdentity = null, recordIdentity = null;
184
+ let socketIdentity = null, recordIdentity = null, transportIdentity;
142
185
  const server = createServer({ allowHalfOpen: true }, socket => {
143
- let raw = '';
144
- socket.setTimeout(2000, () => socket.destroy());
186
+ let raw = '', handled = false;
187
+ socket.setEncoding('utf8');
188
+ const timer = setTimeout(() => socket.destroy(), 2000);
189
+ socket.once('close', () => clearTimeout(timer));
145
190
  socket.on('error', () => { });
146
- socket.on('data', chunk => { raw += chunk; if (Buffer.byteLength(raw) > 4096)
147
- socket.destroy(); });
148
- socket.on('end', () => {
191
+ socket.on('end', () => socket.destroy());
192
+ const reply = (value) => { const frame = JSON.stringify(value) + '\n'; if (Buffer.byteLength(frame) > 4096)
193
+ socket.destroy();
194
+ else
195
+ socket.write(frame); };
196
+ socket.on('data', chunk => {
197
+ if (handled) {
198
+ socket.destroy();
199
+ return;
200
+ }
201
+ raw += chunk;
202
+ if (Buffer.byteLength(raw) > 4096) {
203
+ handled = true;
204
+ socket.destroy();
205
+ return;
206
+ }
207
+ const end = raw.indexOf('\n');
208
+ if (end < 0)
209
+ return;
210
+ handled = true;
149
211
  try {
150
- const request = JSON.parse(raw);
212
+ if (end !== raw.length - 1)
213
+ throw Error('CONTROL_FRAME');
214
+ const request = JSON.parse(raw.slice(0, end));
151
215
  if (!object(request) || typeof request.token !== 'string' || request.token.length !== 43)
152
216
  throw Error('CONTROL_AUTH');
153
217
  const left = Buffer.from(request.token), right = Buffer.from(owner.token);
154
218
  if (left.length !== right.length || !timingSafeEqual(left, right))
155
219
  throw Error('CONTROL_AUTH');
156
220
  if (request.action === 'stop') {
157
- socket.end(JSON.stringify({ ok: true, stopping: true }));
158
221
  stop();
222
+ reply({ ok: true, stopping: true });
159
223
  }
160
224
  else if (request.action === 'status') {
161
225
  const value = status();
162
226
  if (!object(value))
163
227
  throw Error('CONTROL_STATUS');
164
- socket.end(JSON.stringify({ ok: true, ...value }));
228
+ reply({ ok: true, ...value });
165
229
  }
166
230
  else
167
231
  throw Error('CONTROL_ACTION');
168
232
  }
169
233
  catch {
170
- socket.end(JSON.stringify({ ok: false }));
234
+ reply({ ok: false });
171
235
  }
172
236
  });
173
237
  });
@@ -196,6 +260,9 @@ export async function ownRuntime(dir, status, stop) {
196
260
  renameSync(staging, endpoint);
197
261
  socketIdentity = { dev: secured.dev, ino: secured.ino };
198
262
  }
263
+ // Publish the generation fact durably before making its unchanged legacy-
264
+ // compatible record visible; readers can never select EOF for this record.
265
+ transportIdentity = await publishControlTransport(dir, owner);
199
266
  recordIdentity = writePrivateAtomic(recordPath, { ...owner, socket: socketIdentity });
200
267
  }
201
268
  catch (error) {
@@ -204,6 +271,8 @@ export async function ownRuntime(dir, status, stop) {
204
271
  removeOwnedResource(endpoint, socketIdentity, 'socket');
205
272
  if (recordIdentity)
206
273
  removeRuntimeFile(recordPath, recordIdentity, owner, true);
274
+ if (transportIdentity)
275
+ removeControlTransport(dir, transportIdentity, owner);
207
276
  removeRuntimeFile(lockPath, lock, owner);
208
277
  throw error;
209
278
  }
@@ -220,6 +289,8 @@ export async function ownRuntime(dir, status, stop) {
220
289
  if (recordIdentity)
221
290
  removeRuntimeFile(recordPath, recordIdentity, owner, true);
222
291
  removeRuntimeFile(lockPath, lock, owner);
292
+ if (transportIdentity)
293
+ removeControlTransport(dir, transportIdentity, owner);
223
294
  })();
224
295
  return closing;
225
296
  };
package/docs/README.md CHANGED
@@ -12,7 +12,7 @@ separately gated cloud/Apple activation.
12
12
  - [Endpoint controls, occurrences and receipt lifecycle](specs/04-control-and-receipt-lifecycle.md)
13
13
  - [Endpoint and lifecycle behavior](specs/05-endpoint-and-lifecycle.md)
14
14
  - [Managed updates and compatibility](specs/06-managed-updates.md)
15
- - [Public release and trusted-publisher prerequisites](releasing.md)
15
+ - [Public release and existing publishing-secret prerequisites](releasing.md)
16
16
  - [Managed-update decision](decisions/0001-managed-updates.md)
17
17
  - [Managed-update implementation plan](plans/2026-11-10-managed-updates.md)
18
18
  - [Configuration registry](configuration.md)
package/docs/STATE.md CHANGED
@@ -31,8 +31,8 @@ remain separate gates.
31
31
  ## Managed updates and release — local acceptance complete
32
32
 
33
33
  The owner authorized public scoped npm identity `@moxuli/moremote`, retained
34
- private bootstrap/supervisor, cycle-safe automatic runtime activation and OIDC
35
- release workflows. Native service/state/executable identities remain unchanged.
34
+ private bootstrap/supervisor and cycle-safe automatic runtime activation.
35
+ Native service/state/executable identities remain unchanged.
36
36
  See [decision](decisions/0001-managed-updates.md), [specification](specs/06-managed-updates.md),
37
37
  [plan](plans/2026-11-10-managed-updates.md) and [publication prerequisites](releasing.md).
38
38
 
@@ -52,8 +52,31 @@ completed independent-context review is not represented as cross-vendor approval
52
52
  Public GitHub repository `moxuli/moremote-cli` exists. The owner authorized the
53
53
  first public0.1.0 release and reuse of an existing locally protected publishing
54
54
  token; its npm identity is verified without disclosing the credential. No new
55
- token or npm login is required. Hosted workflow execution, registry publication
56
- and trusted-publisher configuration require their actual receiver receipts.
55
+ token or npm login is required. Existing organization secret `NPM_TOKEN` is
56
+ restricted to this selected CLI repository; the release publish step reuses it.
57
+ Workstation0.1.0 publication is independently visible through the anonymous npm
58
+ registry. Published tarball SHA256 is
59
+ `6bf3cab16245745f5f9d43026687cff880ca081f106f195d6abe40a169c5efd6`;
60
+ registry SHA1 matches and a fresh exact public install runs version/help/
61
+ configure/status with cloud off, no runtime/pairs and no installed service.
62
+ Initial asynchronous404 processing was observed; publication was not repeated.
63
+
64
+ Hosted CI42821005843 accepts Ubuntu24.04 and macOS15 check/build/package-upgrade;
65
+ Windows2025 reports8control-transport failures (112pass/10explicit POSIX skips).
66
+ The correction is patch0.1.1: generation-bound transport selection preserves the
67
+ published strict runtime shape; framed peers avoid Windows half-close, while
68
+ known legacy POSIX transport is selected before exactly one write, never replayed.
69
+ Historical0.1.0 Windows EOF control remains explicitly unavailable/unknown;
70
+ managed stop requires real supervisor/runtime retirement evidence.
71
+
72
+ Final types,35focused control/lifecycle/CLI consumers, build and actual published
73
+ 0.1.0 retained-bootstrap→0.1.1 archive upgrade pass. The latter verifies active/
74
+ previous selection, both transport generations, selected frontend and clean
75
+ shutdown without a service/cloud/official-data mutation. Independent review
76
+ closes the mixed-transport finding with no remaining actionable P1/P2 issue.
77
+ Hosted final Windows acceptance and tag publishing still need receiver results.
78
+ Environment `npm-release` has a `v*` tag-only deployment policy; no new secret
79
+ was created.
57
80
 
58
81
  ## Locally accepted implementation
59
82
 
@@ -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
 
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.
@@ -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
@@ -45,5 +51,5 @@ The packaged smoke explicitly invokes the old frontend through a parent-director
45
51
  ## Official design references
46
52
 
47
53
  - [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.
54
+ - [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.
55
+ - [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.1",
4
4
  "description": "Optional encrypted notification and scoped-action companion for Paseo",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",