relay-codex 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 blackspider-ops
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+<p align="center"><img src="https://raw.githubusercontent.com/blackspider-ops/relay/main/assets/relay.svg" alt="Relay — keep Codex moving" width="840"></p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Relay keeps your Codex sessions moving between your own accounts. When an account
+runs out, it finds another available account. When all accounts are waiting for a
+reset, it waits too, then continues the saved task.
+
+**macOS · Native Codex terminal · One account or many**
+
+## Get started
+
+You'll need [Codex](https://learn.chatgpt.com/docs/cli), Node.js 20 or newer, and
+Python 3.11 or newer. If you use Homebrew, `brew install node python@3.13` installs
+Node and Python.
+
+```sh
+npm install -g relay-codex
+relay setup --count 2
+relay run
+```
+
+Choose however many accounts you have. Each person signs into their own accounts;
+this project does not include anyone's saved logins. Existing logins from the
+earlier `codex-accounts` tool are picked up automatically.
+
+The first run downloads Relay's Python libraries. Later runs use the saved copy.
+Your usual `codex` command keeps working.
+
+Prefer trying it without a global install?
+
+```sh
+npx --yes relay-codex setup --count 2
+npx --yes relay-codex run
+```
+
+## Use it like Codex
+
+```sh
+relay run -- resume --yolo
+relay run -- -C ~/projects/website resume
+relay run -- exec --json "Review this project"
+relay status --watch
+relay menubar
+```
+
+`--yolo` keeps its usual full-access meaning. Without it, Relay keeps the task's
+permissions. Resume starts with sessions from your current folder, just like
+`codex resume`. Add `--all` to browse every folder, or `-C PATH` to choose a folder.
+Different terminals can work on different conversations at once.
+
+Put native Codex commands and options after `relay run --`. Use `relay run --help`
+for the full Codex command and flag list, or `relay help` for Relay management.
+Profiles, extra writable directories, Git worktrees, and noninteractive tasks can
+use the account pool. `relay explain -- <arguments>` shows how a launch will run.
+Native utilities, external/local-provider endpoints, and a few native-only setup
+flags run directly; `--require-recovery` rejects a launch outside Relay recovery.
+
+If a conversation is already open in another app, close it there before resuming
+it here, or use Codex's `fork` command for a separate copy. To move a Relay task
+between terminals:
+
+```sh
+relay attach --takeover SESSION_ID
+```
+
+Accounts show their saved email addresses. The watch view updates only when local
+status changes; it uses no model allowance. The menu bar uses an icon and opens
+at Mac login. `relay menubar --no-startup --configure-only` disables login startup.
+
+## What happens when something stops?
+
+- **Account limit:** use an available account, or wait for the earliest usable reset.
+- **One account:** wait for its reset and continue the same conversation.
+- **Connection or sign-in failure:** retry at 5, 10, and 15 minutes, then try another account.
+- **“Selected model is at capacity”:** wait five minutes and try the same model again.
+  Relay keeps waiting rather than cycling logins. A different model is used only
+  if you explicitly configure a fallback.
+- **An unclear interruption during a command:** pause for review before continuing.
+  Relay cannot guarantee that an external action happened exactly once.
+
+## Leave work running
+
+```sh
+relay start --name website --cwd ~/projects/website --prompt "Finish the remaining checks"
+relay attach SESSION_ID
+relay stop SESSION_ID
+```
+
+Background tasks keep running after their terminal closes. Use `relay status --all`
+to find saved sessions and `relay restart SESSION_ID` to recover a stopped one.
+Opt into task recovery at Mac login with `relay startup enable SESSION_ID`.
+`relay workspace save daily` and `relay workspace restore daily` retain the same
+conversations across several terminals.
+
+## A few useful commands
+
+```sh
+relay add personal
+relay account disable personal
+relay pause SESSION_ID
+relay unpause SESSION_ID
+relay retry SESSION_ID
+relay doctor --self-test
+relay menubar
+```
+
+Accounts stay in your Mac's Keychain. Relay keeps its settings and task records
+in your private Application Support folder. Never share that folder.
+
+## Updates and limits
+
+Relay checks the installed Codex version and keeps a working copy for running
+sessions. Future Codex changes may still need a Relay update.
+Update Relay with `npm install -g relay-codex@latest`.
+
+This is an independent tool, not an OpenAI product. Short local tests cover
+parallel tasks and recovery; they are not an overnight reliability guarantee.
+
+[Commands](docs/commands.md) · [Troubleshooting](docs/troubleshooting.md) ·
+[Publishing to npm or Homebrew](docs/publishing.md) · [Contributing](CONTRIBUTING.md)

package/assets/relay.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="360" viewBox="0 0 1280 360" role="img" aria-labelledby="title desc">
+  <title id="title">Relay</title>
+  <desc id="desc">Keep Codex moving. Four paths meet in one forward arrow.</desc>
+  <rect width="1280" height="360" rx="24" fill="#111916"/>
+  <g fill="none" stroke="#a8d9bd" stroke-width="10" stroke-linecap="round">
+    <path d="M96 108h62c48 0 44 72 94 72h44" opacity=".5"/>
+    <path d="M96 156h82c34 0 30 24 72 24h46" opacity=".7"/>
+    <path d="M96 204h82c34 0 30-24 72-24h46"/>
+    <path d="M96 252h62c48 0 44-72 94-72h44" opacity=".5"/>
+    <path d="m278 158 24 22-24 22" stroke="#f7be74"/>
+  </g>
+  <text x="366" y="185" fill="#f5f3ec" font-family="Helvetica Neue,Arial,sans-serif" font-size="98" font-weight="650" letter-spacing="-5">Relay</text>
+  <text x="371" y="239" fill="#acb9b0" font-family="Helvetica Neue,Arial,sans-serif" font-size="27" letter-spacing=".2">Keep Codex moving.</text>
+  <text x="1140" y="73" text-anchor="end" fill="#a8d9bd" font-family="Menlo,monospace" font-size="15">FOR YOUR TERMINAL</text>
+</svg>

package/bin/relay.cjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawnSync, spawn } = require('node:child_process');
+const { setTimeout: delay } = require('node:timers/promises');
+
+const packageRoot = path.resolve(__dirname, '..');
+const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+
+function stateDirectory(env = process.env, home = os.homedir()) {
+  if (env.RELAY_STATE || env.CODEX_ACCOUNTS_STATE) {
+    return path.resolve(env.RELAY_STATE || env.CODEX_ACCOUNTS_STATE);
+  }
+  const support = path.join(home, 'Library', 'Application Support');
+  const legacy = path.join(support, 'Codex Accounts');
+  return fs.existsSync(path.join(legacy, 'accounts')) ? legacy : path.join(support, 'Relay');
+}
+
+function pythonCommand() {
+  const choices = [process.env.RELAY_PYTHON, 'python3', 'python3.14', 'python3.13', 'python3.12', 'python3.11'].filter(Boolean);
+  for (const command of choices) {
+    const result = spawnSync(command, ['-c', 'import sys; print(sys.executable); raise SystemExit(sys.version_info < (3, 11))'], { encoding: 'utf8' });
+    if (result.status === 0) return result.stdout.trim();
+  }
+  throw new Error('Relay needs Python 3.11 or newer. Install it with: brew install python@3.13');
+}
+
+function privateDirectory(directory) {
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const info = fs.lstatSync(directory);
+  if (info.isSymbolicLink() || (process.getuid && info.uid !== process.getuid())) {
+    throw new Error('Relay needs a private folder owned by your user.');
+  }
+  fs.chmodSync(directory, 0o700);
+}
+
+function fingerprint() {
+  const source = path.join(packageRoot, 'python');
+  const names = fs.readdirSync(source).filter(name => /\.(py|swift|lock|txt)$/.test(name)).sort();
+  for (const name of fs.readdirSync(path.join(packageRoot, 'tests')).filter(name => name.endsWith('.py')).sort()) names.push(`tests/${name}`);
+  const hash = crypto.createHash('sha256');
+  hash.update(pkg.version);
+  for (const name of names) hash.update(name).update(fs.readFileSync(name.startsWith('tests/') ? path.join(packageRoot, name) : path.join(source, name)));
+  return { id: `${pkg.version}-${hash.digest('hex').slice(0, 16)}`, names, source };
+}
+
+function processBirth(pid) {
+  const result = spawnSync('/bin/ps', ['-p', String(pid), '-o', 'lstart='], { encoding: 'utf8' });
+  return result.status === 0 ? result.stdout.trim() : '';
+}
+
+function ownerAlive(owner) {
+  try {
+    process.kill(owner.pid, 0);
+    return Boolean(owner.birth) && processBirth(owner.pid) === owner.birth;
+  } catch { return false; }
+}
+
+async function withSetupLock(state, operation) {
+  const lock = path.join(state, 'relay-setup.lock');
+  const deadline = Date.now() + 10 * 60 * 1000;
+  while (true) {
+    try { fs.mkdirSync(lock, { mode: 0o700 }); break; }
+    catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      let stale = false;
+      try {
+        const owner = JSON.parse(fs.readFileSync(path.join(lock, 'owner.json'), 'utf8'));
+        stale = !ownerAlive(owner);
+      } catch {
+        // Another process may be between mkdir and writing its owner record.
+        try { stale = Date.now() - fs.statSync(lock).mtimeMs > 30_000; }
+        catch (error) { if (error.code === 'ENOENT') continue; throw error; }
+      }
+      if (stale) {
+        const abandoned = `${lock}.stale-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+        try { fs.renameSync(lock, abandoned); fs.rmSync(abandoned, { recursive: true, force: true }); }
+        catch (error) { if (!['ENOENT', 'EEXIST'].includes(error.code)) throw error; }
+        continue;
+      }
+      if (Date.now() > deadline) throw new Error('Another Relay setup is still running. Let it finish, then try again.');
+      await delay(200);
+    }
+  }
+  fs.writeFileSync(path.join(lock, 'owner.json'), JSON.stringify({ pid: process.pid, birth: processBirth(process.pid) }), { mode: 0o600 });
+  try { return await operation(); }
+  finally { fs.rmSync(lock, { recursive: true, force: true }); }
+}
+
+function run(command, args) {
+  const result = spawnSync(command, args, { stdio: 'inherit' });
+  if (result.error || result.status !== 0) throw new Error('Setup did not finish. Run Relay again to retry.');
+}
+
+async function prepare(state) {
+  const bundle = fingerprint();
+  const destination = path.join(state, 'relay-runtimes', bundle.id);
+  const interpreter = path.join(destination, '.venv', 'bin', 'python');
+  const marker = path.join(destination, 'ready.json');
+  const ready = () => fs.existsSync(marker) && fs.existsSync(interpreter) && spawnSync(interpreter, ['-c', 'import websockets, jsonschema'], { stdio: 'ignore' }).status === 0;
+  if (ready()) return { interpreter, router: path.join(destination, 'router.py') };
+  const python = pythonCommand();
+  return withSetupLock(state, async () => {
+    if (ready()) return { interpreter, router: path.join(destination, 'router.py') };
+    privateDirectory(destination);
+    for (const name of bundle.names) {
+      const source = name.startsWith('tests/') ? path.join(packageRoot, name) : path.join(bundle.source, name);
+      fs.mkdirSync(path.dirname(path.join(destination, name)), { recursive: true, mode: 0o700 });
+      fs.copyFileSync(source, path.join(destination, name));
+    }
+    console.error('Preparing Relay for this Mac. This only happens on first use or after an update.');
+    // Always retry dependency installation if a previous setup was interrupted.
+    run(python, ['-m', 'venv', path.join(destination, '.venv')]);
+    run(interpreter, ['-m', 'pip', 'install', '--disable-pip-version-check', '-r', path.join(destination, 'requirements.lock')]);
+    fs.writeFileSync(marker, JSON.stringify({ version: pkg.version }), { mode: 0o600 });
+    return { interpreter, router: path.join(destination, 'router.py') };
+  });
+}
+
+async function main() {
+  if (process.platform !== 'darwin') throw new Error('Relay currently supports macOS.');
+  if (process.argv.length === 3 && ['--version', '-V'].includes(process.argv[2])) {
+    console.log(`Relay ${pkg.version}`); return;
+  }
+  const state = stateDirectory(); privateDirectory(state);
+  const runtime = await prepare(state);
+  const child = spawn(runtime.interpreter, [runtime.router, ...process.argv.slice(2)], {
+    stdio: 'inherit', env: { ...process.env, RELAY_STATE: state, CODEX_ACCOUNTS_STATE: state }
+  });
+  // Terminal Ctrl-C already reaches both foreground processes.
+  const interrupt = () => {};
+  const terminate = () => child.kill('SIGTERM');
+  process.on('SIGINT', interrupt); process.on('SIGTERM', terminate);
+  process.on('SIGHUP', terminate);
+  child.on('error', () => { console.error('Relay could not start. Run it again to retry.'); process.exitCode = 1; });
+  await new Promise(resolve => child.on('close', (code, signal) => {
+    process.exitCode = code ?? (signal === 'SIGINT' ? 130 : 1); resolve();
+  }));
+  process.off('SIGINT', interrupt); process.off('SIGTERM', terminate);
+  process.off('SIGHUP', terminate);
+}
+
+module.exports = { stateDirectory, fingerprint, ownerAlive, withSetupLock, prepare };
+if (require.main === module) main().catch(error => { console.error(`relay: ${error.message}`); process.exitCode = 1; });

package/docs/commands.md

@@ -0,0 +1,176 @@
+# Commands
+
+## Help
+
+```sh
+relay help
+relay help account
+relay help workspace
+relay run --help
+relay run -- exec --help
+relay help codex resume
+```
+
+`relay run --help` shows the installed Codex command and flag list, followed by
+Relay's launch options. Put native arguments after `relay run --`.
+
+## Accounts
+
+```sh
+relay setup --count 1
+relay setup --count 6
+relay add personal
+relay list
+relay account identify
+relay refresh
+relay account rename personal "My account"
+relay account disable personal
+relay account enable personal
+relay account priority personal 10
+relay account cap personal 2
+relay account models personal YOUR_MODEL
+relay account reauth personal
+relay account remove personal
+```
+
+Accounts display their saved email addresses. `account identify` fills in emails
+for earlier installations without another sign-in. Commands accept an account's
+label, unique email, or chosen display name. Renaming keeps the login usable.
+A session cap of zero means unlimited. Removing an account retains its login
+unless you request `--revoke`.
+
+## Launch and recovery
+
+```sh
+relay run
+relay run -- resume --yolo
+relay run -- -C ~/projects/website resume
+relay run -- -p work --add-dir ~/shared
+relay run -- --worktree "Try the next change"
+relay run -- exec --json "Run the checks"
+relay run -- review --uncommitted
+relay explain -- resume --yolo
+relay run --require-recovery -- resume
+```
+
+Resume defaults to the current folder. Add `--all` to browse other folders or
+`-C/--cd` to choose another working folder. Native profile files are read from
+`$CODEX_HOME/NAME.config.toml`; explicit config flags override the profile.
+Relay worktrees are detached Git worktrees under its private state folder. Their
+files are retained for review; cleanup does not delete worktrees.
+
+Interactive work, resume/fork, profiles, extra directories, worktrees, and supported
+noninteractive exec/review runs use the account pool. Exec supports text/stdin,
+images, JSON events, output schemas, last-message files, and resume/fork. Review
+supports the working tree, base branch, commit, or custom instructions.
+
+Native utility commands are forwarded unchanged. Local providers, explicitly
+remote servers, hook-trust bypass, and ignoring native config/rules use native
+Codex directly with its ordinary login. Help/version also run directly. These
+modes do not use Relay recovery. `--require-recovery` rejects such a launch, and
+`explain` shows which mode applies without making an inference request.
+
+Noninteractive runs cannot approve a tool request on your behalf. Use explicit
+native permissions such as `--yolo` only when intended, or resume interactively
+when input is required. Automatic review is supported by `--approve-for-me`.
+
+## Dashboard and session controls
+
+```sh
+relay status
+relay status --watch
+relay status --all
+relay status --json
+relay menubar
+relay menubar --no-startup
+relay attach SESSION_ID
+relay attach SESSION_ID --takeover
+relay pause SESSION_ID --wait
+relay unpause SESSION_ID --wait
+relay retry SESSION_ID --wait
+relay switch SESSION_ID --account personal --wait
+relay stop SESSION_ID --wait
+relay restart SESSION_ID
+```
+
+The watch view waits for local file changes and redraws only when useful status
+changes. Heartbeats do not repeatedly print the table. Watching uses no model
+allowance and does not fetch account allowance. `refresh` explicitly checks it.
+The menu uses one local status stream, a template icon, and native session actions.
+It opens at Mac login after `relay menubar`; disable that in its menu or with
+`relay menubar --no-startup --configure-only`.
+
+IDs may be shortened to a unique prefix. Without `--wait`, controls are queued;
+with it, Relay waits for the worker's confirmation and reports a rejection.
+Pause stops automatic recovery after current work finishes. Retry clears a review
+hold: inspect an interrupted external action in the conversation first.
+
+## Background tasks and saved workspaces
+
+```sh
+relay start --name website --cwd ~/projects/website --prompt "Run the checks"
+relay workspace save daily
+relay workspace list
+relay workspace restore daily
+relay workspace remove daily
+relay startup enable SESSION_ID
+relay startup list
+relay startup disable SESSION_ID
+```
+
+A workspace saves the same supervised session IDs, rather than starting fresh
+conversations. Restore restarts stopped jobs and prints reconnect commands; live
+jobs are retained. Save specific sessions by appending their IDs to `workspace save`.
+
+The normal command remains available after reboot. Background task recovery at
+login is a separate opt-in setting; enabling the menu does not enable task startup.
+Uncertain work still pauses for review after recovery.
+
+## Preferences
+
+```sh
+relay config
+relay config notifications true
+relay config background_on_disconnect true
+relay config keep_awake true
+relay config retry_interval 300
+relay config retry_attempts 3
+relay config routing quota
+relay config preferred_accounts '["personal"]'
+relay config fallback_models '["YOUR_CHOSEN_MODEL"]'
+relay config retry_interval 60 --profile quick
+relay run --profile quick
+```
+
+Routing choices are `balanced`, `quota`, `priority`, and `round-robin`. Model
+fallback is opt-in. Capacity errors otherwise retain the selected model/account.
+Keep-awake prevents idle system sleep only while a managed task is active; it does
+not keep the display on. Project preferences may live in `.relay.toml` under
+`[settings]` or `[profiles.NAME]`. Legacy `.codex-accounts.toml` files still work.
+Relay recovery profiles go before `--`; native Codex profiles go after it.
+
+## Diagnostics and cleanup
+
+```sh
+relay doctor --self-test
+relay doctor --backup
+relay doctor --restore-backup
+relay diagnostics relay-diagnostics.json
+relay clean
+relay clean --older-than 30
+relay clean --apply
+relay events --limit 30
+relay usage
+relay runtime list
+relay runtime preflight /path/to/codex
+```
+
+Diagnostics export allowlisted versions, event types, and counts without account
+emails, task names, project paths, prompts, or credentials. Review other files
+before sharing them; private state and connection files must stay private.
+
+Cleanup is a dry run unless `--apply` is given. It retains live/restartable runtime
+references and saved workspaces. `--jobs` also allows removal of old stopped-job
+records. Stop supervised jobs before applying cleanup. Worktrees and account
+logins are retained. Metadata restore also requires stopped tasks and preserves a
+copy of the replaced database. Usage forecasts are local estimates.

package/docs/publishing.md

@@ -0,0 +1,72 @@
+# Sharing Relay
+
+Relay is published on npm as [relay-codex](https://www.npmjs.com/package/relay-codex).
+Friends can run `npx relay-codex` or install it with `npm install -g relay-codex`.
+
+## GitHub and npx
+
+The GitHub repository is enough for friends to install or try Relay:
+
+```sh
+npm install -g github:blackspider-ops/relay#v0.5.0
+npx --yes github:blackspider-ops/relay#v0.5.0 --version
+```
+
+`npx` runs packages; it is not a separate publishing service. Publishing
+`relay-codex` on npm also makes `npx relay-codex` available.
+
+## Publish on npm
+
+The repository includes `.github/workflows/publish.yml`. Configure a trusted
+publisher for `relay-codex` using GitHub user `blackspider-ops`, repository `relay`,
+and workflow filename `publish.yml`. Select direct `npm publish` permission if
+releases should publish automatically. No long-lived publishing token is needed.
+A new trusted publisher must complete its first publish within npm's validation
+window. Run the workflow for an existing reviewed version tag, or publish the
+GitHub release; the workflow runs checks before publishing. After the first
+successful trusted publish, set the repository variable
+`NPM_TRUSTED_PUBLISHING_READY=true` to enable automatic release publishing. Until
+then, releases do not launch a publishing attempt that requires authentication.
+
+Initial trust setup requires npm account verification. Interactive local
+`npm publish` also requires verification when package 2FA applies. Installing and
+running the public package does not require npm sign-in. An expired publishing
+prompt should be restarted once, rather than repeatedly running `npm login`.
+
+For a manual release, review and publish the exact packed artifact:
+
+```sh
+npm test
+npm run check
+npm pack --ignore-scripts
+npm publish ./relay-codex-VERSION.tgz --access public
+```
+
+After publishing, friends can use:
+
+```sh
+npx relay-codex setup --count 2
+npm install -g relay-codex
+```
+
+## Homebrew
+
+The repository includes a formula under `Formula/`. It can be installed from this
+repository as a personal tap; it does not need acceptance into Homebrew's main
+collection. The formula must point to a tagged release archive with its actual
+SHA-256 checksum.
+
+```sh
+brew tap blackspider-ops/relay https://github.com/blackspider-ops/relay
+brew install blackspider-ops/relay/relay-codex
+```
+
+For a new release, update the package and Python versions together, run the checks,
+tag it, upload the archive, then update the formula URL and checksum. Keep the
+previous release available for users who need to roll back.
+
+Official references: [trusted publishing](https://docs.npmjs.com/trusted-publishers/),
+[package publishing verification](https://docs.npmjs.com/requiring-2fa-for-package-publishing-and-settings-modification/),
+[npm publishing](https://docs.npmjs.com/creating-and-publishing-unscoped-public-packages),
+[npx](https://docs.npmjs.com/cli/v11/commands/npx/), and
+[Homebrew taps](https://docs.brew.sh/How-to-Create-and-Maintain-a-Tap).

package/docs/troubleshooting.md

@@ -0,0 +1,49 @@
+# Troubleshooting
+
+**“This conversation is open in another app.”**
+
+Close or unload that conversation in its original app before resuming it. Or fork
+it into a separate conversation. For a Relay-owned task, use
+`relay attach --takeover SESSION_ID`.
+
+**A session needs attention.**
+
+Run `relay status`, then `relay events`. Once the cause is resolved, use
+`relay restart SESSION_ID` if the worker stopped, or `relay retry SESSION_ID` if it
+is still running and you have reviewed the interrupted work.
+
+**Setup was interrupted.**
+
+Run the command again. Relay retries unfinished dependency installation. If Python
+is missing or too old, install it with `brew install python@3.13`.
+
+**An account needs another sign-in.**
+
+Move its live tasks to another account, then run `relay account reauth ACCOUNT`.
+Other accounts can keep working.
+
+**The terminal disconnected after a worker restart.**
+
+Relay reconnects the terminal when a replacement worker publishes a recovered
+connection. If recovery requires review or the project folder is unavailable,
+check `relay status` and `relay events`, then reattach with `relay attach SESSION_ID`.
+
+**Something still seems wrong.**
+
+Run `relay doctor --self-test`. Include the Relay and Codex versions when reporting
+a bug. Do not post auth files, tokens, connection files, or private task prompts.
+
+Long runs, physical sleep/wake cycles, real revoked logins, and future Codex
+versions need broader live testing. The tests do not remove those limits.
+
+**The dashboard repeats or an email is missing.**
+
+Check `relay --version` and update Relay. Watch now prints only meaningful changes
+from local state, without using model allowance. Earlier enrolled accounts can be
+identified with `relay account identify`; this reads saved login metadata locally.
+
+**Why does npm ask for authentication?**
+
+That verification protects package publishing. Installing and running the public
+Relay package does not require npm sign-in. Maintainers can use the repository's
+trusted-publishing workflow once npm has authorized that workflow.

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "relay-codex",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.0",
+  "description": "Keep your Codex sessions moving between your own accounts.",
+  "license": "MIT",
+  "author": "blackspider-ops",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/blackspider-ops/relay.git"
+  },
+  "homepage": "https://github.com/blackspider-ops/relay#readme",
+  "bugs": {
+    "url": "https://github.com/blackspider-ops/relay/issues"
+  },
+  "bin": {
+    "relay": "bin/relay.cjs"
+  },
+  "files": [
+    "bin/*.cjs",
+    "python/*.py",
+    "python/*.swift",
+    "python/*.lock",
+    "python/*.txt",
+    "tests/*.py",
+    "README.md",
+    "LICENSE",
+    "docs/*.md",
+    "assets/*.svg"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "os": [
+    "darwin"
+  ],
+  "keywords": [
+    "codex",
+    "terminal",
+    "accounts",
+    "macos"
+  ],
+  "scripts": {
+    "test": "node --test tests/bootstrap.test.cjs",
+    "check": "node scripts/check-release.cjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}