traintrack 2.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 traintrack
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,158 @@
+<p align="center">
+  <img src="assets/banner.svg" alt="traintrack" width="660">
+</p>
+
+<p align="center">
+  <b>Your coding agents, working as a team — in the terminals you already use.</b><br>
+  Run <code>claude</code> and <code>codex</code> like you always do. After one <code>traintrack setup</code>, every session auto-joins a shared team: they see each other and talk, or one becomes a foreman that spawns the rest.
+</p>
+
+<p align="center">
+  <code>npm i -g traintrack</code> · <code>traintrack setup</code> · Apache-2.0 · <b>beta</b> (Claude Code · Codex) · <b>pre-pre-alpha</b> (OpenCode · Cursor)
+</p>
+
+<p align="center">
+  <i>No daemon · no wrapper command · no new app · just a SQLite file at your repo root.</i>
+</p>
+
+> [!WARNING]
+> **Alpha.** traintrack is brand new and moving fast — commands, config formats, and the wire protocol can change between versions. Claude Code & Codex are live-verified; expect rough edges, and pin a version if you depend on it.
+
+---
+
+## Why traintrack is different
+
+There are many ways to run several agents at once. traintrack is the one that disappears into your existing setup:
+
+- **No wrapper, no relaunch.** You don't start agents *through* traintrack. Set up once, and your normal `claude` / `codex` sessions — however you launch them, even from your IDE's terminal — are already on the team. Nothing to remember at launch time.
+- **Both modes in one install.** A leaderless **peer mesh** (sessions you open by hand discover + message each other) *and* a **foreman** that spawns headless workers into isolated git worktrees. Most tools do one or the other; traintrack does both, and the peer→lead transition is seamless.
+- **Zero infrastructure.** No background daemon, no tmux, no cloud relay, no Electron app. The message bus is a SQLite file at your git repo root; install is a single `npm i -g`.
+- **Native tools, not a prompt blob.** Agents get real MCP tools — `list_team`, `send_message`, `spawn_worker`, `await_results` — not a wall of injected instructions.
+
+---
+
+## Install
+
+```bash
+npm install -g traintrack
+traintrack setup
+```
+
+`traintrack setup` detects which agent CLIs you actually have (**Claude Code**, **Codex**, **OpenCode**, **Cursor**), lets you pick, and wires each one up:
+
+```
+  › ◉ Claude Code  found 'claude' on PATH
+    ◉ Codex        found 'codex' on PATH
+    ◉ OpenCode     found 'opencode' on PATH
+    ◉ Cursor       found 'cursor' on PATH
+  ↑/↓ move · space toggle · a all/none · enter confirm · esc cancel
+```
+
+For each tool it (a) **registers the MCP server** in that tool's config and (b) **injects a short team-awareness note** into its instructions file. From then on you just launch your CLI normally. It's idempotent (safe to re-run), and `traintrack setup --uninstall` reverses it cleanly.
+
+> Installs the `traintrack` command globally.
+
+---
+
+## Try it
+
+### Mesh: open a few sessions, watch them connect
+
+In one project, open two or three `claude` / `codex` sessions the way you always do (any subdirectory is fine — no special command). Then:
+
+```bash
+traintrack team          # see everyone on this project's team
+```
+```
+Team channel: /your/repo/.traintrack/channel.db
+  - claude-3f9a  (claude, role: lead, live, active)
+  - codex-7c12   (codex,  role: lead, live, active)
+```
+
+Tell one session: *"send a message to `codex-7c12`: what are you working on?"* — the other surfaces it on its next turn (a `📨 1 unread` nudge), reads it with `check_messages`, and replies.
+
+### Lead: blabber, get a team
+
+In one session:
+
+> "Build a CSV parser, a test suite for it, and a short README — split it up."
+
+It proposes which worker takes which part, then on your OK spawns headless workers, collects their results, and hands you the finished work.
+
+---
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `traintrack setup` | Detect + wire your agent CLIs (interactive). |
+| `traintrack team` | Show this project's team (handles, agent, role, online status). |
+| `traintrack inbox --handle <h>` | Print unread messages for a handle. |
+| `traintrack join --handle <h> --role <r> [--agent claude\|codex]` | Run a headless auto-responding member that joins the team. |
+| `traintrack init` | Create the `.traintrack/` channel for the current project. |
+| `traintrack worker --agent <a> --role <r> --handle <h>` | Run a single headless worker bound to the channel. |
+
+**`setup` flags:** `--all`, `--yes`, `--dry-run`, `--tools-only`, `--uninstall`, `--home <path>`.
+**Channel selection (any command):** `--channel <path>`, or `--room <name>` for a shared room across projects (`~/.traintrack/rooms/<name>.db`). The default is your **git repo root** (`<repo>/.traintrack/channel.db`).
+
+### The coordination tools your agent gets
+
+`list_team` · `check_messages` · `send_message` · `spawn_worker` · `delegate_task` · `await_results` · `join_team`
+
+---
+
+## How it works
+
+- **The channel is a SQLite file** (WAL) resolved at the **git repo root**, so every session opened in a project shares one team automatically. `--room` gives a shared cross-project bus.
+- **Auto-presence:** each session's MCP server registers itself as a live member on startup and flips to offline when it ends — that's how teammates appear with zero setup.
+- **Auto-receive:** spawned **headless workers** truly auto-respond (they run a drain→turn→reply loop). Hand-driven sessions can't be interrupted mid-task (a CLI limit), so they pick up messages at their next turn — every tool result carries a `📨 N unread` nudge so nothing is missed.
+- **Spawning** = `git worktree add` + a child process, so each worker has an isolated tree and its own provider session.
+- **No daemon, no server, no telemetry.** It's a library + an MCP server + a CLI.
+
+---
+
+## Supported CLIs
+
+| CLI | Mesh (talk to teammates) | Spawn as a headless worker |
+| --- | --- | --- |
+| Claude Code | ✅ | ✅ |
+| Codex | ✅ | ✅ |
+| OpenCode | ⚠️ wired by `setup`, not yet verified | ⏳ planned |
+| Cursor | ⚠️ wired by `setup`, not yet verified | ⏳ planned |
+
+Claude Code and Codex are first-class and live-verified end-to-end. OpenCode and Cursor are wired by `setup` and can join the mesh, but spawning them as headless workers is on the roadmap.
+
+---
+
+## Manual setup (advanced)
+
+If you'd rather not run the wizard, register the MCP server yourself. Resolve the absolute path with `node -e "console.log(require.resolve('traintrack/dist/mcp-server.js'))"`.
+
+- **Claude Code** — add to `~/.claude.json`:
+  ```json
+  { "mcpServers": { "traintrack": { "command": "node", "args": ["<abs>/dist/mcp-server.js"], "env": { "TRAINTRACK_AGENT": "claude" } } } }
+  ```
+- **Codex** — add to `~/.codex/config.toml`:
+  ```toml
+  [mcp_servers.traintrack]
+  command = "node"
+  args = ["<abs>/dist/mcp-server.js"]
+  env = { TRAINTRACK_AGENT = "codex" }
+  ```
+
+(Setup also writes a short awareness note into each tool's instructions file — see `traintrack setup --dry-run` for exactly what it would change.)
+
+---
+
+## Status
+
+Two tiers of maturity:
+
+- **Claude Code + Codex — alpha/beta.** The engine (spawn → work → collect, multi-round delegation, live members, the peer mesh, and the one-command installer) is built and **live-verified with real `claude`/`codex` agents** — see `scripts/verify-*.mjs` and [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
+- **OpenCode + Cursor — pre-pre-alpha.** Wired by `setup` so their sessions join the mesh, but not yet verified end-to-end; spawning them as headless workers is next.
+
+Things will change under you while it's early.
+
+## License
+
+[Apache-2.0](LICENSE) · © 2026 traintrack

package/dist/channel/channel.js

@@ -0,0 +1,64 @@
+import Database from 'better-sqlite3';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+export class Channel {
+    db;
+    dbPath;
+    constructor(dbPath) {
+        this.dbPath = dbPath;
+        mkdirSync(dirname(dbPath), { recursive: true });
+        this.db = new Database(dbPath);
+        this.db.pragma('journal_mode = WAL');
+        this.db.pragma('busy_timeout = 5000');
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS messages (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        from_handle TEXT NOT NULL, to_handle TEXT NOT NULL,
+        body TEXT NOT NULL, type TEXT NOT NULL DEFAULT 'message',
+        read INTEGER NOT NULL DEFAULT 0,
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE TABLE IF NOT EXISTS members (
+        handle TEXT PRIMARY KEY, agent TEXT NOT NULL, role TEXT NOT NULL,
+        kind TEXT NOT NULL, status TEXT NOT NULL, worktree TEXT
+      );`);
+    }
+    insertMessage(m) {
+        const r = this.db.prepare(`INSERT INTO messages (from_handle,to_handle,body,type) VALUES (?,?,?,?)`).run(m.from, m.to, m.body, m.type ?? 'message');
+        return Number(r.lastInsertRowid);
+    }
+    getUnread(handle) {
+        return this.db.prepare(`SELECT id, from_handle as "from", to_handle as "to", body, type, read, created_at as createdAt
+       FROM messages WHERE to_handle = ? AND read = 0 ORDER BY id`).all(handle);
+    }
+    /** The last `limit` messages across the whole channel, oldest→newest (for a timeline view). */
+    getRecentMessages(limit = 100) {
+        return this.db.prepare(`SELECT id, "from", "to", body, type, read, createdAt FROM (
+         SELECT id, from_handle as "from", to_handle as "to", body, type, read, created_at as createdAt
+         FROM messages ORDER BY id DESC LIMIT ?
+       ) ORDER BY id ASC`).all(limit);
+    }
+    markRead(ids) {
+        if (ids.length === 0) {
+            return;
+        }
+        const stmt = this.db.prepare(`UPDATE messages SET read = 1 WHERE id = ?`);
+        const tx = this.db.transaction((xs) => { for (const x of xs) {
+            stmt.run(x);
+        } });
+        tx(ids);
+    }
+    addMember(m) {
+        this.db.prepare(`INSERT OR REPLACE INTO members (handle,agent,role,kind,status,worktree) VALUES (?,?,?,?,?,?)`).run(m.handle, m.agent, m.role, m.kind, m.status, m.worktree);
+    }
+    listMembers() {
+        return this.db.prepare(`SELECT * FROM members ORDER BY rowid`).all();
+    }
+    getMember(handle) {
+        return this.db.prepare(`SELECT * FROM members WHERE handle = ?`).get(handle) ?? null;
+    }
+    setStatus(handle, status) {
+        this.db.prepare(`UPDATE members SET status = ? WHERE handle = ?`).run(status, handle);
+    }
+    close() { this.db.close(); }
+}

package/dist/channel/resolve.js

@@ -0,0 +1,43 @@
+// Resolve WHICH channel db a traintrack process should attach to. The key design
+// point: default to the GIT REPO ROOT (not cwd) so every session opened anywhere
+// inside a project auto-lands in the SAME team — no flags, no path fiddling.
+//
+// Order of precedence:
+//   1. explicit `channel` (a --channel path)
+//   2. `room` → a shared cross-project room at ~/.traintrack/rooms/<room>.db
+//   3. TRAINTRACK_CHANNEL env
+//   4. git repo root → <root>/.traintrack/channel.db   (the common case)
+//   5. cwd → <cwd>/.traintrack/channel.db              (non-git fallback)
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+/** The git repo root for `cwd`, or null if not inside a work tree. */
+export function gitRoot(cwd) {
+    try {
+        const out = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return out.toString().trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Resolve the channel db path per the precedence above. */
+export function resolveChannelPath(opts = {}) {
+    const env = opts.env ?? process.env;
+    const cwd = opts.cwd ?? process.cwd();
+    if (opts.channel)
+        return opts.channel;
+    if (opts.room)
+        return join(homedir(), '.traintrack', 'rooms', `${sanitizeRoom(opts.room)}.db`);
+    if (env['TRAINTRACK_CHANNEL'])
+        return env['TRAINTRACK_CHANNEL'];
+    const root = (opts.gitRootImpl ?? gitRoot)(cwd);
+    return join(root ?? cwd, '.traintrack', 'channel.db');
+}
+/** Room names become a file name; keep them filesystem-safe. */
+function sanitizeRoom(room) {
+    return room.replace(/[^a-zA-Z0-9_-]/g, '_') || 'global';
+}

package/dist/cli.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+// ─── traintrack CLI ──────────────────────────────────────────────────────────
+// The `traintrack` binary (package.json "bin"). Two subcommands:
+//
+//   traintrack init [--channel <path>]
+//     Create .traintrack/ and an empty channel db so the workspace is ready for the
+//     lead's MCP server and any workers to attach to.
+//
+//   traintrack worker --agent <claude|codex> --role <role> --handle <handle> [--channel <path>]
+//     Run a long-lived headless worker loop bound to the channel — it drains its
+//     inbox, runs a headless agent turn per batch, and replies over the channel.
+//
+// Flag parsing mirrors traintrack-desktop's `headless-worker` block: a small
+// `flag(name)` helper over argv, with the agent validated to the two providers.
+import { Channel } from './channel/channel.js';
+import { resolveChannelPath } from './channel/resolve.js';
+import { runWorker } from './worker/worker.js';
+import { runSetup } from './setup/setup.js';
+import { renderBanner, bannerColorEnabled } from './ui/banner.js';
+import { VERSION } from './index.js';
+const USAGE = `Usage:
+  traintrack setup [--all] [--yes] [--dry-run] [--tools-only] [--uninstall] [--home <path>]
+  traintrack team [--room <name>] [--channel <path>]
+  traintrack inbox --handle <handle> [--room <name>] [--channel <path>]
+  traintrack init [--room <name>] [--channel <path>]
+  traintrack worker --agent <claude|codex> --role <role> --handle <handle> [--channel <path>]
+  traintrack join --handle <handle> --role <role> [--agent <claude|codex>] [--room <name>] [--channel <path>]`;
+/** Read the value following a `--name` flag in argv, or undefined if absent. */
+function flag(args, name) {
+    const i = args.indexOf(name);
+    return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
+}
+/** True if a boolean `--name` flag is present in argv. */
+function has(args, name) {
+    return args.includes(name);
+}
+/** Resolve the channel db path from --channel / --room flags, else the git-root
+ *  default (so sessions in a project auto-share a team). */
+function channelFromArgs(args) {
+    return resolveChannelPath({ channel: flag(args, '--channel'), room: flag(args, '--room') });
+}
+function fail(message) {
+    process.stderr.write(`${message}\n`);
+    process.exit(1);
+}
+/** Print the branded banner to stdout (colorized only on a real terminal). */
+function showBanner() {
+    process.stdout.write(renderBanner({ version: VERSION, color: bannerColorEnabled(process.stdout) }));
+}
+async function main(argv) {
+    const command = argv[0];
+    const args = argv.slice(1);
+    if (!command || command === 'help' || command === '--help' || command === '-h') {
+        showBanner();
+        process.stdout.write(`${USAGE}\n`);
+        return;
+    }
+    if (command === 'setup') {
+        showBanner();
+        // TRAINTRACK_SETUP_NO_PATH=1 forces config-hint-only detection (ignores the
+        // real PATH) so the hermetic verify script exercises exactly the seeded HOME.
+        const noPath = process.env['TRAINTRACK_SETUP_NO_PATH'] === '1';
+        await runSetup({
+            all: has(args, '--all'),
+            yes: has(args, '--yes'),
+            dryRun: has(args, '--dry-run'),
+            toolsOnly: has(args, '--tools-only'),
+            uninstall: has(args, '--uninstall'),
+            home: flag(args, '--home'),
+            ...(noPath ? { onPath: () => false } : {}),
+        });
+        return;
+    }
+    if (command === 'init') {
+        // Opening a Channel creates .traintrack/ (mkdir recursive) and the db file with
+        // its schema; close it immediately — init just provisions the workspace.
+        const channelPath = channelFromArgs(args);
+        new Channel(channelPath).close();
+        process.stdout.write(`Initialized traintrack channel at ${channelPath}\n`);
+        return;
+    }
+    if (command === 'team') {
+        // Show everyone on this project's team and where the channel lives.
+        const channelPath = channelFromArgs(args);
+        const channel = new Channel(channelPath);
+        const members = channel.listMembers();
+        channel.close();
+        process.stdout.write(`Team channel: ${channelPath}\n`);
+        if (members.length === 0) {
+            process.stdout.write('No members yet. Open a traintrack-aware session here, or spawn a worker.\n');
+            return;
+        }
+        for (const m of members) {
+            process.stdout.write(`  - ${m.handle}  (${m.agent}, role: ${m.role}, ${m.kind}, ${m.status})\n`);
+        }
+        return;
+    }
+    if (command === 'inbox') {
+        // Print the unread messages addressed to a handle (does NOT mark them read).
+        const handle = flag(args, '--handle') ?? process.env['TRAINTRACK_HANDLE'];
+        if (!handle) {
+            fail('inbox: --handle is required (or set TRAINTRACK_HANDLE)');
+        }
+        const channel = new Channel(channelFromArgs(args));
+        const msgs = channel.getUnread(handle);
+        channel.close();
+        if (msgs.length === 0) {
+            process.stdout.write(`No unread messages for ${handle}.\n`);
+            return;
+        }
+        process.stdout.write(`${msgs.length} unread for ${handle}:\n`);
+        for (const m of msgs) {
+            process.stdout.write(`  [${m.id}] from ${m.from}: ${m.body}\n`);
+        }
+        return;
+    }
+    if (command === 'worker') {
+        const agentRaw = flag(args, '--agent');
+        if (agentRaw !== 'claude' && agentRaw !== 'codex') {
+            fail('worker: --agent must be "claude" or "codex"');
+        }
+        const agent = agentRaw;
+        const role = flag(args, '--role');
+        if (!role) {
+            fail('worker: --role is required');
+        }
+        const handle = flag(args, '--handle');
+        if (!handle) {
+            fail('worker: --handle is required');
+        }
+        const channel = new Channel(channelFromArgs(args));
+        await runWorker({ channel, handle, agent, role, cwd: process.cwd() });
+        return;
+    }
+    if (command === 'join') {
+        const agentRaw = flag(args, '--agent') ?? 'codex';
+        if (agentRaw !== 'claude' && agentRaw !== 'codex') {
+            fail('join: --agent must be "claude" or "codex"');
+        }
+        const agent = agentRaw;
+        const role = flag(args, '--role');
+        if (!role) {
+            fail('join: --role is required');
+        }
+        const handle = flag(args, '--handle');
+        if (!handle) {
+            fail('join: --handle is required');
+        }
+        const channel = new Channel(channelFromArgs(args));
+        // Reject a duplicate handle rather than clobber the existing member (addMember
+        // is INSERT OR REPLACE). Handles must be unique on the team.
+        if (channel.getMember(handle)) {
+            fail(`join: handle "${handle}" is already on the team — pick a unique --handle`);
+        }
+        // A LIVE member the user launched and joined to an existing team. It auto-checks
+        // its inbox on the same responsive loop as a worker, so it never misses a message.
+        await runWorker({ channel, handle, agent, role, cwd: process.cwd(), kind: 'live' });
+        return;
+    }
+    fail(USAGE);
+}
+main(process.argv.slice(2)).catch((err) => {
+    fail(err instanceof Error ? err.message : String(err));
+});

package/dist/index.js

@@ -0,0 +1,6 @@
+export const VERSION = '0.0.1';
+// Public API — so host apps (e.g. the Traintrack desktop studio) and the
+// ecosystem can consume the channel directly. The CLI/MCP server remain the
+// primary writers; readers (a Coordination Room UI) can open the same channel.
+export { Channel } from './channel/channel.js';
+export { resolveChannelPath, gitRoot } from './channel/resolve.js';