@nilsr0711/drydock 0.1.6 → 0.1.7

package/README.md

@@ -63,12 +63,14 @@ It's the difference between *driving* an agent and *operating a dock* of them.
 
 🗂️ **Backlog & queue board** — drag issues from a synced backlog into a sortable, priority-ordered queue. One issue or many in flight, per repo.
 
-🤖 **Autonomous implementation** — spawns a coding agent (`claude` or the `codex` CLI), streams its work, and opens a pull request.
+🤖 **Autonomous implementation** — spawns a coding agent (`claude` or the `codex` CLI), streams its work, and opens a pull request. The agent describes its own change in a `.drydock/PR.md` (a Conventional Commit subject plus a Problem/Solution/Tests/Risks body); Drydock uses it for the commit message and the PR title/body, appends `Closes #N`, and excludes the file from the commit — falling back to `Fix #N` / `Closes #N` when it's absent.
 
 🔌 **Pluggable agents** — choose `claude` or `codex` per repo (with a global default in settings); a preflight check verifies the selected CLI is installed.
 
 🌐 **Opt-in OpenRouter backend** — run jobs against OpenRouter-hosted models, including **free-tier** ones, next to the Claude/Codex CLIs. The model catalog (ids, pricing, capabilities, deprecations) is **mirrored from OpenRouter's Models API into SQLite and refreshed automatically** on a configurable interval, so new models appear in the pickers without a Drydock release; sync failures keep the last-good snapshot working offline. One-shot stages (triage decomposition, verification, plan, PR audit) accept any synced model; implementation jobs are gated to tool-capable models and edit the worktree through a bounded tool loop. Costs use OpenRouter's exact usage accounting (catalog pricing as fallback) and flow into the same budgets and dashboards; 429s park jobs via the provider-limit latch and resume automatically. A global **free-models-only** policy restricts every OpenRouter run to zero-cost models. Off by default — paste an API key and flip the switch in Settings. See [ADR 032](docs/adr/032-openrouter-backend.md).
 
+📦 **Opt-in sandboxed execution** — per repo, run the agent CLI session **inside a container** (Docker or Podman) instead of directly on the host. The job's worktree is bind-mounted as the only writable host path, so a prompt-injected issue cannot reach host files through the test/build scripts the agent runs; networking is **off by default** (`--network none`), with optional CPU/memory caps. The image is resolved per job (explicit per-repo override → repo `devcontainer.json` → a configurable global default) and must carry the agent CLI plus the repo's toolchain. Only the minimum credentials are mounted **read-only** (the agent CLI's config; a `GH_TOKEN` via env) — git push still happens on the host, so no SSH keys enter the container. Timeout/abort **force-remove** the named container, so none is orphaned, and a missing runtime fails preflight with a clear reason. Off by default — zero behavior change for existing repos. See [ADR 033](docs/adr/033-sandboxed-agent-execution.md).
+
 🦊 **GitHub & GitLab** — choose the platform per repo. GitLab (gitlab.com or self-hosted) uses the REST API v4 with a per-repo base URL + access token — no extra CLI to install.
 
 🛂 **Opt-in autonomous triage** — per repo, let Drydock label incoming issues (deterministic keyword classifier, whitelist-only output) and auto-process the ones that are *ready* and not blocked. Off by default; gated by author association for public repos, a per-issue attempt limit, and all the usual cost/concurrency limits. Never auto-merges.
@@ -79,7 +81,7 @@ It's the difference between *driving* an agent and *operating a dock* of them.
 
 🩹 **Opt-in CI auto-heal** — per repo, turn the failure path into a structured classify → fix → verify loop: failing checks are bucketed (healable / external / flaky / unknown), only healable ones get a targeted fix, and each attempt is verified for a real, improving change. Flaky checks get a plain re-run instead of a code edit (GitHub; on forges without re-run support they escalate to a human). External and AI-review checks are never code-healed. Hard budgets (per-session and per-fingerprint attempts, a cooldown, and a concurrency cap) keep it bounded. Off by default; never auto-merges.
 
-💬 **Opt-in PR review-feedback** — per repo, ingest review threads on a Drydock PR and run the mechanical iteration: only **trusted reviewers** and explicitly **allowlisted bots** (e.g. `cursor[bot]`) are acted on — unlisted bots are ignored, each comment walks a lifecycle (`pending → queued → in_progress → resolved`, with `failed` / `rejected` / `flagged` branches), and the agent applies the change on the PR branch, replies, and resolves the thread. Status replies are marker-based and idempotent (updated in place, not duplicated), with bounded per-sweep and per-item budgets. Off by default; never auto-merges. See [ADR 019](docs/adr/019-pr-review-feedback.md).
+💬 **PR review-feedback** — per repo, ingest review threads on a Drydock PR and run the mechanical iteration: only **trusted reviewers** and explicitly **allowlisted bots** are acted on — unlisted bots are ignored, each comment walks a lifecycle (`pending → queued → in_progress → resolved`, with `failed` / `rejected` / `flagged` branches), and the agent applies the change on the PR branch, replies, and resolves the thread. Status replies are marker-based and idempotent (updated in place, not duplicated), with bounded per-sweep and per-item budgets. **On by default** for autonomous operation, seeded with well-known review bots (`cursor[bot]`, `coderabbitai[bot]`) and opt-out per repo; never auto-merges. See [ADR 019](docs/adr/019-pr-review-feedback.md).
 
 🧩 **Opt-in issue decomposition** — per repo, split a large issue ("fix these 5 bugs", "implement X with A/B/C") into ordered, tracked subtasks. A deterministic heuristic handles GitHub task lists (`- [ ]`) and "Bug N —" headings for free; prose falls back to a one-shot agent. Decomposition is idempotent (keyed on the issue body hash, redone only when the body changes), subtasks are surfaced in the agent prompt and worked in order, and progress is reflected on the issue and in the UI. Off by default. See [ADR 020](docs/adr/020-issue-decomposition.md).
 
@@ -105,6 +107,8 @@ It's the difference between *driving* an agent and *operating a dock* of them.
 
 💸 **Cost tracking** — per-job and aggregate spend from the agent's reported `total_cost_usd` (or estimated from tokens), with a **daily cost limit** that gates the driver loop and an optional **per-job cost ceiling** that aborts a single runaway session mid-stream (global default + per-repo override; off when unset). Spend is **exportable** to CSV or JSON from the cost dashboard — line items (jobs plus one-shot agent calls) or aggregates by repo/model, scoped to a date range and repo, with totals that reconcile with the dashboard.
 
+📊 **Proactive OAuth usage gauges** — the agents stream their subscription-quota state on every run Drydock already parses, so the dashboard warns *before* a job hits the wall. A navbar pill and a right-rail card show, per provider, how much of the window is left and when it resets, escalating tone toward the cap and folding the reactive parked state in as the terminal "limited" case. Codex (issue #189) reports exact `used_percent` for its 5-hour and weekly windows; Claude (issue #188) reports its qualitative subscription tier. Both degrade to "usage unknown" when the CLI reports nothing, and only numbers are persisted — never raw output. The forward-looking complement to the reactive `waiting_limit` latch.
+
 ⏯️ **Global pause & per-repo controls** — pause or resume the whole dock with one click from the navbar, pick an agent and model per repo, toggle serial vs. parallel processing, and customize the queue label.
 
 🪝 **Webhook-driven sync & nudges** — opt in per repo to receive forge events instead of waiting for the next poll. Set a secret on a repo and Drydock exposes a signature-verified receiver (`/api/webhooks/<id>`): a validated issue event triggers a targeted, debounced sync so new issues surface near-instantly; a finished `check_suite`/`check_run` (GitLab: pipeline) wakes the CI babysitter so green PRs merge within seconds instead of at the next poll; a new PR review or review comment triggers the review-feedback sweep right away. Polling stays on as the default fallback and shares the same idempotent reconcile, so a change is never double-processed. Since Drydock binds `127.0.0.1`, expose the URL through a tunnel (e.g. `cloudflared`, `ngrok`). See [ADR 029](docs/adr/029-webhook-issue-sync.md).
@@ -213,6 +217,10 @@ drydock --version      # installed version
 drydock --port 8080                   # change port (default: 3737)
 # Non-loopback binds require an explicit opt-in because the dashboard has no auth:
 DRYDOCK_ALLOW_REMOTE=1 drydock --host 0.0.0.0 --port 8080
+drydock start          # run as a background daemon, detached from the terminal
+drydock status         # is the daemon running? (pid, url, uptime) — exit 3 when stopped
+drydock stop           # gracefully stop the daemon (drains in-flight jobs)
+drydock restart        # stop then start
 drydock update         # update a global install (reports current → latest, skips if already current)
 drydock backup         # WAL-safe DB snapshot, works while the server runs
 drydock restore <path> # replace the DB with a backup (server must be stopped)
@@ -290,7 +298,7 @@ project; the `drydock` launcher defaults it to `~/.drydock/drydock.db`.
 | `/repos/[id]` | Repo workspace — backlog/queue board with multi-select bulk actions, settings, activity, cost |
 | `/jobs` | Job history — paginated, filterable, searchable |
 | `/jobs/[id]` | Job detail — live streaming log, cost & tokens |
-| `/analytics` | Analytics — merge rate, time-to-merge p50/p90, CI retries, throughput, cost-per-merge, sliceable by repo/date |
+| `/analytics` | Analytics — merge rate, time-to-merge p50/p90, CI retries, throughput, cost-per-merge, sliceable by repo/date and groupable by model, agent, or prompt version |
 | `/prompts` | Versioned prompt editor |
 | `/adrs` | ADR review queue |
 | `/costs` | Cost dashboard — daily, by model, top jobs, CSV/JSON export |
@@ -341,8 +349,10 @@ pnpm mcp            # start the local stdio MCP server (see "MCP server")
 - **Tests never touch the network** — the `claude`/`gh`/`git` CLIs are injected as fakes.
 - **Architecture decisions** live in [`docs/adr/`](docs/adr) (index:
   [`docs/DECISIONS.md`](docs/DECISIONS.md)).
-- CI runs lint, typecheck, tests, and build on Node 20 & 22; CodeQL scans the codebase;
-  Dependabot keeps dependencies and actions current.
+- CI runs across an ubuntu/macOS/windows matrix so the cross-platform daemon lifecycle is
+  exercised on every target OS: ubuntu (Node 20 & 22) and macOS run the full suite, windows
+  runs the daemon lifecycle subset, with lint, typecheck, build, and the standalone smoke test
+  on ubuntu; CodeQL scans the codebase; Dependabot keeps dependencies and actions current.
 
 ## Operations
 
@@ -363,9 +373,20 @@ pnpm mcp            # start the local stdio MCP server (see "MCP server")
   limit). HTTP 200 while the driver loop ticks; 503 when the loop is stalled (no tick
   within 3 poll intervals), not running, or the DB is unreachable. Read-only and
   secret-free, served from a single cheap query set with no forge calls.
+- **Background daemon** — `drydock start` launches the server detached from the terminal and
+  returns immediately, so closing the shell or losing the SSH session no longer kills it.
+  `drydock status` reports whether it is running (pid, url, uptime; exit 3 when stopped),
+  `drydock stop` shuts it down gracefully — draining in-flight jobs first — and `drydock
+  restart` does both. It works identically on macOS, Windows, and Linux: stop asks the server
+  to drain over a loopback control endpoint (the only portable mechanism on Windows, which has
+  no usable POSIX signals) and only falls back to a signal if that endpoint is unreachable.
+  Single-instance: starting while a daemon (or foreground `drydock`) already runs is refused,
+  and a stale state file left by a crash is taken over. Daemon state lives in
+  `<data dir>/daemon.json` and the detached process logs to `<data dir>/drydock.log`.
 - **Run at login** — `drydock service install` generates and loads a launchd agent (macOS)
   or systemd user unit (Linux) that runs `drydock serve` at login and restarts it on
-  crashes; `drydock service uninstall` removes it again.
+  crashes; `drydock service uninstall` removes it again. (For an ad-hoc background run without
+  a login service, use `drydock start`.)
 - **Retention & pruning** — finished jobs' verbose log events are pruned past the
   **log retention** window (default 30 days; cost summary rows are kept). A daily in-process
   sweep runs automatically; for a manual run use `pnpm db:prune [--days <n>] [--no-vacuum]`,

package/bin/daemon.mjs

@@ -0,0 +1,451 @@
+// Daemon lifecycle for the packaged Drydock CLI (issue #216): start/stop/status/
+// restart run the server as a long-lived background process so it keeps working
+// through issues after the terminal closes. Like ops.mjs this is plain ESM under
+// bin/ (which ships in the npm tarball) with no build step; command functions
+// take their I/O and OS primitives as injected deps and return an exit code
+// instead of calling process.exit, so the cross-platform logic stays unit- and
+// integration-testable. bin/drydock.mjs owns the process boundary.
+//
+// Cross-platform stop is the subtle part. POSIX signals are unreliable on
+// Windows (SIGTERM is a hard TerminateProcess, never a graceful drain), so the
+// primary stop path asks the running server to drain over HTTP via the control
+// endpoint (src/app/api/control/shutdown). Signals are only a fallback when that
+// endpoint is unreachable.
+
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import {
+  closeSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { readLockState } from "./ops.mjs";
+
+/**
+ * Directory holding Drydock's local state. Mirrors bin/drydock.mjs's
+ * resolveDataDir so the daemon's bookkeeping lands beside the database.
+ *
+ * @param {{ env?: Record<string, string | undefined>, home?: string }} [opts]
+ */
+function resolveDataDir({ env = process.env, home = homedir() } = {}) {
+  const override = env.DRYDOCK_DATA_DIR?.trim();
+  return override ? override : join(home, ".drydock");
+}
+
+/**
+ * Path of the daemon state file: the CLI's record of the detached process (pid,
+ * host, port, control token, start time) so later `status`/`stop` invocations
+ * can find and signal it.
+ *
+ * @param {{ env?: Record<string, string | undefined>, home?: string }} [opts]
+ */
+export function resolveDaemonStatePath(opts = {}) {
+  return join(resolveDataDir(opts), "daemon.json");
+}
+
+/**
+ * Path the detached server's stdout/stderr is redirected to, so the operator can
+ * read logs without a terminal attached.
+ *
+ * @param {{ env?: Record<string, string | undefined>, home?: string }} [opts]
+ */
+export function resolveDaemonLogPath(opts = {}) {
+  return join(resolveDataDir(opts), "drydock.log");
+}
+
+/**
+ * @typedef {{ pid: number, host: string, port: number, token: string,
+ *             startedAt: number, logFile: string }} DaemonState
+ */
+
+/**
+ * Read the daemon state file. Returns null when it is absent, unreadable,
+ * corrupt, or missing a valid pid — every caller treats a null state as "no
+ * daemon recorded", never as an error.
+ *
+ * @param {string} path
+ * @returns {DaemonState | null}
+ */
+export function readDaemonState(path) {
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    const { pid } = parsed;
+    if (!Number.isInteger(pid) || pid <= 0) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Atomically write the daemon state file with owner-only permissions: it holds
+ * the control token, so it must not be world-readable. Writing to a temp file
+ * and renaming means a crash mid-write never leaves a torn record.
+ *
+ * @param {string} path
+ * @param {DaemonState} state
+ */
+export function writeDaemonState(path, state) {
+  mkdirSync(dirname(path), { recursive: true });
+  // Open with an explicit 0o600 mode rather than writeFileSync: that keeps the
+  // token-bearing file owner-only without depending on the process umask.
+  const tmp = `${path}.tmp`;
+  const fd = openSync(tmp, "w", 0o600);
+  try {
+    writeSync(fd, JSON.stringify(state));
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(tmp, path);
+}
+
+/** Remove the daemon state file; absent is success. @param {string} path */
+export function clearDaemonState(path) {
+  rmSync(path, { force: true });
+}
+
+/** Cryptographically-random control token for the shutdown endpoint. */
+function defaultGenerateToken() {
+  return randomBytes(24).toString("hex");
+}
+
+/** @param {number} pid */
+function defaultPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM means the process exists but we may not signal it — still alive.
+    return err && typeof err === "object" && err.code === "EPERM";
+  }
+}
+
+/**
+ * Human-readable uptime: "1h 2m 3s", dropping leading zero units but always
+ * keeping seconds so a fresh start still reads "0s".
+ *
+ * @param {number} ms
+ */
+export function formatUptime(ms) {
+  const total = Math.max(0, Math.floor(ms / 1000));
+  const h = Math.floor(total / 3600);
+  const m = Math.floor((total % 3600) / 60);
+  const s = total % 60;
+  const parts = [];
+  if (h > 0) parts.push(`${h}h`);
+  if (h > 0 || m > 0) parts.push(`${m}m`);
+  parts.push(`${s}s`);
+  return parts.join(" ");
+}
+
+/**
+ * @typedef {{ running: boolean, stale?: boolean, pid?: number, host?: string,
+ *             port?: number, url?: string, startedAt?: number, uptimeMs?: number }} DaemonStatus
+ */
+
+/**
+ * Derive a status view from the state file and a liveness probe. A state file
+ * whose pid is dead is "stale" (a crash left it behind), not running.
+ *
+ * @param {DaemonState | null} state
+ * @param {{ pidAlive: (pid: number) => boolean, now: () => number }} deps
+ * @returns {DaemonStatus}
+ */
+export function describeStatus(state, { pidAlive, now }) {
+  if (!state) return { running: false };
+  if (!pidAlive(state.pid)) return { running: false, stale: true, pid: state.pid };
+  return {
+    running: true,
+    pid: state.pid,
+    host: state.host,
+    port: state.port,
+    url: `http://${state.host}:${state.port}`,
+    startedAt: state.startedAt,
+    uptimeMs: now() - state.startedAt,
+  };
+}
+
+/** Render a status view as the lines `drydock status` prints. */
+function formatStatus(status) {
+  if (!status.running) {
+    if (status.stale) {
+      return `Drydock is not running (stale state file for pid ${status.pid}).`;
+    }
+    return "Drydock is not running.";
+  }
+  return [
+    "Drydock is running.",
+    `  pid:    ${status.pid}`,
+    `  url:    ${status.url}`,
+    `  uptime: ${formatUptime(status.uptimeMs)}`,
+  ].join("\n");
+}
+
+/**
+ * Default server command: launch the bundled launcher's `serve` mode. The
+ * child re-enters bin/drydock.mjs, which boots the standalone Next server and
+ * forwards the control token through to it.
+ *
+ * @param {{ host: string, port: number, packageRoot: string }} opts
+ * @returns {{ command: string, args: string[] }}
+ */
+function defaultServerCommand({ host, port, packageRoot }) {
+  return {
+    command: process.execPath,
+    args: [
+      join(packageRoot, "bin", "drydock.mjs"),
+      "serve",
+      "--host",
+      host,
+      "--port",
+      String(port),
+    ],
+  };
+}
+
+/**
+ * `drydock start`: launch the server detached from the terminal and return
+ * immediately. Refuses if a daemon (or a foreground instance holding the lock)
+ * is already running, and takes over a stale state file left by a crash. The
+ * child is unref'd and its stdio redirected to the log file so it survives the
+ * parent shell closing on every OS.
+ *
+ * @param {{ host: string, port: number }} opts
+ * @param {object} deps
+ * @returns {number} exit code
+ */
+export function runStartCommand(
+  { host, port },
+  {
+    statePath,
+    logPath,
+    lockPath,
+    dataDir,
+    packageRoot,
+    now = () => Date.now(),
+    generateToken = defaultGenerateToken,
+    pidAlive = defaultPidAlive,
+    readLock = (p) => readLockState(p),
+    openAppendFd = (p) => openSync(p, "a"),
+    closeFd = (fd) => closeSync(fd),
+    spawnImpl = spawn,
+    buildServerCommand = defaultServerCommand,
+    log = console.log,
+    error = console.error,
+  },
+) {
+  const existing = readDaemonState(statePath);
+  if (existing && pidAlive(existing.pid)) {
+    error(
+      `Drydock is already running (pid ${existing.pid}) on http://${existing.host}:${existing.port}.`,
+    );
+    return 1;
+  }
+
+  // A foreground `drydock` (no daemon state) would still hold the instance lock;
+  // refuse rather than racing it for the port.
+  const lock = readLock(lockPath);
+  if (lock.state === "held") {
+    error(
+      `Drydock is already running (pid ${lock.pid ?? "unknown"}); stop it before starting a daemon.`,
+    );
+    return 1;
+  }
+
+  if (existing) {
+    log(`Removing stale daemon state for dead pid ${existing.pid}.`);
+    clearDaemonState(statePath);
+  }
+
+  mkdirSync(dataDir, { recursive: true });
+  mkdirSync(dirname(logPath), { recursive: true });
+
+  const token = generateToken();
+  const { command, args } = buildServerCommand({ host, port, packageRoot });
+
+  const logFd = openAppendFd(logPath);
+  let child;
+  try {
+    child = spawnImpl(command, args, {
+      cwd: packageRoot,
+      env: { ...process.env, DRYDOCK_CONTROL_TOKEN: token },
+      detached: true,
+      windowsHide: true,
+      stdio: ["ignore", logFd, logFd],
+    });
+  } finally {
+    // The child duplicated the fd; the parent must close its copy so the log
+    // file isn't held open after start returns.
+    closeFd(logFd);
+  }
+
+  child.unref();
+
+  writeDaemonState(statePath, {
+    pid: child.pid,
+    host,
+    port,
+    token,
+    startedAt: now(),
+    logFile: logPath,
+  });
+
+  log(`Drydock started (pid ${child.pid}) on http://${host}:${port}. Logs: ${logPath}`);
+  return 0;
+}
+
+const DEFAULT_STOP_TIMEOUT_MS = 15_000;
+/** Grace given to a graceful drain (HTTP control or SIGTERM) before escalating. */
+const SIGKILL_GRACE_MS = 5_000;
+
+/**
+ * Poll `pidAlive(pid)` until it reports dead or the budget runs out. Bounded by
+ * a fixed iteration count (timeout / poll interval) rather than wall-clock time
+ * so the wait is deterministic and the injected `sleep` can be a no-op in tests.
+ *
+ * @returns {Promise<boolean>} true once the process is gone, false on timeout.
+ */
+async function waitForExit(pid, { pidAlive, sleep, pollMs, timeoutMs }) {
+  const iterations = Math.max(1, Math.ceil(timeoutMs / pollMs));
+  for (let i = 0; i < iterations; i++) {
+    if (!pidAlive(pid)) return true;
+    await sleep(pollMs);
+  }
+  return !pidAlive(pid);
+}
+
+/**
+ * `drydock stop`: stop a running daemon, gracefully on every OS. Asks the server
+ * to drain over the HTTP control endpoint first (the only portable mechanism on
+ * Windows); falls back to SIGTERM→SIGKILL on POSIX, or a hard terminate on
+ * Windows, only when that endpoint is unreachable. Idempotent: stopping when
+ * nothing runs (or only a stale state file remains) succeeds.
+ *
+ * @param {{}} _opts
+ * @param {object} deps
+ * @returns {Promise<number>} exit code
+ */
+export async function runStopCommand(
+  _opts,
+  {
+    statePath,
+    platform = process.platform,
+    timeoutMs = DEFAULT_STOP_TIMEOUT_MS,
+    pollMs = 200,
+    sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+    pidAlive = defaultPidAlive,
+    killImpl = (pid, signal) => process.kill(pid, signal),
+    fetchImpl = fetch,
+    log = console.log,
+    error = console.error,
+  },
+) {
+  const state = readDaemonState(statePath);
+  if (!state) {
+    log("Drydock is not running.");
+    return 0;
+  }
+  if (!pidAlive(state.pid)) {
+    clearDaemonState(statePath);
+    log("Drydock is not running (removed stale state).");
+    return 0;
+  }
+
+  // Primary, portable path: ask the server to drain and exit over HTTP.
+  let drainRequested = false;
+  try {
+    const res = await fetchImpl(`http://${state.host}:${state.port}/api/control/shutdown`, {
+      method: "POST",
+      headers: { "x-drydock-control-token": state.token },
+    });
+    drainRequested = Boolean(res?.ok);
+  } catch {
+    drainRequested = false;
+  }
+
+  // Signal fallback only when the control endpoint did not accept the request.
+  if (!drainRequested) {
+    if (platform === "win32") {
+      // No usable POSIX signal; a hard terminate is the only option left.
+      error("Control endpoint unreachable; terminating the process (drain not guaranteed).");
+      safeKill(killImpl, state.pid, undefined, error);
+    } else {
+      safeKill(killImpl, state.pid, "SIGTERM", error);
+    }
+  }
+
+  const exited = await waitForExit(state.pid, { pidAlive, sleep, pollMs, timeoutMs });
+
+  if (!exited) {
+    // Last resort: escalate. SIGKILL on POSIX, another hard terminate on Windows.
+    safeKill(killImpl, state.pid, platform === "win32" ? undefined : "SIGKILL", error);
+    const killed = await waitForExit(state.pid, {
+      pidAlive,
+      sleep,
+      pollMs,
+      timeoutMs: SIGKILL_GRACE_MS,
+    });
+    if (!killed) {
+      error(`Failed to stop Drydock (pid ${state.pid}); it is still running.`);
+      return 1;
+    }
+  }
+
+  clearDaemonState(statePath);
+  log("Drydock stopped.");
+  return 0;
+}
+
+/** Kill that swallows ESRCH (already gone) and reports anything else. */
+function safeKill(killImpl, pid, signal, error) {
+  try {
+    killImpl(pid, signal);
+  } catch (err) {
+    if (err && typeof err === "object" && err.code === "ESRCH") return;
+    error(`Signal to pid ${pid} failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+/**
+ * `drydock status`: report whether the daemon is running, with pid, URL, and
+ * uptime. Exit 0 when running, 3 (the systemd "program not running" convention)
+ * when stopped or stale, so the command is scriptable.
+ *
+ * @param {{}} _opts
+ * @param {object} deps
+ * @returns {number} exit code
+ */
+export function runStatusCommand(
+  _opts,
+  { statePath, pidAlive = defaultPidAlive, now = () => Date.now(), log = console.log },
+) {
+  const status = describeStatus(readDaemonState(statePath), { pidAlive, now });
+  log(formatStatus(status));
+  return status.running ? 0 : 3;
+}
+
+/**
+ * `drydock restart`: stop any running daemon, then start a fresh one. A failed
+ * stop aborts the restart so a still-running instance is never double-started.
+ *
+ * @param {{ host: string, port: number }} opts
+ * @param {object} deps Shared deps forwarded to stop and start.
+ * @returns {Promise<number>} exit code
+ */
+export async function runRestartCommand(opts, deps) {
+  const stopCode = await runStopCommand({}, deps);
+  if (stopCode !== 0) return stopCode;
+  return runStartCommand(opts, deps);
+}

package/bin/drydock.mjs

@@ -90,10 +90,35 @@ export function parseArgs(argv) {
     return { mode: "service", action };
   }
 
+  // Daemon lifecycle (issue #216). `start`/`restart` launch the background
+  // server and accept the same host/port flags as `serve` (but not `--open`,
+  // since a detached daemon has no terminal to open a browser from). `stop` and
+  // `status` operate on the recorded daemon, so they take no flags.
+  if (argv[0] === "start" || argv[0] === "restart") {
+    const { host, port } = parseHostPort(argv.slice(1));
+    return { mode: argv[0], host, port };
+  }
+  if (argv[0] === "stop" || argv[0] === "status") {
+    if (argv.length > 1) throw new Error(`unexpected argument: ${argv[1]}`);
+    return { mode: argv[0] };
+  }
+
   // `drydock serve` is an explicit alias for the default mode so scripts and
   // service units can spell out what they launch.
   const flags = argv[0] === "serve" ? argv.slice(1) : argv;
+  const { host, port, open } = parseHostPort(flags, { allowOpen: true });
+  return { mode: "serve", host, port, open };
+}
 
+/**
+ * Parse the shared `--host`/`--port` (and optionally `--open`) flags into a
+ * directive fragment. Throws on unknown options or stray positional arguments so
+ * each command surfaces the same error messages.
+ *
+ * @param {string[]} flags
+ * @param {{ allowOpen?: boolean }} [opts]
+ */
+function parseHostPort(flags, { allowOpen = false } = {}) {
   let host = DEFAULT_HOST;
   let port = DEFAULT_PORT;
   let open = false;
@@ -101,7 +126,7 @@ export function parseArgs(argv) {
   for (let i = 0; i < flags.length; i++) {
     const arg = flags[i];
 
-    if (arg === "--open") {
+    if (allowOpen && arg === "--open") {
       open = true;
       continue;
     }
@@ -128,7 +153,7 @@ export function parseArgs(argv) {
     throw new Error(`unexpected argument: ${arg}`);
   }
 
-  return { mode: "serve", host, port, open };
+  return { host, port, open };
 }
 
 function parsePort(raw) {
@@ -164,8 +189,12 @@ export function resolveDbPath({ env = process.env, home = homedir() } = {}) {
 const HELP = `drydock — autonomously turn GitHub issues into pull requests
 
 Usage:
-  drydock [options]      Start the server and dashboard
+  drydock [options]      Start the server and dashboard (foreground)
   drydock serve          Same as running with no subcommand
+  drydock start          Launch the server as a background daemon and return
+  drydock stop           Gracefully stop the background daemon (drains in-flight jobs)
+  drydock status         Report whether the daemon is running (pid, url, uptime)
+  drydock restart        Stop the daemon if running, then start a fresh one
   drydock update         Update to the latest published version
   drydock backup [path]  Snapshot the database (WAL-safe, works while running);
                          default target: <data dir>/backups/drydock-<timestamp>.db
@@ -450,11 +479,49 @@ async function main(argv) {
       );
       return;
     }
+    case "start": {
+      const { runStartCommand } = await import("./daemon.mjs");
+      process.exit(runStartCommand(directive, await daemonDeps()));
+      return;
+    }
+    case "stop": {
+      const { runStopCommand } = await import("./daemon.mjs");
+      process.exit(await runStopCommand(directive, await daemonDeps()));
+      return;
+    }
+    case "status": {
+      const { runStatusCommand } = await import("./daemon.mjs");
+      process.exit(runStatusCommand(directive, await daemonDeps()));
+      return;
+    }
+    case "restart": {
+      const { runRestartCommand } = await import("./daemon.mjs");
+      process.exit(await runRestartCommand(directive, await daemonDeps()));
+      return;
+    }
     default:
       await serve(directive);
   }
 }
 
+/**
+ * Concrete dependencies for the daemon lifecycle commands, resolved against this
+ * install's data dir and package root. Bundled here (rather than inside
+ * daemon.mjs) so the daemon module stays free of process-level state and fully
+ * injectable in tests.
+ */
+async function daemonDeps() {
+  const { resolveDaemonLogPath, resolveDaemonStatePath } = await import("./daemon.mjs");
+  const { resolveLockPath } = await import("./ops.mjs");
+  return {
+    statePath: resolveDaemonStatePath(),
+    logPath: resolveDaemonLogPath(),
+    lockPath: resolveLockPath(),
+    dataDir: resolveDataDir(),
+    packageRoot: PACKAGE_ROOT,
+  };
+}
+
 /**
  * Decide whether this module is the program entry point. A plain string compare
  * against `process.argv[1]` breaks for global/npx installs, where the bin is a

package/drizzle/0030_implement_prompt_version.sql

@@ -0,0 +1 @@
+ALTER TABLE `jobs` ADD COLUMN `implement_prompt_version` integer;

package/drizzle/0031_merge_without_checks.sql

@@ -0,0 +1 @@
+ALTER TABLE `repos` ADD COLUMN `merge_without_checks` integer NOT NULL DEFAULT 0;

package/drizzle/0032_default_review_feedback.sql

@@ -0,0 +1,6 @@
+-- issue #213: default review feedback ON for autonomous operation.
+-- Backfill existing repos that still hold the legacy defaults; rows already
+-- customized by the user are matched out and left untouched.
+UPDATE `repos` SET `auto_review_feedback` = 1 WHERE `auto_review_feedback` = 0;
+--> statement-breakpoint
+UPDATE `repos` SET `trusted_bots` = '["cursor[bot]","coderabbitai[bot]"]' WHERE `trusted_bots` = '[]';

package/drizzle/0033_sandbox.sql

@@ -0,0 +1,5 @@
+ALTER TABLE `repos` ADD COLUMN `sandbox` text NOT NULL DEFAULT 'none';--> statement-breakpoint
+ALTER TABLE `repos` ADD COLUMN `sandbox_image` text;--> statement-breakpoint
+ALTER TABLE `repos` ADD COLUMN `sandbox_allow_network` integer NOT NULL DEFAULT 0;--> statement-breakpoint
+ALTER TABLE `repos` ADD COLUMN `sandbox_cpus` text;--> statement-breakpoint
+ALTER TABLE `repos` ADD COLUMN `sandbox_memory` text;