fcloud-sdk 0.2.0__tar.gz → 0.2.1__tar.gz

{fcloud_sdk-0.2.0 → fcloud_sdk-0.2.1}/CHANGELOG.md

@@ -4,6 +4,52 @@ All notable changes to the `fcloud` Python SDK and CLI are recorded here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
 versions follow [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [0.2.1] - 2026-09-14
+
+### Added
+- `fcloud login`: sign in through the browser (device authorization). Shows a
+  short code, opens the approval page, and saves a key minted for this
+  machine (named `cli:<hostname>`); then installs the fcloud skill for the
+  coding agents present on the machine (`--agents auto`, the default; also
+  `all`, a list, or `none`). `--no-browser` prints the URL and code instead
+  of opening a browser. A fresh install's first command starts the same
+  login, and `fcloud setup` with no key delegates to it.
+- Spend visibility: `fcloud sessions` shows `$/HR` (the rate billed on the
+  session's open usage interval while a host is held, 0 when cold), `SPENT`
+  (compute charged so far) and `AGE` (time on its current host) per row plus
+  a "Spending now" footer; `--json` rows carry `usd_per_hour`, `spent_usd`
+  and `host_age_seconds` (SDK: `Client.session_cost`). New `fcloud usage [--since DUR|TS] [--until TS]`
+  reports what the account was charged over a window (default 30 days) by
+  resource and session (SDK: `Client.billing_usage`).
+
+### Changed
+- `fcloud job ls` shows each job's COMMAND and EXIT code (from its process
+  index; `--json` rows carry `command` and `exit_code`), so rows are
+  tellable apart and failures visible without opening each job.
+
+### Fixed
+- `fcloud logs <sid> <pid>` with a pid the dispatcher has no record of now
+  exits 1 (`process_not_found`) like `wait` and `kill`, instead of printing
+  an empty stream with exit 0 (and `status: ""` in `--json`) that a poller
+  read as a finished, silent process. A just-spawned pid gets a few seconds
+  to reach the durable index before it is called unknown.
+- `fcloud wait` with a `--timeout` shorter than the unknown-pid grace window
+  exits 1 for an unknown pid, not 75 (retry), so scripted callers stop
+  retrying a typo forever.
+- Cold starts of `run`/`exec`/`job run` no longer dump every host status
+  frame (`⟵ session_status: building (phase_change) setup_timing ...`);
+  the fresh-allocation and reconnect paths now use the same quiet printer
+  as warm attaches.
+- `fcloud sweep harvest` no longer pulls the session's virtual `_logs/`
+  directory (`_logs/processes.json`) for a results glob like `*.json`; name
+  `_logs/` in the glob to fetch logs.
+- `fcloud sessions` sizes the HOST and SKU columns to the data (27-char AWS
+  host ids overflowed the fixed width on every row).
+- `fcloud volume list` shows each volume's last update time.
+- SKILL.md documents `fcloud sessions --limit N`.
+
 ## [0.2.0] - 2026-09-08
 
 ### Added

{fcloud_sdk-0.2.0 → fcloud_sdk-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fcloud-sdk
-Version: 0.2.0
+Version: 0.2.1
 Summary: Python SDK and CLI for the fcloud GPU compute platform
 Author: fcloud
 License-Expression: Apache-2.0
@@ -43,25 +43,35 @@ Requires Python 3.10+.
 
 ## Install
 
+```bash
+curl -fsSL https://fcloud-home.vercel.app/install.sh | sh
+```
+
+That installs the CLI from PyPI (via `uv` or `pipx`), signs you in through
+the browser, and installs the fcloud skill for coding agents on your machine.
+With your own Python:
+
 ```bash
 pip install fcloud-sdk
+fcloud login
 ```
 
 ## Setup
 
-Create an account on https://fcloud-home.vercel.app.
-Enter a credit card, and copy your API key.
-Or just run any `fcloud` command (or `fcloud login`): a fresh install
-walks you through sign-up and saves the key you paste.
+`fcloud login` opens https://fcloud-home.vercel.app to sign in (Google or
+email) and add a card, then saves a key minted for this machine. Running any
+`fcloud` command on a fresh install starts the same login.
 
 ```bash
-fcloud setup            # prompts for the key; optionally installs the agent skill
+fcloud login [--no-browser] [--agents auto|all|cursor|claude|codex|none]
+fcloud set_token <key>  # already have a key (CI, agents, a second machine)
+fcloud setup            # save a key you already have; install agent skills
 fcloud health           # verify connectivity
 ```
 
-`fcloud setup` also installs (by default) the fcloud skill file for supported
-coding agents (Cursor, Claude Code, Codex) so an agent can drive fcloud for you.
-Use `--agents none` to skip that.
+`fcloud login` installs the fcloud skill file for the coding agents it finds
+(Cursor, Claude Code, Codex — `--agents all` for every one) so an agent can
+drive fcloud for you. `fcloud setup --agents none` skips that.
 
 ## Quick start
 
@@ -141,6 +151,7 @@ Batch
   fcloud sweeps / fcloud sweep <status|logs|retry|cancel|wait> <name>
 
 Setup
+  fcloud login [--no-browser] [--agents auto|all|cursor|claude|codex|none]
   fcloud setup [--token KEY] [--agents all|cursor|claude|codex|none]
   fcloud set_token <api-key>
   fcloud --version

{fcloud_sdk-0.2.0 → fcloud_sdk-0.2.1}/README.md

@@ -9,25 +9,35 @@ Requires Python 3.10+.
 
 ## Install
 
+```bash
+curl -fsSL https://fcloud-home.vercel.app/install.sh | sh
+```
+
+That installs the CLI from PyPI (via `uv` or `pipx`), signs you in through
+the browser, and installs the fcloud skill for coding agents on your machine.
+With your own Python:
+
 ```bash
 pip install fcloud-sdk
+fcloud login
 ```
 
 ## Setup
 
-Create an account on https://fcloud-home.vercel.app.
-Enter a credit card, and copy your API key.
-Or just run any `fcloud` command (or `fcloud login`): a fresh install
-walks you through sign-up and saves the key you paste.
+`fcloud login` opens https://fcloud-home.vercel.app to sign in (Google or
+email) and add a card, then saves a key minted for this machine. Running any
+`fcloud` command on a fresh install starts the same login.
 
 ```bash
-fcloud setup            # prompts for the key; optionally installs the agent skill
+fcloud login [--no-browser] [--agents auto|all|cursor|claude|codex|none]
+fcloud set_token <key>  # already have a key (CI, agents, a second machine)
+fcloud setup            # save a key you already have; install agent skills
 fcloud health           # verify connectivity
 ```
 
-`fcloud setup` also installs (by default) the fcloud skill file for supported
-coding agents (Cursor, Claude Code, Codex) so an agent can drive fcloud for you.
-Use `--agents none` to skip that.
+`fcloud login` installs the fcloud skill file for the coding agents it finds
+(Cursor, Claude Code, Codex — `--agents all` for every one) so an agent can
+drive fcloud for you. `fcloud setup --agents none` skips that.
 
 ## Quick start
 
@@ -107,6 +117,7 @@ Batch
   fcloud sweeps / fcloud sweep <status|logs|retry|cancel|wait> <name>
 
 Setup
+  fcloud login [--no-browser] [--agents auto|all|cursor|claude|codex|none]
   fcloud setup [--token KEY] [--agents all|cursor|claude|codex|none]
   fcloud set_token <api-key>
   fcloud --version

{fcloud_sdk-0.2.0 → fcloud_sdk-0.2.1}/SKILL.md

@@ -25,6 +25,9 @@ fcloud set_token <api_key>  # one-time; saves to ~/.fcloud/token
 fcloud health               # verify connectivity
 ```
 
+(A human sets up with `fcloud login`, which signs in through the browser and
+mints a key for the machine; agents use `set_token` with a key they were given.)
+
 Token resolution order:
 
 1. `api_key=` parameter to `Client()`
@@ -303,7 +306,8 @@ filesystem later; a **job** for batch/CI-style runs with declared outputs.
 | Command                       | Description                                          |
 | ----------------------------- | ---------------------------------------------------- |
 | `fcloud create [--sku SKU]`     | Create a session (cold — $0, no host, until first used) |
-| `fcloud sessions [--all]`       | List sessions                                        |
+| `fcloud sessions [--all] [--limit N]` | List sessions with `$/HR` (billed rate), `SPENT` (compute so far) and `AGE` (time on its host) per row and a spending-now total (`--all --json` can be large; bound it with `--limit`) |
+| `fcloud usage [--since 24h]`   | What the account has been charged over a window (default 30 days), by resource and session |
 | `fcloud stop <session-id> [--wait]` | Stop a session now: halt GPU spend (files kept). `--wait` blocks until the workspace manifest is durable |
 
 
@@ -1215,6 +1219,8 @@ host (files restored from cloud storage) the next time you use it. You never run
 **Warmth**: `fcloud sessions` reports a session's state — `hot` (running, spending),
 `warm` (idle host held, spending), `stopping` (finishing teardown), `cold`
 (stopped, $0, resumes on use), or `preparing` (coming online).
+The `$/HR` column is the rate billed on the session's open usage interval while a
+host is held (0 when cold); `SPENT` is compute charged so far; the footer sums `$/HR`. `fcloud usage` reports what was actually charged.
 
 **Image**: Declarative container spec. Layers are cached by content hash. First run
 on a host triggers a build (30–120s); subsequent runs with the same image are instant.

{fcloud_sdk-0.2.0 → fcloud_sdk-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fcloud-sdk"
-version = "0.2.0"
+version = "0.2.1"
 description = "Python SDK and CLI for the fcloud GPU compute platform"
 readme = "README.md"
 license = "Apache-2.0"

{fcloud_sdk-0.2.0 → fcloud_sdk-0.2.1}/src/fcloud/SKILL.md

@@ -25,6 +25,9 @@ fcloud set_token <api_key>  # one-time; saves to ~/.fcloud/token
 fcloud health               # verify connectivity
 ```
 
+(A human sets up with `fcloud login`, which signs in through the browser and
+mints a key for the machine; agents use `set_token` with a key they were given.)
+
 Token resolution order:
 
 1. `api_key=` parameter to `Client()`
@@ -303,7 +306,8 @@ filesystem later; a **job** for batch/CI-style runs with declared outputs.
 | Command                       | Description                                          |
 | ----------------------------- | ---------------------------------------------------- |
 | `fcloud create [--sku SKU]`     | Create a session (cold — $0, no host, until first used) |
-| `fcloud sessions [--all]`       | List sessions                                        |
+| `fcloud sessions [--all] [--limit N]` | List sessions with `$/HR` (billed rate), `SPENT` (compute so far) and `AGE` (time on its host) per row and a spending-now total (`--all --json` can be large; bound it with `--limit`) |
+| `fcloud usage [--since 24h]`   | What the account has been charged over a window (default 30 days), by resource and session |
 | `fcloud stop <session-id> [--wait]` | Stop a session now: halt GPU spend (files kept). `--wait` blocks until the workspace manifest is durable |
 
 
@@ -1215,6 +1219,8 @@ host (files restored from cloud storage) the next time you use it. You never run
 **Warmth**: `fcloud sessions` reports a session's state — `hot` (running, spending),
 `warm` (idle host held, spending), `stopping` (finishing teardown), `cold`
 (stopped, $0, resumes on use), or `preparing` (coming online).
+The `$/HR` column is the rate billed on the session's open usage interval while a
+host is held (0 when cold); `SPENT` is compute charged so far; the footer sums `$/HR`. `fcloud usage` reports what was actually charged.
 
 **Image**: Declarative container spec. Layers are cached by content hash. First run
 on a host triggers a build (30–120s); subsequent runs with the same image are instant.

{fcloud_sdk-0.2.0 → fcloud_sdk-0.2.1}/src/fcloud/__main__.py

@@ -119,6 +119,7 @@ from fcloud.cli.sweep import (  # noqa: F401
     cmd_sweep,
     cmd_sweeps,
 )
+from fcloud.cli.usage import cmd_usage  # noqa: F401
 from fcloud.cli.volume import (  # noqa: F401
     _is_within,
     _volume_cat,

{fcloud_sdk-0.2.0 → fcloud_sdk-0.2.1}/src/fcloud/_direct_bridge.py

@@ -593,6 +593,10 @@ class _DirectBridge:
                 api_key=self._cfg.api_key,
                 sku=sku,
                 image_spec=spec_json,
+                # The same printer the attach path uses: without it the
+                # DirectClient default echoes every host frame, and a cold
+                # start dumps a dozen setup_timing lines on the user.
+                on_status=_persistent_session_status_printer,
             )
         )
         try:
@@ -1519,6 +1523,7 @@ class _DirectBridge:
                 allocation,
                 dispatcher_url=self._cfg.dispatcher_url,
                 api_key=self._cfg.api_key,
+                on_status=_persistent_session_status_printer,
             )
         )
         try:

{fcloud_sdk-0.2.0 → fcloud_sdk-0.2.1}/src/fcloud/cli/help.py

@@ -30,6 +30,7 @@ _HELP_GROUPS: tuple[tuple[str, tuple[tuple[str, str], ...]], ...] = (
         ("sessions", "fcloud sessions [SID] [--all] [--limit N]"),
         ("history", "fcloud history <SID> [--limit N]"),
         ("stop", "fcloud stop <SID>"),
+        ("usage", "fcloud usage [--since DUR]"),
     )),
     ("Files", (
         ("upload", "fcloud upload [--on SID] <local> [remote]"),
@@ -50,7 +51,7 @@ _HELP_GROUPS: tuple[tuple[str, tuple[tuple[str, str], ...]], ...] = (
         ("autoresearch", "fcloud autoresearch init [dir]"),
     )),
     ("Setup", (
-        ("login", "fcloud login"),
+        ("login", "fcloud login [--no-browser] [--agents TOOL]"),
         ("setup", "fcloud setup [--token KEY] [--agents TOOL]"),
         ("set_token", "fcloud set_token <api-key>"),
         ("config", "fcloud config <show|get|set|unset> [KEY] [VALUE]"),
@@ -129,8 +130,8 @@ def _print_command_groups() -> None:
 def print_help():
     print("fcloud — GPU compute from the command line\n")
     print("Setup:")
-    print("  fcloud login                Create an account / save your API key")
-    print("  fcloud setup                Save your API key + install agent skills")
+    print("  fcloud login                Sign in with your browser + install agent skills")
+    print("  fcloud setup                Save an API key you already have")
     print("  fcloud health               Check connectivity\n")
     print(_HELP_CONCEPTS + "\n")
     _print_command_groups()

{fcloud_sdk-0.2.0 → fcloud_sdk-0.2.1}/src/fcloud/cli/job.py

@@ -2,6 +2,7 @@
 
 import sys
 import time
+from concurrent.futures import ThreadPoolExecutor
 
 from fcloud.cli import output, sessions
 from fcloud.cli.common import (
@@ -223,22 +224,76 @@ def _job_ls(args: list[str]) -> None:
               reverse=True)
     if limit_n > 0:
         jobs = jobs[:limit_n]
+    runs = _job_runs(client, [s.session_id for s in jobs])
     if output._JSON_OUTPUT:
         output._out({"jobs": [
             {"session_id": s.session_id, "status": s.status,
              "state": _session_state(s), "lifecycle": s.lifecycle,
-             "created_at": s.created_at}
+             "created_at": s.created_at,
+             "command": runs[s.session_id]["command"],
+             "exit_code": runs[s.session_id]["exit_code"]}
             for s in jobs]})
         return
     if not jobs:
         print("No jobs. Run one with: fcloud job run -- <cmd>"
               + ("" if show_all else "  (--all includes finished jobs)"))
         return
-    print(f"{'JOB':<22} {'STATE':<12} {'CREATED'}")
-    print("-" * 56)
+    print(f"{'JOB':<22} {'STATE':<12} {'EXIT':<5} {'CREATED':<21} COMMAND")
+    print("-" * 100)
     for s in jobs:
+        run = runs[s.session_id]
+        code = run["exit_code"]
         print(f"{s.session_id:<22} {_session_state(s):<12} "
-              f"{s.created_at or ''}")
+              f"{'' if code is None else code:<5} {s.created_at or '':<21} "
+              f"{_command_cell(run['command'])}")
+
+
+# One index read per listed job — bounded by the rows shown, and fanned out
+# so a 50-row listing costs one round-trip's latency, not fifty.
+_JOB_LS_INDEX_WORKERS = 8
+
+
+def _job_runs(client, sids: list[str]) -> dict[str, dict]:
+    """The command and exit code of each job's run, from its process index.
+
+    A job is one spawned command, so the index's first record IS the job;
+    without it `job ls` is a list of opaque session ids that cannot say
+    which row failed or which was which. Missing or unreadable index →
+    blanks: a listing must never fail because one job's log is unreadable.
+    """
+    if not sids:
+        return {}
+    with ThreadPoolExecutor(max_workers=_JOB_LS_INDEX_WORKERS) as pool:
+        return dict(zip(sids, pool.map(
+            lambda sid: _job_run_from_index(client, sid), sids), strict=True))
+
+
+def _job_run_from_index(client, sid: str) -> dict:
+    try:
+        procs = client.list_session_processes(sid)
+    except Exception:  # noqa: BLE001 — best-effort enrichment
+        procs = []
+    first = min(procs, key=lambda p: p.get("started_at_ms") or 0,
+                default=None)
+    if not first:
+        return {"command": None, "exit_code": None}
+    command = first.get("command")
+    if isinstance(command, list):
+        # `job run` wraps a string command in a login shell (see
+        # fcloud.job._shape_command); show what the user typed, not the
+        # wrapper.
+        if len(command) == 3 and command[1] == "-lc" \
+                and command[0] in ("/bin/sh", "bash", "sh"):
+            command = [command[2]]
+        command = " ".join(str(c) for c in command)
+    return {"command": command or None, "exit_code": first.get("exit_code")}
+
+
+def _command_cell(command: str | None, width: int = 40) -> str:
+    if not command:
+        return ""
+    one_line = " ".join(command.split())
+    return one_line if len(one_line) <= width else one_line[:width - 1] + "…"
 
 
 def _job_logs(args: list[str]) -> None:

{fcloud_sdk-0.2.0 → fcloud_sdk-0.2.1}/src/fcloud/cli/processes.py

@@ -18,7 +18,12 @@ from fcloud.cli.console import _pid_emitter
 from fcloud.cli.context import _require_volumes_exist, _resolve_volume_mounts
 from fcloud.cli.migration import _follow_reconnect, _tail_follow_delta
 from fcloud.cli.registry import cmd
-from fcloud.cli.wait import _print_lost_process_notice, _process_lost
+from fcloud.cli.wait import (
+    _confirm_unknown_process,
+    _print_lost_process_notice,
+    _process_lost,
+    _process_unregistered,
+)
 from fcloud.cli_args import SPECS, split
 from fcloud.client import Client, SessionNotFoundError
 from fcloud.types import ProcessStatus
@@ -150,10 +155,38 @@ def _logs_dispatch(client: Client, sid: str, pid: str, opts: dict) -> None:
     session_status = log_result.session_status
     if not log_result.is_terminal and not session_status:
         session_status = _authoritative_session_status(client, sid)
+    if _process_unregistered(log_result):
+        _refuse_unknown_process(client, sid, pid)
     _print_log_result(log_result, sid=sid, pid=pid,
                       session_status=session_status)
 
 
+# A just-spawned process reaches the durable index a second or two after
+# `spawn` returns; a one-shot read inside that window must not call the
+# pid unknown. Short — `logs` is interactive — and zeroed by tests.
+_LOGS_UNKNOWN_PID_GRACE_S = 4.0
+_LOGS_UNKNOWN_PID_POLL_S = 1.0
+
+
+def _refuse_unknown_process(client: Client, sid: str, pid: str) -> None:
+    """Exit 1 (process_not_found) for a pid the index has no record of.
+
+    The durable read answers 200 with an empty stream and no status for
+    any pid at all, so without this a typo'd id printed as a finished,
+    silent process: status "" is not "running", and a poller following
+    the docs read it as success. The index is the authority, re-checked
+    briefly so a fresh spawn's flush lag isn't mistaken for a bad id."""
+    deadline = time.monotonic() + _LOGS_UNKNOWN_PID_GRACE_S
+    while True:
+        if not _confirm_unknown_process(client, sid, pid):
+            # Recorded (or the index read failed): print what we have
+            # rather than blame the caller on a transient.
+            return
+        if time.monotonic() >= deadline:
+            _fail_process_not_found(sid, pid)
+        time.sleep(_LOGS_UNKNOWN_PID_POLL_S)
+
+
 def _parse_logs_args(args: list[str]) -> tuple[str, str, dict]:
     sid = ""
     pid = ""

{fcloud_sdk-0.2.0 → fcloud_sdk-0.2.1}/src/fcloud/cli/sessions.py

@@ -2,6 +2,7 @@
 
 import re
 import sys
+from concurrent.futures import ThreadPoolExecutor
 from datetime import datetime, timezone
 
 from fcloud.cli import output
@@ -214,6 +215,7 @@ def cmd_sessions(args: list[str]) -> None:
     truncated = limit_n > 0 and total > limit_n
     if limit_n > 0:
         sessions = sessions[:limit_n]
+    costs = _session_costs(client, sessions)
     if output._JSON_OUTPUT:
         output._out({"sessions": [
             {"session_id": s.session_id, "project_id": s.project_id,
@@ -232,6 +234,11 @@ def cmd_sessions(args: list[str]) -> None:
              # False = owner opted out of checkpoint/restore (preemption
              # rebuilds cold, no region pin).
              "checkpoint": s.checkpoint,
+             # What this row costs right now and for how long it has: the
+             # first question in a beta ("what am I paying for?").
+             "usd_per_hour": _session_rate(s, costs),
+             "spent_usd": _session_spent(s, costs),
+             "host_age_seconds": _session_host_age_s(s),
              "provisioning": s.provisioning}
             for s in sessions],
             "total": total, "returned": len(sessions),
@@ -241,16 +248,7 @@ def cmd_sessions(args: list[str]) -> None:
         print("No active sessions." + ("" if show_all
               else " Try --all to include cold/failed/dead."))
         return
-    print(f"{'SESSION ID':<30} {'HOST':<25} {'SKU':<18} {'STATE'}")
-    print("-" * 85)
-    for s in sessions:
-        state = _session_state(s)
-        detail = _provisioning_label(s)
-        if detail:
-            state = f"{state}: {detail}"
-        if not s.checkpoint:
-            state += " [no-checkpoint]"
-        print(f"{s.session_id:<30} {s.host_id:<25} {s.sku:<18} {state}")
+    _print_sessions_table(sessions, costs)
     if truncated:
         print(f"\nShowing {len(sessions)} of {total} sessions. "
               f"Use --limit N (or --limit 0 for all).")
@@ -260,6 +258,122 @@ def cmd_sessions(args: list[str]) -> None:
           "ended = finished job (never resumes)")
 
 
+def _print_sessions_table(sessions: list, costs: dict[str, dict]) -> None:
+    # Sized to the data: a fixed HOST width overflowed into SKU on every
+    # row for 27-char AWS host ids.
+    host_w = max(25, *(len(s.host_id) for s in sessions))
+    sku_w = max(18, *(len(s.sku) for s in sessions))
+    print(f"{'SESSION ID':<30} {'HOST':<{host_w}} {'SKU':<{sku_w}} "
+          f"{'$/HR':>7} {'SPENT':>7} {'AGE':>7}  STATE")
+    print("-" * (30 + host_w + sku_w + 36))
+    for s in sessions:
+        state = _session_state(s)
+        detail = _provisioning_label(s)
+        if detail:
+            state = f"{state}: {detail}"
+        if not s.checkpoint:
+            state += " [no-checkpoint]"
+        rate, spent = _session_rate(s, costs), _session_spent(s, costs)
+        age = _session_host_age_s(s)
+        print(f"{s.session_id:<30} {s.host_id:<{host_w}} {s.sku:<{sku_w}} "
+              f"{_fmt_usd(rate):>7} {_fmt_usd(spent):>7} "
+              f"{_fmt_age(age) if age is not None else '-':>7}  {state}")
+    print(_spend_footer(sessions, costs))
+
+
+# States in which a host is held for the session and the meter runs.
+_SPENDING_STATES = frozenset({"hot", "warm", "stopping"})
+_COST_READ_WORKERS = 8
+
+
+def _session_costs(client, sessions: list) -> dict[str, dict]:
+    """Session id -> its billing record, for the sessions holding a host.
+
+    The rate a session accrues at is the price snapshotted on its open
+    usage interval — the admin price book keyed by SKU, falling back to
+    the host's internal cost — so it is read from the session's own cost
+    record, never re-derived. One read per spending row (cold rows cost
+    $0 and are skipped), fanned out. Best-effort: a billing-less
+    environment (501) or a failed read leaves the columns blank; the
+    listing itself never fails over pricing."""
+    spending = [s for s in sessions if _session_state(s) in _SPENDING_STATES]
+    if not spending:
+        return {}
+
+    def _read(sid: str) -> dict | None:
+        try:
+            return client.session_cost(sid)
+        except Exception:  # noqa: BLE001 — pricing is decoration on a listing
+            return None
+    with ThreadPoolExecutor(max_workers=_COST_READ_WORKERS) as pool:
+        got = list(pool.map(_read, [s.session_id for s in spending]))
+    return {s.session_id: rec for s, rec in zip(spending, got, strict=True)
+            if rec is not None}
+
+
+def _session_rate(s, costs: dict[str, dict]) -> float | None:
+    """$/hr the session is accruing now: the open interval's snapshotted
+    price while a host is held, 0 for a cold/ended session, None when
+    the cost record could not be read."""
+    if _session_state(s) not in _SPENDING_STATES:
+        return 0.0
+    rec = costs.get(s.session_id)
+    if rec is None:
+        return None
+    intervals = rec.get("intervals") or []
+    open_ivs = [iv for iv in intervals if iv.get("open")]
+    current = (open_ivs or intervals)[-1:] or [{}]
+    return (current[0].get("price_usd_micros_per_hour") or 0) / 1_000_000
+
+
+def _session_spent(s, costs: dict[str, dict]) -> float | None:
+    """Compute charged so far on this session, when its record was read."""
+    rec = costs.get(s.session_id)
+    if rec is None:
+        return None
+    return (rec.get("compute_usd_micros") or 0) / 1_000_000
+
+
+def _fmt_usd(amount: float | None) -> str:
+    if amount is None:
+        return "-"
+    # Cents-scale rates (a $0.015/hr CPU box) must not round to 0.00/0.02.
+    return f"{amount:.2f}" if amount == 0 or amount >= 0.1 else f"{amount:.4f}"
+
+
+def _session_host_age_s(s) -> int | None:
+    """Seconds the session has held its current host, or None off-host."""
+    if _session_state(s) not in _SPENDING_STATES:
+        return None
+    since = _parse_api_timestamp(s.allocated_at or s.created_at)
+    if since is None:
+        return None
+    return max(0, int((datetime.now(timezone.utc) - since).total_seconds()))
+
+
+def _fmt_age(seconds: int) -> str:
+    if seconds < 60:
+        return f"{seconds}s"
+    if seconds < 3600:
+        return f"{seconds // 60}m"
+    if seconds < 86400:
+        return f"{seconds // 3600}h{(seconds % 3600) // 60:02d}m"
+    return f"{seconds // 86400}d{(seconds % 86400) // 3600}h"
+
+
+def _spend_footer(sessions: list, costs: dict[str, dict]) -> str:
+    spending = [s for s in sessions if _session_state(s) in _SPENDING_STATES]
+    if not spending:
+        return "\nSpending now: $0/hr (no session holds a host)"
+    rates = [_session_rate(s, costs) for s in spending]
+    known = [r for r in rates if r is not None]
+    line = (f"\nSpending now: ${_fmt_usd(sum(known))}/hr across "
+            f"{len(spending)} session(s) holding a host")
+    if len(known) < len(spending):
+        line += f" ({len(spending) - len(known)} with no billing record)"
+    return line + " — stop one with: fcloud stop <session-id>"
+
+
 @cmd("history", "fcloud history <session-id> [--limit N]",
      "Show a session's lifecycle timeline")
 def cmd_history(args: list[str]) -> None: