ftown 0.25.2 → 0.26.0

package/dist/wire-types.d.ts

@@ -50,8 +50,23 @@ export interface Session {
     /** Historical automation provenance; new sessions cannot set it. */
     loopId?: string;
     usage?: SessionUsage;
+    card?: {
+        state: string;
+        headline: string;
+        progress?: {
+            done: number;
+            total: number;
+        };
+        blockedOn?: {
+            kind: string;
+            ref?: string;
+            text: string;
+        };
+        next?: string;
+        updatedAt: string;
+    };
 }
-export type MailType = 'message' | 'task' | 'result' | 'escalation';
+export type MailType = 'message' | 'task' | 'result' | 'escalation' | 'fyi';
 export declare const MAIL_TYPES: readonly MailType[];
 /** Per-session inbox message, as returned by GET/POST /api/sessions/:id/inbox. */
 export interface MailMessage {
@@ -65,6 +80,7 @@ export interface MailMessage {
     body: string;
     deliveredAt?: string;
     deliveredVia?: string;
+    nudgedAt?: string;
 }
 export declare const AUTOMATION_REMOVED_CODE: "automation_removed";
 export declare const AUTOMATION_REMOVED_MESSAGE = "Recurring loops and factory automation have been removed";

package/dist/wire-types.js

@@ -1,5 +1,5 @@
 // Shared wire shapes for the in-process CLI runtime and local bridge API.
-export const MAIL_TYPES = ['message', 'task', 'result', 'escalation'];
+export const MAIL_TYPES = ['message', 'task', 'result', 'escalation', 'fyi'];
 export const AUTOMATION_REMOVED_CODE = 'automation_removed';
 export const AUTOMATION_REMOVED_MESSAGE = 'Recurring loops and factory automation have been removed';
 /**

package/dist/wire-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"wire-types.js","sourceRoot":"","sources":["../src/wire-types.ts"],"names":[],"mappings":"AAAA,0EAA0E;AA4D1E,MAAM,CAAC,MAAM,UAAU,GAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC;AAgB3F,MAAM,CAAC,MAAM,uBAAuB,GAAG,oBAA6B,CAAC;AACrE,MAAM,CAAC,MAAM,0BAA0B,GAAG,0DAA0D,CAAC;AAErG;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,UAAmB;IAC9C,OAAO,IAAI,CAAC;AACd,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,iBAAiB,CAAC,CAAc;IAC9C,OAAO,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;AACpE,CAAC"}
+{"version":3,"file":"wire-types.js","sourceRoot":"","sources":["../src/wire-types.ts"],"names":[],"mappings":"AAAA,0EAA0E;AA6D1E,MAAM,CAAC,MAAM,UAAU,GAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,CAAC,CAAC;AAiBlG,MAAM,CAAC,MAAM,uBAAuB,GAAG,oBAA6B,CAAC;AACrE,MAAM,CAAC,MAAM,0BAA0B,GAAG,0DAA0D,CAAC;AAErG;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,UAAmB;IAC9C,OAAO,IAAI,CAAC;AACd,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,iBAAiB,CAAC,CAAc;IAC9C,OAAO,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;AACpE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ftown",
-  "version": "0.25.2",
+  "version": "0.26.0",
   "description": "CLI bridge for ftown — generic PTY-over-Centrifugo relay",
   "type": "module",
   "main": "dist/index.js",
@@ -9,6 +9,7 @@
     "ftown": "dist/ftown-cli.js",
     "ftown-harness": "dist/harness-cli.js",
     "ftown-env": "dist/ftown-env-cli.js",
+    "ftown-quota": "dist/quota-cli.js",
     "ftown-sessions": "bin/ftown-sessions"
   },
   "files": [
@@ -72,5 +73,5 @@
   "overrides": {
     "qs": "6.16.1"
   },
-  "gitHead": "2d012a347cd62c7aac8834e6519812c05651dac1"
+  "gitHead": "033b06c892db214c1104779f68ef4f36e3c567f8"
 }

package/skills/ftown/SKILL.md

@@ -51,6 +51,8 @@ ftown sessions preview --add ./extra.html
 ftown sessions preview --remove notes.md
 ftown sessions preview --clear
 ftown sessions preview-reply --message "The preview is ready."
+ftown status set --state working --headline "Reviewing the API client" --progress 0/1
+ftown board
 ftown harness mail send <session-id> --type task "review the API client"
 ftown harness mail read
 ftown env --help
@@ -60,7 +62,8 @@ ftown start --help
 
 Read `references/sessions.md` for the session, mail and terminal command
 reference. Read `references/orchestrator.md` for practical worker coordination
-examples. Each command group also has `--help`.
+examples. Read `references/quota.md` before choosing a CLI, model and effort for delegated
+work (`ftown quota --json`). Each command group also has `--help`.
 
 `ftown sessions preview <path...>` registers up to 12 files in the current
 session's working directory for the dashboard, in this order. Kind is by
@@ -94,10 +97,33 @@ ftown harness mail send --parent --type escalation "Blocked: need the API contra
 ```
 
 Mail arrives as `[ftown mail]` context through harness hooks/extensions where
-available. Cursor and shell sessions receive an idle nudge to read their inbox.
-Prefer mail for agent communication; use terminal key injection only when the
-task needs it. Inspect peers with `ftown sessions list` and
-`ftown sessions screen <id> --limit 100`.
+available. Mail is for directed instructions (`--type task`), results
+(`--type result`) and escalations (`--type escalation`). Use `--type fyi` for
+non-urgent notes; `fyi` never wakes the recipient. Progress and status go on
+your card (below), never as mail. Each new batch of mail nudges the recipient
+at most once; un-read mail stays in the inbox — read it with
+`ftown harness mail read`. Prefer mail for agent communication; use terminal
+key injection only when the task needs it. Inspect peers with `ftown board`
+and `ftown sessions list`.
+
+## Status and board
+
+Keep your card current with `ftown status set` at meaningful transitions —
+starting, becoming blocked, finishing — not every turn. Set state
+(`working`, `blocked`, `waiting_review`, `done`, `failed`), a short headline,
+progress and any blocker. Writing a card wakes nobody. Parents read
+`ftown board` (one line per child) instead of screening quiet workers, and
+wait with `ftown board --wait --until any-done|any-blocked|any-ready` or
+`ftown events --wait`. Idle workers show on the board and as an `idle` event.
+
+```bash
+ftown status set --state working --headline "Implementing the card store" --progress 1/4
+ftown status set --state blocked --headline "Need the API contract" --on parent --text "Waiting on the contract decision"
+ftown status set --state done --headline "Card store shipped; checks green"
+ftown board
+ftown board --wait --until any-done --timeout 300
+ftown events --wait
+```
 
 ## Human attention and pull requests
 

package/skills/ftown/references/orchestrator.md

@@ -11,20 +11,30 @@ bounded task, clear writable files and acceptance checks; save the returned
 set it when the task calls for a different harness. Provider flavors require a
 bridge-host token configured with `ftown env set <flavor>`.
 
+Before picking a CLI, model and effort for delegated work, run `ftown quota --json`
+and follow the decision procedure in `quota.md` (owner tiers first). Pass the
+choice as `--shell <provider>`; add `--model <id>` only with an id from that
+harness's model list. Never route to `exhausted`.
+
 ```bash
 ftown sessions list
 ftown sessions create --parent --workdir /path/to/repo --name review-auth \
   --prompt "Review auth; read-only. Report concrete findings and validation."
-ftown sessions screen <worker-id> --limit 100
-ftown sessions running <worker-id>
+ftown board --wait --until any-done --timeout 300
+ftown board
 ftown harness mail send <worker-id> --type task "Check the expired-token case too"
-ftown sessions tell --children "Pause and report status"
 ```
 
-Use terminal output to investigate a quiet worker. Mail handles results and
-escalations; read them with `ftown harness mail read`. When waiting, let incoming
-mail resume the conversation rather than repeatedly polling. Parallel tasks need
-disjoint write ownership and serialized shared resources.
+Coordinate in a loop: spawn children, wait with
+`ftown board --wait --until any-done --timeout 300` (or `any-blocked`,
+`any-ready`, `all-done`; `ftown events --wait` waits for the next event), act
+on the board and mail, then repeat until every child is done. Children keep
+their cards current; progress goes on the card, never as mail. Use
+`ftown sessions screen <worker-id> --limit 100` only to investigate terminal
+detail. Mail handles directed instructions, results and escalations; read it
+with `ftown harness mail read`. Each new batch nudges the recipient at most
+once, and a nudge may append a one-line digest of child status. Parallel tasks
+need disjoint write ownership and serialized shared resources.
 
 After accepting a worker's result, request any concrete follow-up before
 explicit cleanup with `ftown sessions remove <worker-id>`.

package/skills/ftown/references/quota.md

@@ -0,0 +1,177 @@
+# Quota-aware routing
+
+Read `../SKILL.md` for identity and reporting. This reference covers choosing the
+CLI, model and effort for delegated work. The owner sets up tiers; you choose.
+`ftown quota` reports data and never chooses for you.
+
+## When to use
+
+- Before `ftown sessions create` for a child whose harness you are free to pick.
+- When a worker stopped on a usage limit, before re-routing its task.
+- Not needed when the user named the harness or model. Keep their choice.
+
+## What to run
+
+```bash
+ftown quota --json                    # full report
+ftown quota claude codex --json       # only the named harnesses
+ftown quota --json --no-models        # skip model lists (picks become unchecked)
+ftown quota --json --timeout 30       # per-harness limit, 1-600 s, default 15
+```
+
+Harnesses: `claude`, `codex`, `grok`, `muse`, `agy`, `opencode`. If `ftown` is
+not on PATH, use `~/.ftown/ftown quota`. `--models` only affects table mode.
+
+A run takes several seconds. It launches hidden local CLIs to read their usage
+and model lists. It makes no model turns. The numbers describe the owner's
+subscription plans (5-hour and weekly windows), not API spend.
+
+## Decision procedure
+
+The owner configures tiers in the dashboard ("Model routing..." on a bridge).
+Each tier has a `name`, a `description` of the work it is for, an ordered list of
+`picks` (CLI + model + effort), and free-text `guidance`. The report also has a
+global free-text `steering`.
+
+1. Read `routingConfig.status`. If it is not `ok`, see "When things are missing".
+2. Match the task to a tier by the tier `description`s. Pick the closest one.
+3. Walk that tier's `picks` in order. Skip any pick whose `problem` is not null:
+   the model is gone or the effort is unsupported.
+4. Weigh each remaining pick: `availability`, `leftPercent` (null when `unknown`),
+   `resetsAt` (null when `unknown`), and `scopedLimits`. A scoped limit (for example
+   one model family) can be tighter than the plan-wide figure. Scopes usually name a
+   model family that appears in the model id or name, so matching a scope to a pick
+   is your judgment; when several match use the one with most used.
+5. `checked: false` means the harness's model list could not be read, so the pick
+   was not verified. It is usable with care: expect a possible launch failure.
+6. Apply the tier's `guidance` and the global `steering`. They are the owner's
+   instructions and outrank the pick order when they conflict. Example: if
+   steering says "don't fully exhaust Claude", skip a Claude pick that is `low`
+   even when it is first.
+7. Guidance is free text and may name a class, such as "otherwise any free
+   opencode model". Resolve it against `models`: filter that provider's
+   `models[].models[]` by `pricing` and choose one that fits the task. If that
+   provider's list is empty you cannot resolve the class, so fall back to `routing[]`
+   and say so. `pricing` is `free` (zero-priced), `included` (covered by a plan the
+   owner holds) or `paid` (billed per use). It is omitted when unknown.
+8. Launch the choice (next section). Report to the user which tier and pick you
+   used, and why if you departed from the pick order.
+
+## Availability values
+
+Each pick carries its provider's `availability`. The same values appear in `routing[]`.
+
+- `available`: enough left for normal work. Use it.
+- `low`: `leftPercent` below 15 in the binding (tightest) window, or `runway`
+  below 0.5 when `runway` is not null. Use only for small tasks, when guidance
+  allows it, or when nothing `available` fits.
+- `exhausted`: `leftPercent` 1 or less. Never use it before `resetsAt`.
+- `unknown`: no usable numbers. It is not proof of empty or full quota. It ranks
+  below `low` and above `exhausted`; use it as a fallback after `available` and
+  `low`, and say so.
+
+If a window resets within 10 minutes it is reported as `available` with `leftPercent`
+100 and `runway` null, even if `usedPercent` was high. `routing[]` is ordered best
+first as available, then low, then unknown, then exhausted.
+
+`leftPercent` is percent left in the binding (tightest) window. `windows[].usedPercent`
+in `providers` is percent used. Do not mix them up.
+
+## Turning a pick into a launch
+
+Find the provider's entry in `models`. It gives `modelFlag` (for example
+`--model <id>`) and `effortFlag` (for example `--effort <level>`, or null when
+the harness has no effort flag). Use the pick's `model` as the id, verbatim, and
+its `effort` as the level. `effort: null` means omit the effort flag.
+
+opencode takes effort as a `#variant` suffix on the model, for example
+`provider/model#high`. Check its `effortFlag` and the model's `efforts` in the report.
+
+```bash
+ftown sessions create --shell <provider> --model <id> --parent \
+  --workdir "$PWD" --name review-auth --prompt "..."
+```
+
+Where `ftown sessions create` has no flag for the effort, apply `effortFlag` as
+the harness documents it. Omit `--model` to take the harness default.
+
+## When things are missing
+
+- `routingConfig.status` is `missing`: the owner has set no tiers. `tiers` is
+  empty. Walk `routing[]` in order (already best first: available, low, unknown,
+  exhausted): take the first `available`, else `low` only for small tasks, else
+  `unknown` with disclosure, and never use `exhausted` before its `resetsAt`.
+  Pick a model from `models` and tell the user no tiers are configured.
+- `routingConfig.status` is `invalid`: `routingConfig.errors` lists the problems.
+  Treat it like `missing`, and tell the user the file at `routingConfig.path`
+  needs fixing. Still honor `steering` if it is non-empty.
+- An empty tier (no `picks`): use its `guidance` if it has any; otherwise fall
+  back to `routing[]`.
+- Every pick unusable (all have a `problem`, or are `exhausted`): follow the
+  guidance if it names an alternative. Otherwise try the next closest tier, then
+  `routing[]`. If nothing is usable, stop and ask the user rather than launching
+  on an exhausted plan.
+- A provider with `status` other than `ok` (`no_data`, `auth`, `unavailable`,
+  `error`): read its `message`. Its routing is `unknown`. For `auth`, tell the
+  user what to fix. A `models` entry with status other than `ok` has an empty
+  `models` list, so its picks are `checked: false`.
+- opencode may expose no plan usage at all, so when it reports no windows its
+  availability will be `unknown`. That is expected when it happens. Judge it by
+  `pricing` (`free` models are safe to use) and by the owner's guidance, not by
+  quota.
+
+## JSON field reference
+
+| Field | Meaning |
+|---|---|
+| `generatedAt` | ISO time of the report |
+| `providers[]` | raw readings: `provider`, `status`, `plan`, `windows[]`, `source`, `observedAt`, `message`, optional `scopedLimits[]` |
+| `providers[].windows[]` | `kind` (`five_hour`/`weekly`), `usedPercent` (used, may be null), `resetsAt`, `windowMinutes`, `note` |
+| `scopedLimits[]` | partial limit: `scope` (e.g. a model family), `kind`, `usedPercent`, `resetsAt` |
+| `routing[]` | per provider, best first: `provider`, `availability`, `leftPercent`, `bindingWindow`, `resetsAt`, `resetsInMinutes`, `runway` (1 = on pace, >1 spare, <1 will run out early, null when length or reset unknown), `reason` |
+| `models[]` | per provider: `provider`, `status` (`ok`/`unavailable`/`error`; empty `models` unless `ok`), `models[]`, `source` (`live`/`cached`), `observedAt`, `message`, `modelFlag`, `effortFlag` |
+| `models[].models[]` | `id`, `name`, `isDefault`, `description`, `contextTokens`, `efforts[]`, `defaultEffort`, optional `pricing` |
+| `routingConfig` | `status` (`ok`/`missing`/`invalid`), `path`, `errors[]` |
+| `tiers[]` | `name`, `description`, `picks[]`, `guidance`. Empty unless status is `ok` |
+| `tiers[].picks[]` | `provider`, `model`, `effort`, `modelName`, `availability`, `leftPercent`, `resetsAt`, `scopedLimits[]`, `problem`, `checked` |
+| `steering` | global owner instructions, verbatim, `""` when none |
+
+Trimmed example (invented values):
+
+```json
+{
+  "routingConfig": { "status": "ok", "path": "/home/u/.ftown/model-routing.json", "errors": [] },
+  "steering": "Don't fully exhaust Claude.",
+  "tiers": [
+    {
+      "name": "complex",
+      "description": "Hard development and debugging",
+      "guidance": "Otherwise any free opencode model.",
+      "picks": [
+        { "provider": "claude", "model": "model-a", "effort": "high", "modelName": "Model A",
+          "availability": "low", "leftPercent": 9, "resetsAt": "2026-01-05T00:00:00Z",
+          "scopedLimits": [], "problem": null, "checked": true },
+        { "provider": "codex", "model": "model-b", "effort": "medium", "modelName": null,
+          "availability": "available", "leftPercent": 70, "resetsAt": "2026-01-06T00:00:00Z",
+          "scopedLimits": [], "problem": null, "checked": true }
+      ]
+    }
+  ],
+  "models": [
+    { "provider": "codex", "status": "ok", "modelFlag": "--model <id>", "effortFlag": "--effort <level>",
+      "models": [ { "id": "model-b", "efforts": ["low", "medium", "high"], "pricing": "included" } ] }
+  ]
+}
+```
+
+Here the first pick is `low` and steering says not to exhaust Claude, so choose
+the second pick: `codex`, `model-b`, effort `medium`.
+
+## Limits
+
+- Grok has only a weekly window. `FTOWN_QUOTA_GROK_NO_REFRESH=1` skips its hidden
+  refresh and uses the last logged value.
+- opencode lists only its subscription providers by default. Override with
+  `FTOWN_QUOTA_OPENCODE_PROVIDERS=a,b`.
+- The tool does not rank models by capability. The owner's tiers and your
+  judgment decide.

package/skills/ftown/references/sessions.md

@@ -51,6 +51,43 @@ ftown sessions archive
 ftown sessions revive <session-id>
 ```
 
+## Status, board and events
+
+Each session has a card: state (`working`, `blocked`, `waiting_review`,
+`done`, `failed`), headline, optional progress, blocker and next step. Keep
+your own card current at meaningful transitions, not every turn. Writing a
+card wakes nobody. The target defaults to `FTOWN_SESSION_ID`; `--session-id
+<id>` selects another session.
+
+```bash
+# Print my card
+ftown status [--json] [--session-id <id>]
+
+# Update my card (omitted fields unchanged; first write needs --state and --headline)
+ftown status set [--state <s>] [--headline <t>] [--progress <d>/<t>|--no-progress] \
+  [--on human|parent|external|session:<id>] [--text <t>] [--next <t>|--no-next] [--session-id <id>]
+
+# Remove my card
+ftown status clear [--session-id <id>]
+
+# One line per child of my tree
+ftown board [--json] [--since <n>] [--ready] [--all] [--session-id <id>]
+
+# Wait until a board condition holds
+ftown board [--wait --until any-change|any-done|any-blocked|all-done|any-ready [--timeout <s≤300>]] [--session-id <id>]
+
+# Tree events for my tree (status, attention, pr, preview, exit, idle, result, mail)
+ftown events [--json] [--since <n>] [--limit <n>] [--wait [--timeout <s≤300>]] [--session-id <id>]
+```
+
+`--ready` lists only children whose PR checks passed and who are not done;
+`--all` includes archived/completed children; `--since <n>` limits the board
+to children with events after that cursor (the board prints its cursor).
+Pass the cursor back as `--since` to see only what changed.
+
+Exit codes for `status`, `board` and `events`: 0 ok, 1 error, 2 usage,
+3 wait timed out with the condition unmet.
+
 ## Preview session files
 
 ```bash
@@ -213,8 +250,12 @@ reports the conversation id and delivers mail at turn end.
 Grok and Antigravity hooks do not run in the interactive TUI until the folder
 has been trusted in that CLI's own trust prompt; the owner answers it once per
 folder, and ftown does not bypass it.
-Cursor and shell sessions rely on an idle one-line nudge to run `ftown harness
-mail read` instead.
+Cursor and shell sessions rely on a one-line nudge to run `ftown harness
+mail read` instead. Each new batch of mail nudges the recipient at most once;
+un-read mail stays in the inbox. Mail types are `message`, `task`, `result`,
+`escalation` and `fyi`; `fyi` is for non-urgent notes and never wakes the
+recipient. Progress and status go on the session card (see above), never as
+mail.
 
 ```bash
 # Tell a specific session
@@ -265,7 +306,8 @@ ftown sessions list
 ftown sessions create --prompt "Run tests and report" --workdir "$PWD" --parent
 # -> note session.id from JSON
 
-ftown sessions screen <child-id> --limit 100
+ftown board --wait --until any-done --timeout 300
+ftown board
 ftown sessions grep <child-id> --pattern 'FAIL|Error'
 ```