ftown 0.19.50 → 0.19.51

package/skills/ftown/SKILL.md

@@ -2,8 +2,9 @@
 name: ftown
 description: >-
   Control ftown sessions: create/list/read/drive sibling sessions, send ftown
-  mail, and coordinate worker agents. Use for ftown sessions, child/sibling
-  agents, bridge mail/inbox, or explicitly requested orchestration.
+  mail, request human attention, link session PRs, and coordinate worker agents.
+  Use for ftown sessions, child/sibling agents, bridge mail/inbox, or explicitly
+  requested orchestration.
 ---
 
 # ftown
@@ -39,6 +40,9 @@ entrypoint with `--repair`.
 ftown sessions list
 ftown sessions create --prompt "Review the auth module" --workdir "$PWD" --parent
 ftown sessions screen <session-id> --limit 200
+ftown sessions attention --message "Please review the migration plan" --title "Review requested"
+ftown sessions pr https://github.com/owner/repo/pull/123
+ftown sessions pr --clear
 ftown harness mail send <session-id> --type task "review the API client"
 ftown harness mail read
 ftown env --help
@@ -66,6 +70,40 @@ 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`.
 
+## Human attention and pull requests
+
+Use `ftown sessions attention --message "..."` when you need human input. It
+creates a durable attention record and uses the dashboard's existing notice flow;
+it does not answer a prompt or guarantee a push notification. Push remains opt-in
+and requires a supported hosted session. Repeating an unresolved request updates
+its occurrence count; after an uncertain result, inspect the existing request
+before retrying.
+
+Attach one GitHub pull request with `ftown sessions pr <URL>`; another URL
+replaces it and `--clear` removes it. This records a link without fetching GitHub
+or creating a PR. Both commands target trimmed `$FTOWN_SESSION_ID` unless you
+supply `--session-id <id>`; they never guess identity from the working directory.
+Older bridges report `bridge_upgrade_required` before mutation.
+
+Remote MCP callers use `attention_request` with explicit `machine` and
+`sessionId`, or `sessions_update` with `pullRequestUrl` (string to set, null to
+clear). Mutation tools require control access; remote callers have no automatic
+local self identity. Keep the returned attention event ID for existing inbox,
+acknowledge and resolve operations, which do not answer the agent's question.
+
+For tasks performed in an FTown session, associate the task's GitHub PR when
+created or updated, before the completion notice: use `ftown sessions pr <URL>`
+or MCP `sessions_update.pullRequestUrl`. Omit this step for tasks without a PR;
+never invent a PR or guess a session identity.
+
+Once the task is complete, request user attention **once per completed task**,
+before the final handoff, using `ftown sessions attention --title 'Work complete'
+--message "<truthful outcome, checks and PR summary>"` or MCP `attention_request`.
+Do not send a completion notice every turn; retain the uncertain-result guidance
+above. Children must still report their result to the parent as assigned; user
+attention does not replace that reporting. See the completion example in
+`references/sessions.md`.
+
 ## Cleanup
 
 Session cleanup is an explicit user or orchestrator action. Reporting a result

package/skills/ftown/references/sessions.md

@@ -51,6 +51,51 @@ ftown sessions archive
 ftown sessions revive <session-id>
 ```
 
+## Ask the human or associate a pull request
+
+```bash
+# Request human input for this session (JSON {event} by default)
+ftown sessions attention --message "Please review the migration plan" --title "Review requested"
+
+# Set or replace this session's single GitHub PR link (JSON {session})
+ftown sessions pr https://github.com/owner/repo/pull/123
+
+# Clear the association
+ftown sessions pr --clear
+
+# Explicit target overrides FTOWN_SESSION_ID for either command
+ftown sessions attention --session-id <id> --message "Which approach should I take?"
+ftown sessions pr --session-id <id> https://github.com/owner/repo/pull/123
+```
+
+Both commands use trimmed `FTOWN_SESSION_ID` when `--session-id` is omitted;
+missing/invalid identity, empty/oversized text, malformed URLs and contradictory
+arguments fail before transport. There is no working-directory or latest-session
+fallback. Title is optional (default `Session needs your input`, max 200 characters);
+message is required (max 2000). Controls and common credentials are sanitized.
+`--plain` prints a concise success summary. `--help` is read-only.
+
+Attention persists an `agent_needs_input` event, returns its exact ID and updates
+the existing dashboard attention flow. Logical duplicate unresolved requests
+coalesce while recording occurrences; resolving it permits a new incident.
+Only creation triggers notification, and hosted push remains opt-in with existing
+session/harness eligibility. Do not automatically retry an uncertain mutation.
+Acknowledging/resolving an event never answers or approves a CLI prompt.
+
+PR links accept only HTTPS GitHub `/owner/repo/pull/<positive-number>` URLs.
+Outer whitespace, query/fragment and a trailing slash are normalized; credentials,
+nondefault ports and other paths/hosts are rejected. No GitHub request is made.
+Attaching/replacing/clearing is metadata-only; omitting it on an update preserves
+its value. New sessions/children do not implicitly inherit a parent's PR.
+
+New commands probe the exact bridge capability before writing; update old bridges
+with the exact version setup command in their readiness hint. For remote MCP,
+`attention_request` requires explicit `{machine, sessionId, message, title?}` and
+returns `{machine, sessionId, event}`. `sessions_update` accepts `pullRequestUrl`
+(string or null), alongside existing name/parent fields. A mixed PR+name update
+rejects an old bridge before changing either field. Read-only MCP clients cannot
+see these mutation tools; control authorization and machine ownership still apply.
+
 ## Messaging (mail)
 
 `tell` posts to the target session's **inbox**. Mail is delivered into the
@@ -117,6 +162,30 @@ ftown sessions screen <child-id> --limit 100
 ftown sessions grep <child-id> --pattern 'FAIL|Error'
 ```
 
+### Completion handoff
+
+When the task creates or updates a GitHub PR, associate its actual URL with the
+FTown session before the completion notice. Then request user attention once the
+task is complete, before the final handoff. Replace the sample URL and summary
+below with truthful outcomes and checks (including checks not run):
+
+```bash
+ftown sessions pr https://github.com/owner/repo/pull/123
+ftown sessions attention --title 'Work complete' \
+  --message 'Outcome: <actual result>. Checks: <actual results or not run>. PR: https://github.com/owner/repo/pull/123'
+```
+
+For tasks without a PR, omit the PR command and PR summary. Use the verified
+`FTOWN_SESSION_ID` or explicit `--session-id`; never guess a target. MCP callers
+instead use `sessions_update` with `pullRequestUrl` when applicable, then
+`attention_request` with title `Work complete` and the same truthful summary,
+always supplying explicit `machine` and `sessionId`.
+
+Send one completion request per completed task, not repeated per-turn notices.
+Logical duplicate coalescing does not justify retries after an uncertain outcome;
+inspect the existing request first, as described above. Child agents still send
+their assigned result to the parent; the user attention request is additional.
+
 ## Environment
 
 Spawned ftown sessions receive:
@@ -145,7 +214,8 @@ The CLI wraps the loopback API. Raw access if needed:
 |--------|------|---------|
 | GET | `/api/sessions` | List |
 | POST | `/api/sessions` | Create |
-| PATCH | `/api/sessions/:id` | Rename and/or move (`{ name?, parentSessionId? }`; `null` moves to the root) |
+| PATCH | `/api/sessions/:id` | Rename, move or associate a PR (`{ name?, parentSessionId?, pullRequestUrl? }`; `null` detaches/clears) |
+| POST | `/api/sessions/:id/attention` | Request human input (`{ message, title? }`) → `{ event }` |
 | GET | `/api/sessions/:id/screen` | Terminal lines |
 | POST | `/api/sessions/:id/grep` | Search |
 | POST | `/api/sessions/:id/keys` | Send keys |