propr-cli 0.8.3 → 0.8.5

package/README.md

@@ -5,7 +5,7 @@ Command-line interface for interacting with the ProPR backend. ProPR enables AI-
 ## Installation
 
 ```bash
-npm install -g @propr/cli
+npm install -g propr-cli
 ```
 
 The host CLI requires Node.js 22 or newer. The Docker launcher image is separate
@@ -223,12 +223,12 @@ For OpenCode agents, install and authenticate OpenCode on the host before adding
 
 ```bash
 curl -fsSL https://opencode.ai/install | bash
-mkdir -p ~/.config/opencode ~/.opencode
+mkdir -p ~/.config/opencode
 opencode auth login
 mkdir -p ~/.config/opencode/xdg-data/opencode && cp ~/.local/share/opencode/auth.json ~/.config/opencode/xdg-data/opencode/auth.json
 ```
 
-OpenCode stores `auth.json` under `~/.local/share/opencode`, but ProPR mounts the configured OpenCode config directory into the agent container. When using copied file-based auth, set `XDG_DATA_HOME=/home/node/.config/opencode/xdg-data` on the OpenCode agent. Legacy agents can keep `~/.opencode` as their `configPath`; new agents should use `~/.config/opencode`.
+OpenCode stores `auth.json` under `~/.local/share/opencode`, but ProPR mounts the configured OpenCode config directory into the agent container. When using copied file-based auth, set `XDG_DATA_HOME=/home/node/.config/opencode/xdg-data` on the OpenCode agent. Use `~/.config/opencode` as the agent `configPath`.
 
 The example model `opencode-minimax-m3-free` is a built-in free OpenCode model. OpenCode's model list changes with auth providers; run `opencode models` after logging in and register any desired provider/model IDs with ProPR's `opencode-` prefix, such as `opencode-openai/gpt-5.5`. ProPR converts these IDs back to OpenCode's native `provider/model` syntax at execution time and does not add authenticated provider models by default.
 Dynamic OpenCode GitHub labels use the format `llm-<agent-alias>~<propr-opencode-model-id>`, for example `llm-opencode~opencode-openai/gpt-5.5`. The `~` separator is an intentional public contract — these labels are persisted on GitHub issues and resolved later for execution routing.
@@ -348,7 +348,7 @@ import {
   createConfigManager,
   createApiClient,
   resolveProject,
-} from '@propr/cli';
+} from 'propr-cli';
 
 const config = await createConfigManager();
 const client = await createApiClient();

package/dist/api/relay.js

@@ -58,6 +58,16 @@ async function relayRequest(options, path, method, body, init) {
         throw new Error("The relay returned a malformed JSON response.");
     }
 }
+/**
+ * Identity probe: returns the GitHub user and the installations they may access
+ * (the same `/v1/auth/me` route the dashboard boots from). Used by `propr relay`
+ * to discover an installation id when none was passed explicitly. Note these are
+ * access-scoped (ownership or team membership); minting a relay token is stricter
+ * (owner-only), so a discovered installation may still 403 on enroll.
+ */
+export function fetchAuthenticatedUser(options) {
+    return relayRequest(options, "/auth/me", "GET");
+}
 export function enrollRelayToken(options, params) {
     return relayRequest(options, "/relay-tokens", "POST", {
         installation_id: params.installationId,

package/dist/assets/env.example.txt

@@ -1,34 +1,128 @@
-# GitHub App Configuration
-GH_APP_ID=your_app_id
-GH_PRIVATE_KEY_PATH=./path/to/your-app-private-key.pem
-GH_INSTALLATION_ID=your_installation_id
+# =============================================================================
+# GitHub event intake mode
+# =============================================================================
+# How ProPR receives GitHub events. New installs use the hosted ProPR GitHub App
+# with WebSocket routing — no public URL and no GitHub App of your own required.
+# This is the default and the normal path; polling and direct webhook below are
+# advanced opt-ins.
+#   routing_websocket — events stream over the ProPR routing WebSocket (default)
+#   polling           — ProPR pulls events from the GitHub API (advanced opt-in)
+#   direct_webhook    — GitHub delivers events to your own public /webhook URL
+#                       (advanced; requires your own GitHub App)
+#
+# Migrating an existing install: the default is now routing_websocket. If you run
+# your OWN GitHub App (the old polling/webhook setup), routing_websocket will not
+# work for you — it needs the hosted ProPR App via the relay (relay auth mode).
+# Keep your current behavior by setting this explicitly to `polling` or
+# `direct_webhook`, or migrate to the hosted path with `propr relay enroll`.
+GITHUB_EVENT_INTAKE_MODE=routing_websocket
 
-# Host path to the GitHub App private key (.pem). Recommended when running via
-# the `propr` CLI or launcher: the key is bind-mounted (read-only) into the app
-# containers and GH_PRIVATE_KEY_PATH above is overridden to point at it, so you
-# can keep the key anywhere on the host instead of staging it under data/.
-# Must be an absolute host path (no '~').
-# HOST_GH_PRIVATE_KEY=/home/your-user/propr/app-private-key.pem
-
-# GitHub auth: token relay (shared-app path) — ALTERNATIVE to the App private key
-# above. When PROPR_GH_RELAY_URL is set, the backend fetches short-lived
-# installation tokens from a vendor-run relay instead of minting them from a
-# private key, so you don't need to hold the shared App's key. You still set
-# GH_INSTALLATION_ID (which installation), but GH_PRIVATE_KEY_PATH /
-# HOST_GH_PRIVATE_KEY are not required in relay mode.
-#   PROPR_GH_RELAY_URL   — https URL of the relay (http only allowed for localhost)
-#   PROPR_GH_RELAY_TOKEN — the durable relay credential issued for your install
-# PROPR_GH_RELAY_URL=https://relay.propr.dev/v1
+# --- Routing WebSocket (default intake) --------------------------------------
+# The hosted path: ProPR authenticates through the shared ProPR GitHub App via
+# the token relay and streams events over the routing WebSocket. Run
+# `propr relay enroll` to populate PROPR_GH_RELAY_URL / PROPR_GH_RELAY_TOKEN /
+# GH_INSTALLATION_ID for you, or set them by hand below.
+#   PROPR_ROUTING_URL    — routing WebSocket origin (wss://; ws:// only for localhost)
+#   PROPR_GH_RELAY_URL   — token relay URL incl. version prefix
+#                          (https://; http only for localhost)
+#   PROPR_GH_RELAY_TOKEN — durable relay credential issued for your install
+#   GH_INSTALLATION_ID   — which GitHub App installation ProPR acts on
+# Both URLs default to the hosted relay (webhook.propr.dev) when unset, so you
+# only need them below to point at a self-hosted relay.
+# PROPR_ROUTING_URL=wss://webhook.propr.dev
+# PROPR_GH_RELAY_URL=https://webhook.propr.dev/v1
+# Optional transport keepalive override. The default is 300000 ms (5 minutes);
+# lower it only if a network path closes otherwise-healthy WebSockets too quickly.
+# PROPR_ROUTING_WS_PING_INTERVAL_MS=300000
+# Per-install secrets — left commented so an unedited copy is not mistaken for a
+# configured relay. Run `propr relay enroll` to fill these in, or uncomment and set
+# them by hand. (Active placeholder values here could make intake/auth mode look
+# configured when it is not.)
 # PROPR_GH_RELAY_TOKEN=your_relay_token
-# Optional: force a mode explicitly instead of inferring (app | relay | demo).
+# GH_INSTALLATION_ID=your_installation_id
+# Optional: force the auth mode explicitly instead of inferring (app | relay | demo).
+# Relay mode is inferred automatically when PROPR_GH_RELAY_URL + PROPR_GH_RELAY_TOKEN
+# are set, so you normally do not need this.
 # GH_AUTH_MODE=relay
 
+# --- Hosted UI tunnel (v1, optional) -----------------------------------------
+# Expose this local stack's API to the hosted control plane at
+# https://app.propr.dev through a Cloudflare Tunnel, so you can drive a
+# locally-running stack from the hosted UI. The tunnel publishes the API
+# container (only /api/* and /socket.io/* are routed; the root URL returns 404);
+# the UI bundle is served by app.propr.dev, not through the tunnel. Cloudflare
+# forwards the tunnel to the Docker-internal http://api:4000, NOT host port 4000,
+# so the published host port is irrelevant to the tunnel and cannot conflict with
+# it. Off by default; local development is unaffected (API_PUBLIC_URL /
+# FRONTEND_URL keep their localhost defaults below).
+#
+# Normal setup is CLI-first: ProPR Connect shows a one-time command such as
+# `propr tunnel setup --token ... --url https://<id>.proxy.propr.dev --start`.
+# Run that from this stack directory so the CLI writes these values and restarts
+# the stack for you. The variables below are documented as a fallback for older
+# CLI versions, manual recovery, or auditing what the setup command persists.
+#
+# Enable the tunnel:
+#   PROPR_UI_TUNNEL_TOKEN   — Cloudflare Tunnel token; required to start. Setting it
+#                             enables the tunnel by default, so the next `propr start`
+#                             brings up the sidecar (unless you ran `propr tunnel off`).
+#                             WARNING: this is a LIVE Cloudflare credential — anyone
+#                             with it can route traffic through your tunnel. Do not
+#                             commit, log, or share it; keep it in this .env only.
+#   PROPR_UI_TUNNEL_ENABLED — explicitly enable the tunnel (`true`/`1`). A token is
+#                             STILL required — `propr check` fails if this is set
+#                             without PROPR_UI_TUNNEL_TOKEN. Redundant when a token
+#                             is set, since a token alone already enables the tunnel
+#   PROPR_INSTANCE_ID       — this stack's instance id; must be a valid DNS label
+#                             (letters, digits, hyphens; 1-63 chars). Derives the
+#                             public URL https://<id>.proxy.propr.dev when no
+#                             explicit URL is set
+#   PROPR_UI_PUBLIC_API_URL — explicit public API URL the hosted UI talks to (overrides the derived one)
+#   PROPR_CLOUDFLARED_IMAGE — cloudflared image (default: cloudflare/cloudflared:2024.12.2,
+#                             a pinned tag; override only if you need a different build)
+# PROPR_UI_TUNNEL_TOKEN=your_cloudflare_tunnel_token
+# PROPR_INSTANCE_ID=abc123
+# PROPR_UI_PUBLIC_API_URL=https://abc123.proxy.propr.dev
+# PROPR_CLOUDFLARED_IMAGE=cloudflare/cloudflared:2024.12.2
+#
+# Why `.proxy.propr.dev`: each enabled stack is published under a per-instance
+# hostname `<PROPR_INSTANCE_ID>.proxy.propr.dev`. The hosted UI at
+# https://app.propr.dev discovers and reaches your stack's API through that
+# single shared suffix, without you owning or registering a domain.
+#
+# Browser origin vs API host — they are DIFFERENT and must be set accordingly.
+# The browser loads the UI from app.propr.dev; the API, Socket.IO, OAuth
+# callback, and session cookie all live on the proxy host. In tunnel mode
+# FRONTEND_URL, API_PUBLIC_URL, and GH_OAUTH_CALLBACK_URL are derived
+# automatically (FRONTEND_URL -> https://app.propr.dev, API_PUBLIC_URL -> the
+# proxy host, GH_OAUTH_CALLBACK_URL -> <proxy host>/api/auth/github/callback);
+# set them only to override. You must still register the callback URL — derived
+# or explicit — in your GitHub OAuth App.
+# FRONTEND_URL=https://app.propr.dev
+# API_PUBLIC_URL=https://abc123.proxy.propr.dev
+# GH_OAUTH_CALLBACK_URL=https://abc123.proxy.propr.dev/api/auth/github/callback
+#
+# COOKIE_DOMAIN: leave UNSET for v1. The session cookie is host-only on the
+# single `<id>.proxy.propr.dev` host — correct because that host and
+# app.propr.dev share the propr.dev registrable domain (same-site). Setting
+# COOKIE_DOMAIN (e.g. `.proxy.propr.dev`) would scope the cookie across every
+# instance's subdomain and is not supported for v1 proxy sessions.
+# COOKIE_DOMAIN=
+
 # Logging Configuration
 LOG_LEVEL=info
 NODE_ENV=development
 
 # Daemon Configuration
 GITHUB_REPOS_TO_MONITOR=owner/repo1,owner/repo2
+
+# --- Polling intake (advanced opt-in) ----------------------------------------
+# Polling is an explicit opt-in alternative to the default routing WebSocket.
+# It is only used when GITHUB_EVENT_INTAKE_MODE=polling (set above); leave the
+# intake mode at routing_websocket to keep the hosted path. In polling mode
+# ProPR pulls events from the GitHub API on this interval using any usable
+# GitHub auth (relay or your own App). POLLING_INTERVAL_MS is the poll period in
+# milliseconds (default: 60000).
 POLLING_INTERVAL_MS=60000
 
 # Config Repository (for dynamic repository management)
@@ -55,10 +149,34 @@ COMMENT_BATCH_DELAY_MS=3000
 # and fallback paths fail. Defaults to 3600000 (1 hour).
 # SUMMARIZATION_QUOTA_COOLDOWN_MS=3600000
 
-# Webhook Configuration
-# Webhooks are received by the dashboard API service (port 4000)
-ENABLE_GITHUB_WEBHOOKS=false
-GH_WEBHOOK_SECRET=your-webhook-secret
+# --- Direct webhook intake (advanced) ----------------------------------------
+# Direct webhook is an advanced alternative to the default routing WebSocket.
+# It is only used when GITHUB_EVENT_INTAKE_MODE=direct_webhook (set near the top
+# of this file). This path requires your OWN GitHub App (not the hosted ProPR
+# App) and a publicly reachable POST /webhook URL that GitHub can deliver events
+# to — the endpoint is served by the dashboard API service (port 4000). Because
+# of those requirements, most installs should stay on routing_websocket.
+#
+# Own GitHub App credentials (app auth mode — required for direct webhook):
+#   GH_APP_ID            — your GitHub App's numeric id
+#   GH_PRIVATE_KEY_PATH  — path to your App's private key (.pem)
+#   GH_INSTALLATION_ID   — which installation to act on (set in the routing
+#                          section above; reused here)
+# GH_APP_ID=your_app_id
+# GH_PRIVATE_KEY_PATH=./path/to/your-app-private-key.pem
+# Host path to the GitHub App private key (.pem). Recommended when running via
+# the `propr` CLI or launcher: the key is bind-mounted (read-only) into the app
+# containers and GH_PRIVATE_KEY_PATH above is overridden to point at it, so you
+# can keep the key anywhere on the host instead of staging it under data/.
+# Must be an absolute host path (no '~').
+# HOST_GH_PRIVATE_KEY=/home/your-user/propr/app-private-key.pem
+# Shared secret GitHub signs webhook deliveries with; required for this mode.
+# GH_WEBHOOK_SECRET=your-webhook-secret
+
+# Deprecated: ENABLE_GITHUB_WEBHOOKS no longer selects the intake mode. Use
+# GITHUB_EVENT_INTAKE_MODE instead (routing_websocket | polling | direct_webhook).
+# Documented here only so existing .env files are recognized; do not rely on it.
+# ENABLE_GITHUB_WEBHOOKS=false
 
 # System Task Authorization
 # Secret used to sign system task requests (e.g., revert operations)
@@ -104,19 +222,14 @@ ANTIGRAVITY_TIMEOUT_MS=300000
 OPENCODE_TIMEOUT_MS=3600000
 # Launcher credential mount paths (required when using docker/launcher).
 # HOST_OPENCODE_XDG_DIR points to the XDG config directory
-# (/home/your-user/.config/opencode)
-# and takes precedence over HOST_OPENCODE_DIR.
-# HOST_OPENCODE_DIR is accepted as a fallback alias for HOST_OPENCODE_XDG_DIR.
-# HOST_OPENCODE_LEGACY_DIR points to the legacy /home/your-user/.opencode directory.
-# The saved agent configPath still controls the runtime mount; the launcher
-# sets OPENCODE_CONFIG_PATH only as the default path for worker/API processes.
+# (/home/your-user/.config/opencode). The saved agent configPath still controls
+# the runtime mount; the launcher sets OPENCODE_CONFIG_PATH only as the default
+# path for worker/API processes.
 # HOST_OPENCODE_DATA_DIR points to normal opencode auth data
 # (/home/your-user/.local/share/opencode). Set it for launcher deployments
 # so normal `opencode auth login` credentials are visible to spawned OpenCode
 # agent containers and can refresh auth metadata when required.
 # HOST_OPENCODE_XDG_DIR=/home/your-user/.config/opencode
-# HOST_OPENCODE_DIR=/home/your-user/.config/opencode
-# HOST_OPENCODE_LEGACY_DIR=/home/your-user/.opencode
 # HOST_OPENCODE_DATA_DIR=/home/your-user/.local/share/opencode
 
 # --- Mistral Vibe Configuration (only required when using a Vibe agent) ---
@@ -135,19 +248,31 @@ VIBE_TIMEOUT_MS=3600000
 # directory name intentionally differs from the variable name.
 # HOST_ANTIGRAVITY_DIR=/home/your-user/.gemini
 # HOST_VIBE_DIR=/home/your-user/.vibe
-# Required for Vibe Docker-outside-Docker: prompt files must be written to a
-# host-visible directory so spawned agent containers can bind-mount them.
-# Both should reference the same host path.
-# NOTE: These are required whenever Vibe agents are used with the launcher
-# (i.e. when MISTRAL_API_KEY is set), not only when HOST_VIBE_DIR is set.
-# Create the directory before starting: mkdir -p /tmp/propr-vibe-prompts
+# Vibe Docker-outside-Docker writes prompt files to a host-visible directory so
+# spawned agent containers can bind-mount them. When Vibe is enabled, the
+# launcher defaults the host path to /tmp/propr-vibe-prompts-<uid>; the container
+# path defaults to /tmp/propr-vibe-prompts. Set both only to override those
+# locations.
 # VIBE_PROMPT_CACHE_DIR=/tmp/propr-vibe-prompts
-# HOST_VIBE_PROMPT_CACHE_DIR=/tmp/propr-vibe-prompts
+# HOST_VIBE_PROMPT_CACHE_DIR=/tmp/propr-vibe-prompts-1000
 
 # Dashboard API Configuration
 DASHBOARD_API_PORT=4000
-# Required in normal and demo mode for auth redirects.
-FRONTEND_URL=http://localhost:5173
+# Browser origin: required in normal and demo mode for CORS and auth redirects.
+# Defaults to http://localhost:5173 when unset. In hosted UI tunnel mode this is
+# derived automatically as the hosted UI origin (https://app.propr.dev) — NOT the
+# proxy host — so leave it COMMENTED to let derivation win. An uncommented value
+# here always overrides the derived origin (set one only to force a custom
+# origin). See the "Hosted UI tunnel" section above.
+# FRONTEND_URL=http://localhost:5173
+# Public URL the API is reached at (auth redirects, attachment links, cookie
+# security). Defaults to http://localhost:4000 when unset; set it to the
+# https://<id>.proxy.propr.dev host when the hosted UI tunnel is enabled.
+# API_PUBLIC_URL=http://localhost:4000
+# Session cookie domain. Leave UNSET for v1 — including hosted UI tunnel proxy
+# sessions, which run on a single <id>.proxy.propr.dev host (see the tunnel
+# section above). Only set it for a custom multi-subdomain deployment.
+# COOKIE_DOMAIN=
 # Optional comma-separated redirect hosts for auth preview flows.
 # Entries are exact host matches by default. Prefix with "." or "*." only for
 # parent domains where every subdomain is trusted, for example .preview.example.com.
@@ -155,9 +280,16 @@ FRONTEND_URL=http://localhost:5173
 # AUTH_REDIRECT_ALLOWED_HOSTS=preview.example.com
 
 # GitHub OAuth Configuration
+# The OAuth callback is served by the API and is derived automatically when left
+# unset: <proxy host>/api/auth/github/callback in hosted UI tunnel mode, or
+# http://localhost:4000/api/auth/github/callback for local development. Leave it
+# commented so enabling the tunnel (token/instance id) cannot leave a stale
+# localhost callback that breaks hosted OAuth — an active localhost value is used
+# as-is even in tunnel mode (the launcher only warns). Uncomment to override; then
+# register that exact URL in your GitHub OAuth App.
 GH_OAUTH_CLIENT_ID=your_github_oauth_client_id
 GH_OAUTH_CLIENT_SECRET=your_github_oauth_client_secret
-GH_OAUTH_CALLBACK_URL=http://localhost:4000/api/auth/github/callback
+# GH_OAUTH_CALLBACK_URL=http://localhost:4000/api/auth/github/callback
 SESSION_SECRET=your-session-secret-here
 
 # Bearer Token Authentication (CLI)
@@ -174,25 +306,16 @@ PROPR_DEMO_MODE=false
 DB_FILENAME=./data/propr.sqlite
 
 # --- PR Preview Environment ---
+# docker-compose.yml and scripts/deploy-pr.sh consume these local names.
+# The PR Preview workflow maps repository variable PR_PREVIEW_STAGING_ENV_FILE
+# to STAGING_ENV_FILE for deploys.
 # Path to staging .env file (provides base configuration for PR previews)
 # PR-specific values (ports, API URLs) are passed as inline overrides
 STAGING_ENV_FILE=/path/to/staging/.env
 
-# Path to staging database file for seeding PR preview environments
+# Optional path to a staging database file for seeding PR preview environments.
+# The workflow maps repository variable PR_PREVIEW_STAGING_DB_PATH to this env.
 STAGING_DB_PATH=/path/to/staging/data/propr.sqlite
 
-# Enable preview environment routing (routes webhooks to PR preview instances)
-ENABLE_PREVIEW_ROUTING=false
-
-# The ProPR repository in 'owner/repo' format. Label events from this repo
-# trigger processor assignment changes. Defaults to 'integry/propr'.
-PROPR_REPO=integry/propr
-
-# The label that designates a ProPR PR as the active processor for webhook routing.
-# When this label is added to a ProPR repo PR, that PR's preview instance becomes
-# the active processor. Defaults to 'preview-env'.
-PROCESSOR_LABEL=preview-env
-
-# Host address for forwarding webhooks to PR preview instances.
-# Defaults to 'http://host.docker.internal' for Docker environments.
-# HOST_GATEWAY_ADDRESS=http://host.docker.internal
+# PR preview deploys are owned by the GitHub Actions workflow and run only after
+# a maintainer adds the preview-env label to a pull request.

package/dist/auth/githubLogin.js

@@ -0,0 +1,66 @@
+/**
+ * Shared GitHub authentication via the `gh` CLI.
+ *
+ * Both `propr login` (commands wired in index.ts) and `propr setup`'s relay
+ * enrollment need a stored GitHub token. This centralises the `gh`-CLI flow —
+ * reuse an existing `gh` session, or run the interactive `gh auth login` — so
+ * the two callers stay in sync. It returns a result object instead of writing to
+ * the console or calling process.exit, leaving presentation to the caller.
+ */
+/** Scopes requested when launching the interactive `gh auth login`. */
+const GH_LOGIN_SCOPES = "repo,read:org";
+/**
+ * Authenticate with GitHub through the `gh` CLI and persist the token.
+ *
+ * Order: confirm `gh` is installed → reuse an existing `gh auth token` →
+ * (interactive only) run `gh auth login` and read the token back.
+ */
+export async function loginWithGithubCli(configManager, options = {}) {
+    const { interactive = false, onLog } = options;
+    const { execSync, spawnSync } = await import("child_process");
+    // Require the gh CLI up front — every path below shells out to it.
+    try {
+        execSync("gh --version", { stdio: "ignore" });
+    }
+    catch {
+        return {
+            ok: false,
+            message: "GitHub CLI (gh) is not installed. Install it from https://cli.github.com, or run `propr login <token>` with a personal access token.",
+        };
+    }
+    // Reuse an existing gh session when one is already authenticated.
+    const existing = readGhToken(execSync);
+    if (existing) {
+        await configManager.setGithubToken(existing);
+        return { ok: true, token: existing, message: "Authenticated using your existing gh CLI session." };
+    }
+    if (!interactive) {
+        return {
+            ok: false,
+            message: "No gh CLI session found. Run `propr login` (or `gh auth login`) to authenticate first.",
+        };
+    }
+    // Launch the interactive browser/device login. Inherits stdio so the user can
+    // complete the gh prompts directly.
+    onLog?.("No existing gh session found. Starting interactive login…");
+    const result = spawnSync("gh", ["auth", "login", "-s", GH_LOGIN_SCOPES], { stdio: "inherit" });
+    if (result.status !== 0) {
+        return { ok: false, message: "GitHub login failed or was cancelled." };
+    }
+    const token = readGhToken(execSync);
+    if (!token) {
+        return { ok: false, message: "Could not retrieve a token after login." };
+    }
+    await configManager.setGithubToken(token);
+    return { ok: true, token, message: "Authentication successful." };
+}
+/** Read the current `gh` token, or null when no session is authenticated. */
+function readGhToken(execSync) {
+    try {
+        const token = execSync("gh auth token", { encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] }).trim();
+        return token || null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/commands/agentCommands.js

@@ -5,7 +5,14 @@
  * Provides the `agent` command group with `list`, `add`, and `delete` subcommands.
  */
 import { Command } from "commander";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { listAgents, addAgent, deleteAgent, setAgentEnabled, AGENT_TYPES, } from "../api/agents.js";
+import { createConfigManager } from "../config/index.js";
+import { getHostConfig } from "../orchestrator/index.js";
+import { planAgentLogin, loginableAgents } from "./agentValidation.js";
 import { ApiError, NetworkError, NotFoundError, UnauthorizedError } from "../api/errors.js";
 import { printOutput, readJsonInput, validateJsonFields, JsonInputError, } from "../utils/index.js";
 const AGENT_TYPE_LIST = AGENT_TYPES.join(", ");
@@ -401,5 +408,72 @@ Examples:
             process.exit(1);
         }
     });
+    // agent login
+    agent
+        .command("login [type]")
+        .description("Authenticate an agent by logging in through its Docker image (writes host credentials)")
+        .option("--root <dir>", "Stack root directory (where .env/data/logs/repos live)")
+        .addHelpText("after", `
+Logs in using the agent's own pinned CLI inside its image, with the credential
+directory mounted — so the credentials match exactly what runs jobs (no host
+install or host/image version drift). Useful after a failed image check.
+
+Examples:
+  $ propr agent login antigravity
+  $ propr agent login opencode
+`)
+        .action(async (type, options) => {
+        try {
+            const available = loginableAgents();
+            if (!type) {
+                console.log("Usage: propr agent login <type>");
+                console.log(`Agents with interactive login: ${available.join(", ")}`);
+                return;
+            }
+            if (!process.stdin.isTTY || !process.stdout.isTTY) {
+                console.error("Error: propr agent login requires an interactive terminal because Docker login runs with -it.");
+                process.exit(1);
+            }
+            const configManager = await createConfigManager();
+            const { orch, cfg } = await getHostConfig({ configManager, root: options.root });
+            const tmp = mkdtempSync(join(tmpdir(), "propr-login-"));
+            const workspaceDir = join(tmp, "workspace");
+            mkdirSync(workspaceDir, { recursive: true });
+            try {
+                const loginType = type.toLowerCase();
+                const { plan, error } = planAgentLogin(loginType, cfg, workspaceDir, orch.validateDockerBindPath);
+                if (error || !plan) {
+                    console.error(`Error: ${error ?? "could not plan login"}`);
+                    if (available.length > 0)
+                        console.error(`Agents with interactive login: ${available.join(", ")}`);
+                    process.exit(1);
+                }
+                if (orch.docker(["images", "-q", plan.image], { capture: true }).stdout.trim().length === 0) {
+                    console.error(`Image ${plan.image} is not present locally. Pull it first: propr images pull`);
+                    process.exit(1);
+                }
+                mkdirSync(plan.hostDir, { recursive: true, mode: 0o700 });
+                console.log(`Logging in to ${loginType} via ${plan.image}`);
+                console.log(`Credentials will be written to ${plan.hostDir}`);
+                console.log("");
+                const res = spawnSync("docker", plan.dockerArgs, { stdio: "inherit" });
+                if (res.status === 0) {
+                    console.log("");
+                    console.log(`${loginType} login finished. Verify with: propr check agents --agents ${loginType}`);
+                }
+                else {
+                    console.error(`\n${loginType} login exited with code ${res.status ?? "?"}.`);
+                    process.exit(1);
+                }
+            }
+            finally {
+                rmSync(tmp, { recursive: true, force: true });
+            }
+        }
+        catch (error) {
+            console.error(`Error during agent login: ${error.message}`);
+            process.exit(1);
+        }
+    });
     return agent;
 }