dockhand-cli 0.3.1__tar.gz → 0.4.0__tar.gz

dockhand_cli-0.4.0/.github/workflows/publish.yml

@@ -0,0 +1,16 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # required for PyPI trusted publishing (OIDC) - no token needed
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv build
+      - run: uv publish

{dockhand_cli-0.3.1 → dockhand_cli-0.4.0}/AGENTS.md

@@ -42,6 +42,12 @@ uv run ruff format .
 uv run ruff check --fix .
 ```
 
+**Build / release:**
+The PyPI distribution is named `dockhand-cli` (the `dockhand` name is taken); the installed command and import package are still `dockhand`. Version lives in `pyproject.toml`. Publishing a GitHub release triggers `.github/workflows/publish.yml`, which runs `uv build && uv publish` via PyPI trusted publishing (OIDC, no API token). Pushing to `main` alone publishes nothing.
+```bash
+uv build   # local sanity check; artifacts land in dist/
+```
+
 ## Architecture
 
 ### Entry Point
@@ -52,6 +58,7 @@ uv run ruff check --fix .
 - `dockhand run` — queue/run from an already-built image, no sync
 - `dockhand install` — build the image only
 - `dockhand logs`, `stop`, `remove`, `jobs`, `urgent`, `prune` — job/queue lifecycle (`manage.py` + `queue.py`)
+  - `jobs` shows this project's last 30 active jobs; `--all` lifts the cap and includes finished/failed/stopped; `--queue` shows the host's whole task-spooler queue, including other projects' jobs
 - `dockhand history` — show past runs
 - `dockhand volumes`, `download` — inspect and pull files from mounted volumes
 - `dockhand resubmit` — rerun a past job with optional overrides
@@ -76,10 +83,10 @@ Config file: `.dockhand.json` in the project root (must also contain a `.git`
 ### Key Modules
 - `submit.py` — Builds the `docker run` command (code mount vs. data volumes vs. GPU/port flags), resolves code delivery, and hands off to a transport to start the job.
 - `build.py` — Runs `docker build` on the client (optionally syncing first).
-- `manage.py` — Job lifecycle: `logs`, `stop`, `remove`, `jobs` (`execute_stats`), and `prune` (removes baked images no longer referenced by an active job).
+- `manage.py` — Job lifecycle: `logs`, `stop`, `remove`, `jobs` (`execute_stats`), `jobs --queue` (`execute_queue`), and `prune` (removes baked images no longer referenced by an active job). Also owns job timing (`_observe_job_time`, `_docker_started_at`, `_host_now`).
 - `resubmit.py` — Looks up a history entry and re-invokes `execute_submit` with overrides; pins to the original baked image when applicable.
-- `queue.py` — Task spooler (`tsp`) integration: submit/list/promote/remove/kill, plus `ts -l` output parsing.
-- `transport.py` — Abstracts "how a job runs": `TaskSpoolerTransport` (queue enabled) vs. `DockerTransport` (direct `docker run -d`). Both expose the same interface (`submit`, `list_jobs`, `logs`, `stop`, `remove`) so job-management commands don't care which backend created a job; the transport used is recorded per job in history.
+- `queue.py` — Task spooler (`tsp`) integration: submit/list/promote/remove/kill, `tsp -l` output parsing, max slot count (`ts_max_slots`), and start times from `tsp -i` (`ts_start_times`).
+- `transport.py` — Abstracts "how a job runs": `TaskSpoolerTransport` (queue enabled) vs. `DockerTransport` (direct `docker run -d`). Both expose the same interface (`run_flags`, `submit`, `list_jobs`, `container_name`, `logs`, `stop`, `remove`) so job-management commands don't care which backend created a job; the transport used is recorded per job in history. Containers are named `dockhand-<local_id>` in both modes (queued: `--rm --name`; direct: `-d --name`, no `--rm` so logs survive exit).
 - `tagging.py` — Resolves the image tag/ref for baked code delivery (content-addressed from git commit + dirty-state hash; unique per queued submit, reused for direct runs).
 - `history.py` — Reads/writes `.dockhand_history.json`, reserves/looks up local job IDs.
 - `volumes.py` — Lists the container filesystem as a tree (code mount + data volumes) and resolves a workdir-relative path back to its host path.
@@ -111,28 +118,36 @@ Stores container runs in `.dockhand_history.json` as JSON. Each entry contains:
   "handle": 12,                  // tsp job id, or container name for direct runs
   "ts_job_id": 12,                // task_spooler transport only
   "host": "remote.example.com",   // or "localhost"
-  "started_at": 1234567891.0,     // optional, set the first time `jobs` observes it running
-  "ended_at": 1234567895.0        // optional, set the first time `jobs` observes it finished/failed/stopped
+  "started_at": 1234567891.0,     // optional, set when `jobs`/`logs` first sees it running
+  "ended_at": 1234567895.0,       // optional, set when `jobs`/`logs` first sees it finished/failed/stopped
+  "stopped": true                 // optional, set by `dockhand stop`; shows finished/failed as "stopped"
 }
 ```
 
 Used by `resubmit` (look up a previous run and re-run with overrides, pinning the original baked image when unchanged), `logs`, `stop`, `remove`, `jobs`, `urgent`, `prune` (default to latest if no ID given). Job-management commands dispatch to the transport recorded on the entry (`transport_for_entry`), so `logs`/`stop`/`remove` work the same regardless of whether a job went through the queue or ran directly.
 
-`started_at`/`ended_at` aren't queried from tsp/docker (neither exposes exact start/end timestamps cheaply for both transports) — `jobs` and `logs` each stamp them lazily the first time they happen to observe a job in the running/terminal state, so a job never checked on while running will show no start time once it finishes. `dockhand jobs` displays these as Started/Ended (absolute, `%Y-%m-%d %H:%M:%S`) and Duration (elapsed while running, total once finished) columns; `dockhand logs` prints a one-line "running for Xm" / "finished in Xm" header before the log output.
+`started_at`/`ended_at` are written the first time `jobs` or `logs` observes a job in the running/terminal state (`_observe_job_time`), but the values come from docker/ts, not the observation time:
+- `started_at` — the container's real `docker inspect .State.StartedAt` (found via the `dockhand-<local_id>` name). Falls back to "now" only if the container can't be inspected (pre-naming jobs, already removed).
+- `ended_at` — `started_at + duration_seconds` from ts's own elapsed-time field when available, else "now".
+- Running durations are measured against the host clock (`_host_now` runs `date +%s` on the host) so local/host clock skew doesn't distort them.
+
+`dockhand jobs` shows Started/Ended (absolute, `%Y-%m-%d %H:%M:%S`) and Duration columns, grouped running → queued → finished/failed/stopped, newest ID first within each group. `dockhand logs` prints a one-line "running for Xm" / "finished in Xm" header before the log output.
+
+`dockhand jobs --queue` bypasses history entirely: it prints the raw host-wide `tsp -l` queue (ts is one shared queue per host), with each job's dockhand ID parsed from its `dockhand-<n>` container name, a project column from the image name, start times from `tsp -i`, and a "N running / M slots, K queued" footer.
 
 ### Design Patterns
 
 **DockerDefault factory:**
-In `__init__.py`, `DockerDefault` is a callable factory that pulls defaults from `cli_config.docker` at call time. Enables Typer's `default_factory` to respect active profiles.
+In `__init__.py`, `DockerDefault` is a callable factory that pulls defaults from `cli_config.docker` at call time (after the `--profile` callback has run), for use with Typer's `default_factory`. `SyncDefault` does the same for `cli_config.sync`.
 
 **Transport abstraction:**
-`get_transport()` in `transport.py` picks `TaskSpoolerTransport` or `DockerTransport` based on `cli_config.queue.enabled` at submit time. Every job-management command re-derives the correct transport per-job from the history entry (`transport_for_entry`) rather than from current config, so switching `queue.enabled` doesn't strand in-flight jobs from the other mode.
+`get_transport()` in `transport.py` picks `TaskSpoolerTransport` or `DockerTransport` based on `cli_config.queue.enabled` at submit time. Per-job commands (`logs`, `stop`, `remove`, `urgent`) re-derive the transport from the history entry (`transport_for_entry`; entries without a `transport` field are treated as task spooler), and `logs`/`stop`/`remove` also connect to the entry's recorded `host`. The exception is `jobs`, which lists via the *current* config's transport and host.
 
 **Code delivery resolution:**
 `DockerConfig.resolve_code_delivery(queue_enabled)` picks `mount` or `bake` when `code_delivery` isn't explicitly set: `bake` when the queue is enabled (avoids code drift while a job waits in queue), `mount` otherwise (zero-rebuild iteration). See README's [Code delivery](README.md#code-delivery-mount-vs-bake) section for the full rationale.
 
 **Profile support:**
-`cli_config.load_profile(name)` loads overrides from `.dockhand.json` profiles section (currently merges `history_path`, `remote_path`, `ssh`). All config classes support `validate()` for safe merging.
+`cli_config.load_profile(name)` loads overrides from `.dockhand.json` profiles section. It only merges `history_path`, `remote_path` and `ssh` — `docker`, `queue` and `sync` keys in a profile are silently ignored. `SSHConfig.validate()` is used for safe merging of partial ssh overrides.
 
 **Command structure:**
 Each command:
@@ -155,7 +170,7 @@ Each command:
 | `__init__.py` | CLI app definition, command routing, config defaults |
 | `submit.py` | Builds the `docker run` command, resolves code delivery, submits via transport |
 | `build.py` | `docker build` execution |
-| `manage.py` | `logs`, `stop`, `remove`, `jobs`, `prune` |
+| `manage.py` | `logs`, `stop`, `remove`, `jobs`, `jobs --queue`, `prune`, job timing |
 | `resubmit.py` | Rerun a past job with overrides |
 | `queue.py` | Task spooler (`tsp`) integration |
 | `transport.py` | Task-spooler vs. direct-docker execution backends |
@@ -172,6 +187,7 @@ Each command:
 | `sync.py` | rsync-based code synchronization |
 | `error.py` | Error reporting |
 | `constants.py` | Config/history file names |
+| `.github/workflows/publish.yml` | Publish `dockhand-cli` to PyPI on GitHub release |
 
 ## Configuration Format
 
@@ -207,11 +223,9 @@ Each command:
   },
   "remote_path": "~/my-project",
   "profiles": {
-    "dev": {
-      "docker": {
-        "gpus": "1",
-        "dockerfile": "Dockerfile.dev"
-      }
+    "gpu2": {
+      "ssh": { "hostname": "gpu2.example.com" },
+      "remote_path": "~/my-project-gpu2"
     }
   }
 }
@@ -242,13 +256,14 @@ uv run dockhand run 'bash'                           # Run interactively
 
 **Using profiles:**
 ```bash
-uv run dockhand --profile dev submit 'python train.py'   # Use dev profile
-uv run dockhand --profile prod install                   # Build prod image
+uv run dockhand --profile gpu2 install                    # Build on the gpu2 host
+uv run dockhand --profile gpu2 submit 'python train.py'  # Run there
 ```
 
 **Queue management:**
 ```bash
 uv run dockhand jobs                  # List active jobs
+uv run dockhand jobs --queue          # Whole host queue, all projects, with slot usage
 uv run dockhand urgent 5               # Promote job #5 to front of queue
 uv run dockhand prune --dry-run        # Preview unused baked images before removing
 ```
@@ -269,7 +284,7 @@ uv run ruff format --check .   # Format check
 2. **SSH by default** — Assumes docker host is remote. Auto-detects local by resolving the configured hostname to a loopback address.
 3. **History in JSON** — Simple, human-readable, easily editable.
 4. **Profile support** — Allows per-project config variants.
-5. **Minimal dependencies** — typer, fabric, paramiko, gitpython, rich.
+5. **Minimal dependencies** — typer, fabric, paramiko, gitpython (rich comes in via typer).
 6. **Transport abstraction over queue state** — job-management commands read the transport from each job's own history entry rather than current `queue.enabled`, so toggling the queue mid-flight doesn't orphan existing jobs.
 7. **Code-delivery default follows queue mode** — `bake` when queued (avoids code drift while waiting), `mount` when not (zero-rebuild iteration); explicit `code_delivery` overrides either way.
 

{dockhand_cli-0.3.1 → dockhand_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dockhand-cli
-Version: 0.3.1
+Version: 0.4.0
 Summary: CLI for managing Docker containers on remote machines
 Project-URL: Repository, https://github.com/NicholasPHansen/dockhand
 Author: Nicholas P. Hansen
@@ -108,7 +108,7 @@ All commands work with the same `.dockhand.json` configuration file. See [Config
 | `submit` | Build the image and queue a container run |
 | `run` | Queue a container run from an already-built image |
 | `install` | Build the Docker image without running it |
-| `jobs` | List active (running/queued) jobs, with start/end/duration — use `--all` for finished jobs too |
+| `jobs` | List active (running/queued) jobs, with start/end/duration — use `--all` for finished jobs too, or `--queue` for the host's whole task-spooler queue across all projects |
 | `logs` | Show logs from a job, preceded by a running/finished duration line — use `--follow`/`-f` to stream live |
 | `stop` | Stop a **running** job |
 | `remove` | Remove a **queued** job before it starts |
@@ -164,6 +164,9 @@ dockhand jobs
 # Check all jobs including finished
 dockhand jobs --all
 
+# Show the host's whole task-spooler queue, including other projects' jobs
+dockhand jobs --queue
+
 # Stream logs from the last job
 dockhand logs --follow
 
@@ -198,10 +201,23 @@ dockhand resubmit --gpus 2
 **Note:** If you've installed dockhand globally, you can omit `uv run`.
 
 `jobs` shows Started/Ended/Duration for each job, and `logs` prints a one-line
-`running for 5m30s` / `finished in 12m45s` header before the log output. Neither the
-queue nor docker exposes exact start/end timestamps cheaply, so these are recorded the
-first time `jobs` or `logs` happens to observe a job as running or finished — a job
-never checked on while running will show no duration once it's done.
+`running for 5m30s` / `finished in 12m45s` header before the log output. Start times come
+from the container's `docker inspect` and finished durations from task spooler itself, so
+they're exact no matter when you check (older jobs from before container naming fall back
+to the time they were first observed). A running job's elapsed time is measured against the
+host's clock, so clock skew between your machine and the host doesn't distort it (keep the
+host's clock NTP-synced, though — Started/Ended are shown in the host's time).
+
+`jobs --queue` lists every job in the host's task-spooler queue, not just this project's:
+
+| Column | Meaning |
+|--------|---------|
+| `ID` | dockhand job ID in the submitting project — what `logs`/`stop`/`urgent` take there (`-` for jobs submitted before dockhand named its containers) |
+| `Project` | Image the job runs (the project's `imagename`) |
+| `Status` / `Started` / `Duration` | From task spooler (`tsp -l`, `tsp -i`), measured on the host's clock |
+| `TS ID` | Task spooler's own job ID, for use with `tsp` directly |
+
+Running and queued jobs come first (queued in queue order), then the rest newest-started first.
 
 Resubmitting a job that ran in [`bake`](#code-delivery-mount-vs-bake) mode reruns the exact
 image it originally built — recorded per job — rather than rebuilding from current code, so a

{dockhand_cli-0.3.1 → dockhand_cli-0.4.0}/README.md

@@ -91,7 +91,7 @@ All commands work with the same `.dockhand.json` configuration file. See [Config
 | `submit` | Build the image and queue a container run |
 | `run` | Queue a container run from an already-built image |
 | `install` | Build the Docker image without running it |
-| `jobs` | List active (running/queued) jobs, with start/end/duration — use `--all` for finished jobs too |
+| `jobs` | List active (running/queued) jobs, with start/end/duration — use `--all` for finished jobs too, or `--queue` for the host's whole task-spooler queue across all projects |
 | `logs` | Show logs from a job, preceded by a running/finished duration line — use `--follow`/`-f` to stream live |
 | `stop` | Stop a **running** job |
 | `remove` | Remove a **queued** job before it starts |
@@ -147,6 +147,9 @@ dockhand jobs
 # Check all jobs including finished
 dockhand jobs --all
 
+# Show the host's whole task-spooler queue, including other projects' jobs
+dockhand jobs --queue
+
 # Stream logs from the last job
 dockhand logs --follow
 
@@ -181,10 +184,23 @@ dockhand resubmit --gpus 2
 **Note:** If you've installed dockhand globally, you can omit `uv run`.
 
 `jobs` shows Started/Ended/Duration for each job, and `logs` prints a one-line
-`running for 5m30s` / `finished in 12m45s` header before the log output. Neither the
-queue nor docker exposes exact start/end timestamps cheaply, so these are recorded the
-first time `jobs` or `logs` happens to observe a job as running or finished — a job
-never checked on while running will show no duration once it's done.
+`running for 5m30s` / `finished in 12m45s` header before the log output. Start times come
+from the container's `docker inspect` and finished durations from task spooler itself, so
+they're exact no matter when you check (older jobs from before container naming fall back
+to the time they were first observed). A running job's elapsed time is measured against the
+host's clock, so clock skew between your machine and the host doesn't distort it (keep the
+host's clock NTP-synced, though — Started/Ended are shown in the host's time).
+
+`jobs --queue` lists every job in the host's task-spooler queue, not just this project's:
+
+| Column | Meaning |
+|--------|---------|
+| `ID` | dockhand job ID in the submitting project — what `logs`/`stop`/`urgent` take there (`-` for jobs submitted before dockhand named its containers) |
+| `Project` | Image the job runs (the project's `imagename`) |
+| `Status` / `Started` / `Duration` | From task spooler (`tsp -l`, `tsp -i`), measured on the host's clock |
+| `TS ID` | Task spooler's own job ID, for use with `tsp` directly |
+
+Running and queued jobs come first (queued in queue order), then the rest newest-started first.
 
 Resubmitting a job that ran in [`bake`](#code-delivery-mount-vs-bake) mode reruns the exact
 image it originally built — recorded per job — rather than rebuilding from current code, so a

{dockhand_cli-0.3.1 → dockhand_cli-0.4.0}/dockhand/__init__.py

@@ -15,7 +15,7 @@ from dockhand.submit import execute_submit
 from dockhand.tunnel import execute_tunnel
 from dockhand.volumes import execute_volumes
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"
 
 cli = typer.Typer(pretty_exceptions_show_locals=False)
 

{dockhand_cli-0.3.1 → dockhand_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dockhand-cli"
-version = "0.3.1"
+version = "0.4.0"
 description = "CLI for managing Docker containers on remote machines"
 readme = "README.md"
 license = { text = "MIT" }

{dockhand_cli-0.3.1 → dockhand_cli-0.4.0}/uv.lock

@@ -266,8 +266,8 @@ wheels = [
 ]
 
 [[package]]
-name = "dockhand"
-version = "0.3.1"
+name = "dockhand-cli"
+version = "0.4.0"
 source = { editable = "." }
 dependencies = [
     { name = "fabric" },

dockhand_cli-0.3.1/.claude/settings.local.json

@@ -1,9 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(uv run:*)",
-      "Bash(uv sync:*)",
-      "WebFetch(domain:github.com)"
-    ]
-  }
-}

dockhand_cli-0.3.1/CLAUDE.md

@@ -1,309 +0,0 @@
-# CLAUDE.md — dockhand Development Guide
-
-## Project Overview
-
-**dockhand** is a standalone CLI tool, originally extracted from DTU-HPC-CLI, for managing Docker containers on remote machines (or locally). It provides a unified interface to build, run, queue, manage, and monitor Docker containers via SSH or locally.
-
-**Key philosophy:** Simple, flat command structure with sensible SSH defaults. One `.dockhand.json` config file works everywhere.
-
-Since extraction, dockhand has grown features DTU-HPC-CLI never had: a task-spooler-based job queue, a mount-vs-bake code delivery mode, a direct (non-queued) run transport, and baked-image pruning. See [Relationship to DTU-HPC-CLI](#relationship-to-dtu-hpc-cli).
-
-## Commands
-
-**Prerequisites:**
-- Install [uv](https://docs.astral.sh/uv/): `curl -LsSf https://astral.sh/uv/install.sh | sh`
-
-**Installation & Setup:**
-```bash
-# Install dependencies and create lock file
-uv sync
-
-# Update lock file with latest versions (if needed)
-uv lock --upgrade
-```
-
-**Run the CLI locally:**
-```bash
-uv run dockhand --help
-```
-
-**Lint:**
-```bash
-uv run ruff check .
-```
-
-**Format:**
-```bash
-uv run ruff format .
-```
-
-**Auto-fix lint issues:**
-```bash
-uv run ruff check --fix .
-```
-
-## Architecture
-
-### Entry Point
-`dockhand/__init__.py` — Defines the Typer CLI app. All commands are at the top level (flat structure, not nested under a `docker` sub-group). Each command validates config with `cli_config.check_docker()` and delegates to an `execute_*` function in the relevant module below.
-
-**Commands at top level:**
-- `dockhand submit` — sync code, then queue/run a container
-- `dockhand run` — queue/run from an already-built image, no sync
-- `dockhand install` — build the image only
-- `dockhand logs`, `stop`, `remove`, `jobs`, `urgent`, `prune` — job/queue lifecycle (`manage.py` + `queue.py`)
-- `dockhand history` — show past runs
-- `dockhand volumes`, `download` — inspect and pull files from mounted volumes
-- `dockhand resubmit` — rerun a past job with optional overrides
-- `dockhand tunnel` — SSH-forward container ports to localhost
-
-### Configuration System
-`dockhand/config.py` — The `CLIConfig` class is loaded at module import time (`cli_config = CLIConfig.load()`) by walking up the directory tree to find `.dockhand.json`. Contains:
-- `SSHConfig` — hostname, user, identity file for SSH connections
-- `DockerConfig` — dockerfile, imagename, volumes, ports, gpus, containerworkdir, preserve_paths, code_delivery
-- `QueueConfig` — enabled, tool, slots (task-spooler queue settings)
-- `CLIConfig` — top-level config holder (ssh, docker, queue, sync, remote_path, profiles)
-
-Config file: `.dockhand.json` in the project root (must also contain a `.git` — `CLIConfig.load()` errors if no git repo is found). History file: `.dockhand_history.json` (same location by default, overridable via `history_path`).
-
-### Client Abstraction
-`dockhand/client/` — `Client` (abstract base) has two implementations:
-- `SSHClient` — connects via Fabric/Paramiko over SSH
-- `LocalClient` — runs commands locally
-
-`get_client()` picks `LocalClient` when `cli_config.ssh` is unset or the configured hostname resolves to loopback, otherwise `SSHClient`. `get_client_for_host(hostname)` does the same but for an explicit hostname (used by `logs`/`stop`/`remove`, which read the host from the job's history entry rather than current config).
-
-### Key Modules
-- `submit.py` — Builds the `docker run` command (code mount vs. data volumes vs. GPU/port flags), resolves code delivery, and hands off to a transport to start the job.
-- `build.py` — Runs `docker build` on the client (optionally syncing first).
-- `manage.py` — Job lifecycle: `logs`, `stop`, `remove`, `jobs` (`execute_stats`), and `prune` (removes baked images no longer referenced by an active job).
-- `resubmit.py` — Looks up a history entry and re-invokes `execute_submit` with overrides; pins to the original baked image when applicable.
-- `queue.py` — Task spooler (`tsp`) integration: submit/list/promote/remove/kill, plus `ts -l` output parsing.
-- `transport.py` — Abstracts "how a job runs": `TaskSpoolerTransport` (queue enabled) vs. `DockerTransport` (direct `docker run -d`). Both expose the same interface (`submit`, `list_jobs`, `logs`, `stop`, `remove`) so job-management commands don't care which backend created a job; the transport used is recorded per job in history.
-- `tagging.py` — Resolves the image tag/ref for baked code delivery (content-addressed from git commit + dirty-state hash; unique per queued submit, reused for direct runs).
-- `history.py` — Reads/writes `.dockhand_history.json`, reserves/looks up local job IDs.
-- `volumes.py` — Lists the container filesystem as a tree (code mount + data volumes) and resolves a workdir-relative path back to its host path.
-- `download.py` — Uses `volumes._resolve_to_host` + rsync to pull a file/directory from a volume.
-- `tunnel.py` — SSH local port forwarding to container ports (via Fabric).
-- `sync.py` — Uses `rsync` over SSH to copy local files to `remote_path`, respecting `.gitignore`; prompts to confirm when the worktree is dirty.
-- `config.py` — Configuration loading and validation.
-- `error.py` — Centralized error reporting with rich panels.
-- `constants.py` — Config/history filenames.
-
-> **Known inconsistency:** `tunnel.py` still looks up history entries by a `container_id` field (`entry["container_id"]`), but `history.py` no longer writes that field — entries are keyed by `local_id` with a transport `handle`. Passing an explicit `container_id` to `dockhand tunnel` will not resolve; only the no-argument (last job) path works reliably.
-
-### Docker History
-Stores container runs in `.dockhand_history.json` as JSON. Each entry contains:
-```json
-{
-  "local_id": 7,
-  "timestamp": 1234567890.123,
-  "config": {
-    "gpus": "all",
-    "volumes": [...],
-    "imagename": "my-image",
-    "commands": ["python", "train.py"],
-    "ports": ["6006:6006"],
-    "image_ref": "my-image:abc123def456",  // present when built (baked delivery)
-    "branch": "main"                        // optional, detected from git
-  },
-  "transport": "task_spooler",   // or "docker"
-  "handle": 12,                  // tsp job id, or container name for direct runs
-  "ts_job_id": 12,                // task_spooler transport only
-  "host": "remote.example.com",   // or "localhost"
-  "started_at": 1234567891.0,     // optional, set the first time `jobs` observes it running
-  "ended_at": 1234567895.0        // optional, set the first time `jobs` observes it finished/failed/stopped
-}
-```
-
-Used by `resubmit` (look up a previous run and re-run with overrides, pinning the original baked image when unchanged), `logs`, `stop`, `remove`, `jobs`, `urgent`, `prune` (default to latest if no ID given). Job-management commands dispatch to the transport recorded on the entry (`transport_for_entry`), so `logs`/`stop`/`remove` work the same regardless of whether a job went through the queue or ran directly.
-
-`started_at`/`ended_at` aren't queried from tsp/docker (neither exposes exact start/end timestamps cheaply for both transports) — `jobs` and `logs` each stamp them lazily the first time they happen to observe a job in the running/terminal state, so a job never checked on while running will show no start time once it finishes. `dockhand jobs` displays these as Started/Ended (absolute, `%Y-%m-%d %H:%M:%S`) and Duration (elapsed while running, total once finished) columns; `dockhand logs` prints a one-line "running for Xm" / "finished in Xm" header before the log output.
-
-### Design Patterns
-
-**DockerDefault factory:**
-In `__init__.py`, `DockerDefault` is a callable factory that pulls defaults from `cli_config.docker` at call time. Enables Typer's `default_factory` to respect active profiles.
-
-**Transport abstraction:**
-`get_transport()` in `transport.py` picks `TaskSpoolerTransport` or `DockerTransport` based on `cli_config.queue.enabled` at submit time. Every job-management command re-derives the correct transport per-job from the history entry (`transport_for_entry`) rather than from current config, so switching `queue.enabled` doesn't strand in-flight jobs from the other mode.
-
-**Code delivery resolution:**
-`DockerConfig.resolve_code_delivery(queue_enabled)` picks `mount` or `bake` when `code_delivery` isn't explicitly set: `bake` when the queue is enabled (avoids code drift while a job waits in queue), `mount` otherwise (zero-rebuild iteration). See README's [Code delivery](README.md#code-delivery-mount-vs-bake) section for the full rationale.
-
-**Profile support:**
-`cli_config.load_profile(name)` loads overrides from `.dockhand.json` profiles section (currently merges `history_path`, `remote_path`, `ssh`). All config classes support `validate()` for safe merging.
-
-**Command structure:**
-Each command:
-1. Calls `cli_config.check_docker()` to validate config
-2. Calls an `execute_*` function from the relevant module
-3. Passes `cli_config.docker` (and often `cli_config.queue`) as config arguments
-
-## Relationship to DTU-HPC-CLI
-
-- **Flat commands** — no `docker` sub-group. Commands are top-level.
-- **No HPC support** — SubmitConfig, InstallConfig, and all LSF/job submission code removed
-- **Docker-focused** — all UI/UX optimized for docker workflows
-- **Config-compatible in spirit, not in filename** — dockhand originally reused DTU-HPC-CLI's `.dtu_hpc.json`/`.dtu_docker_history.json` names; both have since been renamed to `.dockhand.json`/`.dockhand_history.json` (see `constants.py`). Old DTU-HPC-CLI config files need renaming (or a `history_path` override) to work with dockhand.
-- **Diverged, not just trimmed** — dockhand has added its own features DTU-HPC-CLI doesn't have: a task-spooler queue (`queue.py`/`transport.py`), slot reservations, `mount`/`bake` code delivery (`tagging.py`), a direct-run transport for when the queue is off, `urgent`/`prune`/`tunnel` commands. Maintained independently; version/release cadence is separate from DTU-HPC-CLI.
-
-## Key Files and Their Responsibilities
-
-| File | Purpose |
-|------|---------|
-| `__init__.py` | CLI app definition, command routing, config defaults |
-| `submit.py` | Builds the `docker run` command, resolves code delivery, submits via transport |
-| `build.py` | `docker build` execution |
-| `manage.py` | `logs`, `stop`, `remove`, `jobs`, `prune` |
-| `resubmit.py` | Rerun a past job with overrides |
-| `queue.py` | Task spooler (`tsp`) integration |
-| `transport.py` | Task-spooler vs. direct-docker execution backends |
-| `tagging.py` | Image tag resolution for baked code delivery |
-| `history.py` | Read/write `.dockhand_history.json`, job ID allocation |
-| `volumes.py` | Container filesystem tree, path resolution |
-| `download.py` | rsync-based file download from volumes |
-| `tunnel.py` | SSH port forwarding to container ports |
-| `config.py` | Config loading, validation, profile support |
-| `client/__init__.py` | Auto-detect and return appropriate client |
-| `client/base.py` | Abstract Client interface |
-| `client/local.py` | Local command execution |
-| `client/ssh.py` | Remote execution via SSH (Fabric/Paramiko) |
-| `sync.py` | rsync-based code synchronization |
-| `error.py` | Error reporting |
-| `constants.py` | Config/history file names |
-
-## Configuration Format
-
-`.dockhand.json` in project root (project root is also where `CLIConfig.load()` expects to find a `.git` directory):
-
-```json
-{
-  "sync": true,
-  "ssh": {
-    "user": "your_username",
-    "identityfile": "~/.ssh/id_rsa",
-    "hostname": "remote.example.com"
-  },
-  "queue": {
-    "enabled": true,
-    "slots": 1
-  },
-  "docker": {
-    "dockerfile": "Dockerfile",
-    "imagename": "my-image",
-    "volumes": [
-      {
-        "hostpath": "/local/data",
-        "containerpath": "/data",
-        "permissions": "rw"
-      }
-    ],
-    "ports": ["8080:80"],
-    "gpus": "all",
-    "containerworkdir": "/",
-    "preserve_paths": [".venv"],
-    "code_delivery": null
-  },
-  "remote_path": "~/my-project",
-  "profiles": {
-    "dev": {
-      "docker": {
-        "gpus": "1",
-        "dockerfile": "Dockerfile.dev"
-      }
-    }
-  }
-}
-```
-
-All options are optional except `dockerfile`, `imagename`, and `volumes` within docker config. `queue.slots` may also be set as `docker.slots` for back-compat (deprecation warning printed). Full option tables and defaults are documented in README.md's [Configuration](README.md#configuration) section — keep both in sync when config shape changes.
-
-## Common Workflows
-
-**First time setting up:**
-1. Create `.dockhand.json` with `docker` and `ssh` sections
-2. Run `dockhand install` to build the image
-3. Run `dockhand submit 'command'` to run a container
-
-**Development iteration:**
-```bash
-uv run dockhand submit --gpus 1 'python train.py'  # Sync + queue/run with 1 GPU
-uv run dockhand logs --n 50                        # Check last 50 log lines
-uv run dockhand resubmit --gpus 2                  # Re-run with 2 GPUs
-uv run dockhand download results/model.pth         # Get results back
-```
-
-**Quick rebuild:**
-```bash
-uv run dockhand install --dockerfile Dockerfile.dev  # Rebuild only
-uv run dockhand run 'bash'                           # Run interactively
-```
-
-**Using profiles:**
-```bash
-uv run dockhand --profile dev submit 'python train.py'   # Use dev profile
-uv run dockhand --profile prod install                   # Build prod image
-```
-
-**Queue management:**
-```bash
-uv run dockhand jobs                  # List active jobs
-uv run dockhand urgent 5               # Promote job #5 to front of queue
-uv run dockhand prune --dry-run        # Preview unused baked images before removing
-```
-
-## Testing & Validation
-
-No automated tests yet. Manual validation:
-```bash
-uv run dockhand --help         # Check CLI structure
-uv run dockhand submit --help  # Check submit options
-uv run ruff check .            # Lint
-uv run ruff format --check .   # Format check
-```
-
-## Important Design Decisions
-
-1. **Flat commands** — No `docker` sub-group. Simpler for a docker-only tool.
-2. **SSH by default** — Assumes docker host is remote. Auto-detects local by resolving the configured hostname to a loopback address.
-3. **History in JSON** — Simple, human-readable, easily editable.
-4. **Profile support** — Allows per-project config variants.
-5. **Minimal dependencies** — typer, fabric, paramiko, gitpython, rich.
-6. **Transport abstraction over queue state** — job-management commands read the transport from each job's own history entry rather than current `queue.enabled`, so toggling the queue mid-flight doesn't orphan existing jobs.
-7. **Code-delivery default follows queue mode** — `bake` when queued (avoids code drift while waiting), `mount` when not (zero-rebuild iteration); explicit `code_delivery` overrides either way.
-
-## Extraction History
-
-- **Source:** DTU-HPC-CLI (github.com/ChrisFugl/DTU-HPC-CLI)
-- **Extracted:** 2026-04-09
-- **Initial changes:**
-  - Removed: SubmitConfig, InstallConfig, types.py, all HPC modules
-  - Modified: config.py (trimmed), __init__.py (flat commands)
-  - Unchanged at the time: docker.py, sync.py, error.py, client/*, constants.py
-- **Since extraction:** the original monolithic `docker.py` was split into `build.py`, `submit.py`, `manage.py`, `resubmit.py`, `history.py`, `download.py`, `volumes.py`, `tunnel.py`; `queue.py`, `transport.py`, and `tagging.py` were added for the task-spooler queue, transport abstraction, and baked code delivery. Config/history filenames moved from `.dtu_hpc.json`/`.dtu_docker_history.json` to `.dockhand.json`/`.dockhand_history.json`.
-
-## Future Enhancements
-
-Potential improvements specific to dockhand (volume inspection is already implemented — see `volumes.py`):
-- Docker Compose support (`dockhand compose up`)
-- Kubernetes pod management
-- Local-only mode (drop SSH dependency for pure local docker)
-- Config auto-generation wizard
-- Container registry integration (Docker Hub, ECR, GCR)
-- Multi-container orchestration helpers
-- Fix `tunnel.py`'s stale `container_id` history lookup (see [Known inconsistency](#key-modules) above)
-
-## Contributing
-
-When working on dockhand:
-1. Keep the flat command structure — don't re-introduce `docker` sub-groups
-2. Maintain `.dockhand.json` compatibility
-3. Test manually with `uv run dockhand <command> --help` and actual docker operations
-4. Follow ruff lint/format rules (use `uv run ruff check . && uv run ruff format .`)
-5. Document new features in README.md and CLAUDE.md
-6. Update this file's Architecture section when modules are added, split, or renamed — it has drifted from actual code structure before
-
-## Maintenance
-
-dockhand is maintained independently from DTU-HPC-CLI. Version bumps and releases are separate. If you need HPC support, use the original DTU-HPC-CLI package.