trajectories 0.0.0 → 0.1.2

package/legacy/src/writer-lease.ts

@@ -0,0 +1,310 @@
+import { existsSync, renameSync, statSync } from "node:fs";
+import { Database } from "bun:sqlite";
+import { ensurePrivateDatabase } from "./private-storage.js";
+
+/**
+ * Cross-process writer arbitration for one store.
+ *
+ * The lease is a sibling SQLite database (`<dbPath>-write.lock`) whose write
+ * lock *is* the lease: a holder commits its label, then keeps an uncommitted
+ * `BEGIN IMMEDIATE` transaction open for the lease lifetime. Process death
+ * releases it by descriptor teardown, so there is no TTL, no lease row
+ * expiry, and no reaper. The lock file is never unlinked — unlink plus
+ * recreate splits the inode and hands two writers the same "exclusive" lock.
+ * It holds no user data: deleting it while no writer runs is a safe repair,
+ * and an unreadable one is renamed aside automatically.
+ */
+
+/** Bounded wait before a contended writer refuses. */
+export const DEFAULT_WRITER_LEASE_WAIT_MS = 250;
+/** Busy retry spacing; the attempt budget is derived from it. */
+export const WRITER_LEASE_RETRY_MS = 25;
+
+const LEASE_TABLE = "lease_state";
+const LEASE_TABLE_SQL = `CREATE TABLE IF NOT EXISTS ${LEASE_TABLE} (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  holder TEXT NOT NULL,
+  pid INTEGER NOT NULL,
+  started_at TEXT NOT NULL
+)`;
+
+/** Label committed by the process that currently holds the lease. */
+export interface WriterLeaseMetadata {
+  holder: string;
+  pid: number;
+  started_at: string;
+}
+
+export interface WriterLease {
+  /** Sibling lock database holding the lease. */
+  readonly lockPath: string;
+  /** Label this holder committed when it took the lease. */
+  readonly metadata: WriterLeaseMetadata;
+  /** Idempotent release: rollback the held transaction, then close. */
+  close(): void;
+}
+
+export interface WriterLeaseOptions {
+  /** Bounded wait for a contended lease; `0` tries once (default 250 ms). */
+  waitMs?: number;
+  /** Verb or service class recorded in the lease label. */
+  holder: string;
+}
+
+/** Lease path derived from the store path; a sibling, never the store itself. */
+export function writerLockPath(dbPath: string): string {
+  return `${dbPath}-write.lock`;
+}
+
+/**
+ * In-memory stores are process-local: there is no file to derive a lock from and
+ * no other process to arbitrate with, so writers skip the lease. Only SQLite's
+ * URI forms count — `:memory:`, `file::memory:…`, and a `file:` URI whose query
+ * asks for `mode=memory` — never a filename that merely contains those words.
+ */
+export function isMemoryStorePath(dbPath: string): boolean {
+  if (dbPath === ":memory:" || dbPath.startsWith("file::memory:")) return true;
+  if (!dbPath.startsWith("file:") || !dbPath.includes("?")) return false;
+  return new URLSearchParams(dbPath.slice(dbPath.indexOf("?"))).get("mode") === "memory";
+}
+
+/** Attempts for a wait budget: one immediate try plus one per retry slot. */
+export function writerLeaseAttempts(waitMs: number, retryMs = WRITER_LEASE_RETRY_MS): number {
+  return waitMs > 0 ? Math.ceil(waitMs / Math.max(1, retryMs)) + 1 : 1;
+}
+
+/**
+ * Human label for a peer's lease, used by every refusal and skip message. A null
+ * label means the peek could not read one (no holder ever committed one, or the
+ * lock database was unreadable under contention) — say exactly that instead of a
+ * vague "unknown".
+ */
+export function describeLeaseHolder(holder: WriterLeaseMetadata | null): string {
+  return holder ? `pid ${holder.pid}, holder ${holder.holder}` : "holder unknown (label unavailable)";
+}
+
+/** Typed refusal: another process holds the store and this writer may not take it. */
+export class WriterLeaseBusyError extends Error {
+  readonly code = "WRITER_BUSY";
+  readonly lockPath: string;
+  /** Current label from the lock database, when it was readable. */
+  readonly holder: WriterLeaseMetadata | null;
+
+  constructor(lockPath: string, holder: WriterLeaseMetadata | null, message?: string) {
+    super(
+      message ??
+      `store is held by another writer (${describeLeaseHolder(holder)}); ` +
+        "retry shortly or stop the scheduled ledger service",
+    );
+    this.name = "WriterLeaseBusyError";
+    this.lockPath = lockPath;
+    this.holder = holder;
+  }
+}
+
+/**
+ * Take the writer lease for `dbPath`, waiting up to `waitMs` for a busy peer.
+ * Busy failures retry inside that budget; an unreadable lock database is
+ * quarantined once and retried; every other failure propagates as-is.
+ */
+export function acquireWriterLease(dbPath: string, options: WriterLeaseOptions): WriterLease {
+  const lockPath = writerLockPath(dbPath);
+  const waitMs = Math.max(0, options.waitMs ?? DEFAULT_WRITER_LEASE_WAIT_MS);
+  const attempts = writerLeaseAttempts(waitMs);
+  const startedAt = Date.now();
+  let repaired = false;
+
+  for (let attempt = 1; ; attempt++) {
+    let db: Database | null = null;
+    let metadata: WriterLeaseMetadata | null = null;
+    let failure: unknown = null;
+    try {
+      db = openLockDatabase(lockPath);
+      if (beginImmediate(db)) metadata = holdLease(db, options.holder);
+    } catch (error) {
+      failure = error;
+    }
+    if (metadata && db) return heldWriterLease(db, lockPath, metadata);
+    db?.close();
+    if (failure && !isBusyError(failure)) {
+      // Only a lock database that is not a SQLite database at all is safe to
+      // rename aside; every other failure class fails closed (see below).
+      if (isNotADatabaseError(failure) && !repaired && quarantineLockDatabase(lockPath)) {
+        repaired = true;
+        continue;
+      }
+      throw failure;
+    }
+    const remaining = waitMs - (Date.now() - startedAt);
+    if (attempt >= attempts || remaining <= 0) break;
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.min(WRITER_LEASE_RETRY_MS, remaining));
+  }
+  throw new WriterLeaseBusyError(lockPath, readWriterLease(dbPath));
+}
+
+/**
+ * Best-effort peek at the committed lease label. It answers while another
+ * process holds the lease (readers do not conflict with the held RESERVED
+ * lock) and returns null when no holder committed a readable label.
+ */
+export function readWriterLease(dbPath: string): WriterLeaseMetadata | null {
+  const lockPath = writerLockPath(dbPath);
+  if (!existsSync(lockPath)) return null;
+  let db: Database;
+  try {
+    db = new Database(lockPath, { readonly: true });
+    // The label must be readable while another process holds the lease: without
+    // this, a reader that meets a writer's commit fails and reports "holder
+    // unknown" at exactly the moment the label matters.
+    db.exec("PRAGMA busy_timeout = 250");
+  } catch {
+    return null;
+  }
+  try {
+    const row = db.query(`SELECT holder, pid, started_at FROM ${LEASE_TABLE} WHERE id = 1`).get() as
+      | { holder: unknown; pid: unknown; started_at: unknown }
+      | null;
+    if (!row || typeof row.holder !== "string" || !Number.isSafeInteger(row.pid) ||
+      typeof row.started_at !== "string") {
+      return null;
+    }
+    return { holder: row.holder, pid: row.pid as number, started_at: row.started_at };
+  } catch {
+    // A fresh, empty, or conflicting lock database has no readable label yet.
+    return null;
+  } finally {
+    db.close();
+  }
+}
+
+function openLockDatabase(lockPath: string): Database {
+  ensurePrivateDatabase(lockPath);
+  const db = new Database(lockPath);
+  // Disable SQLite's own wait loop: the caller's clock and attempt budget are
+  // the only timeouts in play.
+  db.exec("PRAGMA busy_timeout = 0");
+  return db;
+}
+
+/**
+ * Called while holding the write lock: commit the label, then take the
+ * uncommitted transaction that the lease actually is. Returns null when a
+ * contender won the commit-to-hold gap, which is a busy attempt, not a lease.
+ */
+function holdLease(db: Database, holder: string): WriterLeaseMetadata | null {
+  const metadata: WriterLeaseMetadata = { holder, pid: process.pid, started_at: new Date().toISOString() };
+  try {
+    db.exec(LEASE_TABLE_SQL);
+    // Row id=1 is the single label slot: a stale label (a killed holder, a
+    // skipped clear) must be replaced, never collide with this holder.
+    db.query(`INSERT OR REPLACE INTO ${LEASE_TABLE} (id, holder, pid, started_at) VALUES (1, ?, ?, ?)`)
+      .run(metadata.holder, metadata.pid, metadata.started_at);
+    db.exec("COMMIT");
+  } catch (error) {
+    // The label is bookkeeping, the lock is the lease: keep holding either way.
+    try {
+      db.exec("ROLLBACK");
+    } catch {
+      // Closing the connection releases any remaining SQLite lock.
+    }
+    if (isBusyError(error)) throw error;
+    console.error(
+      "[ledger] writer lease label unavailable " +
+      `(${error instanceof Error ? error.message : String(error)}); holding the store unlabelled`,
+    );
+  }
+  if (beginImmediate(db)) return metadata;
+  // A contender slipped into the commit-to-hold gap: drop our own label and
+  // report a busy attempt instead of a half-held lease.
+  clearLeaseLabel(db, metadata.pid);
+  return null;
+}
+
+function heldWriterLease(db: Database, lockPath: string, metadata: WriterLeaseMetadata): WriterLease {
+  let released = false;
+  return {
+    lockPath,
+    metadata,
+    close(): void {
+      if (released) return;
+      released = true;
+      try {
+        db.exec("ROLLBACK");
+      } catch {
+        // Closing the connection releases any remaining SQLite lock.
+      }
+      // Best-effort: drop our own label so a later peek does not name a
+      // released holder. A successor's label is never touched.
+      clearLeaseLabel(db, metadata.pid);
+      db.close();
+    },
+  };
+}
+
+/**
+ * Drop the label only when it is still this process's own: an unconditional
+ * delete would erase the label a successor just committed, leaving contended
+ * refusals unable to name a holder.
+ */
+function clearLeaseLabel(db: Database, pid: number): void {
+  try {
+    if (!beginImmediate(db)) return;
+    db.query(`DELETE FROM ${LEASE_TABLE} WHERE id = 1 AND pid = ?`).run(pid);
+    db.exec("COMMIT");
+  } catch {
+    // Bookkeeping only: the lock, not the label, is the lease.
+  }
+}
+
+/**
+ * Rename an unreadable lock database aside so it cannot wedge every writer
+ * forever. The bytes are kept for inspection, the path is never unlinked, and
+ * only a regular file is touched.
+ *
+ * Renaming is safe *because* of how narrow the caller keeps the condition: only
+ * SQLITE_NOTADB (the path is not a SQLite database at all) reaches here. A peer
+ * that genuinely holds the lease necessarily holds a valid SQLite write lock on
+ * a valid database file, so a NOTADB path cannot be a live hold and this rename
+ * cannot split one live inode between two holders. Every ambiguous failure —
+ * permissions, I/O errors, an unexpected path type, any other open failure —
+ * fails closed instead: the caller rethrows it untouched and never renames.
+ */
+function quarantineLockDatabase(lockPath: string): boolean {
+  const target = `${lockPath}.corrupt-${Date.now()}`;
+  try {
+    if (!statSync(lockPath).isFile()) return false;
+    renameSync(lockPath, target);
+  } catch {
+    return false;
+  }
+  console.error(
+    `[ledger] writer lease lock database is not a SQLite database; ` +
+    `quarantined as ${target} and retried`,
+  );
+  return true;
+}
+
+function beginImmediate(db: Database): boolean {
+  try {
+    db.exec("BEGIN IMMEDIATE");
+    return true;
+  } catch (error) {
+    if (isBusyError(error)) return false;
+    throw error;
+  }
+}
+
+function isBusyError(error: unknown): boolean {
+  const code = (error as { code?: unknown } | null | undefined)?.code;
+  if (typeof code === "string" && code.startsWith("SQLITE_BUSY")) return true;
+  const message = error instanceof Error ? error.message : String(error);
+  return /SQLITE_BUSY|database is locked|database is busy/i.test(message);
+}
+
+/** The one failure class that proves no valid holder can be using this file. */
+function isNotADatabaseError(error: unknown): boolean {
+  const code = (error as { code?: unknown } | null | undefined)?.code;
+  if (code === "SQLITE_NOTADB") return true;
+  const message = error instanceof Error ? error.message : String(error);
+  return /file is not a database|file is encrypted or is not a database/i.test(message);
+}

package/ops/README.md

@@ -0,0 +1,150 @@
+# Trajectories installation and scheduled indexing
+
+These operations port Ledger's CLI and OS-supervised bounded lexical sync.
+CLI and release installation leave the existing database and native histories
+unchanged. Scheduled native sync remains separate from indexing a managed
+session/log store, which requires an explicit `index --store` command.
+
+## Install the CLI
+
+### Native CLI
+
+Native releases require no Bun, Node or npm. The repository is currently private,
+so GitHub downloads require an authenticated `gh` client with repository access.
+On an Apple Silicon Mac:
+
+```sh
+gh release download 'trajectories@0.1.2' --repo archeism/oh-my-ai \
+  --pattern 'trajectories-0.1.2-darwin-arm64.tar.gz*'
+shasum -a 256 --check trajectories-0.1.2-darwin-arm64.tar.gz.sha256
+mkdir -p "$HOME/.local/share/trajectories/native"
+tar -xzf trajectories-0.1.2-darwin-arm64.tar.gz -C "$HOME/.local/share/trajectories/native"
+bash "$HOME/.local/share/trajectories/native/trajectories-0.1.2-darwin-arm64/install.sh"
+trajectories --version
+```
+
+On Linux, choose `linux-x64` or `linux-arm64`, and use `sha256sum --check`.
+The installer refuses existing commands unless `--force` explicitly authorizes
+replacement. It creates a symlink to the retained release directory; do not
+delete that directory or separate the executable from `lib/`. It does not change
+the search database or enable an indexing service. Ensure `~/.local/bin` is on PATH.
+Local ONNX inference requires glibc 2.28+ on Linux or macOS 14+ on Apple Silicon. Deep Agents SQLite conversion
+still uses the harness's own Python/LangGraph environment.
+
+The service installers below are for source/npm installations and invoke Bun.
+For a native service, its command is the installed `trajectories sync` executable
+directly; the CLI's bounded sync and scheduler protocol are unchanged.
+
+### npm or source CLI
+
+For the npm distribution, use Bun 1.4.2 or newer:
+
+```sh
+bun add --global trajectories@0.1.2
+trajectories --version
+trajectories status --robot
+```
+
+Put Bun's global bin directory on PATH (`bun pm bin -g`). Packaged `ops/` and
+`skills/` live under `~/.bun/install/global/node_modules/trajectories`
+with the default Bun layout; resolve the installed package location before
+using its OS service installers. The Git-only `install-release.sh` below is
+for source checkouts, not npm installations.
+
+Use Bun 1.4.2 or newer. From a monorepo checkout with dependencies installed and the SDK built:
+
+```sh
+bun install --frozen-lockfile
+bun run --cwd packages/trajectories build
+bash packages/trajectories/ops/install-cli.sh --bin-dir "$HOME/.local/bin"
+trajectories status --json
+```
+
+This creates a worktree-following `trajectories` wrapper. Existing unrelated
+executables are refused unless `--force` is supplied. `TRAJECTORIES_BUN` and
+`TRAJECTORIES_BIN_DIR` override Bun and the target directory; their `LEDGER_*`
+equivalents remain fallback inputs. Installation leaves the `ledger` executable
+and any running Ledger service untouched.
+The wrapper prefers the checkout's `src/cli.ts`; a packed package uses
+`dist/cli.js`. The service installers use the same entrypoint selection.
+Both require `dist/index.js`: the source search/managed-session commands load
+the built SDK. An unbuilt checkout fails before writing a wrapper or service
+definition, with an explicit build command. Installers do not build silently.
+Rebuild after changing SDK source.
+
+For reviewed committed bytes, rather than the live worktree:
+
+```sh
+bash packages/trajectories/ops/install-release.sh REVIEWED_COMMIT --bin-dir "$HOME/.local/bin"
+```
+
+The release gate uses Bun 1.4.2 and stores a full reviewed monorepo archive under
+`${TRAJECTORIES_RELEASES_DIR:-${XDG_DATA_HOME:-~/.local/share}/trajectories/releases}/COMMIT`.
+`LEDGER_RELEASES_DIR` remains a fallback. At the audited `7eecb3b` checkpoint the
+tracked archive was approximately 126 MB; dependencies are additional. The root
+frozen lockfile refers to other workspace manifests and the patched Letta
+dependency, so the reviewed archive retains them. The install filters to the
+Trajectories dependency graph with lifecycle scripts disabled, then builds only
+Trajectories. Unrelated root postinstall builds do not run. This is a source
+release path; npm installation uses the separately packed package.
+
+Release publication is atomic after dependency installation and build. An
+incomplete, foreign, or symlink release directory is refused. The commit marker
+must match the directory's resolved commit. Reinstallation reuses a completed
+release; do not modify its files. The installer never enables a service.
+
+## Scheduled local indexing
+
+Keep the original database path during cutover:
+
+```sh
+export TRAJECTORIES_DB="$HOME/.local/share/ledger/ledger.sqlite"
+trajectories status --json
+trajectories sync --robot
+```
+
+The database is `TRAJECTORIES_DB`, then `LEDGER_DB`, then
+`${XDG_DATA_HOME:-~/.local/share}/ledger/ledger.sqlite`. `TRAJECTORIES_DATA_DIR`
+(`LEDGER_DATA_DIR` fallback) changes the fallback directory. Managed sessions
+under `TRAJECTORIES_HOME` are a separate store.
+
+Stop the previous Ledger writer before enabling a replacement against that
+database. The installers operate only on the new Trajectories unit/label and
+do not stop the old one for you.
+
+The first writable `sync` can upgrade a compatible older search database to
+schema 16. Preserve one consistent SQLite backup before that cutover: read-only
+commands serve schema 15 without upgrading it, but the old Ledger writer cannot
+write the upgraded database. The [Mac cutover receipt](../evidence/mac-cutover-2026-10-07/README.md)
+records a restored schema-15 rollback and the observed writer migration.
+
+```sh
+# Linux: writes private units and reloads systemd; default does not enable them.
+bash packages/trajectories/ops/linux/install-systemd-user.sh --write-only
+systemctl --user cat archeism-trajectories.service archeism-trajectories.timer
+# After inspecting the definition and one bounded manual pass:
+bash packages/trajectories/ops/linux/install-systemd-user.sh --enable-now
+
+# macOS: writes private logs/plist and enables the 15-minute RunAtLoad job.
+bash packages/trajectories/ops/macos/install-launchd.sh
+```
+
+The Linux installer reads `${TRAJECTORIES_ENV_FILE:-${LEDGER_ENV_FILE:-${XDG_CONFIG_HOME:-~/.config}/ledger/daemon.env}}`
+when present. On both systems, every `TRAJECTORIES_*` sync setting takes
+precedence over the equivalent `LEDGER_*` setting. Defaults retain Ledger's
+availability bounds: 25 sessions, 64 MiB source work, 120-second pass, three
+retries, eight attempts/session, 8 MiB/s aggregate reads, 30-second worker
+deadline, two Linux workers (one macOS worker), five reserved fresh sessions,
+one-hour freshness window, 1 MiB chunks, automatic pressure response,
+five-second maintenance and 64 FTS merge pages. Defaults cover all 18 current
+history readers. `ops/sync-settings.sh` lists the exact setting names.
+
+The supervised command is lexical `sync` every 15 minutes, with no restart
+loop. Linux also sets 1 GiB memory, 50% CPU and 16-task limits. The retained
+engine intentionally receives `LEDGER_SCHEDULER=1` so scheduled passes yield
+to another writer. Foreground `watch` remains available; it is not the service
+command. Pending work is retained for later passes, rather than treated as a
+complete archive.
+
+Fixtures exercise temporary homes, fake OS supervisors and synthetic databases;
+tests never install real units or modify the global CLI.

package/ops/install-cli.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Install a worktree-following trajectories wrapper. Does not install dependencies
+# or enable services. Usage: ops/install-cli.sh [--bin-dir DIR] [--force]
+set -euo pipefail
+
+SOURCE="${BASH_SOURCE[0]}"
+while [[ -h "$SOURCE" ]]; do
+  DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ "$SOURCE" == /* ]] || SOURCE="$DIR/$SOURCE"
+done
+PACKAGE_DIR="$(cd -P "$(dirname "$SOURCE")/.." && pwd)"
+CLI_PATH="$PACKAGE_DIR/src/cli.ts"
+[[ -f "$CLI_PATH" ]] || CLI_PATH="$PACKAGE_DIR/dist/cli.js"
+BIN_DIR="${TRAJECTORIES_BIN_DIR:-${LEDGER_BIN_DIR:-$HOME/.local/bin}}"
+FORCE=0
+usage() { echo 'Usage: install-cli.sh [--bin-dir DIR] [--force]'; }
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --bin-dir)
+      [[ $# -ge 2 && -n "$2" ]] || { echo '--bin-dir requires a directory.' >&2; exit 1; }
+      BIN_DIR="$2"; shift 2 ;;
+    --bin-dir=*)
+      BIN_DIR="${1#--bin-dir=}"
+      [[ -n "$BIN_DIR" ]] || { echo '--bin-dir requires a directory.' >&2; exit 1; }
+      shift ;;
+    --force) FORCE=1; shift ;;
+    --help|-h) usage; exit 0 ;;
+    *) echo "Unknown option: $1" >&2; usage >&2; exit 1 ;;
+  esac
+done
+[[ -f "$CLI_PATH" ]] || { echo "Trajectories CLI not found: $CLI_PATH" >&2; exit 1; }
+[[ -f "$PACKAGE_DIR/dist/index.js" ]] || {
+  printf 'Build Trajectories before installation: bun run --cwd %q build\n' "$PACKAGE_DIR" >&2
+  exit 1
+}
+BUN_BIN="${TRAJECTORIES_BUN:-${LEDGER_BUN:-$(command -v bun || true)}}"
+[[ -n "$BUN_BIN" && -x "$BUN_BIN" ]] || { echo 'Bun executable not found; set TRAJECTORIES_BUN.' >&2; exit 1; }
+mkdir -p "$BIN_DIR"
+TARGET="$BIN_DIR/trajectories"
+if [[ -e "$TARGET" || -L "$TARGET" ]]; then
+  if [[ -f "$TARGET" ]] && grep -q 'TRAJECTORIES_CLI_WRAPPER' "$TARGET" && grep -qxF "# package: $PACKAGE_DIR" "$TARGET"; then
+    :
+  elif [[ "$FORCE" == 1 && ! -d "$TARGET" ]]; then
+    echo "Replacing existing $TARGET (--force)." >&2
+  else
+    echo "Refusing to overwrite $TARGET; use --force or another --bin-dir." >&2
+    exit 1
+  fi
+fi
+TEMPORARY="$(mktemp "$BIN_DIR/.trajectories.XXXXXX")"
+trap 'rm -f "$TEMPORARY"' EXIT
+{
+  echo '#!/usr/bin/env bash'
+  echo '# TRAJECTORIES_CLI_WRAPPER v1; delete to uninstall.'
+  printf '# package: %s\n' "$PACKAGE_DIR"
+  printf 'exec %q run %q "$@"\n' "$BUN_BIN" "$CLI_PATH"
+} > "$TEMPORARY"
+chmod 755 "$TEMPORARY"
+mv -f "$TEMPORARY" "$TARGET"
+trap - EXIT
+echo "Installed trajectories CLI wrapper: $TARGET"
+case ":$PATH:" in *":$BIN_DIR:"*) ;; *) echo "Add $BIN_DIR to PATH to use trajectories." >&2 ;; esac

package/ops/install-native.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Run from an extracted native release kept in a permanent directory.
+set -euo pipefail
+RELEASE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+BIN_DIR="${TRAJECTORIES_BIN_DIR:-$HOME/.local/bin}"
+FORCE=0
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --bin-dir) [[ $# -ge 2 && -n "$2" ]] || { echo '--bin-dir requires a directory.' >&2; exit 1; }; BIN_DIR="$2"; shift 2 ;;
+    --force) FORCE=1; shift ;;
+    --help|-h) echo 'Usage: install.sh [--bin-dir DIR] [--force]'; exit 0 ;;
+    *) echo "Unknown option: $1" >&2; exit 1 ;;
+  esac
+done
+[[ -x "$RELEASE_DIR/trajectories" && -d "$RELEASE_DIR/lib" ]] || {
+  echo 'Keep install.sh, the trajectories executable, and lib/ together in the extracted release.' >&2; exit 1;
+}
+"$RELEASE_DIR/trajectories" --version
+mkdir -p "$BIN_DIR"
+TARGET="$BIN_DIR/trajectories"
+if [[ -e "$TARGET" || -L "$TARGET" ]]; then
+  if [[ -L "$TARGET" && "$(readlink "$TARGET")" == "$RELEASE_DIR/trajectories" ]]; then
+    echo "Already installed: $TARGET"; exit 0
+  fi
+  [[ "$FORCE" == 1 && ! -d "$TARGET" ]] || {
+    echo "Refusing to overwrite $TARGET; use --force for an explicit cutover." >&2; exit 1;
+  }
+fi
+STAGE="$(mktemp -d "$BIN_DIR/.trajectories-install.XXXXXX")"
+trap 'rm -rf "$STAGE"' EXIT
+ln -s "$RELEASE_DIR/trajectories" "$STAGE/trajectories"
+mv -f "$STAGE/trajectories" "$TARGET"
+echo "Installed: $TARGET"
+echo "Keep the release directory: $RELEASE_DIR"
+case ":$PATH:" in *":$BIN_DIR:"*) ;; *) echo "Add $BIN_DIR to PATH." ;; esac

package/ops/install-release.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Install a reviewed monorepo revision into a SHA-pinned directory, never the
+# live worktree. Usage: ops/install-release.sh REF [--bin-dir DIR] [--force]
+set -euo pipefail
+umask 077
+if [[ $# == 0 || "$1" == --help || "$1" == -h ]]; then
+  echo 'Usage: install-release.sh REF [--bin-dir DIR] [--force]'
+  echo 'Requires git, tar and the verified Bun 1.4.2 runtime; does not enable services.'
+  exit 0
+fi
+REF="$1"; shift
+PACKAGE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P)"
+REPO="$(git -C "$PACKAGE_DIR" rev-parse --show-toplevel)"
+BUN_BIN="${TRAJECTORIES_BUN:-${LEDGER_BUN:-$(command -v bun || true)}}"
+[[ -n "$BUN_BIN" && -x "$BUN_BIN" ]] || { echo 'Bun is required; set TRAJECTORIES_BUN.' >&2; exit 1; }
+[[ "$("$BUN_BIN" --version)" == 1.4.2 ]] || { echo 'This release gate is verified with Bun 1.4.2; use that runtime.' >&2; exit 1; }
+SHA="$(git -C "$REPO" rev-parse --verify --end-of-options "${REF}^{commit}")"
+RELEASES="${TRAJECTORIES_RELEASES_DIR:-${LEDGER_RELEASES_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/trajectories/releases}}"
+mkdir -p "$RELEASES"
+[[ ! -L "$RELEASES" ]] || { echo 'Refusing a symlink release directory.' >&2; exit 1; }
+chmod 700 "$RELEASES"
+TARGET="$RELEASES/$SHA"
+STAGE=''
+trap '[[ -z "$STAGE" ]] || rm -rf "$STAGE"' EXIT
+if [[ -e "$TARGET" || -L "$TARGET" ]]; then
+  [[ ! -L "$TARGET" && -f "$TARGET/.trajectories-release" && "$(cat "$TARGET/.trajectories-release")" == "$SHA" && -f "$TARGET/packages/trajectories/src/cli.ts" && -f "$TARGET/packages/trajectories/ops/install-cli.sh" ]] || {
+    echo "Refusing an incomplete or foreign release directory: $TARGET" >&2; exit 1;
+  }
+else
+  STAGE="$(mktemp -d "$RELEASES/.install.XXXXXX")"
+  # The root lockfile references workspace manifests and dependency patches.
+  # Preserve the reviewed monorepo, then install only Trajectories' graph.
+  git -C "$REPO" archive --format=tar "$SHA" | tar -xf - -C "$STAGE"
+  [[ -f "$STAGE/bun.lock" && -f "$STAGE/package.json" && -f "$STAGE/packages/trajectories/package.json" && -f "$STAGE/packages/trajectories/ops/install-cli.sh" ]] || {
+    echo 'Revision lacks the supported Trajectories installer and frozen monorepo lockfile.' >&2; exit 1;
+  }
+  (
+    cd "$STAGE"
+    "$BUN_BIN" install --filter trajectories --frozen-lockfile --ignore-scripts
+    cd packages/trajectories
+    "$BUN_BIN" run build
+  )
+  printf '%s\n' "$SHA" > "$STAGE/.trajectories-release"
+  [[ ! -e "$TARGET" && ! -L "$TARGET" ]] || { echo 'Another installer completed this revision; retry.' >&2; exit 1; }
+  mv "$STAGE" "$TARGET"
+  STAGE=''
+fi
+TRAJECTORIES_BUN="$BUN_BIN" bash "$TARGET/packages/trajectories/ops/install-cli.sh" "$@"
+printf 'Pinned revision: %s\nRelease directory: %s\n' "$SHA" "$TARGET"