@bli-cockpit/cli 0.1.16 → 0.1.17

package/README.md

@@ -19,7 +19,7 @@ npm install -g @bli-cockpit/cli@latest
 cockpit onboard \
   --email <APPROVED_EMAIL> \
   --device-name "$COCKPIT_DEVICE_NAME" \
-  --repo "$PWD"
+  --workspace "$PWD"
 ```
 
 If a work folder contains multiple repos, run the same command from the parent:
@@ -31,7 +31,7 @@ npm install -g @bli-cockpit/cli@latest
 cockpit onboard \
   --email <APPROVED_EMAIL> \
   --device-name "$COCKPIT_DEVICE_NAME" \
-  --repo "$PWD"
+  --workspace "$PWD"
 ```
 
 The CLI defaults to the production dashboard. Normal intern/operator setup,
@@ -39,7 +39,8 @@ updates, and syncs omit `--dashboard-url`. Pass `--dashboard-url` only for
 staging, a custom dashboard, or deliberately forcing a different dashboard
 pairing. Already-onboarded users update with
 `npm install -g @bli-cockpit/cli@latest`, then run
-`cockpit sync --repo "$PWD" --json`.
+`cockpit sync --workspace "$PWD" --json`. `--repo <path>` remains supported
+for older prompts and the Codex ticket-binding guardrail.
 
 On machines where Codex agents will do ticketed work, install the user-scope
 agent rule once:
@@ -97,7 +98,7 @@ cockpit start \
   --repo "$PWD"
 
 cockpit sync \
-  --repo "$PWD" \
+  --workspace "$PWD" \
   --json
 ```
 
@@ -149,7 +150,7 @@ repo, ticket, and raw JSONL object, see
 Local attribution preview:
 
 ```bash
-cockpit sessions --repo "$PWD" --json
+cockpit sessions --workspace "$PWD" --json
 ```
 
 Remote metadata path:

package/dist/autostart.js

@@ -126,12 +126,12 @@ async function existingWatchPaths(homeDir) {
     return candidates.filter((_, i) => present[i]);
 }
 function renderPlist(options) {
-    // The repo path is shell-quoted because it lands inside a `/bin/zsh -lc "…"`
+    // The work path is shell-quoted because it lands inside a `/bin/zsh -lc "…"`
     // command string; the whole command is then XML-escaped for the <string>.
     const dashboardArg = options.dashboardUrl === DEFAULT_DASHBOARD_URL
         ? ""
         : ` --dashboard-url ${shellQuote(options.dashboardUrl)}`;
-    const command = `cockpit sync --repo ${shellQuote(options.workDir)}${dashboardArg} --json`;
+    const command = `cockpit sync --workspace ${shellQuote(options.workDir)}${dashboardArg} --json`;
     return [
         '<?xml version="1.0" encoding="UTF-8"?>',
         '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',

package/dist/commands/local-args.js

@@ -5,6 +5,7 @@
 // Behavior-preserving extraction: functions moved verbatim, no logic change.
 import { DEFAULT_DASHBOARD_URL } from "../local-state.js";
 import { DEFAULT_AUTOSTART_INTERVAL_SECONDS } from "../autostart.js";
+const WORK_ROOT_FLAGS = ["--repo", "--workspace"];
 export function parseLocalArgs(argv) {
     const command = argv[0];
     switch (command) {
@@ -40,6 +41,7 @@ function parseOnboardArgs(args) {
         allowedFlags: [
             "--home",
             "--repo",
+            "--workspace",
             "--dashboard-url",
             "--email",
             "--device-name",
@@ -54,6 +56,7 @@ function parseOnboardArgs(args) {
         valueFlags: [
             "--home",
             "--repo",
+            "--workspace",
             "--dashboard-url",
             "--email",
             "--device-name",
@@ -69,7 +72,7 @@ function parseOnboardArgs(args) {
     return {
         kind: "onboard",
         homeDir: optionalNonEmpty(values.flags.get("--home")),
-        repoRoot: optionalNonEmpty(values.flags.get("--repo")),
+        repoRoot: optionalNonEmpty(workRootFlagValue(values)),
         dashboardUrl: normalizeUrl(values.flags.get("--dashboard-url") ?? DEFAULT_DASHBOARD_URL),
         claimedOwnerEmail: optionalEmail(values.flags.get("--email")),
         deviceName: optionalNonEmpty(values.flags.get("--device-name")),
@@ -87,17 +90,24 @@ function parseInstallArgs(args) {
         allowedFlags: [
             "--home",
             "--repo",
+            "--workspace",
             "--dashboard-url",
             "--supabase-url",
             "--json",
         ],
-        valueFlags: ["--home", "--repo", "--dashboard-url", "--supabase-url"],
+        valueFlags: [
+            "--home",
+            "--repo",
+            "--workspace",
+            "--dashboard-url",
+            "--supabase-url",
+        ],
     });
     assertNoPositionals(values.positionals, "install");
     return {
         kind: "install",
         homeDir: optionalNonEmpty(values.flags.get("--home")),
-        repoRoot: optionalNonEmpty(values.flags.get("--repo")),
+        repoRoot: optionalNonEmpty(workRootFlagValue(values)),
         dashboardUrl: normalizeUrl(values.flags.get("--dashboard-url") ?? DEFAULT_DASHBOARD_URL),
         supabaseUrl: optionalNonEmpty(values.flags.get("--supabase-url")),
         json: values.booleans.has("--json"),
@@ -152,6 +162,7 @@ function parseStartArgs(args) {
         allowedFlags: [
             "--home",
             "--repo",
+            "--workspace",
             "--branch",
             "--ticket",
             "--operator-id",
@@ -163,6 +174,7 @@ function parseStartArgs(args) {
         valueFlags: [
             "--home",
             "--repo",
+            "--workspace",
             "--branch",
             "--ticket",
             "--operator-id",
@@ -175,7 +187,7 @@ function parseStartArgs(args) {
     return {
         kind: "start",
         homeDir: optionalNonEmpty(values.flags.get("--home")),
-        repoRoot: optionalNonEmpty(values.flags.get("--repo")),
+        repoRoot: optionalNonEmpty(workRootFlagValue(values)),
         branch: optionalNonEmpty(values.flags.get("--branch")),
         activeTicketId: optionalNonEmpty(values.flags.get("--ticket")),
         operatorId: optionalNonEmpty(values.flags.get("--operator-id")),
@@ -187,14 +199,29 @@ function parseStartArgs(args) {
 }
 function parseSyncArgs(args) {
     const values = parseNamedArgs(args, {
-        allowedFlags: ["--home", "--repo", "--dashboard-url", "--json", "--max-depth", "--max-repos"],
-        valueFlags: ["--home", "--repo", "--dashboard-url", "--max-depth", "--max-repos"],
+        allowedFlags: [
+            "--home",
+            "--repo",
+            "--workspace",
+            "--dashboard-url",
+            "--json",
+            "--max-depth",
+            "--max-repos",
+        ],
+        valueFlags: [
+            "--home",
+            "--repo",
+            "--workspace",
+            "--dashboard-url",
+            "--max-depth",
+            "--max-repos",
+        ],
     });
     assertNoPositionals(values.positionals, "sync");
     return {
         kind: "sync",
         homeDir: optionalNonEmpty(values.flags.get("--home")),
-        repoRoot: optionalNonEmpty(values.flags.get("--repo")),
+        repoRoot: optionalNonEmpty(workRootFlagValue(values)),
         dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
         json: values.booleans.has("--json"),
         maxDepth: optionalPositiveInteger(values.flags.get("--max-depth"), "--max-depth"),
@@ -203,14 +230,27 @@ function parseSyncArgs(args) {
 }
 function parseStatusArgs(args) {
     const values = parseNamedArgs(args, {
-        allowedFlags: ["--home", "--repo", "--json", "--max-depth", "--max-repos"],
-        valueFlags: ["--home", "--repo", "--max-depth", "--max-repos"],
+        allowedFlags: [
+            "--home",
+            "--repo",
+            "--workspace",
+            "--json",
+            "--max-depth",
+            "--max-repos",
+        ],
+        valueFlags: [
+            "--home",
+            "--repo",
+            "--workspace",
+            "--max-depth",
+            "--max-repos",
+        ],
     });
     assertNoPositionals(values.positionals, "status");
     return {
         kind: "status",
         homeDir: optionalNonEmpty(values.flags.get("--home")),
-        repoRoot: optionalNonEmpty(values.flags.get("--repo")),
+        repoRoot: optionalNonEmpty(workRootFlagValue(values)),
         json: values.booleans.has("--json"),
         maxDepth: optionalPositiveInteger(values.flags.get("--max-depth"), "--max-depth"),
         maxRepos: optionalPositiveInteger(values.flags.get("--max-repos"), "--max-repos"),
@@ -218,8 +258,23 @@ function parseStatusArgs(args) {
 }
 function parseSessionsArgs(args) {
     const values = parseNamedArgs(args, {
-        allowedFlags: ["--home", "--repo", "--source", "--json", "--max-depth", "--max-repos"],
-        valueFlags: ["--home", "--repo", "--source", "--max-depth", "--max-repos"],
+        allowedFlags: [
+            "--home",
+            "--repo",
+            "--workspace",
+            "--source",
+            "--json",
+            "--max-depth",
+            "--max-repos",
+        ],
+        valueFlags: [
+            "--home",
+            "--repo",
+            "--workspace",
+            "--source",
+            "--max-depth",
+            "--max-repos",
+        ],
     });
     assertNoPositionals(values.positionals, "sessions");
     const source = values.flags.get("--source");
@@ -229,7 +284,7 @@ function parseSessionsArgs(args) {
     return {
         kind: "sessions",
         homeDir: optionalNonEmpty(values.flags.get("--home")),
-        repoRoot: optionalNonEmpty(values.flags.get("--repo")),
+        repoRoot: optionalNonEmpty(workRootFlagValue(values)),
         source,
         json: values.booleans.has("--json"),
         maxDepth: optionalPositiveInteger(values.flags.get("--max-depth"), "--max-depth"),
@@ -238,8 +293,8 @@ function parseSessionsArgs(args) {
 }
 function parseServeArgs(args) {
     const values = parseNamedArgs(args, {
-        allowedFlags: ["--home", "--repo", "--port"],
-        valueFlags: ["--home", "--repo", "--port"],
+        allowedFlags: ["--home", "--repo", "--workspace", "--port"],
+        valueFlags: ["--home", "--repo", "--workspace", "--port"],
     });
     assertNoPositionals(values.positionals, "serve");
     const port = Number(values.flags.get("--port") ?? "4174");
@@ -249,7 +304,7 @@ function parseServeArgs(args) {
     return {
         kind: "serve",
         homeDir: optionalNonEmpty(values.flags.get("--home")),
-        repoRoot: optionalNonEmpty(values.flags.get("--repo")),
+        repoRoot: optionalNonEmpty(workRootFlagValue(values)),
         port,
     };
 }
@@ -258,11 +313,18 @@ function parseAutostartArgs(args) {
         allowedFlags: [
             "--home",
             "--repo",
+            "--workspace",
             "--dashboard-url",
             "--interval-seconds",
             "--json",
         ],
-        valueFlags: ["--home", "--repo", "--dashboard-url", "--interval-seconds"],
+        valueFlags: [
+            "--home",
+            "--repo",
+            "--workspace",
+            "--dashboard-url",
+            "--interval-seconds",
+        ],
     });
     if (values.positionals.length > 1) {
         throw new Error("autostart accepts at most one action (install|uninstall|status).");
@@ -275,7 +337,7 @@ function parseAutostartArgs(args) {
         kind: "autostart",
         action,
         homeDir: optionalNonEmpty(values.flags.get("--home")),
-        repoRoot: optionalNonEmpty(values.flags.get("--repo")),
+        repoRoot: optionalNonEmpty(workRootFlagValue(values)),
         dashboardUrl: normalizeUrl(values.flags.get("--dashboard-url") ?? DEFAULT_DASHBOARD_URL),
         intervalSeconds: optionalPositiveInteger(values.flags.get("--interval-seconds"), "--interval-seconds") ?? DEFAULT_AUTOSTART_INTERVAL_SECONDS,
         json: values.booleans.has("--json"),
@@ -334,6 +396,16 @@ function parseNamedArgs(args, options) {
     }
     return { flags, booleans, positionals };
 }
+function workRootFlagValue(values) {
+    const provided = WORK_ROOT_FLAGS.filter((flag) => values.flags.has(flag));
+    if (provided.length === 0)
+        return undefined;
+    const uniqueValues = new Set(provided.map((flag) => values.flags.get(flag)).filter(Boolean));
+    if (uniqueValues.size > 1) {
+        throw new Error("--repo and --workspace must point to the same path.");
+    }
+    return values.flags.get("--workspace") ?? values.flags.get("--repo");
+}
 function assertNoPositionals(positionals, command) {
     if (positionals.length > 0) {
         throw new Error(`${command} does not accept positional arguments.`);

package/dist/commands/local.js

@@ -75,17 +75,17 @@ export function localCommandHelp(command) {
     if (command)
         return localSubcommandHelp(command);
     return [
-        "  cockpit onboard [--ticket <id>] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--repo <path>] [--branch <name>] [--max-depth <n>] [--max-repos <n>] [--json]",
-        "  cockpit install [--dashboard-url <url>] [--repo <path>] [--json]",
+        "  cockpit onboard [--ticket <id>] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--branch <name>] [--max-depth <n>] [--max-repos <n>] [--json]",
+        "  cockpit install [--dashboard-url <url>] [--workspace <path>] [--json]",
         "  cockpit login [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--json]",
         "  cockpit pair [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--json]",
         "  cockpit logout",
-        "  cockpit start [--ticket <id>] [--repo <path>] [--branch <name>] [--max-depth <n>] [--max-repos <n>] [--json]",
-        "  cockpit sync [--repo <path>] [--dashboard-url <url>] [--max-depth <n>] [--max-repos <n>] [--json]",
-        "  cockpit status [--repo <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
-        "  cockpit sessions [--source codex|claude] [--repo <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
-        "  cockpit serve [--port <port>] [--repo <path>]",
-        "  cockpit autostart [install|uninstall|status] [--repo <path>] [--dashboard-url <url>] [--interval-seconds <n>] [--json]",
+        "  cockpit start [--ticket <id>] [--workspace <path>] [--branch <name>] [--max-depth <n>] [--max-repos <n>] [--json]",
+        "  cockpit sync [--workspace <path>] [--dashboard-url <url>] [--max-depth <n>] [--max-repos <n>] [--json]",
+        "  cockpit status [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
+        "  cockpit sessions [--source codex|claude] [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
+        "  cockpit serve [--port <port>] [--workspace <path>]",
+        "  cockpit autostart [install|uninstall|status] [--workspace <path>] [--dashboard-url <url>] [--interval-seconds <n>] [--json]",
         "  cockpit agent-rules [install|uninstall|status] [--json]",
         "",
         `Default dashboard: ${DEFAULT_DASHBOARD_URL}. Omit --dashboard-url for normal production use; pass it only for staging/custom dashboards or to force a different pairing.`,
@@ -96,10 +96,11 @@ function localSubcommandHelp(command) {
         [
             "onboard",
             [
-                "Usage: cockpit onboard [--ticket <id>] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--repo <path>] [--branch <name>] [--json]",
+                "Usage: cockpit onboard [--ticket <id>] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--branch <name>] [--json]",
                 "",
                 "Installs, pairs, starts work context(s), syncs once, and prints readiness proof.",
-                "If --repo is a parent folder, scans child git repos/worktrees and rolls them up by repo.",
+                "If --workspace is a parent folder, scans child git repos/worktrees and rolls them up by repo.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
                 `Omit --dashboard-url for normal production setup (${DEFAULT_DASHBOARD_URL}).`,
                 "Pass --dashboard-url only for staging/custom dashboards or to force a different pairing.",
                 "Run with no flags in a terminal and it prompts for the dashboard email; pass --email to skip the prompt (and on shared/reused machines, where mismatched sessions are re-paired).",
@@ -108,9 +109,10 @@ function localSubcommandHelp(command) {
         [
             "install",
             [
-                "Usage: cockpit install [--dashboard-url <url>] [--repo <path>] [--json]",
+                "Usage: cockpit install [--dashboard-url <url>] [--workspace <path>] [--json]",
                 "",
                 "Writes local collector config. Pair with `cockpit login`, then run `cockpit start` when work begins.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
                 "Omit --dashboard-url for the production dashboard; pass it only for staging/custom dashboards.",
             ],
         ],
@@ -135,19 +137,21 @@ function localSubcommandHelp(command) {
         [
             "start",
             [
-                "Usage: cockpit start [--ticket <id>] [--repo <path>] [--branch <name>] [--json]",
+                "Usage: cockpit start [--ticket <id>] [--workspace <path>] [--branch <name>] [--json]",
                 "",
                 "Starts local ambient capture. Parent folders start each child git worktree.",
                 "Add --ticket only when the work already has a visible ticket.",
+                "`--repo <path>` remains supported and is still the canonical agent-rule spelling.",
             ],
         ],
         [
             "sync",
             [
-                "Usage: cockpit sync [--repo <path>] [--dashboard-url <url>] [--json]",
+                "Usage: cockpit sync [--workspace <path>] [--dashboard-url <url>] [--json]",
                 "",
                 "Uploads latest local ambient envelope(s), or spools safe retries if blocked.",
                 "Omit --dashboard-url for normal production sync; pass it only for staging/custom dashboards or forced re-pairing.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
                 "Parent folders sync each child git worktree; Codex AND Claude Code JSONL",
                 "transcripts (and Claude subagent sidecars) are attributed to repos",
                 "deterministically and ambiguous transcripts are retained as unattributed",
@@ -161,38 +165,42 @@ function localSubcommandHelp(command) {
         [
             "status",
             [
-                "Usage: cockpit status [--repo <path>] [--json]",
+                "Usage: cockpit status [--workspace <path>] [--json]",
                 "",
                 "Prints install, pairing, active work, upload, and retry state.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
             ],
         ],
         [
             "sessions",
             [
-                "Usage: cockpit sessions [--source codex|claude] [--repo <path>] [--json]",
+                "Usage: cockpit sessions [--source codex|claude] [--workspace <path>] [--json]",
                 "",
                 "Read-only: re-runs Codex + Claude session attribution and prints each",
                 "session's id, source, state, reason, scores, signals, and per-sidecar",
                 "skip reasons. No upload, no cursor writes. Answers \"why is session X",
                 "missing?\" locally — counts and labels only, never paths or content.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
             ],
         ],
         [
             "serve",
             [
-                "Usage: cockpit serve [--port <port>] [--repo <path>]",
+                "Usage: cockpit serve [--port <port>] [--workspace <path>]",
                 "",
                 "Starts the local collector HTTP status server.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
             ],
         ],
         [
             "autostart",
             [
-                "Usage: cockpit autostart [install|uninstall|status] [--repo <path>] [--dashboard-url <url>] [--interval-seconds <n>] [--json]",
+                "Usage: cockpit autostart [install|uninstall|status] [--workspace <path>] [--dashboard-url <url>] [--interval-seconds <n>] [--json]",
                 "",
                 "Installs a macOS launchd LaunchAgent that runs `cockpit sync` at login and",
                 "every 15 min (default), surviving reboots — so machines never drift to Stale.",
-                "Action defaults to `install`. `--repo` is the parent work folder to sync.",
+                "Action defaults to `install`. `--workspace` is the parent work folder to sync.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
                 "Omit --dashboard-url for production; pass it only for staging/custom dashboards.",
                 "macOS-only for now; see docs/runbooks/cockpit-launchd-sync.md.",
             ],

package/dist/commands/public-root.js

@@ -24,7 +24,7 @@ function cockpitHelp() {
     "",
     "Install/update: `npm install -g @bli-cockpit/cli@latest`.",
     "Intern path: run `cockpit onboard` from the repo root; add `--ticket <id>` only when work already has a ticket.",
-    "Already onboarded: run `cockpit sync --repo \"$PWD\" --json`.",
+    "Already onboarded: run `cockpit sync --workspace \"$PWD\" --json`.",
     "Agent setup: run `cockpit agent-rules install` so Codex asks for or binds Linear tickets before edits.",
     "Dashboard URL is optional for normal production use; pass `--dashboard-url` only for staging/custom dashboards or forced re-pairing.",
     "Manual collector path: `install`, `login`, `start [--ticket <id>]`, `sync`, `status`, `agent-rules`.",

package/dist/upload.js

@@ -19,7 +19,7 @@ export async function buildLocalAmbientEnvelope(options = {}) {
     const now = options.now ?? new Date();
     const paths = getCollectorRuntimePaths(options.homeDir);
     const config = await readLocalCollectorConfig(paths).catch(() => {
-        throw new LocalUploadBlockedError("not_installed", "Local collector config missing. Install/update the CLI, then run `cockpit onboard` before `cockpit sync`.", "npm install -g @bli-cockpit/cli@latest && cockpit onboard --email <email> --repo \"$PWD\"");
+        throw new LocalUploadBlockedError("not_installed", "Local collector config missing. Install/update the CLI, then run `cockpit onboard` before `cockpit sync`.", "npm install -g @bli-cockpit/cli@latest && cockpit onboard --email <email> --workspace \"$PWD\"");
     });
     const sessionFile = await readLocalCollectorSessionFile(paths).catch(() => {
         throw new LocalUploadBlockedError("unpaired", "No paired collector session found. Run `cockpit login` or `cockpit pair` before `cockpit sync`.", "cockpit login");
@@ -32,7 +32,7 @@ export async function buildLocalAmbientEnvelope(options = {}) {
     }
     const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
     const activeContext = await readLocalWorkContextForRepo(paths, repoRoot).catch(() => {
-        throw new LocalUploadBlockedError("missing_context", "Active work context missing. Run `cockpit start --repo \"$PWD\"` before `cockpit sync`.", "cockpit start --repo \"$PWD\"");
+        throw new LocalUploadBlockedError("missing_context", "Active work context missing. Run `cockpit start --workspace \"$PWD\"` before `cockpit sync`.", "cockpit start --workspace \"$PWD\"");
     });
     const repoLabel = safeRepoLabel(activeContext.repo_label ?? repoRoot);
     const uploadContext = makeUploadWorkContext({

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "private": false,
   "type": "module",
   "bin": {
-    "cockpit": "./dist/cli.js"
+    "cockpit": "dist/cli.js"
   },
   "files": [
     "dist/",