ftown 0.25.3 → 0.26.0

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.3",
+  "version": "0.26.0",
   "description": "CLI bridge for ftown — generic PTY-over-Centrifugo relay",
   "type": "module",
   "main": "dist/index.js",
@@ -73,5 +73,5 @@
   "overrides": {
     "qs": "6.16.1"
   },
-  "gitHead": "9792eca1d4fb17bf061d771defc5aa16932fdc17"
+  "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
@@ -95,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

@@ -20,16 +20,21 @@ harness's model list. Never route to `exhausted`.
 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/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'
 ```