@runeditrun/rer 0.2.121 → 0.2.122

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (146) hide show
  1. package/cli/README.md +124 -5
  2. package/cli/archive.mjs +1 -1
  3. package/cli/authoring.mjs +1 -1
  4. package/cli/browser-runtime.mjs +2 -2
  5. package/cli/business/agent-help.mjs +11 -11
  6. package/cli/business/agent-verbs.mjs +9 -8
  7. package/cli/business/api.mjs +11 -7
  8. package/cli/business/carry.mjs +4 -3
  9. package/cli/business/choices.mjs +1 -1
  10. package/cli/business/command.mjs +33 -11
  11. package/cli/business/connect.mjs +4 -4
  12. package/cli/business/credential-file.mjs +102 -0
  13. package/cli/business/errors.mjs +5 -2
  14. package/cli/business/invocation.mjs +7 -4
  15. package/cli/business/keychain.mjs +6 -2
  16. package/cli/business/local-commands.mjs +9 -3
  17. package/cli/business/mcp-bridge.mjs +2 -1
  18. package/cli/business/questions.mjs +1 -1
  19. package/cli/business/run-child.mjs +5 -5
  20. package/cli/business/run-grant.mjs +27 -8
  21. package/cli/business/run-mask.mjs +8 -1
  22. package/cli/business/scan-command.mjs +1 -1
  23. package/cli/business/service.mjs +4 -2
  24. package/cli/business/state.mjs +2 -2
  25. package/cli/checkout-folders.mjs +1 -1
  26. package/cli/checkout-preparation.mjs +4 -4
  27. package/cli/command-guidance.mjs +9 -0
  28. package/cli/companion/command.mjs +4 -3
  29. package/cli/companion/providers/sandbox.mjs +1 -1
  30. package/cli/companion/setup.mjs +4 -4
  31. package/cli/contract.mjs +8 -8
  32. package/cli/demo.mjs +1 -1
  33. package/cli/deploy-command.mjs +10 -5
  34. package/cli/deploy-hook.mjs +3 -2
  35. package/cli/deploy-inputs.mjs +7 -3
  36. package/cli/deploy-owner-input.mjs +2 -2
  37. package/cli/deploy-source.mjs +1 -1
  38. package/cli/deploy.mjs +4 -2
  39. package/cli/deployment-record.mjs +1 -1
  40. package/cli/dev-identity.mjs +4 -4
  41. package/cli/door-clauses.mjs +2 -2
  42. package/cli/door-mode.mjs +7 -7
  43. package/cli/door.mjs +7 -7
  44. package/cli/errors.mjs +15 -1
  45. package/cli/export-summary.mjs +1 -1
  46. package/cli/export.mjs +1 -1
  47. package/cli/hosted-export.mjs +1 -1
  48. package/cli/hosted-output.mjs +2 -2
  49. package/cli/human-error.mjs +8 -2
  50. package/cli/hydration/browser.mjs +1 -1
  51. package/cli/hydration/check.mjs +1 -1
  52. package/cli/import-summary.mjs +2 -2
  53. package/cli/inspect.mjs +3 -3
  54. package/cli/lifecycle.mjs +9 -9
  55. package/cli/listen.mjs +1 -1
  56. package/cli/listing.mjs +1 -1
  57. package/cli/local-env.mjs +1 -1
  58. package/cli/local.mjs +4 -4
  59. package/cli/managed-server.mjs +36 -13
  60. package/cli/output.mjs +2 -1
  61. package/cli/owner-entry-ready.mjs +92 -0
  62. package/cli/parse.mjs +8 -8
  63. package/cli/port.mjs +3 -3
  64. package/cli/portability-runtime.mjs +16 -0
  65. package/cli/portability.mjs +4 -4
  66. package/cli/production-auth.mjs +4 -2
  67. package/cli/production-mail.mjs +1 -1
  68. package/cli/project.mjs +2 -0
  69. package/cli/rehearse/options.mjs +3 -3
  70. package/cli/release-candidate.mjs +2 -2
  71. package/cli/release.mjs +5 -5
  72. package/cli/server-registry.mjs +3 -3
  73. package/cli/server-resources.mjs +1 -1
  74. package/cli/setup-input.mjs +6 -6
  75. package/cli/signin.mjs +11 -10
  76. package/cli/site-render.mjs +1 -1
  77. package/cli/size/schema.mjs +1 -1
  78. package/cli/size/verify-step.mjs +1 -1
  79. package/cli/transfers.mjs +4 -4
  80. package/edition-authoring/api-source.mjs +121 -0
  81. package/edition-authoring/archive-source.mjs +1 -86
  82. package/edition-authoring/base-copies.mjs +5 -3
  83. package/global/CHANGELOG.md +31 -0
  84. package/global/cli/command.mjs +6 -5
  85. package/global/cli/install.mjs +6 -3
  86. package/global/cli/path-link.mjs +11 -22
  87. package/global/cli/repo-command.mjs +4 -3
  88. package/global/cli/repository-contract.mjs +3 -3
  89. package/global/door/command.mjs +39 -38
  90. package/global/door/control.mjs +3 -3
  91. package/global/door/pages.mjs +6 -5
  92. package/global/door/server.mjs +8 -5
  93. package/global/door/sites.mjs +14 -13
  94. package/global/launch/capacity.mjs +2 -2
  95. package/global/launch/dev.mjs +6 -6
  96. package/global/launch/door.mjs +1 -1
  97. package/global/launch/facts.mjs +2 -2
  98. package/global/launch/failure.mjs +1 -1
  99. package/global/launch/prepare.mjs +3 -3
  100. package/global/launch/render.mjs +3 -2
  101. package/global/launch/worker.mjs +1 -1
  102. package/global/list.mjs +4 -4
  103. package/global/main.mjs +32 -31
  104. package/global/registry.mjs +1 -1
  105. package/global/run.mjs +4 -4
  106. package/global/update/command.mjs +5 -5
  107. package/global/update/notice.mjs +1 -1
  108. package/global/version.mjs +1 -1
  109. package/install.sh +17 -4
  110. package/modules/deploy-kit/README.md +10 -3
  111. package/modules/deploy-kit/asset-health.mjs +6 -4
  112. package/modules/deploy-kit/cancellation.mjs +26 -0
  113. package/modules/deploy-kit/d1-import-diagnostics.mjs +3 -2
  114. package/modules/deploy-kit/deploy.mjs +8 -3
  115. package/modules/deploy-kit/diagnostics.mjs +11 -4
  116. package/modules/deploy-kit/health-request.mjs +16 -9
  117. package/modules/deploy-kit/health.mjs +14 -11
  118. package/modules/deploy-kit/owner-cli.mjs +49 -21
  119. package/modules/deploy-kit/owner-remove.mjs +7 -6
  120. package/modules/deploy-kit/owner-secret.mjs +7 -4
  121. package/modules/deploy-kit/owner.mjs +46 -28
  122. package/modules/deploy-kit/provider-transport.mjs +2 -0
  123. package/modules/deploy-kit/provider.mjs +10 -9
  124. package/modules/deploy-kit/readiness-window.mjs +5 -3
  125. package/modules/deploy-kit/site.mjs +1 -1
  126. package/modules/deploy-kit/teardown.mjs +5 -4
  127. package/modules/operator-auth/dev/index.mjs +4 -3
  128. package/modules/operator-auth/dev/sign-in-as.mjs +2 -1
  129. package/modules/operator-auth/dev-gate.mjs +3 -2
  130. package/modules/operator-auth/routes.mjs +2 -1
  131. package/modules/operator-auth/terminal-guidance.mjs +3 -0
  132. package/onboarding/adapter-settings.mjs +1 -0
  133. package/onboarding/adapter.mjs +3 -3
  134. package/onboarding/agent-handoff.mjs +1 -1
  135. package/onboarding/busy.mjs +1 -1
  136. package/onboarding/launcher.mjs +1 -1
  137. package/onboarding/local/environment.mjs +1 -1
  138. package/onboarding/local/operation.mjs +12 -4
  139. package/onboarding/local/owner.mjs +2 -2
  140. package/onboarding/operator-installer.mjs +4 -3
  141. package/onboarding/operator-migrations.mjs +1 -1
  142. package/onboarding/operator-prerequisites.mjs +26 -14
  143. package/onboarding/operator-settings.mjs +28 -0
  144. package/onboarding/process-diagnostics.mjs +2 -2
  145. package/onboarding/project-vite.mjs +1 -1
  146. package/package.json +1 -1
package/cli/README.md CHANGED
@@ -81,6 +81,31 @@ starts waiting on an existing server have one five-minute elapsed deadline,
81
81
  including control requests and polling. Loopback HTTP requests use an elapsed
82
82
  deadline, so a response that keeps sending bytes cannot extend readiness.
83
83
 
84
+ Signed: Run Edit Run fleet, 2026-11-17.
85
+
86
+ Before announcing `RER_READY`, `RER_OPEN` or the JSON `ready` event, managed
87
+ dev keeps its persona API check and opens the intended owner link in an isolated
88
+ headless browser through the public origin. It follows the fragment exchange,
89
+ cookies and server/client redirects to a 2xx page with visible usable controls,
90
+ without a busy/retry interstitial or loading state. The destination comes from
91
+ the application; no `/setup` path is assumed. Preview and demo also verify their
92
+ native owner entry, then issue a fresh single-use link for the owner.
93
+ Demo verifies that native entry before exchanging its persona dev key, preserving
94
+ the native entry authorization requirement. A front-door server permits routing
95
+ once its runtime can serve requests; registry readiness and ready announcements
96
+ still wait for the browser to verify the destination through that door.
97
+
98
+ This uses the checkout's locked Playwright and provisions its headless browser
99
+ on first use, as verification does. Owner readiness has a 60-second elapsed
100
+ deadline, including provisioning, browser launch and navigation. Set
101
+ `RER_OWNER_READY_TIMEOUT_MS` to positive integer milliseconds to change it.
102
+ Expiry exits 1 with `owner_entry_not_ready`, naming the entry and last destination
103
+ without credentials, for example: `Destination http://127.0.0.1:8787/workspace/start-here:
104
+ HTTP 503 (busy/retry interstitial)`. No ready event or open link is emitted.
105
+ An available persona API or health endpoint alone cannot establish that the
106
+ owner's page is ready. Inline recovery-script text is not mistaken for a visible
107
+ busy page.
108
+
84
109
  `rer dev` runs the local migration hook before starting the app and checking its
85
110
  owner prerequisites. The shared operator hook reads every SQL file in the seed's
86
111
  canonical `migrations/core` inventory, including changes pulled since the last
@@ -88,6 +113,22 @@ build, and prints the applied names. A failed migration stops startup with its
88
113
  captured error and `rer setup` guidance. `rer demo` uses the same inventory in
89
114
  its isolated state directory.
90
115
 
116
+ Signed: Run Edit Run fleet, 2026-11-17.
117
+
118
+ The shared operator adapter returns a named local prerequisite failure: the
119
+ field, found value and expected value. Secret settings report only set/unset.
120
+ This applies to dev and preview, including missing migration names, the durable
121
+ owner claim and the active owner. Legacy adapters returning false report their
122
+ `localPrerequisites` result.
123
+ Local operator mail requires `MAIL_PROVIDER=development`: some adopting seeds
124
+ select a real sender for hosted values even with local authentication enabled.
125
+ A hosted mail-off declaration (`none`, public settings and `mailOffSignIn`)
126
+ describes hosted behavior and does not establish a seed's local mail behavior.
127
+ Fresh setup refuses a hosted choice by field name and accepted value;
128
+ ordinary repeat `rer setup` repairs an already stored unsupported mail value to
129
+ `development`, preserving the owner, secrets and data. Hosted mail settings
130
+ remain in the deployment declaration and hosted environment.
131
+
91
132
  Successful terminal setup saves declared nonsecret installer answers in owned
92
133
  0600 storage under `.seed/installer`. A non-interactive repeat reuses those
93
134
  answers, with explicit flags or an answers file taking precedence. Runtime
@@ -128,6 +169,10 @@ restore has no door plan, reviewed fingerprint, reconciliation or Undo. Keep own
128
169
  Local `export --output FILE` and `import --input FILE --yes` use the Base
129
170
  portability implementation through the shared command runner and real Wrangler
130
171
  bindings. Seed adapters declare their database, buckets and archive policy.
172
+ The selected dispatcher supplies `@runeditrun/rer/portability` when it loads a
173
+ package adapter, including an explicitly invoked package CLI outside the
174
+ checkout. An older checkout package therefore cannot silently supply an older
175
+ archive worker. The seed's declared bindings and executable policy still apply.
131
176
  Export writes a new 0600 archive and reports its verified content hash, resource
132
177
  counts, exclusions and configuration names. Import applies migrations, verifies
133
178
  the archive and restores atomically into an empty destination. Stop dev or
@@ -138,6 +183,9 @@ destination refuses rows erased since. Erasure-fence refusals (`erased_row`,
138
183
  available only when the adapter declares complete resource coverage. Unsupported
139
184
  hosted export exits 2 before effects; unsupported import or transfer capability
140
185
  can refuse with exit 4.
186
+ Failed local transfers write their classified diagnostic into the private
187
+ capture and name its path. If capture could not be created or written, the
188
+ failure says so. Unexpected native messages, SQL and row values stay private.
141
189
 
142
190
  A first-party adapter may also declare `portability.hostedExport` as an argv
143
191
  array, for example `['node', 'scripts/export.mjs']`. With that declaration,
@@ -519,7 +567,19 @@ the local plan, while a real deployment validates the hosted identity before upl
519
567
 
520
568
  `--env-file` values are available in the command's preflight, custom hook and
521
569
  child build environment and are redacted; the caller environment is restored
522
- on success and failure. `--remove`, `--set-secret` and `--unset-secret` always go
570
+ on success and failure. If the caller already holds a non-empty
571
+ `CLOUDFLARE_API_TOKEN` (including a `rer business run --grant` child), any
572
+ `CLOUDFLARE_*` or `CF_*` key in `--env-file` is refused before provider calls.
573
+ The error names the file and key, never its value. Remove those keys from the
574
+ file and repeat the command. Without a caller token, file precedence is unchanged.
575
+
576
+ SIGTERM cancels provider requests, response reads, polling waits and owned child
577
+ processes, releases the deployment lock and retains deployment state for resume.
578
+ `rer deploy` exits 143 on SIGTERM (130 on SIGINT); repeat the command with fresh
579
+ credentials to resume. An unconfirmed provider create remains uncertain rather
580
+ than being repeated or adopted by name.
581
+
582
+ `--remove`, `--set-secret` and `--unset-secret` always go
523
583
  through the owner-account controller, without invoking the application's build
524
584
  or deploy hook. `--set-secret A,B` (or the flag repeated) changes several
525
585
  secrets in one Worker version or none, after checking that each is declared
@@ -693,6 +753,40 @@ On loopback, `rer preview` prints `RER_OPEN` for native owner entry.
693
753
  owner session in its isolated demo data. These native entry links work once,
694
754
  expire within 15 minutes and are never saved. Restarting retires them.
695
755
 
756
+ ## Business device credential storage
757
+
758
+ Business state lives in `$RER_BUSINESS_STATE_DIR` when set, otherwise in
759
+ `~/.rer/business`. Device credentials use the OS Keychain on macOS or Secret
760
+ Service on Linux by default; leaving `RER_BUSINESS_CREDENTIAL_DIR` unset preserves
761
+ that behavior.
762
+
763
+ Set `RER_BUSINESS_CREDENTIAL_DIR` to keep the device credential in an atomic
764
+ `0600` file in that directory instead. The directory must be caller-owned, mode
765
+ `0700`, and must not be a symbolic link; unsafe directories are refused. Filenames use a
766
+ digest derived from the platform origin and Business ID. Device secrets never
767
+ appear in filenames or storage diagnostics. With this variable set, device
768
+ credential operations never touch OS credential storage. There is no automatic
769
+ migration between stores: use the same selection to access an existing pairing.
770
+ All public Business commands use the selected backend when accessing device
771
+ credentials.
772
+
773
+ A sealed launcher must set both directories consistently for **every** Business
774
+ invocation, including the service process. Setting the state directory alone does
775
+ not select file credential storage. For a private, per-session pair of directories:
776
+
777
+ ```sh
778
+ umask 077
779
+ business_session_dir="$(mktemp -d)"
780
+ mkdir "$business_session_dir/state" "$business_session_dir/credentials"
781
+ export RER_BUSINESS_STATE_DIR="$business_session_dir/state"
782
+ export RER_BUSINESS_CREDENTIAL_DIR="$business_session_dir/credentials"
783
+ rer business connect --business ID
784
+ rer business status
785
+ ```
786
+
787
+ Keep both values available to subsequent commands and service invocations for
788
+ that session.
789
+
696
790
  ## Run your business demo
697
791
 
698
792
  ```sh
@@ -762,7 +856,9 @@ rer business run --grant GRANT_ID -- any-command 'argument with spaces'
762
856
  `cloudflare.token` in the Business MCP describes the exchange without returning a
763
857
  credential. Only the paired rer exchange receives a child token; the parent OAuth
764
858
  credential stays on the trusted server. The command gets `CLOUDFLARE_API_TOKEN`
765
- and `CLOUDFLARE_ACCOUNT_ID` in its environment. Cloudflare credential aliases from
859
+ and `CLOUDFLARE_ACCOUNT_ID` in its environment. The child also receives
860
+ `RER_BUSINESS_GRANT` set to the grant ID, so a queue or tool can recognise a
861
+ granted command. This marker contains only the ID, never the credential. Cloudflare credential aliases from
766
862
  the caller environment are removed. No shell is inserted and arguments after
767
863
  `--`, including help flags, are passed unchanged. Existing `run [--once]` continues
768
864
  its computer check-in behavior.
@@ -777,12 +873,35 @@ approved credential, never retries with broader or ambient access, and does not
777
873
  protect a process from its own deliberate credential loading.
778
874
 
779
875
  The child expires after at most 15 minutes, bounded also by the grant and the
780
- provider authorization. The wrapper interrupts a command at that expiry. It
781
- requests revocation after success, failure, signals or spawn failure; SIGKILL,
876
+ provider authorization. Before starting the command, stderr shows the child's
877
+ UTC credential expiry and minutes remaining, rounded up. The wrapper interrupts
878
+ a command at that expiry and reports that the credential expired, with
879
+ `run it again to resume` and the caller exit status. Invoke the command again to
880
+ obtain a new credential; the command's own behavior determines how work resumes.
881
+ The old credential is not extended or renewed.
882
+ Child exit codes and Unix terminating signals are preserved. At expiry the wrapper
883
+ sends SIGTERM: shell status 143 holds only for a command that exits on SIGTERM.
884
+ A process still running after the existing three-second grace is killed with
885
+ SIGKILL (shell status 137). A child that handles the signal keeps its own exit code. There is no separate synthetic
886
+ expiry failure code: the expiry message distinguishes it from a child failure. The wrapper requests revocation after success, failure,
887
+ signals or spawn failure; SIGKILL,
782
888
  crashes, network loss and lost acknowledgements may leave a token until server
783
- expiry. Child exit codes and Unix terminating signals are preserved. Cleanup has
889
+ expiry. Cleanup has
784
890
  its own stderr status, including **unconfirmed**, which is never called revoked.
785
891
  The safe lease ID in that status supports `rer business cleanup LEASE` to retry
786
892
  revocation and `rer business cleanup LEASE --status` to read its status. Cleanup
787
893
  needs the original pairing, but does not require the removed deploy action or an
788
894
  active grant. No child token is saved in state, OS storage, logs or MCP output.
895
+
896
+ Expiry guidance: Codex, 17 November 2026.
897
+
898
+ When the exchange refuses, the command never starts and the wrapper exits 1.
899
+ If Business names why, stderr shows one line: `Not started:` and Business's gap
900
+ sentence, then `The grant stays pending; nothing was issued.` for a pending
901
+ grant. When the refusal carries the Cloudflare permission catalogue's shape,
902
+ the line ends with its two counts only, for example
903
+ `catalogue: 93 rows, 7 mention Workers (see the audit row cloudflare.token.catalogue)`;
904
+ the rows themselves stay in that audit row. No other part of the refusal is
905
+ printed. Without a gap, the general refusal line names what to check in Business.
906
+
907
+ Signed: Run Edit Run fleet, 2026-11-17.
package/cli/archive.mjs CHANGED
@@ -3,6 +3,6 @@ import { createReadStream } from 'node:fs';
3
3
  import { diffArchives } from '../modules/portability/diff.mjs';
4
4
  import { invalid } from './errors.mjs';
5
5
  export async function archiveCommand(args,out) {
6
- if (args.length!==3 || args[0]!=='diff') throw invalid('Usage: rer archive diff BEFORE AFTER');
6
+ if (args.length!==3 || args[0]!=='diff') throw invalid('Usage: ~/.local/bin/rer archive diff BEFORE AFTER');
7
7
  const result=await diffArchives(Readable.toWeb(createReadStream(args[1])),Readable.toWeb(createReadStream(args[2]))); out.human(JSON.stringify(result,null,2)); return 0;
8
8
  }
package/cli/authoring.mjs CHANGED
@@ -4,7 +4,7 @@ import {refreshCopies, options as copyOptions} from '../edition-authoring/base-c
4
4
  import {refuse, invalid} from './errors.mjs';
5
5
 
6
6
  export function authoringCommand(options) {
7
- if (options.verb === 'refresh-base' && !options.ref) throw invalid('Provide --ref with the full immutable Base commit. Run rer refresh-base --help.');
7
+ if (options.verb === 'refresh-base' && !options.ref) throw invalid('Provide --ref with the full immutable Base commit. Run ~/.local/bin/rer refresh-base --help.');
8
8
  try {
9
9
  return options.verb === 'adopt-edition' ? adoptEdition(options.cwd) : refreshCopies(options.cwd, copyOptions([
10
10
  ...(options.editionMigration ? options.editionMigration.split(',').flatMap(id => ['--edition-migration', id]) : []),
@@ -9,8 +9,8 @@ import { dirname, join, relative } from 'node:path';
9
9
  import { RerError } from './errors.mjs';
10
10
  import { shared } from './shared.mjs';
11
11
 
12
- export const browserRepair = 'rer install';
13
- export const browserDownload = 'rer verify downloads the required browser on first use; rer install installs dependencies, not browsers';
12
+ export const browserRepair = '~/.local/bin/rer install';
13
+ export const browserDownload = '~/.local/bin/rer verify downloads the required browser on first use; ~/.local/bin/rer install installs dependencies, not browsers';
14
14
 
15
15
  export function checkoutPlaywright(root, { required = true } = {}) {
16
16
  const require = createRequire(join(root, 'package.json'));
@@ -3,7 +3,7 @@ import { rows, families } from './agent-table.mjs';
3
3
  const verb = name => name.split(' ')[1];
4
4
  const exits = `Exits 0 done, 1 refused or failed (the server's message is printed), 2 usage, 3 not built yet, 75 still working when\n--timeout ran out. A verb the owner has not granted this computer names where the owner grants it: Business, under Computers.`;
5
5
  const flags = `
6
- --app ID, --installation-id ID The installed app (from rer business installations list)
6
+ --app ID, --installation-id ID The installed app (from ~/.local/bin/rer business installations list)
7
7
  --FLAG VALUE Any other flag is an argument of the tool: --change-id, --preparation-id,
8
8
  --domain-id, --request-key, --method, --surface, --hostname, --public-path
9
9
  (kebab-case becomes snake_case). A value that starts with { or [ is JSON;
@@ -15,12 +15,12 @@ ${exits}`;
15
15
 
16
16
  /** The lines the advanced-commands help adds for the agent verbs. */
17
17
  export const agentUsage = `
18
- Agent verbs (Usage: rer business FAMILY VERB [--flags] [--json])
19
- Act on the company's installed apps from this computer, with no browser. Needs rer business connect first.
18
+ Agent verbs (Usage: ~/.local/bin/rer business FAMILY VERB [--flags] [--json])
19
+ Act on the company's installed apps from this computer, with no browser. Needs ~/.local/bin/rer business connect first.
20
20
  ${Object.entries(rows).map(([name, row]) => ` ${name.padEnd(24)} ${row.about}`).join('\n')}
21
21
  tools List the tools the Business server offers
22
22
  call TOOL [--flags] Call a tool that has no verb of its own yet
23
- mcp A local stdio MCP server for Claude Code or Codex: add \`rer business mcp\` as a server
23
+ mcp A local stdio MCP server for Claude Code or Codex: add \`~/.local/bin/rer business mcp\` as a server
24
24
  and the agent never handles a token
25
25
  change request --app ID "WHAT TO CHANGE" [--wait] [--publish]
26
26
  --wait follows the change to its preview; --publish also publishes it and waits for live
@@ -29,25 +29,25 @@ ${exits}
29
29
 
30
30
  const family = name => Object.entries(rows).filter(([key]) => key.split(' ')[0] === name)
31
31
  .map(([key, row]) => ` ${verb(key).padEnd(22)} ${row.about}`).join('\n');
32
- const help = name => `Usage: rer business ${name} VERB [--flags] [--json]
32
+ const help = name => `Usage: ~/.local/bin/rer business ${name} VERB [--flags] [--json]
33
33
  ${family(name)}
34
34
  ${flags}
35
35
  `;
36
36
 
37
37
  export const agentHelp = {
38
38
  ...Object.fromEntries(families.map(name => [name, help(name)])),
39
- tools: `Usage: rer business tools [--json]
40
- List the tools the Business server offers: name and a one-line description. Use rer business call TOOL to call one that has no verb.
39
+ tools: `Usage: ~/.local/bin/rer business tools [--json]
40
+ List the tools the Business server offers: name and a one-line description. Use ~/.local/bin/rer business call TOOL to call one that has no verb.
41
41
  `,
42
- call: `Usage: rer business call TOOL [--flag VALUE ...] [--args JSON] [--json]
42
+ call: `Usage: ~/.local/bin/rer business call TOOL [--flag VALUE ...] [--args JSON] [--json]
43
43
  Call any Business tool by name, such as installation.status. Flags become the tool's arguments (kebab-case to snake_case).
44
44
  Exits 0 done, 1 refused or failed, 3 not built yet.
45
45
  `,
46
- mcp: `Usage: rer business mcp
46
+ mcp: `Usage: ~/.local/bin/rer business mcp
47
47
  Run a local MCP server on stdin and stdout (newline-delimited JSON-RPC, revision 2025-11-25) that forwards to the Business
48
48
  MCP. It keeps the short-lived bearer fresh from this computer's pairing, so the agent that starts it never handles a token.
49
- Claude Code: claude mcp add business -- rer business mcp
49
+ Claude Code: claude mcp add business -- ~/.local/bin/rer business mcp
50
50
  Codex: add [mcp_servers.business] with command = "rer" and args = ["business", "mcp"]
51
- Needs rer business connect first. Only protocol messages go to stdout; diagnostics go to stderr.
51
+ Needs ~/.local/bin/rer business connect first. Only protocol messages go to stdout; diagnostics go to stderr.
52
52
  `,
53
53
  };
@@ -8,6 +8,7 @@ import { parseArguments, place, missing, Usage } from './agent-args.mjs';
8
8
  import { plain, refusalText, clean } from './agent-output.mjs';
9
9
  import { waitFor, failedState, stateName, exitStillWaiting } from './agent-wait.mjs';
10
10
  import { agentUsage } from './agent-help.mjs';
11
+ import { maskDeviceText } from './run-mask.mjs';
11
12
 
12
13
  export const exitNotBuilt = 3;
13
14
 
@@ -62,7 +63,7 @@ const waiters = { change, update };
62
63
 
63
64
  async function work(row, parsed, session, out) {
64
65
  const args = place(row, parsed), absent = missing(row, args), { control } = parsed;
65
- if (absent.length) throw new Usage(`${row.tool} needs ${absent.map(name => `--${name.replaceAll('_', '-')}`).join(', ')}. Run rer business ${row.name.split(' ')[0]} --help.`);
66
+ if (absent.length) throw new Usage(`${row.tool} needs ${absent.map(name => `--${name.replaceAll('_', '-')}`).join(', ')}. Run ~/.local/bin/rer business ${row.name.split(' ')[0]} --help.`);
66
67
  for (const flag of ['wait', 'publish']) {
67
68
  if (control[flag] && !(row.wait && (flag === 'wait' || row.tool.startsWith('change.')))) throw new Usage(`${row.name} does not take --${flag}.`);
68
69
  }
@@ -73,8 +74,8 @@ async function work(row, parsed, session, out) {
73
74
  // Lines for a person go to stdout; with --json only the final structuredContent does, and progress goes to stderr.
74
75
  function output(json) {
75
76
  return {
76
- line: text => (json ? process.stderr : process.stdout).write(text + '\n'),
77
- result: (tool, data) => { if (json) process.stdout.write(JSON.stringify(data) + '\n'); else for (const line of plain(tool, data)) process.stdout.write(line + '\n'); },
77
+ line: text => (json ? process.stderr : process.stdout).write(maskDeviceText(text) + '\n'),
78
+ result: (tool, data) => { if (json) process.stdout.write(maskDeviceText(JSON.stringify(data)) + '\n'); else for (const line of plain(tool, data)) process.stdout.write(line + '\n'); },
78
79
  };
79
80
  }
80
81
 
@@ -88,7 +89,7 @@ async function listTools(session, json) {
88
89
  cursor = response.result?.nextCursor;
89
90
  if (!cursor) break;
90
91
  }
91
- if (json) process.stdout.write(JSON.stringify({ tools }) + '\n');
92
+ if (json) process.stdout.write(maskDeviceText(JSON.stringify({ tools })) + '\n');
92
93
  else for (const tool of tools) process.stdout.write(`${clean(tool.name, 80)} ${clean(String(tool.description ?? '').split('\n')[0], 160)}`.trimEnd() + '\n');
93
94
  }
94
95
 
@@ -100,11 +101,11 @@ export async function agentCommand(argv) {
100
101
  let row, tail = rest;
101
102
  if (first === 'tools') { row = { name: 'tools' }; tail = [second, ...rest].filter(item => item !== undefined); }
102
103
  else if (first === 'call') {
103
- if (!/^[a-z][a-z0-9_.]{0,80}$/.test(second ?? '')) return usage('Name the tool: rer business call TOOL [--flag VALUE].');
104
+ if (!/^[a-z][a-z0-9_.]{0,80}$/.test(second ?? '')) return usage('Name the tool: ~/.local/bin/rer business call TOOL [--flag VALUE].');
104
105
  row = { name: `call ${second}`, tool: second };
105
106
  } else {
106
107
  row = rows[`${first} ${second}`] && { name: `${first} ${second}`, ...rows[`${first} ${second}`] };
107
- if (!row) return usage(`Unknown command: rer business ${first}${second ? ` ${clean(second, 40)}` : ''}.`);
108
+ if (!row) return usage(`Unknown command: ~/.local/bin/rer business ${first}${second ? ` ${clean(second, 40)}` : ''}.`);
108
109
  }
109
110
  let parsed;
110
111
  try { parsed = await parseArguments(tail); } catch (error) { if (error instanceof Usage) return usage(error.message); throw error; }
@@ -121,11 +122,11 @@ export async function agentCommand(argv) {
121
122
  if (error instanceof Usage) return usage(error.message);
122
123
  if (error instanceof Refused) {
123
124
  const text = refusalText(error.data, ownerLink(state));
124
- if (parsed.control.json) process.stdout.write(JSON.stringify(error.data ?? {}) + '\n');
125
+ if (parsed.control.json) process.stdout.write(maskDeviceText(JSON.stringify(error.data ?? {})) + '\n');
125
126
  process.stderr.write(text + '\n');
126
127
  return error.data?.status === 'not_built' ? exitNotBuilt : 1;
127
128
  }
128
- if (error.data && parsed.control.json) process.stdout.write(JSON.stringify(error.data) + '\n');
129
+ if (error.data && parsed.control.json) process.stdout.write(maskDeviceText(JSON.stringify(error.data)) + '\n');
129
130
  process.stderr.write(describe(error) + '\n');
130
131
  return error.exitCode ?? 1;
131
132
  }
@@ -24,9 +24,10 @@ export class ApiError extends Error {
24
24
  }
25
25
  }
26
26
 
27
- async function refusal(response, quiet = false) {
27
+ async function refusal(response, quiet = false, detail) {
28
28
  let text = '';
29
- try { text = (await response.text()).slice(0, 4096); } catch { /* The status alone is the reason. */ }
29
+ // A caller that reads its own detail gets the platform's whole error envelope (at most 64 KB); others read 4 KB.
30
+ try { text = (await response.text()).slice(0, detail ? 65_536 : 4096); } catch { /* The status alone is the reason. */ }
30
31
  let body = null;
31
32
  try { body = JSON.parse(text); } catch { /* A plain-text reason is used as it is. */ }
32
33
  const line = value => typeof value === 'string' && value.trim() ? redact(value).replace(/\s+/g, ' ').trim().slice(0, 300) : null;
@@ -35,8 +36,11 @@ async function refusal(response, quiet = false) {
35
36
  const code = typeof body?.code === 'string' && /^[a-z][a-z0-9_]{0,79}$/.test(body.code) ? body.code : null;
36
37
  // Pairing responses can echo secrets, including the short user code. Only
37
38
  // the bounded machine code is needed by that flow, never server prose.
38
- return new ApiError(response.status, quiet ? null : reason, quiet ? null : requestId, code,
39
+ const error = new ApiError(response.status, quiet ? null : reason, quiet ? null : requestId, code,
39
40
  quiet ? {} : { state: body?.state === 'waiting_for_owner' ? body.state : undefined, link: line(body?.link) });
41
+ // Only the fields the caller picks and bounds travel with the error, never the body itself.
42
+ if (detail && body && typeof body === 'object' && !Array.isArray(body)) error.detail = detail(body);
43
+ return error;
40
44
  }
41
45
 
42
46
  const network = {
@@ -68,12 +72,12 @@ export class Api {
68
72
  || !Number.isFinite(Date.parse(result.expires_at)) || Date.parse(result.expires_at) <= Date.now()) throw Error('Business server returned an invalid scoped bearer.');
69
73
  return result;
70
74
  }
71
- async post(path, body, { token = this.credential, signal, timeout = 30_000, headers = {}, withStatus = false, quiet = false } = {}) {
72
- return this.request('POST', path, body, { token, signal, timeout, headers, withStatus, quiet });
75
+ async post(path, body, { token = this.credential, signal, timeout = 30_000, headers = {}, withStatus = false, quiet = false, detail } = {}) {
76
+ return this.request('POST', path, body, { token, signal, timeout, headers, withStatus, quiet, detail });
73
77
  }
74
78
  async get(path) { return this.request('GET', path); }
75
79
  async delete(path) { return this.request('DELETE', path); }
76
- async request(method, path, body, { token = this.credential, signal, timeout = 30_000, headers = {}, withStatus = false, quiet = false } = {}) {
80
+ async request(method, path, body, { token = this.credential, signal, timeout = 30_000, headers = {}, withStatus = false, quiet = false, detail } = {}) {
77
81
  if (!path.startsWith('/api/business/') || path.includes('..') || path.includes('?') || path.includes('#')) throw Error('Invalid Business route.');
78
82
  let response;
79
83
  try {
@@ -83,7 +87,7 @@ export class Api {
83
87
  ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(timeout)]) : AbortSignal.timeout(timeout),
84
88
  });
85
89
  } catch (error) { if (signal?.aborted) throw signal.reason; throw unreachable(this.origin, error); }
86
- if (!response.ok) throw await refusal(response, quiet);
90
+ if (!response.ok) throw await refusal(response, quiet, detail);
87
91
  // Successful bodies are untrusted: callers validate them and print only fields they template.
88
92
  if (response.status === 202 && response.headers.get('content-length') === '0' || response.status === 204) return null;
89
93
  const text = await response.text();
@@ -1,5 +1,6 @@
1
1
  import { Api } from './api.mjs';
2
2
  import { createCredentialStore } from './keychain.mjs';
3
+ import { credentialLocation } from './credential-file.mjs';
3
4
  import { deviceCredentialHandle, loadState } from './state.mjs';
4
5
  import { localCause } from './errors.mjs';
5
6
  import { carryCheckouts, firstParty, writeCarry } from './carry-files.mjs';
@@ -31,10 +32,10 @@ function warning(origin, error, checkout, report = true) {
31
32
  const reason = error.status ? `the server refused the request (HTTP ${error.status})`
32
33
  : error.name === 'TimeoutError' || error.name === 'AbortError' ? 'the server did not answer within 5 seconds'
33
34
  : error.message?.startsWith('Could not reach the Business server at ') ? 'the server is unreachable'
34
- : error.message === 'credential unavailable' ? 'the Business credential is unavailable in OS credential storage'
35
+ : error.message === 'credential unavailable' ? `the Business credential is unavailable in ${credentialLocation()}`
35
36
  : error.preparation ? error.message
36
- : localCause(error) ?? (['the response names another Business', 'the Business profile is invalid', 'the checkout is not first-party', 'the carry path is linked or not a regular file', 'the existing file is not a carry for this paired Business', 'the carry registry is invalid', 'the checkout is not set up yet: run rer setup'].includes(error.message) ? error.message : 'the Business profile could not be refreshed');
37
- const step = error.code === 'ENOENT' ? ' Open the app with rer dev --cwd FOLDER, then run business next again.' : '';
37
+ : localCause(error) ?? (['the response names another Business', 'the Business profile is invalid', 'the checkout is not first-party', 'the carry path is linked or not a regular file', 'the existing file is not a carry for this paired Business', 'the carry registry is invalid', 'the checkout is not set up yet: run ~/.local/bin/rer setup'].includes(error.message) ? error.message : 'the Business profile could not be refreshed');
38
+ const step = error.code === 'ENOENT' ? ' Open the app with ~/.local/bin/rer dev --cwd FOLDER, then run business next again.' : '';
38
39
  const text = `Business carry at ${origin}${checkout ? ` for ${JSON.stringify(checkout)}` : ''}: ${reason}; keeping any local carry.${step}\n`;
39
40
  if (report) process.stderr.write(text);
40
41
  return text;
@@ -100,7 +100,7 @@ export async function applyChoices(api, state, { reconnecting = false } = {}) {
100
100
  : `No local app carry files changed for ${JSON.stringify(carried.name)}.\n`);
101
101
  for (const checkout of carried.unchanged) process.stdout.write(`Already current: ${join(checkout, '.rer/local/business.json')}\n`);
102
102
  if (carried.failed) process.stdout.write(`${carried.failed} local app carry ${carried.failed === 1 ? 'file could' : 'files could'} not be refreshed; see the carry warnings.\n`);
103
- if (!count && !carried.unchanged.length && !carried.failed) process.stdout.write(`No local apps were found. Run ${businessCommand('next')} in the folder where rer list shows your apps.\n`);
103
+ if (!count && !carried.unchanged.length && !carried.failed) process.stdout.write(`No local apps were found. Run ${businessCommand('next')} in the folder where ~/.local/bin/rer list shows your apps.\n`);
104
104
  }
105
105
  return { applied: lines.length, serviceInstalled };
106
106
  }
@@ -10,12 +10,12 @@ import { appAddress, appSignInHelp } from '../app-address.mjs';
10
10
  import { agentUsage, agentHelp } from './agent-help.mjs';
11
11
  import { agentFamilies } from './agent-table.mjs';
12
12
 
13
- const usage = `Set up your business: rer business connect --business ID
13
+ const usage = `Set up your business: ~/.local/bin/rer business connect --business ID
14
14
  The Business Connect page names the ID.
15
15
  Business keeps your business name, logo and brand colour together for the apps
16
16
  that support shared Business settings. Choose what to share in your browser.
17
17
 
18
- Advanced commands (Usage: rer business VERB)
18
+ Advanced commands (Usage: ~/.local/bin/rer business VERB)
19
19
  setup --origin URL --session-file FILE --confirm-demo
20
20
  Create the synthetic demo company's Business and its profile
21
21
  --hosting managed|assisted|self_host (default: managed); --json
@@ -41,13 +41,24 @@ Advanced commands (Usage: rer business VERB)
41
41
  disconnect Revoke this computer, then remove local credentials and additions;
42
42
  inside an agent sandbox it names the one command that finishes
43
43
  State lives in $RER_BUSINESS_STATE_DIR when set, otherwise in ~/.rer/business.
44
- In an agent sandbox that writes only inside its working folder, use RER_BUSINESS_STATE_DIR="$PWD/.rer-business".
44
+ Device credentials use OS Keychain/Secret Service unless RER_BUSINESS_CREDENTIAL_DIR is set.
45
+ When set, all public Business commands use atomic 0600 device credential files there,
46
+ in a caller-owned 0700 directory that is not a symlink; unsafe directories are refused.
47
+ Names use a digest of origin and Business ID; secrets never enter names or storage diagnostics.
48
+ This selection never touches OS device credential storage; no automatic migration occurs.
49
+ A sealed launcher must set both directories consistently for every Business invocation,
50
+ including its service process. Example private per-session directories:
51
+ umask 077
52
+ business_session_dir="$(mktemp -d)"
53
+ mkdir "$business_session_dir/state" "$business_session_dir/credentials"
54
+ export RER_BUSINESS_STATE_DIR="$business_session_dir/state"
55
+ export RER_BUSINESS_CREDENTIAL_DIR="$business_session_dir/credentials"
45
56
  ${agentUsage}${appSignInHelp}
46
57
  `;
47
58
 
48
59
  const verbHelp = {
49
60
  ...agentHelp,
50
- setup: `Usage: rer business setup --origin URL --session-file FILE --confirm-demo [--hosting managed|assisted|self_host] [--json]
61
+ setup: `Usage: ~/.local/bin/rer business setup --origin URL --session-file FILE --confirm-demo [--hosting managed|assisted|self_host] [--json]
51
62
  Create the Business for the synthetic demo company in setup-company.json and save
52
63
  its profile, through the platform's owner routes. A repeat reuses that Business and
53
64
  changes nothing when its profile already matches. It provisions no seeds.
@@ -64,31 +75,42 @@ changes nothing when its profile already matches. It provisions no seeds.
64
75
  Exits 0 when the Business exists with that profile; 1 with a named {code} on stderr.
65
76
  ${appSignInHelp}
66
77
  `,
67
- run: `Usage: rer business run --grant G -- <command> [args...]
78
+ run: `Usage: ~/.local/bin/rer business run --grant G -- <command> [args...]
68
79
  Run any software command under this paired agent’s explicit deploy action and grant.
69
80
  The scoped Cloudflare token and account reach only the child environment. Output
70
81
  is masked and cleanup is reported separately; the child’s exit status is kept.
82
+ Before starting, stderr shows the credential's UTC expiry and minutes remaining
83
+ (rounded up). At expiry the command is interrupted and says: run it again to resume.
84
+ The reported caller exit status keeps the child's code or terminating signal
85
+ (normally SIGTERM, shell status 143); a child that handles it keeps its own code.
86
+ A refused exchange starts nothing and exits 1. When Business says why (a pending
87
+ grant's gap), stderr prints it on one line after "Not started:".
71
88
 
72
- Usage: rer business run [--once]
89
+ Usage: ~/.local/bin/rer business run [--once]
73
90
  Work this computer's tasks (the folder scan the owner allows) and check in every
74
91
  25 seconds until stopped. Steps for this computer's agent, such as a seed's Move in,
75
- are shown by rer business next. --once returns after one check-in.
92
+ are shown by ~/.local/bin/rer business next. --once returns after one check-in.
76
93
  Exits 0 completed, idle or waiting for the owner; 1 failed; 2 usage.
77
94
  `,
78
- connect: `Usage: rer business connect --business ID [--origin URL] [--timeout SECONDS]
95
+ connect: `Usage: ~/.local/bin/rer business connect --business ID [--origin URL] [--timeout SECONDS]
79
96
  Pair this computer with a Business. Prints a code and a link: the owner opens the
80
97
  link in a signed-in browser, checks the code and approves. Waits for that (up to
81
- the code's 10 minutes), then keeps the credential in OS credential storage.
98
+ the code's 10 minutes), then keeps the device credential in OS Keychain/Secret Service,
99
+ or an atomic 0600 file when RER_BUSINESS_CREDENTIAL_DIR is set. That directory must
100
+ be caller-owned, mode 0700, and not a symlink; unsafe directories are refused.
101
+ File storage never touches OS device credential storage and does not migrate it.
102
+ Keep both RER_BUSINESS_STATE_DIR and RER_BUSINESS_CREDENTIAL_DIR consistent across
103
+ all Business invocations, including the service process.
82
104
  --business ID The Business to join; the Connect prompt names it.
83
105
  --origin URL Business platform address (default: ${appAddress}).
84
106
  --timeout SECONDS Wait at most this long, then exit 75 with the pairing kept;
85
107
  run the same command again to keep waiting (same code).
86
108
  Exits 0 connected, 1 ended (refused, expired or failed), 2 usage, 75 still waiting.
87
109
  `,
88
- token: `Usage: rer business token
110
+ token: `Usage: ~/.local/bin/rer business token
89
111
  Print an MCP Authorization header object for this computer's paired Business.
90
112
  Send this headersHelper output directly to the MCP client; it contains a credential.
91
- Requires an existing pairing: rer business connect --business ID (the Connect page names the ID).
113
+ Requires an existing pairing: ~/.local/bin/rer business connect --business ID (the Connect page names the ID).
92
114
  `,
93
115
  };
94
116
 
@@ -3,6 +3,7 @@ import { join } from 'node:path';
3
3
  import { Api, originUrl, identifier, pause } from './api.mjs';
4
4
  import { loadState, saveState, credentialHandle, deviceCredentialHandle, loadPending, savePending, clearPending, checkStateWritable, lockPairing } from './state.mjs';
5
5
  import { createCredentialStore } from './keychain.mjs';
6
+ import { credentialLocation } from './credential-file.mjs';
6
7
  import { applyChoices } from './choices.mjs';
7
8
  import { rerCommand, businessCommand } from './invocation.mjs';
8
9
  import { Stopped } from './errors.mjs';
@@ -65,7 +66,7 @@ async function connectDevice({ business, origin, timeout } = {}) {
65
66
  if (stored.revoked) throw Error(`This computer was ${revokedText(stored)}`);
66
67
  if (stored.origin !== origin || stored.businessId !== business) throw Error(`This state folder is connected to Business ${identifier(stored.businessId)} at ${originUrl(stored.origin)}. Run disconnect, or use another RER_BUSINESS_STATE_DIR.`);
67
68
  const credential = await createCredentialStore().get(deviceCredentialHandle(stored));
68
- if (!credential) throw Error('This computer\'s Business credential is missing from OS credential storage. Run disconnect, then connect again.');
69
+ if (!credential) throw Error(`This computer's Business credential is missing from ${credentialLocation()}. Run disconnect, then connect again.`);
69
70
  await unlock(); unlock = undefined;
70
71
  return await connected(new Api(origin, credential), stored, { reconnecting: true });
71
72
  }
@@ -75,8 +76,7 @@ async function connectDevice({ business, origin, timeout } = {}) {
75
76
  validateDevicePairing({ ...pending, business_id: pending.businessId }, origin, business);
76
77
  if (!timestampValid(pending.keep_until) || Date.parse(pending.keep_until) > Date.parse(pending.expires_at) + approvalWindow) throw Error('The saved Business pairing is invalid. Run business disconnect, then connect again.');
77
78
  }
78
- // Both probes precede even the unauthenticated start. Keychain / Secret
79
- // Service handling and the device credential's account are unchanged.
79
+ // Both storage probes precede even the unauthenticated pairing start.
80
80
  const store = createCredentialStore();
81
81
  resume = `${rerCommand()} business connect --business ${business} --origin ${origin}${timeout === undefined ? '' : ` --timeout ${timeout}`}`;
82
82
  try { await store.check(); }
@@ -120,7 +120,7 @@ async function connectDevice({ business, origin, timeout } = {}) {
120
120
  await store.set(handle, result.device_credential);
121
121
  try { await saveState(state); } catch (error) { await store.delete(handle); throw error; }
122
122
  await clearPending();
123
- process.stdout.write('Approved. Device credential stored in OS credential storage.\n');
123
+ process.stdout.write(`Approved. Device credential stored in ${credentialLocation()}.\n`);
124
124
  return await connected(new Api(origin, result.device_credential), state);
125
125
  } finally { await clearPending(); }
126
126
  }