Add workspace naming and discovery

Make concurrent workspaces easier to rediscover and resume without relying on opaque IDs alone.

Add optional workspace names, key/value labels, workspace list, and workspace update across the CLI, Python SDK, and MCP surface, and persist last_activity_at so list ordering reflects real mutating activity.

Update the stable contract, install/first-run docs, roadmap, and Python workspace example to teach the new discovery flow, and validate it with focused manager/CLI/API/server coverage plus uv lock, make check, make dist-check, and a real multi-workspace smoke for create, list, update, exec, reorder, and delete.

docs/public-contract.md

@@ -25,6 +25,7 @@ Top-level commands:
 - `pyro mcp serve`
 - `pyro run`
 - `pyro workspace create`
+- `pyro workspace list`
 - `pyro workspace sync push`
 - `pyro workspace stop`
 - `pyro workspace start`
@@ -53,6 +54,7 @@ Top-level commands:
 - `pyro workspace shell signal`
 - `pyro workspace shell close`
 - `pyro workspace status`
+- `pyro workspace update`
 - `pyro workspace logs`
 - `pyro workspace delete`
 - `pyro doctor`
@@ -78,8 +80,10 @@ Behavioral guarantees:
 - `pyro demo ollama` prints log lines plus a final summary line.
 - `pyro workspace create` auto-starts a persistent workspace.
 - `pyro workspace create --seed-path PATH` seeds `/workspace` from a host directory or a local `.tar` / `.tar.gz` / `.tgz` archive before the workspace is returned.
+- `pyro workspace create --name NAME --label KEY=VALUE` attaches human-oriented discovery metadata without changing the stable `workspace_id`.
 - `pyro workspace create --network-policy {off,egress,egress+published-ports}` controls workspace guest networking and whether services may publish localhost ports.
 - `pyro workspace create --secret NAME=VALUE` and `--secret-file NAME=PATH` persist guest-only UTF-8 secrets outside `/workspace`.
+- `pyro workspace list` returns persisted workspaces sorted by most recent `last_activity_at`.
 - `pyro workspace sync push WORKSPACE_ID SOURCE_PATH [--dest WORKSPACE_PATH]` imports later host-side directory or archive content into a started workspace.
 - `pyro workspace stop WORKSPACE_ID` stops one persistent workspace without deleting its `/workspace`, snapshots, or command history.
 - `pyro workspace start WORKSPACE_ID` restarts one stopped workspace without resetting `/workspace`.
@@ -103,11 +107,14 @@ Behavioral guarantees:
 - `pyro workspace shell open --secret-env SECRET_NAME[=ENV_VAR]` maps one persisted secret into the opened shell environment.
 - `pyro workspace shell *` manages persistent PTY sessions inside a started workspace.
 - `pyro workspace logs` returns persisted command history for that workspace until `pyro workspace delete`.
+- `pyro workspace update` changes only discovery metadata such as `name` and key/value `labels`.
 - Workspace create/status results expose `workspace_seed` metadata describing how `/workspace` was initialized.
+- Workspace create/status/reset/update results expose `name`, `labels`, and `last_activity_at`.
 - Workspace create/status/reset results expose `network_policy`.
 - Workspace create/status/reset results expose `reset_count` and `last_reset_at`.
 - Workspace create/status/reset results expose safe `secrets` metadata with each secret name and source kind, but never the secret values.
 - `pyro workspace status` includes aggregate `service_count` and `running_service_count` fields.
+- `pyro workspace list` returns one summary row per persisted workspace with `workspace_id`, `name`, `labels`, `environment`, `state`, `created_at`, `last_activity_at`, `expires_at`, `command_count`, `service_count`, and `running_service_count`.
 - `pyro workspace service start`, `pyro workspace service list`, and `pyro workspace service status` expose published-port metadata when present.
 
 ## Python SDK Contract
@@ -125,7 +132,8 @@ Supported public entrypoints:
 - `Pyro.inspect_environment(environment)`
 - `Pyro.prune_environments()`
 - `Pyro.create_vm(...)`
-- `Pyro.create_workspace(..., network_policy="off", secrets=None)`
+- `Pyro.create_workspace(..., name=None, labels=None, network_policy="off", secrets=None)`
+- `Pyro.list_workspaces()`
 - `Pyro.push_workspace_sync(workspace_id, source_path, *, dest="/workspace")`
 - `Pyro.stop_workspace(workspace_id)`
 - `Pyro.start_workspace(workspace_id)`
@@ -160,6 +168,7 @@ Supported public entrypoints:
 - `Pyro.delete_workspace(workspace_id)`
 - `Pyro.status_vm(vm_id)`
 - `Pyro.status_workspace(workspace_id)`
+- `Pyro.update_workspace(workspace_id, *, name=None, clear_name=False, labels=None, clear_labels=None)`
 - `Pyro.logs_workspace(workspace_id)`
 - `Pyro.network_info_vm(vm_id)`
 - `Pyro.reap_expired()`
@@ -173,7 +182,8 @@ Stable public method names:
 - `inspect_environment(environment)`
 - `prune_environments()`
 - `create_vm(...)`
-- `create_workspace(..., network_policy="off", secrets=None)`
+- `create_workspace(..., name=None, labels=None, network_policy="off", secrets=None)`
+- `list_workspaces()`
 - `push_workspace_sync(workspace_id, source_path, *, dest="/workspace")`
 - `stop_workspace(workspace_id)`
 - `start_workspace(workspace_id)`
@@ -208,6 +218,7 @@ Stable public method names:
 - `delete_workspace(workspace_id)`
 - `status_vm(vm_id)`
 - `status_workspace(workspace_id)`
+- `update_workspace(workspace_id, *, name=None, clear_name=False, labels=None, clear_labels=None)`
 - `logs_workspace(workspace_id)`
 - `network_info_vm(vm_id)`
 - `reap_expired()`
@@ -220,8 +231,10 @@ Behavioral defaults:
 - `allow_host_compat` defaults to `False` on `create_vm(...)` and `run_in_vm(...)`.
 - `allow_host_compat` defaults to `False` on `create_workspace(...)`.
 - `Pyro.create_workspace(..., seed_path=...)` seeds `/workspace` from a host directory or a local `.tar` / `.tar.gz` / `.tgz` archive before the workspace is returned.
+- `Pyro.create_workspace(..., name=..., labels=...)` attaches human-oriented discovery metadata without changing the stable `workspace_id`.
 - `Pyro.create_workspace(..., network_policy="off"|"egress"|"egress+published-ports")` controls workspace guest networking and whether services may publish host ports.
 - `Pyro.create_workspace(..., secrets=...)` persists guest-only UTF-8 secrets outside `/workspace`.
+- `Pyro.list_workspaces()` returns persisted workspace summaries sorted by most recent `last_activity_at`.
 - `Pyro.push_workspace_sync(...)` imports later host-side directory or archive content into a started workspace.
 - `Pyro.stop_workspace(...)` stops one persistent workspace without deleting its `/workspace`, snapshots, or command history.
 - `Pyro.start_workspace(...)` restarts one stopped workspace without resetting `/workspace`.
@@ -248,6 +261,7 @@ Behavioral defaults:
 - `Pyro.open_shell(...)` opens a persistent PTY shell attached to one started workspace.
 - `Pyro.read_shell(...)` reads merged text output from that shell by cursor.
 - `Pyro.write_shell(...)`, `Pyro.signal_shell(...)`, and `Pyro.close_shell(...)` operate on that persistent shell session.
+- `Pyro.update_workspace(...)` changes only discovery metadata such as `name` and key/value `labels`.
 
 ## MCP Contract
 
@@ -270,6 +284,7 @@ Advanced lifecycle tools:
 Persistent workspace tools:
 
 - `workspace_create`
+- `workspace_list`
 - `workspace_sync_push`
 - `workspace_stop`
 - `workspace_start`
@@ -298,6 +313,7 @@ Persistent workspace tools:
 - `shell_signal`
 - `shell_close`
 - `workspace_status`
+- `workspace_update`
 - `workspace_logs`
 - `workspace_delete`
 
@@ -308,8 +324,10 @@ Behavioral defaults:
 - `vm_run` and `vm_create` expose `allow_host_compat`, which defaults to `false`.
 - `workspace_create` exposes `allow_host_compat`, which defaults to `false`.
 - `workspace_create` accepts optional `seed_path` and seeds `/workspace` from a host directory or a local `.tar` / `.tar.gz` / `.tgz` archive before the workspace is returned.
+- `workspace_create` accepts optional `name` and `labels` metadata for human discovery without changing the stable `workspace_id`.
 - `workspace_create` accepts `network_policy` with `off`, `egress`, or `egress+published-ports` to control workspace guest networking and service port publication.
 - `workspace_create` accepts optional `secrets` and persists guest-only UTF-8 secret material outside `/workspace`.
+- `workspace_list` returns persisted workspace summaries sorted by most recent `last_activity_at`.
 - `workspace_sync_push` imports later host-side directory or archive content into a started workspace, with an optional `dest` under `/workspace`.
 - `workspace_stop` stops one persistent workspace without deleting its `/workspace`, snapshots, or command history.
 - `workspace_start` restarts one stopped workspace without resetting `/workspace`.
@@ -327,6 +345,7 @@ Behavioral defaults:
 - `service_start` accepts optional `published_ports` to expose guest TCP ports on `127.0.0.1` when the workspace network policy is `egress+published-ports`.
 - `vm_exec` runs one command and auto-cleans that VM after the exec completes.
 - `workspace_exec` accepts optional `secret_env` mappings for one exec call and leaves the workspace alive.
+- `workspace_update` changes only discovery metadata such as `name` and key/value `labels`.
 - `service_start` accepts optional `secret_env` mappings for one service start call.
 - `shell_open` accepts optional `secret_env` mappings for the opened shell session.
 - `shell_open`, `shell_read`, `shell_write`, `shell_signal`, and `shell_close` manage persistent PTY shells inside a started workspace.