@jbaehova/onthego 0.1.3 → 0.3.1

package/README.md

@@ -1,212 +1,218 @@
-<h1 align="center">ONTHEGO</h1>
+# ONTHEGO
 
-<p align="center">
-  <strong>Carry the work. Keep the context.</strong>
-</p>
+Continue your coding-agent conversation on another device, with your unfinished Git workspace intact.
 
-<p align="center">
-  <em>Secure, project-scoped AI agent handoffs from your local Git workspace to a Daytona sandbox.</em>
-</p>
+ONTHEGO is an MIT-licensed CLI for explicit handoffs between your own computers. It carries staged and unstaged work together with project-scoped Codex CLI and Claude Code histories. Each destination keeps its Git settings, hooks, local dependencies, and editor directory intact.
 
-<p align="center">
-  <img alt="npm version" src="https://img.shields.io/npm/v/%40jbaehova%2Fonthego?style=flat-square&logo=npm&logoColor=white&color=CB3837">
-  <img alt="Node 18+" src="https://img.shields.io/badge/Node-18%2B-43853D?style=flat-square&logo=node.js&logoColor=white">
-  <img alt="Go 1.25.4+" src="https://img.shields.io/badge/Go-1.25.4%2B-00ADD8?style=flat-square&logo=go&logoColor=white">
-  <img alt="macOS arm64 and Linux x64" src="https://img.shields.io/badge/Platform-macOS_arm64_%7C_Linux_x64-334155?style=flat-square">
-  <a href="LICENSE"><img alt="License MIT" src="https://img.shields.io/badge/License-MIT-C5A800?style=flat-square"></a>
-</p>
+No ONTHEGO account or central server is needed. SSH connects your devices. Install and authenticate the coding agent separately on each device. This project targets individual CLI users.
 
-<p align="center">
-  <img src="assets/onthego-banner.webp" alt="ONTHEGO carrying secure agent context from a local workspace to a cloud sandbox" width="88%">
-</p>
+## Install
 
-Your repository moves easily. Agent memory does not.
+```sh
+npm install -g @jbaehova/onthego@^0.3.1
+```
+
+The npm package includes binaries for macOS arm64/amd64 and Linux arm64/amd64. Git and OpenSSH are required. Node.js is needed only for the npm launcher. Install the same ONTHEGO version on both devices.
 
-ONTHEGO finds the Codex, Cursor, Hermes, and Claude sessions that belong to the current Git project, removes common secrets on your machine, creates a focused handoff, and sends it to an isolated Daytona workload. Run status is synchronized through a lightweight control plane. Results come back only after their SHA-256 digest matches the remote receipt.
+You can also build from source with Go 1.26 or newer (the build selects Go 1.27.2):
 
-```text
-local project  ->  redact  ->  HANDOFF.md  ->  Daytona  ->  verify  ->  local result
+```sh
+git clone https://github.com/peerproblem/onthego.git
+cd onthego
+make build
+mkdir -p ~/.local/bin
+install -m 755 dist/onthego ~/.local/bin/onthego
+# Or: go install github.com/peerproblem/onthego/cmd/onthego@latest
 ```
 
-## What It Does
+## Desktop to laptop
 
-- Discovers every supported agent session associated with the current Git repository.
-- Redacts tokens, authorization headers, private keys, and matching secret assignments before transfer.
-- Generates a redacted context envelope and human-readable `HANDOFF.md`.
-- Starts the default `agent-sync` workload in Daytona with one command.
-- Synchronizes run state, redacted logs, and summaries across authenticated devices.
-- Uses GPT-5.6 Luna with high reasoning effort to turn current state into a concise status update.
-- Downloads an artifact only after its hash matches the remote run receipt.
+Enable SSH on the destination and establish a trusted SSH connection first. An existing SSH alias can use a LAN address or your own VPS. Tailscale and other VPNs are optional ways to provide reachability. Both devices must be reachable during a direct transfer.
 
-## Quick Start
+Inside the project on the desktop:
 
-Install the CLI:
+```sh
+onthego init
+onthego device add laptop --host me@my-laptop
+onthego remote set laptop /Users/me/projects/my-app
+onthego doctor laptop
+onthego push laptop --dry-run
 
-```bash
-npm install -g @jbaehova/onthego
+# Stop agents and other processes that write project files, then:
+onthego push laptop --verbose
 ```
 
-Create a private `.env` at the Git root:
+`device add` pairs both public identities through your trusted SSH connection. It discovers the remote executable using a login shell. Use `--binary /absolute/path/onthego` when needed. `--port` and `--identity-file` select an existing SSH connection; private SSH keys are never copied.
+
+Devices store hosts and identities once. Project paths are separate mappings under `~/.onthego/projects/<id>/peers.yaml`. Without a mapping, the path relative to your home directory is used under the remote home. `device add ... --path ...` remains a shortcut for the current project's mapping.
 
-```dotenv
-DAYTONA_API_KEY=...
-ONTHEGO_CONTROL_PLANE_URL=https://your-control-plane.example.com
-ONTHEGO_CONTROL_PLANE_TLS_SHA256=...
-ONTHEGO_LOGIN_BOOTSTRAP_TOKEN=...
+For the first transfer, choose a destination directory that does not exist. On the laptop:
 
-# Optional. Enables the LLM summary in `onthego status`.
-OPENAI_API_KEY=...
+```sh
+cd /Users/me/projects/my-app
+onthego status
+codex resume <session-id>
+# Or: claude --resume <session-id>
 ```
 
-Lock down the file, then run the five-command flow:
+Use the session ID printed by the handoff. These commands resume a native history, not a running process. See the exact tested CLI versions and validation boundaries in [agent compatibility](docs/agent-compatibility.md).
 
-```bash
-chmod 600 .env
+To bring laptop changes back, run this from the desktop project:
 
-onthego init
-onthego login
-onthego pass
-onthego status
-onthego pull
+```sh
+onthego pull laptop --verbose
 ```
 
-That is the complete Phase 1 workflow. You do not choose an agent or paste a session ID. `onthego pass` resolves the current Git root and collects the matching sessions automatically.
+The destination is updated in place. Existing shells, editor watchers, and local dependency directories continue to refer to the same project directory. Stop writers during the transfer so they cannot race with capture or application.
 
-> [!NOTE]
-> The current release expects a Daytona account and a deployed ONTHEGO control plane. The control plane server is included in this repository. See [Architecture](docs/architecture.md) and the [Contabo operations guide](docs/contabo.md).
+After a successful push, `status` warns that the project and sessions were handed to the other device. Pull before editing or resuming them on the original device.
 
-## The Five Commands
+## What moves
 
-| Command | Purpose |
+| Data | Behavior |
 | --- | --- |
-| `onthego init` | Register the current Git repository, create its stable `.onthego.yaml` identity, and add local-only paths to `.gitignore`. |
-| `onthego login` | Authenticate this device with the ONTHEGO control plane. |
-| `onthego pass` | Collect project sessions, redact them locally, create the handoff, and start `agent-sync` in Daytona. |
-| `onthego status` | Refresh the latest Daytona run and redacted logs, synchronize state, and generate a concise summary. |
-| `onthego pull` | Download the latest result after receipt and SHA-256 verification. |
+| Git history | Missing objects travel in a negotiated bundle. GitHub is optional. |
+| Staged and unstaged work | Temporary Git trees preserve their distinction, binary content, and executable bits. |
+| Untracked project files | Included subject to project exclusions and the secret policy. |
+| Ignored files | Include explicitly with `--include` or project policy. |
+| Secret candidates such as `.env` | Excluded and reported; eligible files require `--include-secret`. |
+| Codex and Claude histories | Recent project sessions by default; path values are remapped without rewriting conversation content. |
+| Destination Git configuration and hooks | Preserved in place, together with remotes, reflogs, and existing stashes. |
+| Destination caches and local dependencies | Left in place when they are outside the managed file set. |
+| Agent logins, global databases, and running processes | Not transferred. Authenticate and run the agent separately on each device. |
+
+Native transcripts may contain sensitive prompts or tool output. ONTHEGO preserves them inside an encrypted package for resumability. All tracked Git content and history also travel as recorded, including anything previously committed. Supplemental secret-file rules cannot remove secrets from Git history.
+
+## Sessions and conflicts
+
+The default selection is sessions active in the last seven days. Choose a narrower or broader set explicitly:
+
+```sh
+onthego push laptop --session <id>
+onthego push laptop --session-days 2
+onthego push laptop --all-sessions
+onthego pull laptop --no-sessions
+onthego pull laptop --session-conflict skip
+```
 
-Every public command supports schema-versioned JSON output:
+Malformed completed JSONL lines exclude that session with a warning. An incomplete final line is discarded with a warning. These histories do not stop the workspace handoff. An explicitly requested ID that cannot be found fails before packaging. `--no-sessions` skips session discovery and leaves receiving agent homes untouched.
 
-```bash
-onthego status --json
-onthego pull --output ./handoff-result.md --json
-```
+Identical sessions are skipped. Incoming extensions update an older destination, while a newer destination is kept. Divergent sessions keep the destination and save the incoming history in private `~/.onthego/conflicts/` storage by default. `--session-conflict keep-both`, `--session-conflict theirs`, and `--session-conflict skip` make the policy explicit. Conflict copies remain until you review and remove them. Plaintext staging copies are removed after import. If an adapter cannot write its destination, the workspace still arrives and its authenticated inbound histories are retained in a private `session-recovery-*` directory under ONTHEGO state. The warning prints its location. `status` reports pending recovery. Retry the same package or run `onthego sessions recover --session-conflict keep-both` to import only the saved sessions while preserving subsequent workspace edits. JSON reports `sessions.status: "recovery_needed"` until recovery succeeds. The deprecated `--sessions` alias still works and warns; it only chooses a conflict policy.
 
-## How It Works
-
-```mermaid
-flowchart LR
-    A[Codex] --> E[Project session discovery]
-    B[Cursor] --> E
-    C[Hermes] --> E
-    D[Claude] --> E
-    E --> F[Local redaction]
-    F --> G[Context envelope and HANDOFF.md]
-    G --> H[Daytona agent-sync]
-    H --> I[Redacted logs and run receipt]
-    I --> J[ONTHEGO control plane]
-    J --> K[Authenticated devices]
-    I --> L[SHA-256 verified pull]
+Concurrent workspace edits require a deliberate decision. ONTHEGO checks Git handoff ancestry and the destination's captured workspace state. `--replace` applies incoming managed files after retaining a Git backup; a different project ID is always rejected.
+
+```sh
+onthego backups list
+onthego undo
+onthego backups prune --keep 3
 ```
 
-### 1. Scope by project
+The newest five Git backups are retained automatically. Explicitly included supplemental secrets stay outside Git objects; their backup contents are encrypted under the private ONTHEGO state directory. Unmanaged `node_modules`, caches, and local environment files are not copied into backups. Undo restores the backed-up managed state and clears the delivery baseline, since restoring old work does not prove that another device has received it. Backup listing, pruning and undo remain available even if `.onthego.yaml` is missing or invalid. Use Git to reconcile intentional concurrent development.
 
-ONTHEGO uses the Git root as the trust and discovery boundary. It scans the local storage used by Codex, Cursor, Hermes, and Claude, then keeps only sessions associated with that project.
+## Configuration
 
-### 2. Redact before transfer
+Commit the project policy `.onthego.yaml`:
 
-Raw sessions stay local. Before an envelope leaves the machine, ONTHEGO filters common API keys, bearer tokens, private keys, secret assignments, and opaque encrypted agent payloads. The envelope records source hashes and byte ranges so the handoff remains auditable without exposing local paths.
+```yaml
+schema_version: 2
+project_id: generated-by-onthego-init
+include:
+  - .onthego.yaml
+exclude:
+  - .git
+  - .onthego.local
+  - node_modules
+  - vendor
+  - dist
+  - build
+  - .cache
+  - __pycache__
+agent: auto
+```
 
-### 3. Run in isolation
+`agent` accepts `auto`, `codex`, `claude`, or `none`. `none` performs workspace-only handoffs.
 
-The official Daytona Go SDK creates or selects a sandbox, uploads the redacted context, and starts an ONTHEGO-owned process session. The default CPU-only `agent-sync` workload returns `HANDOFF.md` and can be replaced with a project-defined workload in `.onthego.yaml`.
+Personal configuration and pinned identities live in `~/.onthego/config.yaml`. Private ONTHEGO keys live in `~/.onthego/identity/keys.json`. Private directories use mode `0700` and files use `0600`. `ONTHEGO_HOME` optionally selects a different state directory. ONTHEGO never automatically loads `.env` files.
 
-### 4. Resume with proof
+```sh
+onthego config path
+onthego device list
+onthego identity
+onthego push laptop --include scratch/notes.txt
+onthego push laptop --include-secret .env
+```
 
-`onthego status` combines local Git state with remote run state. `onthego pull` refuses results with a missing or mismatched SHA-256 receipt, so an unverified artifact never becomes the local handoff.
+Explicitly selected files remain managed across subsequent handoffs, including deletions. Do not opt in credentials that must stay device-local. Adding a managed supplemental file to `exclude` stops future transfer and leaves the receiving copy in place with a warning. Source deletions still propagate. Project exclusions override previously remembered secret selections; explicitly combining an excluded path with `--include-secret` fails.
 
-## Security Model
+Credential filenames such as `.npmrc` and `.netrc` are excluded from automatic selection. `--include-secret .npmrc` carries an allowed file in the encrypted supplemental payload, outside Git objects. Names such as `tokenizer.ts`, `docs-secret-santa.md`, and `design.key` are ordinary project files, not secret candidates.
 
-| Boundary | Protection |
-| --- | --- |
-| Project | Session discovery is limited to the current Git repository. |
-| Secrets | The root `.env` must not be accessible by group or other users and is never tracked. |
-| Transfer | Session content is redacted locally before upload. |
-| Control plane | TLS is pinned by certificate SHA-256 fingerprint. |
-| State | Authenticated generation checks reject stale writes. |
-| Results | Remote artifacts are accepted only when their SHA-256 hash matches the receipt. |
-| Snapshots | Portable `.otg` snapshots use age X25519 encryption and Ed25519 signatures. |
+## Portable snapshots
 
-`onthego init` always keeps `AGENTS.md`, `.agents/`, `.env`, `.onthego.local/`, `HANDOFF.md`, and `*.otg` out of Git. Device login sessions are stored outside the repository with `0600` permissions.
+For removable storage or another delivery channel, create an encrypted `.otg` file:
 
-## Project Configuration
+```sh
+onthego snapshot pack --output /tmp/project.otg --recipient age1...
 
-`onthego init` creates a safe, trackable `.onthego.yaml`. It contains the project identity and workload policy, never secret values. Re-running `init` preserves the existing project ID.
+# On the receiving device:
+onthego snapshot restore /tmp/project.otg \
+  --output /path/to/project \
+  --signing-public <trusted-source-public-key>
+```
 
-The default workload is deliberately small:
+Use the recipient and signing public keys printed by `onthego identity`. Without `--recipient`, packing targets the local device. SSH handoffs resolve both identities from pairing; offline restores require you to authenticate the source signing key.
 
-```yaml
-workloads:
-  agent-sync:
-    kind: agent
-    image: debian:bookworm-slim
-    gpu_count: 0
-    argv:
-      - /bin/sh
-      - -lc
-      - cp ../context/HANDOFF.md ./HANDOFF.md
-    output_path: HANDOFF.md
-    timeout_seconds: 600
-```
+Offline exports retain pending receipts for up to 30 days, bounded to 64 per workspace. A returning descendant can acknowledge this lineage without `--replace`. Retrying an already applied snapshot succeeds without overwriting later local edits.
 
-The CLI reads `.env` from the current directory up to the Git root. Existing process environment values take precedence over file values. Daytona also accepts `DAYTONA_JWT_TOKEN` as an alternative to `DAYTONA_API_KEY`.
+## Commands
 
-## Platform Support
+| Command | Purpose |
+| --- | --- |
+| `init` | Initialize project policy. |
+| `device add/list/remove` | Pair and manage devices. |
+| `remote set` | Manage project paths on those devices. |
+| `push`, `pull` | Hand off a workspace and selected histories. |
+| `status [device]` | Inspect changes and active-device guidance. |
+| `inspect` | Preview file selection and excluded secret candidates. |
+| `doctor [device]` | Check prerequisites, CLI versions, and optional peer access. |
+| `snapshot pack/restore` | Create or receive an offline package. |
+| `sessions recover` | Retry saved native histories without changing the workspace. |
+| `backups list/prune`, `undo` | Inspect, limit, or restore Git backups. |
+| `identity`, `config path`, `version` | Inspect public identity and installation. |
+
+Text output escapes control characters in filenames and session IDs. Suggested commands for these unusual names use Bash/Zsh quoting. `--json` emits structured results and errors. `--verbose` reports transfer phases on stderr. Dry-run validates local options and previews files plus selected sessions. Its `not_checked` field lists `peer` and `destination_conflict`.
+
+| Exit status | Public error codes |
+| --- | --- |
+| 0 | Success, including delivered workspaces with pending session recovery |
+| 1 | `E_INTERNAL` |
+| 2 | `E_INPUT` |
+| 3 | `E_PRECONDITION`, `E_UNSUPPORTED_GIT`, `E_SECRET_POLICY`, `E_SESSION_FORMAT` |
+| 4 | `E_TARGET_AUTH`, `E_TARGET_UNAVAILABLE` |
+| 5 | `E_PACKAGE_INVALID`, `E_RESTORE_FAILED` |
+| 6 | `E_GENERATION_CONFLICT`, `E_SOURCE_CHANGED` |
+| 130 | `E_CANCELED` |
 
-The npm package currently ships prebuilt binaries for:
+## Upgrading to 0.3.1
 
-- macOS on Apple silicon (`darwin-arm64`)
-- Linux on x86-64 (`linux-x64`)
+Upgrade both devices together. Snapshot schema 3 adds signed `retained_paths` and `payload_sizes`; 0.3.1 reads schema 2 and 3, while older receivers reject schema 3. Peer transfers require the `snapshot-v3` and `session-scope` capabilities. Project policy and handoff receipt schemas remain 2; session recovery uses a separate state file.
 
-Node.js 18 or newer is required for the npm launcher. Building from source requires Go 1.25.4 or newer.
+If you transferred an untracked credential file such as `.npmrc` with 0.3.0 or earlier, rotate its tokens. Those bytes can remain in the source and receiving repositories' Git objects through retained WIP history. This update prevents new automatic capture but does not remove existing objects; Git garbage collection alone does not remove referenced history. See the [0.3.1 release notes](docs/releases/0.3.1.md).
 
 ## Development
 
-```bash
-git clone https://github.com/jbaehova/onthego.git
-cd onthego
+```sh
 make check
+go test -race ./...
 make build
-```
-
-Useful project commands:
-
-```bash
-make test
 ./scripts/demo.sh
-go run ./cmd/onthego --help
-go run ./cmd/onthego-server
-```
-
-The release workflow tests and vets the Go code, builds static Linux amd64 and macOS arm64 binaries, scans the npm package for local or secret files, publishes with npm provenance, and attaches checksummed binaries to the GitHub release.
-
-## Repository Layout
-
-```text
-cmd/                  CLI and control plane entry points
-internal/             capture, redaction, transport, state, and verification
-npm/                  cross-platform npm launcher and packaged binaries
-deploy/contabo/       hardened systemd service for the control plane
-docs/                 architecture, demo, pitch, and progress notes
-scripts/              local demo workflow
+./scripts/ssh-e2e.sh
+make package
 ```
 
-## Roadmap
-
-The five-command agent handoff is the supported Phase 1 contract. GPU fine-tuning, GPU model serving, and Hugging Face model and dataset connectors are active backlog items and are not presented as production features yet.
+The tests and demos isolate project and agent homes. The SSH script uses a real temporary OpenSSH server. See [validation and feedback coverage](docs/progress.md), [architecture](docs/architecture.md), and [migration](docs/migration.md).
 
-Follow the implementation record in [docs/progress.md](docs/progress.md).
+This is an explicit handoff tool. Continuous synchronization and user-owned asynchronous storage adapters remain future work.
 
 ## License
 
-MIT. See [LICENSE](LICENSE).
+[MIT](LICENSE).

package/npm/bin/onthego.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 
-const { spawnSync } = require("node:child_process");
+const { spawn } = require("node:child_process");
 const { existsSync } = require("node:fs");
 const path = require("node:path");
 
 const supported = new Map([
   ["darwin-arm64", "onthego-darwin-arm64"],
+  ["darwin-x64", "onthego-darwin-amd64"],
   ["linux-x64", "onthego-linux-amd64"],
+  ["linux-arm64", "onthego-linux-arm64"],
 ]);
 
 const platform = `${process.platform}-${process.arch}`;
@@ -22,13 +24,39 @@ if (!existsSync(binary)) {
   process.exit(1);
 }
 
-const result = spawnSync(binary, process.argv.slice(2), {
+const child = spawn(binary, process.argv.slice(2), {
   stdio: "inherit",
   env: process.env,
+  // Supported platforms are POSIX. A separate group prevents a terminal or
+  // group signal from reaching the child both directly and via forwarding.
+  // Keep the child referenced so this launcher always waits for cleanup.
+  detached: true,
 });
 
-if (result.error) {
-  process.stderr.write(`${result.error.message}\n`);
-  process.exit(1);
+const handlers = new Map();
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  const forward = () => child.kill(signal);
+  handlers.set(signal, forward);
+  process.on(signal, forward);
+}
+
+function removeHandlers() {
+  for (const [signal, handler] of handlers) {
+    process.removeListener(signal, handler);
+  }
 }
-process.exit(result.status ?? 1);
+
+child.once("error", (error) => {
+  removeHandlers();
+  process.stderr.write(`${error.message}\n`);
+  process.exit(1);
+});
+
+child.once("exit", (code, signal) => {
+  removeHandlers();
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 1);
+});

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@jbaehova/onthego",
-  "version": "0.1.3",
-  "description": "Carry agent context and work between local projects and Daytona sandboxes",
+  "version": "0.3.1",
+  "description": "Open-source workspace and coding-agent session handoffs between your own devices",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/jbaehova/onthego.git"
+    "url": "git+https://github.com/peerproblem/onthego.git"
   },
-  "homepage": "https://github.com/jbaehova/onthego#readme",
+  "homepage": "https://github.com/peerproblem/onthego#readme",
   "bugs": {
-    "url": "https://github.com/jbaehova/onthego/issues"
+    "url": "https://github.com/peerproblem/onthego/issues"
   },
   "bin": {
     "onthego": "npm/bin/onthego.js"
@@ -17,6 +17,8 @@
   "files": [
     "npm/bin/onthego.js",
     "npm/vendor/onthego-darwin-arm64",
+    "npm/vendor/onthego-darwin-amd64",
+    "npm/vendor/onthego-linux-arm64",
     "npm/vendor/onthego-linux-amd64",
     "README.md",
     "LICENSE"
@@ -27,7 +29,10 @@
   "scripts": {
     "demo": "./scripts/demo.sh",
     "prepack": "node npm/scripts/verify-package.mjs",
-    "test": "go test ./..."
+    "test": "go test ./...",
+    "test:e2e": "./scripts/ssh-e2e.sh",
+    "test:interrupt": "python3 scripts/sigint-e2e.py",
+    "benchmark": "python3 scripts/benchmark.py"
   },
   "publishConfig": {
     "access": "public",