agentic-runner 3.26.1__tar.gz → 3.28.0__tar.gz

{agentic_runner-3.26.1 → agentic_runner-3.28.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: agentic-runner
-Version: 3.26.1
+Version: 3.28.0
 Summary: The Agentic OS Runner: an activity-only Temporal executor for workspaces, Agent Runtimes and verb seams
 License-Expression: AGPL-3.0-only
 License-File: LICENSE
 Requires-Python: >=3.12
-Requires-Dist: agentic-runner-contracts==3.26.1
+Requires-Dist: agentic-runner-contracts==3.28.0
 Requires-Dist: cryptography<51,>=50
 Requires-Dist: httpx<1.0,>=0.27
 Requires-Dist: pydantic-settings<3.0,>=2.0
@@ -46,8 +46,9 @@ It ships as `ghcr.io/qtsone/agentic-runner` (`Dockerfile.runner` at the reposito
 root: Python, git, `codex`, `claude`, nothing else) and installs with
 `charts/agentic-runner`.
 
-On a workstation it is a per-user login agent, one per Organisation:
-`agentic-runner install | start | stop | status <org>` (LaunchAgent, systemd user unit or
-logon task; never `sudo`), with Credential References in the OS credential store.
+On a workstation it is a per-user login agent, one per Runner:
+`agentic-runner install | start | stop | status <name>` and `agentic-runner list`
+(LaunchAgent, systemd user unit or logon task; never `sudo`), with Credential References in
+the OS credential store.
 
 Licensed under AGPL-3.0-only.

{agentic_runner-3.26.1 → agentic_runner-3.28.0}/README.md

@@ -27,8 +27,9 @@ It ships as `ghcr.io/qtsone/agentic-runner` (`Dockerfile.runner` at the reposito
 root: Python, git, `codex`, `claude`, nothing else) and installs with
 `charts/agentic-runner`.
 
-On a workstation it is a per-user login agent, one per Organisation:
-`agentic-runner install | start | stop | status <org>` (LaunchAgent, systemd user unit or
-logon task; never `sudo`), with Credential References in the OS credential store.
+On a workstation it is a per-user login agent, one per Runner:
+`agentic-runner install | start | stop | status <name>` and `agentic-runner list`
+(LaunchAgent, systemd user unit or logon task; never `sudo`), with Credential References in
+the OS credential store.
 
 Licensed under AGPL-3.0-only.

{agentic_runner-3.26.1 → agentic_runner-3.28.0}/pyproject.toml

@@ -10,7 +10,7 @@ dependencies = [
   # Exactly this release's contracts: the two ship as one version, and an unpinned
   # requirement let `uv tool upgrade` keep an older contracts wheel the Runner cannot
   # import from (QTS-1473). `scripts/set-version.py` moves it with the version.
-  "agentic-runner-contracts==3.26.1",
+  "agentic-runner-contracts==3.28.0",
   # Imported directly by `registration.py` (the Ed25519 identity that signs every
   # heartbeat); already present transitively through pyjwt[crypto], declared because
   # we import it.

{agentic_runner-3.26.1 → agentic_runner-3.28.0}/src/agentic_runner/__init__.py

@@ -7,6 +7,6 @@ stay on the platform; this package imports none of them, and a CI partition test
 (``tests/test_package_partition.py``) fails the build if that changes.
 """
 
-__version__ = "3.26.1"
+__version__ = "3.28.0"
 
 __all__ = ["__version__"]

{agentic_runner-3.26.1 → agentic_runner-3.28.0}/src/agentic_runner/cli.py

@@ -11,9 +11,10 @@ namespace and queue this process was assigned. It is idempotent by state file --
 restart re-reads what is already there rather than registering a second Runner against
 the Organisation's cap.
 
-``install | start | stop | status <org>`` and ``credential set`` are the workstation
-Runner (PRD issue 47, ``workstation.py``): one login agent per Organisation, managed by
-the user who hosts it, with no ``sudo`` anywhere.
+``install | start | stop | status <name>``, ``credential set`` and ``list`` are the
+workstation Runner (PRD issue 47, ``workstation.py``): one login agent per Runner, managed
+by the user who hosts it, with no ``sudo`` anywhere. ``<name>`` is the Runner's, the one the
+console lists it under (QTS-1773); a machine with one Runner needs none (QTS-1774).
 
 ``sign-in [claude|codex]`` gives a person's own Runner their LLM access: their subscription,
 through the vendor's own sign-in in this terminal, or an API key stored in the Runner's
@@ -102,6 +103,19 @@ __all__ = [
 STATE_DIR_ENV = "AGENTIC_RUNNER_STATE_DIR"
 
 
+_NAME_HELP = (
+    "this Runner's name: the console lists it under this name, and every command on this "
+    "machine takes it"
+)
+_INSTALLED_NAME_HELP = "the Runner's name; omitted when this machine runs one Runner"
+
+
+def _old_org_flag(parser: argparse.ArgumentParser) -> None:
+    # A login agent written before QTS-1773 runs `run --org <name>` and is not rewritten
+    # until its next `install`, so the old spelling keeps parsing, unlisted.
+    parser.add_argument("--org", dest="name", help=argparse.SUPPRESS)
+
+
 def _state_dir() -> Path:
     return load_config().state_dir
 
@@ -158,14 +172,15 @@ def main(argv: Sequence[str] | None = None) -> int:
     )
 
     run = subcommands.add_parser("run", help="register if needed, then heartbeat and poll for work")
-    run.add_argument("--org", default=None, help="run an installed workstation Organisation")
+    run.add_argument("--name", default=None, help="run an installed workstation Runner")
+    _old_org_flag(run)
     run.add_argument("--root", default=None, type=Path, help=argparse.SUPPRESS)
     run.add_argument("--login-agent", action="store_true", help=argparse.SUPPRESS)
 
     install = subcommands.add_parser(
-        "install", help="register a workstation Runner for one Organisation (issue 47)"
+        "install", help="register a workstation Runner and install its login agent (issue 47)"
     )
-    install.add_argument("org")
+    install.add_argument("name", help=_NAME_HELP)
     install.add_argument(
         "--control-plane", default=os.environ.get(CONTROL_PLANE_ENV), help="control plane URL"
     )
@@ -195,16 +210,21 @@ def main(argv: Sequence[str] | None = None) -> int:
     install.add_argument("--root", default=None, type=Path, help="state root (default per OS)")
     for service_verb in ("start", "stop"):
         driven = subcommands.add_parser(
-            service_verb, help=f"{service_verb} one Organisation's login agent"
+            service_verb, help=f"{service_verb} one workstation Runner's login agent"
         )
-        driven.add_argument("org")
+        driven.add_argument("name", nargs="?", help=_INSTALLED_NAME_HELP)
         driven.add_argument("--root", default=None, type=Path)
 
+    listed = subcommands.add_parser(
+        "list", help="the workstation Runners installed on this machine, and which are running"
+    )
+    listed.add_argument("--root", default=None, type=Path)
+
     credential = subcommands.add_parser(
         "credential", help="install a Credential Reference value into this host's store"
     )
     credential.add_argument("action", choices=("set",))
-    credential.add_argument("org")
+    credential.add_argument("name", nargs="?", help=_INSTALLED_NAME_HELP)
     credential.add_argument("reference")
     credential.add_argument("--root", default=None, type=Path)
 
@@ -219,7 +239,7 @@ def main(argv: Sequence[str] | None = None) -> int:
     status = subcommands.add_parser(
         "status", help="print this installation's versions and Recipient Key fingerprint"
     )
-    status.add_argument("org", nargs="?", help="a workstation Organisation (issue 47)")
+    status.add_argument("name", nargs="?", help=_INSTALLED_NAME_HELP)
     status.add_argument("--root", default=None, type=Path)
 
     sign_in = subcommands.add_parser(
@@ -240,10 +260,11 @@ def main(argv: Sequence[str] | None = None) -> int:
         "claude_ai: a Claude.ai login (claude auth login --claudeai)",
     )
     sign_in.add_argument(
-        "--org",
+        "--name",
         default=None,
-        help="the workstation Organisation, when this workstation runs more than one",
+        help="the workstation Runner's name, when this machine runs more than one",
     )
+    _old_org_flag(sign_in)
     sign_in.add_argument("--root", default=None, type=Path, help=argparse.SUPPRESS)
 
     annotate = subcommands.add_parser("annotate", help="attach an annotation to this Work Record")
@@ -332,11 +353,25 @@ def main(argv: Sequence[str] | None = None) -> int:
             return 1
         return 0
     if arguments.command == "run":
-        if arguments.org:
-            return workstation.run_process(_org_paths(arguments), login_agent=arguments.login_agent)
+        if arguments.name:
+            return workstation.run_process(
+                _runner_paths(arguments), login_agent=arguments.login_agent
+            )
+        if installed := _installed_instead_of_run():
+            print(
+                f"this machine runs {', '.join(installed)} as login agents: start one with "
+                "`agentic-runner start <name>`. `run` serves a Runner its environment sets "
+                "up, as in a container",
+                file=sys.stderr,
+            )
+            return 2
         return asyncio.run(service.run(attestation=_image_attestation(), install=_run_install()))
     if arguments.command in {"install", "start", "stop", "credential"}:
         return _workstation(arguments)
+    if arguments.command == "list":
+        for line in workstation.list_lines(arguments.root or workstation.default_root()):
+            print(line)
+        return 0
     if arguments.command == "recipient-key":
         api, kube_ns = in_cluster()
         pair = ensure_recipient_key(
@@ -347,7 +382,17 @@ def main(argv: Sequence[str] | None = None) -> int:
         )
         return 0
     if arguments.command == "status":
-        lines = workstation.status_lines(_org_paths(arguments)) if arguments.org else status_lines()
+        if arguments.name or (
+            not _in_container()
+            and workstation.installed_names(arguments.root or workstation.default_root())
+        ):
+            try:
+                lines = workstation.status_lines(_runner_paths(arguments))
+            except ValueError as error:
+                print(error, file=sys.stderr)
+                return 2
+        else:
+            lines = status_lines()
         for line in lines:
             print(line)
         return 0
@@ -370,28 +415,45 @@ def main(argv: Sequence[str] | None = None) -> int:
     return _callback(arguments)
 
 
-def _org_paths(arguments: argparse.Namespace) -> workstation.OrgPaths:
-    return workstation.OrgPaths(
-        root=arguments.root or workstation.default_root(),
-        org=workstation.validate_org(arguments.org),
-    )
+def _runner_paths(
+    arguments: argparse.Namespace, *, how: str = "name one"
+) -> workstation.RunnerPaths:
+    """``<name>``, or the one Runner this machine runs -- nothing to remember (QTS-1774)."""
+
+    root = arguments.root or workstation.default_root()
+    if not arguments.name:
+        return workstation.only_runner(root, how=how)
+    return workstation.RunnerPaths(root=root, name=workstation.validate_name(arguments.name))
+
+
+def _installed_instead_of_run() -> list[str]:
+    """The Runners installed here, when a bare ``run`` would start none of them.
+
+    An installed Runner is its login agent's process; ``run`` without ``--name`` registers
+    from the environment, and on a workstation that holds neither a token nor an identity
+    it could only fail without saying what to type instead (QTS-1774).
+    """
+
+    if _in_container() or registration_token_from_env() or load_state(_state_dir()):
+        return []
+    return workstation.installed_names(workstation.default_root())
 
 
 def _workstation(arguments: argparse.Namespace) -> int:
-    paths = _org_paths(arguments)
     try:
+        paths = _runner_paths(arguments)
         if arguments.command == "install":
             return _install(arguments, paths)
         if arguments.command == "start":
             workstation.start(paths)
-            print(f"started {paths.org}")
+            print(f"started {paths.name}")
             return 0
         if arguments.command == "stop":
             workstation.stop(paths)
-            print(f"stopped {paths.org}; every other Organisation's Runner keeps polling")
+            print(f"stopped {paths.name}; every other Runner on this machine keeps polling")
             return 0
         # The value arrives on stdin so it is never in argv or shell history.
-        store = open_workstation_store(paths.org, fallback=paths.credentials)
+        store = open_workstation_store(paths.name, fallback=paths.credentials)
         store.put(arguments.reference, sys.stdin.read().strip())
         print(f"{arguments.reference} stored in the {store.kind.value} store")
         return 0
@@ -461,42 +523,22 @@ def _sign_in(arguments: argparse.Namespace) -> int:
         )
         return 2
     store: KeyStore
-    if arguments.org or not _in_container():
+    if arguments.name or not _in_container():
         try:
-            paths = _sign_in_org(arguments)
+            paths = _runner_paths(arguments, how="name one with --name")
         except ValueError as error:
             print(error, file=sys.stderr)
             return 2
         os.environ.update(
             workstation.run_environment(paths, workstation.WorkstationSettings.load(paths))
         )
-        store = open_workstation_store(paths.org, fallback=paths.credentials)
+        store = open_workstation_store(paths.name, fallback=paths.credentials)
     else:
         store = service.own_store(load_config())
     return asyncio.run(service.sign_in(arguments.runtime, store=store, method=arguments.method))
 
 
-def _sign_in_org(arguments: argparse.Namespace) -> workstation.OrgPaths:
-    """``--org``, or the one Organisation this workstation runs -- no id to type."""
-
-    if arguments.org:
-        return _org_paths(arguments)
-    root = arguments.root or workstation.default_root()
-    installed = (
-        sorted(path.name for path in root.iterdir() if (path / "workstation.json").is_file())
-        if root.is_dir()
-        else []
-    )
-    if len(installed) != 1:
-        raise ValueError(
-            "no workstation Runner is installed here"
-            if not installed
-            else f"this workstation runs {', '.join(installed)}: name one with --org"
-        )
-    return workstation.OrgPaths(root=root, org=installed[0])
-
-
-def _install(arguments: argparse.Namespace, paths: workstation.OrgPaths) -> int:
+def _install(arguments: argparse.Namespace, paths: workstation.RunnerPaths) -> int:
     if not arguments.control_plane:
         print(f"--control-plane (or {CONTROL_PLANE_ENV}) is required", file=sys.stderr)
         return 2
@@ -518,7 +560,6 @@ def _install(arguments: argparse.Namespace, paths: workstation.OrgPaths) -> int:
         else None
     )
     settings = workstation.WorkstationSettings(
-        org=paths.org,
         control_plane_url=arguments.control_plane,
         temporal_address=arguments.temporal_address,
         temporal_tls=not arguments.temporal_plaintext,
@@ -549,7 +590,7 @@ def _install(arguments: argparse.Namespace, paths: workstation.OrgPaths) -> int:
     return 0
 
 
-def _acp_cli_kinds(flag: str | None, paths: workstation.OrgPaths) -> str:
+def _acp_cli_kinds(flag: str | None, paths: workstation.RunnerPaths) -> str:
     # A reinstall to pick up a new PATH or retry a token must not turn ACP off (QTS-1355).
     if flag is not None:
         return workstation.parse_acp_cli_kinds(flag)

{agentic_runner-3.26.1 → agentic_runner-3.28.0}/src/agentic_runner/service.py

@@ -250,7 +250,7 @@ _VERIFIER_ACTIVITY_BUDGET_SECONDS = 20 * 60
 # chart's value and this must move together).
 _SHUTDOWN_HEADROOM_SECONDS = 60
 
-# What `agentic-runner status <org>` reads (PRD issue 47): the live pid, and a file the
+# What `agentic-runner status <name>` reads (PRD issue 47): the live pid, and a file the
 # process touches on every acknowledged heartbeat, whose mtime is the heartbeat age.
 PIDFILE_NAME = "runner.pid"
 HEARTBEAT_STAMP_NAME = "last-heartbeat"
@@ -849,6 +849,9 @@ class ControlPlaneStream:
     # control plane on 3.25 named them, and the LLM access report is sent only after.
     _llm_contracts: list[ContractLlmTerms] | None = None
     _pool: PoolTerms | None = None
+    # QTS-1773: the control plane's contracts version, from its ack; None until an ack from
+    # one on 3.27 or later, the first to send it and to parse `RunnerInstall.name`.
+    _control_plane_contracts: str | None = None
     _last_seen: tuple[float, datetime] | None = None
 
     def _observe_sleep(self, now: datetime) -> None:
@@ -976,6 +979,17 @@ class ControlPlaneStream:
             for terms in self._llm_contracts
         ]
 
+    def _install_report(self) -> RunnerInstall | None:
+        """Where a command reaches this Runner, sent once an ack named the Contracts -- a
+        control plane below 3.25 refuses the field -- and with its name only once an ack
+        came from a control plane on 3.27, since one below refuses that key (QTS-1773)."""
+
+        if self.install is None or self._llm_contracts is None:
+            return None
+        if self._control_plane_contracts is None:
+            return self.install.model_copy(update={"name": None})
+        return self.install
+
     def _credential_report(self) -> list[CredentialValidity]:
         """Per Contract the last ack named, whether each reference would resolve (§7).
 
@@ -1037,7 +1051,7 @@ class ControlPlaneStream:
             oauth_outcomes=self.oauth.take_outcomes() if self.oauth else [],
             runner_limit=self.runner_limit,
             llm_access=self._llm_access_report(),
-            install=self.install if self._llm_contracts is not None else None,
+            install=self._install_report(),
             pool_key_fingerprint=self.pool_key_fingerprint if self._pool is not None else None,
         )
         ack = await self.client.heartbeat(self.state, envelope)
@@ -1065,6 +1079,8 @@ class ControlPlaneStream:
         self._manifests = list(ack.credential_manifests)
         self._take_llm_contracts(ack.llm_contracts)
         self._take_pool(ack.pool)
+        if ack.contracts_version is not None:
+            self._control_plane_contracts = ack.contracts_version
         await self._sync_llm_slots()
         if ack.runner_token is not None:
             self.runner_token = ack.runner_token

{agentic_runner-3.26.1 → agentic_runner-3.28.0}/src/agentic_runner/skills/agentic-runner-setup/SKILL.md

@@ -8,7 +8,8 @@ license: AGPL-3.0-only
 
 You help a person who has never run a Runner. A **Runner** is the program that does their
 Agents' work: it runs Codex or Claude Code on a machine they choose and connects out to the
-Agentic OS control plane. It belongs to one **Organisation** (the company the work is for).
+Agentic OS control plane. It belongs to one **Organisation** (the company the work is for),
+and has a **name** the person chose for it in the console.
 
 The install documents in the `qtsone/agentic-runner` repository are the source for every
 command. Do not reconstruct a command from memory: open the section named in each step and
@@ -18,7 +19,9 @@ follow it.
 
 The prompt they pasted from the console holds these. Ask for any that is missing.
 
-- **Organisation**: a short local name for it, lowercase letters, digits and `-` (`acme`).
+- **Runner name**: the name the person gave the Runner in the console, lowercase letters,
+  digits and `-` (`alice-laptop`). A prompt from an older console calls it **Organisation**;
+  it is the same value.
 - **Control plane URL**: the Runner's `controlPlane.url`, copied from the console's
   Runners page. It is the only control plane address you use, and only as a value you
   pass to the Runner. Never call it or any other control plane address yourself.
@@ -75,13 +78,13 @@ missing.
 
 **This machine.** Follow
 https://github.com/qtsone/agentic-runner/blob/main/docs/workstation.md#install. Install the
-Runner, then show the person the command that registers it for the Organisation and ask
+Runner, then show the person the command that registers it under its name and ask
 them to run it in their own terminal. The Runner asks them for the Runner Registration Token there,
 without showing it:
 
 ```sh
 uv tool install agentic-runner
-agentic-runner install <org> --control-plane <control-plane-url>
+agentic-runner install <name> --control-plane <control-plane-url>
 ```
 
 You run the first line. Do not run the second yourself: wait until the person says it
@@ -113,7 +116,7 @@ agentic-runner sign-in claude
 ```
 
 `codex` in place of `claude` for Codex; with no argument it asks about each. Add
-`--org <org>` only if this machine runs Runners for several Organisations. On Docker it is
+`--name <name>` only if this machine runs more than one Runner. On Docker it is
 `docker exec -it <container> agentic-runner sign-in claude`, on Kubernetes
 `kubectl exec -it <pod> -c runner -- agentic-runner sign-in claude`.
 
@@ -130,7 +133,7 @@ it: it uses the Organisation's keys, which its admin puts in the Runner's own st
 On this machine, run every 10 seconds, for at most 3 minutes:
 
 ```sh
-agentic-runner status <org>
+agentic-runner status <name>
 ```
 
 The Runner is online when `process` says `running` and `heartbeat` shows a number of
@@ -141,7 +144,7 @@ it" section. If 3 minutes pass, stop and show the last output and the "Check it"
 
 One screen, nothing more:
 
-- the way, the Organisation and the Runner's identity line from `status`;
+- the way, the Runner's name and its identity line from `status`;
 - whether the LLM credential is in place, or the one thing the person still does in the
   console;
 - the `next` line `status` prints: where in the console to see the Runner and give it work.

{agentic_runner-3.26.1 → agentic_runner-3.28.0}/src/agentic_runner/workstation.py

@@ -1,12 +1,16 @@
-"""The workstation Runner: one login agent per Organisation (PRD issue 47, map ticket 23).
+"""The workstation Runner: one login agent per Runner (PRD issue 47, map ticket 23).
 
-``agentic-runner install | start | stop | status <org>``. Everything a CI-runner
+``agentic-runner install | start | stop | status <name>`` and ``list``. Everything a CI-runner
 precedent does on a developer machine and nothing a daemon would need:
 
-* **One process per Organisation** (23 item 3), each with its own state directory,
-  identity, namespace, Runner Token, hooks, credential store and Workspaces under
-  ``<root>/<org>/``. A contractor with two clients runs two. There is no supervisor over
-  N Organisations -- that is the "one Runner straddling Organisations" 12 A6 rejected.
+* **One process per Runner** (23 item 3), each with its own state directory, identity,
+  namespace, Runner Token, hooks, credential store and Workspaces under ``<root>/<name>/``.
+  A contractor with two clients runs two. There is no supervisor over N Runners -- that
+  is the "one Runner straddling Organisations" 12 A6 rejected.
+* **The name is the Runner's** (QTS-1773): the console lists the Runner under the name it
+  was installed as, and every local command takes it. It was an Organisation label before,
+  so the name a person chose on /me/runners read as an Organisation; an install made then
+  keeps its directory, login agent and keychain entries, all keyed by the same string.
 * **A login agent, never a system daemon** (23 item 1): a LaunchAgent in
   ``~/Library/LaunchAgents`` on macOS, a systemd *user* unit (with linger) on Linux, a
   per-user logon task on Windows. No ``sudo`` anywhere: the login keychain is unreachable
@@ -18,8 +22,8 @@ precedent does on a developer machine and nothing a daemon would need:
   under a harness root -- the per-Contract ``CODEX_HOME`` / ``CLAUDE_CONFIG_DIR`` belongs
   to the login the funder created there (issues 30, 31).
 * **``isolation: none``** (17 A2): no root and no uid switch, so the control plane routes
-  at most one Contract at a time here (issue 42), which one Organisation per process and
-  one active Contract per (Organisation, User Profile) pair already implied.
+  at most one Contract at a time here (issue 42), which one Contract per personal Runner
+  already implied.
 """
 
 from __future__ import annotations
@@ -43,17 +47,21 @@ from xml.sax.saxutils import escape
 import httpx
 from pydantic import BaseModel, ConfigDict
 
+from agentic_runner import __version__ as runner_version
 from agentic_runner import service
 from agentic_runner.build import build_id
 from agentic_runner.cli_floor import CLI_FLOORS, CLI_NAMES, meets_floor, parse_cli_version
 from agentic_runner.config import CONFIG_FILE_ENV
 from agentic_runner.host_store import open_workstation_store
 from agentic_runner.lifecycle import LifecycleOutbox
+from agentic_runner.llm_contracts import load_llm_contracts
 from agentic_runner.pool_key import parse_pool_key, save_pool_key
 from agentic_runner.registration import load_state
 from agentic_runner.service import HEARTBEAT_STAMP_NAME, PIDFILE_NAME
 from agentic_runner.workers.acp_runtime import ACP_BRIDGES
+from agentic_runner_contracts.public_metadata import NAMESPACE_PREFIX
 from agentic_runner_contracts.runner_registration import (
+    RUNNER_NAME_PATTERN,
     CliVersion,
     EgressPosture,
     HostAttestation,
@@ -71,7 +79,7 @@ __all__ = [
     "CLI_NAMES",
     "ROOT_ENV",
     "CliMissingError",
-    "OrgPaths",
+    "RunnerPaths",
     "ServiceDefinition",
     "WorkstationSettings",
     "cli_versions",
@@ -79,7 +87,10 @@ __all__ = [
     "default_root",
     "install",
     "install_channel",
+    "installed_names",
+    "list_lines",
     "locate_clis",
+    "only_runner",
     "parse_acp_cli_kinds",
     "require_any_cli",
     "run_environment",
@@ -88,12 +99,11 @@ __all__ = [
     "start",
     "status_lines",
     "stop",
-    "validate_org",
+    "validate_name",
 ]
 
 ROOT_ENV: Final = "AGENTIC_RUNNER_WORKSTATION_ROOT"
 
-_ORG = re.compile(r"^[a-z0-9][a-z0-9-]{0,31}$")
 _LABEL_PREFIX: Final = "agentic-runner"
 
 Run = Callable[..., subprocess.CompletedProcess[str]]
@@ -103,18 +113,19 @@ class CliMissingError(RuntimeError):
     pass
 
 
-def validate_org(org: str) -> str:
+def validate_name(name: str) -> str:
     """One path segment, one launchd label, one systemd instance name -- all at once."""
 
-    if not _ORG.fullmatch(org):
+    if not re.fullmatch(RUNNER_NAME_PATTERN, name):
         raise ValueError(
-            f"Organisation name {org!r} must be 1-32 of lowercase letters, digits and '-'"
+            f"Runner name {name!r} must be 1-32 of lowercase letters, digits and '-', "
+            "starting with a letter or digit"
         )
-    return org
+    return name
 
 
 def default_root(*, platform: str = sys.platform, environ: Mapping[str, str] = os.environ) -> Path:
-    """Where every Organisation's directory lives, per the OS's per-user convention."""
+    """Where every Runner's directory lives, per the OS's per-user convention."""
 
     if environ.get(ROOT_ENV, "").strip():
         return Path(environ[ROOT_ENV])
@@ -127,20 +138,50 @@ def default_root(*, platform: str = sys.platform, environ: Mapping[str, str] = o
     return (Path(state_home) if state_home else home / ".local" / "state") / "agentic-runner"
 
 
+def installed_names(root: Path) -> list[str]:
+    """Every Runner installed under ``root``, by name.
+
+    A directory whose name is not a Runner's is skipped: the guide moves an old install
+    aside as ``<name>.organisation`` before a new token, and that one is not a Runner here.
+    """
+
+    if not root.is_dir():
+        return []
+    return sorted(
+        path.name
+        for path in root.iterdir()
+        if re.fullmatch(RUNNER_NAME_PATTERN, path.name)
+        and RunnerPaths(root=root, name=path.name).settings_file.is_file()
+    )
+
+
+def only_runner(root: Path, *, how: str = "name one") -> RunnerPaths:
+    """The one Runner installed here, so a command needs no name (QTS-1774)."""
+
+    names = installed_names(root)
+    if len(names) == 1:
+        return RunnerPaths(root=root, name=names[0])
+    if not names:
+        raise ValueError(f"no workstation Runner is installed under {root}")
+    raise ValueError(
+        f"this machine runs {', '.join(names)}: {how} (`agentic-runner list` shows each)"
+    )
+
+
 @dataclass(frozen=True)
-class OrgPaths:
-    """``<root>/<org>/`` and everything the process keeps under it."""
+class RunnerPaths:
+    """``<root>/<name>/`` and everything the process keeps under it."""
 
     root: Path
-    org: str
+    name: str
 
     @property
     def state_dir(self) -> Path:
-        return self.root / self.org
+        return self.root / self.name
 
     @property
     def hooks(self) -> Path:
-        # Issue 45's path, per map ticket 26: `<state_dir>/<org>/hooks/`.
+        # Issue 45's path, per map ticket 26: `<state_dir>/<name>/hooks/`.
         return self.state_dir / "hooks"
 
     @property
@@ -179,6 +220,12 @@ class OrgPaths:
     def log(self) -> Path:
         return self.state_dir / "runner.log"
 
+    @property
+    def started_version(self) -> Path:
+        # Written by the process, not `install`: every Runner here runs one console script,
+        # and after `uv tool upgrade` a Runner not restarted still runs the old version.
+        return self.state_dir / "runner-version"
+
     @property
     def socket_dir(self) -> Path:
         # `sun_path` is ~104 bytes and "~/Library/Application Support/..." is most of
@@ -189,7 +236,7 @@ class OrgPaths:
             tempfile.gettempdir() if sys.platform == "darwin" else ""
         )
         if runtime:
-            return Path(runtime) / f"agentic-runner-{self.org}"
+            return Path(runtime) / f"agentic-runner-{self.name}"
         return self.state_dir / "sockets"
 
     def create(self) -> None:
@@ -203,10 +250,10 @@ class WorkstationSettings(BaseModel):
     """What ``install`` was told, so ``run`` and ``status`` need no flags."""
 
     # `ignore`, not `forbid`: only `save` writes this file, and an install made before
-    # local-agents 01 retired the per-process `cli_kind` still has to `run` and `status`.
+    # local-agents 01 retired the per-process `cli_kind`, or before QTS-1773 dropped the
+    # `org` its directory already names, still has to `run` and `status`.
     model_config = ConfigDict(extra="ignore", frozen=True)
 
-    org: str
     control_plane_url: str
     # A fallback only: `run` uses the address the registration response carries (ADR-0022
     # §4). An install made before 3.17 saved one and keeps it.
@@ -222,15 +269,15 @@ class WorkstationSettings(BaseModel):
     # which every `install` rewrites (QTS-1355).
     acp_cli_kinds: str = ""
 
-    def save(self, paths: OrgPaths) -> None:
+    def save(self, paths: RunnerPaths) -> None:
         paths.settings_file.write_text(self.model_dump_json(indent=2), encoding="utf-8")
 
     @classmethod
-    def load(cls, paths: OrgPaths) -> WorkstationSettings:
+    def load(cls, paths: RunnerPaths) -> WorkstationSettings:
         if not paths.settings_file.is_file():
             raise FileNotFoundError(
-                f"no Runner is installed for {paths.org!r} under {paths.root}; "
-                f"run `agentic-runner install {paths.org}` first"
+                f"no Runner is installed for {paths.name!r} under {paths.root}; "
+                f"run `agentic-runner install {paths.name}` first"
             )
         return cls.model_validate_json(paths.settings_file.read_text(encoding="utf-8"))
 
@@ -262,8 +309,8 @@ def install_channel(
     return InstallChannel.SYSTEMD_USER
 
 
-def run_environment(paths: OrgPaths, settings: WorkstationSettings) -> dict[str, str]:
-    """The environment ``agentic-runner run --org`` gives ``service.run``.
+def run_environment(paths: RunnerPaths, settings: WorkstationSettings) -> dict[str, str]:
+    """The environment ``agentic-runner run --name`` gives ``service.run``.
 
     Set here rather than in the service definition so one definition format -- a plist,
     a unit, a task -- stays a one-liner, and the three OSes cannot drift apart.
@@ -285,7 +332,7 @@ def run_environment(paths: OrgPaths, settings: WorkstationSettings) -> dict[str,
         "TEMPORAL_ADDRESS": settings.temporal_address,
         "WORKSPACE_ROOT": str(paths.workspaces),
         "WORKER_STATE_DIR": str(paths.contract_state),
-        # Ephemeral: one process per Organisation shares the host, so a fixed readiness
+        # Ephemeral: one process per Runner shares the host, so a fixed readiness
         # port inherited from a pod-style environment would collide on the second one.
         service.READINESS_PORT_ENV: "0",
     }
@@ -396,16 +443,16 @@ class ServiceDefinition:
     stop: list[list[str]]
 
 
-def runner_command(org: str, root: Path) -> list[str]:
+def runner_command(name: str, root: Path) -> list[str]:
     # The console script as found, not resolved: Homebrew's `bin/agentic-runner` is a
     # symlink into a versioned Cellar path that the next `brew upgrade` deletes.
     script = shutil.which("agentic-runner")
     prefix = [script] if script else [sys.executable, "-m", "agentic_runner.launch"]
-    return [*prefix, "run", "--org", org, "--root", str(root), "--login-agent"]
+    return [*prefix, "run", "--name", name, "--root", str(root), "--login-agent"]
 
 
 def service_definition(
-    paths: OrgPaths,
+    paths: RunnerPaths,
     settings: WorkstationSettings,
     *,
     platform: str = sys.platform,
@@ -415,8 +462,8 @@ def service_definition(
     command: Sequence[str] | None = None,
 ) -> ServiceDefinition:
     home = home or Path.home()
-    argv = list(command or runner_command(paths.org, paths.root))
-    name = f"{_LABEL_PREFIX}.{paths.org}"
+    argv = list(command or runner_command(paths.name, paths.root))
+    name = f"{_LABEL_PREFIX}.{paths.name}"
     if platform == "darwin":
         return _launch_agent(paths, settings, argv, name=name, home=home, uid=uid)
     if platform == "win32":
@@ -425,7 +472,7 @@ def service_definition(
 
 
 def _launch_agent(
-    paths: OrgPaths,
+    paths: RunnerPaths,
     settings: WorkstationSettings,
     argv: list[str],
     *,
@@ -458,19 +505,19 @@ def _launch_agent(
 
 
 def _systemd_user_unit(
-    paths: OrgPaths,
+    paths: RunnerPaths,
     settings: WorkstationSettings,
     argv: list[str],
     *,
     home: Path,
     user: str | None,
 ) -> ServiceDefinition:
-    unit_name = f"{_LABEL_PREFIX}-{paths.org}.service"
+    unit_name = f"{_LABEL_PREFIX}-{paths.name}.service"
     unit = home / ".config" / "systemd" / "user" / unit_name
     exec_start = " ".join(_systemd_quote(arg) for arg in argv)
     content = (
         "[Unit]\n"
-        f"Description=Agentic OS Runner for {paths.org}\n"
+        f"Description=Agentic OS Runner for {paths.name}\n"
         "After=network-online.target\n\n"
         "[Service]\n"
         f"ExecStart={exec_start}\n"
@@ -504,16 +551,16 @@ def _systemd_quote(value: str) -> str:
 
 
 def _logon_task(
-    paths: OrgPaths, argv: list[str], *, name: str, user: str | None
+    paths: RunnerPaths, argv: list[str], *, name: str, user: str | None
 ) -> ServiceDefinition:
     task_xml = paths.state_dir / f"{name}.task.xml"
-    task_name = f"\\agentic-runner\\{paths.org}"
+    task_name = f"\\agentic-runner\\{paths.name}"
     who = user or os.environ.get("USERNAME", "")
     arguments = subprocess.list2cmdline(argv[1:])
     content = f"""<?xml version="1.0" encoding="UTF-16"?>
 <Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
   <RegistrationInfo>
-    <Description>Agentic OS Runner for {escape(paths.org)}</Description>
+    <Description>Agentic OS Runner for {escape(paths.name)}</Description>
   </RegistrationInfo>
   <Triggers>
     <LogonTrigger><Enabled>true</Enabled><UserId>{escape(who)}</UserId></LogonTrigger>
@@ -564,7 +611,7 @@ def drive(commands: list[list[str]], *, run: Run = subprocess.run) -> None:
 # ------------------------------------------------------------------ status
 
 
-def process_id(paths: OrgPaths) -> int | None:
+def process_id(paths: RunnerPaths) -> int | None:
     """The running process's pid, if the pidfile names a live one."""
 
     try:
@@ -580,7 +627,7 @@ def process_id(paths: OrgPaths) -> int | None:
     return pid
 
 
-def heartbeat_age(paths: OrgPaths, *, now: datetime | None = None) -> float | None:
+def heartbeat_age(paths: RunnerPaths, *, now: datetime | None = None) -> float | None:
     try:
         stamped = paths.heartbeat_stamp.stat().st_mtime
     except OSError:
@@ -588,14 +635,14 @@ def heartbeat_age(paths: OrgPaths, *, now: datetime | None = None) -> float | No
     return max(0.0, (now or datetime.now(UTC)).timestamp() - stamped)
 
 
-def status_lines(paths: OrgPaths, *, now: datetime | None = None) -> list[str]:
-    """``status <org>``: the process, its identity and its heartbeat age."""
+def status_lines(paths: RunnerPaths, *, now: datetime | None = None) -> list[str]:
+    """``status <name>``: the process, its identity and its heartbeat age."""
 
     pid = process_id(paths)
     state = load_state(paths.state_dir)
     age = heartbeat_age(paths, now=now)
     lines = [
-        f"organisation   {paths.org} ({paths.state_dir})",
+        f"runner name    {paths.name} ({paths.state_dir})",
         f"process        {'running, pid ' + str(pid) if pid else 'not running'}",
         (
             f"identity       {state.runner_id} in {state.temporal_namespace} on {state.task_queue}"
@@ -609,6 +656,58 @@ def status_lines(paths: OrgPaths, *, now: datetime | None = None) -> list[str]:
     return lines
 
 
+_LIST_HEADER: Final = (
+    "NAME",
+    "ORGANISATION",
+    "CONTRACT",
+    "CONTROL PLANE",
+    "VERSION",
+    "LOGIN AGENT",
+)
+
+
+def list_lines(root: Path) -> list[str]:
+    """``list``: one row per Runner installed here (QTS-1774).
+
+    Ids, not names: the Runner is told neither the Organisation's nor the Contract's name.
+    Eight characters, as the console shows a Runner's id beside its name (Spec: Runners
+    rev 7).
+    """
+
+    names = installed_names(root)
+    if not names:
+        return [f"no workstation Runner is installed under {root}"]
+    rows = [_LIST_HEADER, *(_list_row(RunnerPaths(root=root, name=name)) for name in names)]
+    widths = [max(len(row[column]) for row in rows) for column in range(len(_LIST_HEADER) - 1)]
+    return [
+        "  ".join([*(cell.ljust(width) for cell, width in zip(row, widths, strict=False)), row[-1]])
+        for row in rows
+    ]
+
+
+def _list_row(paths: RunnerPaths) -> tuple[str, str, str, str, str, str]:
+    state = load_state(paths.state_dir)
+    contracts = load_llm_contracts(paths.state_dir)
+    try:
+        version = paths.started_version.read_text(encoding="utf-8").strip() or "-"
+    except OSError:
+        version = "-"
+    return (
+        paths.name,
+        state.temporal_namespace.removeprefix(NAMESPACE_PREFIX)[:8] if state else "-",
+        (
+            "-"
+            if not contracts
+            else str(contracts[0].contract_id)[:8]
+            if len(contracts) == 1
+            else f"{len(contracts)} Contracts"
+        ),
+        WorkstationSettings.load(paths).control_plane_url,
+        version,
+        "running" if process_id(paths) else "stopped",
+    )
+
+
 def next_step_lines(host_party: str) -> list[str]:
     """Where to go once the Runner is live (QTS-1314): the dogfood install ended at
     ``started`` and left the person with no idea what the console wanted next.
@@ -634,7 +733,7 @@ def next_step_lines(host_party: str) -> list[str]:
 
 
 async def install(
-    paths: OrgPaths,
+    paths: RunnerPaths,
     settings: WorkstationSettings,
     *,
     registration_token: str,
@@ -645,7 +744,7 @@ async def install(
     run: Run = subprocess.run,
     http_client: httpx.AsyncClient | None = None,
 ) -> list[str]:
-    """Register this Organisation's process and install its login agent.
+    """Register this Runner and install its login agent.
 
     Registration happens here, once, with the Runner Registration Token this user minted
     on /me/runners or the Organisation's Admin issued them (12 A6, QTS-1304) -- pasted at the
@@ -696,18 +795,18 @@ async def install(
     return lines
 
 
-def start(paths: OrgPaths, **driver: Any) -> None:
+def start(paths: RunnerPaths, **driver: Any) -> None:
     _drive_service(paths, "start", **driver)
 
 
-def stop(paths: OrgPaths, **driver: Any) -> None:
-    """Stop this Organisation's process; every other Organisation's keeps polling."""
+def stop(paths: RunnerPaths, **driver: Any) -> None:
+    """Stop this Runner; every other Runner on this machine keeps polling."""
 
     _drive_service(paths, "stop", **driver)
 
 
 def _drive_service(
-    paths: OrgPaths,
+    paths: RunnerPaths,
     verb: str,
     *,
     platform: str = sys.platform,
@@ -719,8 +818,8 @@ def _drive_service(
     drive(definition.start if verb == "start" else definition.stop, run=run)
 
 
-def run_process(paths: OrgPaths, *, login_agent: bool) -> int:
-    """``agentic-runner run --org``: what the login agent executes."""
+def run_process(paths: RunnerPaths, *, login_agent: bool) -> int:
+    """``agentic-runner run --name``: what the login agent executes."""
 
     settings = WorkstationSettings.load(paths)
     try:
@@ -730,13 +829,15 @@ def run_process(paths: OrgPaths, *, login_agent: bool) -> int:
         return 1
     for name, value in run_environment(paths, settings).items():
         os.environ[name] = value
-    store = open_workstation_store(paths.org, fallback=paths.credentials)
+    paths.started_version.write_text(runner_version, encoding="utf-8")
+    store = open_workstation_store(paths.name, fallback=paths.credentials)
     attestation = collect_attestation(
         channel=settings.install_channel,
         session=SessionKind.LOGIN_AGENT if login_agent else SessionKind.INTERACTIVE,
         store=store.kind,
         path=settings.path,
     )
-    # A workstation's hostname can name its person, so it is never reported (rev 3).
-    install = RunnerInstall(target=InstallTarget.WORKSTATION)
+    # A workstation's hostname can name its person, so it is never reported (rev 3); the
+    # name it was installed as is the person's choice, and the console lists it (QTS-1773).
+    install = RunnerInstall(target=InstallTarget.WORKSTATION, name=paths.name)
     return asyncio.run(service.run(host_store=store, attestation=attestation, install=install))