@flowmind/cli 0.3.3 → 0.3.7

package/README.md

@@ -115,7 +115,11 @@ session with a turn in progress in the repository. The duration is the main agen
 time since the session's last staged proof, in whole minutes; the remaining seconds carry over to
 the next proof. Idle time between turns does not count, and neither does sleep: the hooks read the
 awake clock that Codex uses for "Worked for". Subagent prompts never start a turn, because the main
-agent's turn already contains their work. When nothing new is recorded, or when a Codex subagent
+agent's turn already contains their work. Codex runs no prompt hook for a turn that another chat
+starts (`send_message_to_thread`, `create_thread`). For such a turn the CLI reads the start, the end
+and Codex's own awake time from the Codex session file. It places a time on the awake clock only where
+the record shows no sleep in between; on macOS that record is the kernel's last wake time. The JSON
+output gives the recorded `unstagedSeconds`. When nothing new is recorded, or when a Codex subagent
 calls the command, it stages nothing, prints `"staged": false` with a `reason` and a `message`,
 and exits 0. The source kind is `codex` or `claude_code` from the recording host.
 `--dry-run` prints the request and its retry key without staging anything.
@@ -138,6 +142,27 @@ The retry key derives from the session id, project id, and start time, so each w
 session gets its own key. `agent capabilities`, `agent projects`, `agent routines`, `agent proposals`,
 and `agent cancel` accept `--json`. `auth status` shows the API URL and accepts `--json`.
 
+### Saved stages
+
+The CLI saves every stage on the machine before it sends it, so a crash, a timeout or a lost answer
+never loses it. When Flowmind does not take the stage, because the API is unreachable, answers too
+slowly (30 seconds), fails, limits the request, or sends an answer the CLI cannot read, the stage
+stays saved and the command exits 0 with `"staged": false`, `"reason": "saved"`, the `error`, and a
+`pendingStageId`. The session counts its time as staged, so the next proof does not repeat it. A
+refused or missing credential, or an unexpected CLI error, keeps the stage saved but exits 1, because
+someone must act. A stage that the API refuses for its content is removed, and its time stays unstaged
+for a corrected proof.
+
+Saved stages are sent with the same retry key and body. The API keeps one proof per account and
+retry key, also after its 24-hour receipt expires and under another credential, so a stage that
+reached the server before its answer was lost comes back as the same proposal. Saved stages go out after the next accepted stage
+(`savedStagesSent` in the JSON output) and from the session hooks, which start `agent retry --due`
+in the background when one is due: 1, 2, 4 … minutes after each failed attempt, at most an hour.
+`agent pending` lists them and `agent retry` sends them now; both accept `--json`. A saved stage that
+the API later refuses for its content stays listed as `rejected` and is not sent again.
+If a process ends between saving a stage and marking its session, the next stage on the machine
+restores the mark first. One sender runs at a time per machine.
+
 ## Momentum brief
 
 ```sh
@@ -188,6 +213,11 @@ Errors go to stderr and exit with status 1.
 [`src/api.ts`](src/api.ts) exposes `apiRequest(descriptor, args, options)` through the shared response decoder.
 [`src/contracts.ts`](src/contracts.ts) binds command workflows to generated descriptors and `@flowmind/contracts/wire` types.
 Every API request validates the media type, envelope, status agreement, and response schema.
+An installed CLI can be older than the API, so it accepts one kind of difference: a response field that its contracts do not declare, inside a closed object.
+It drops that field before the command reads the response, so the field never reaches the output or `--json`.
+Every other difference still fails: a missing, retyped or renamed field, an unknown enum value, a union that matches no branch, and an unknown top-level envelope field.
+[`src/response-additions.ts`](src/response-additions.ts) owns this rule; the [decision](../../docs/decisions/2026-10-23-cli-response-additions.md) gives the reasons and the limits.
+The rule is sound only for some schema forms, so the build runs [`response-forms.mjs`](response-forms.mjs) and fails when a response that the CLI reads uses another form.
 See the [contract generation flow](../../docs/reference/codebase/ARCHITECTURE.md#api-contract-generation-and-decoding) and [endpoint procedure](../../docs/reference/codebase/CONVENTIONS.md#add-or-change-an-endpoint).
 Do not cast response data, write payload parsers, or add generic request helpers.
 Commands exit with status 1 when transport, JSON, media type, envelope, or payload checks fail.

package/dist/flowmind/SKILL.md

@@ -53,15 +53,19 @@ flowmind agent stage --intention "<what you set out to do>" --outcome "<one line
 ```
 
 - The CLI reads the project from `.flowmind.json` and the time from the session record. The time is the main agent's turn time on the awake clock that Codex uses for "Worked for", so sleep does not count. It includes the time that subagents work during the turn.
+- A turn that another chat starts, for example with `send_message_to_thread` or `create_thread`, counts like a typed turn. Codex runs no prompt hook for it, so the CLI reads its start from the Codex session file.
 - A stage covers the whole minutes since the session's last proof. The remaining seconds carry over to the next proof.
 - When several units of work finish together, stage them as one proof that names them all. A second stage right after the first has no new time.
 - Subagents do not stage. In a Codex subagent, `flowmind agent stage` stages nothing and tells the subagent to report its outcome to the main agent.
 - `"staged": false` in the JSON output means that nothing was staged, and it is not an error. `reason` is `no-new-time` when the last proof (`lastProposalId`) already holds the session's time, or `subagent`. Tell the user which proof covers the work.
+- `"reason": "saved"` means that the server did not take the proof yet, for example because Flowmind was unreachable, a limit was reached, or its answer could not be read. The CLI saved it on this machine and sends it automatically: after the next accepted stage, or in the background from the session hooks. Its time already counts as staged. Do not stage it again, do not invent another `--idempotency-key`, and tell the user it waits to be sent.
+- A refused credential also keeps the proof saved, but exits with an error: the user must run `flowmind auth login`. A proof that the server refuses for its content (too long, unknown project) is not saved; fix it and stage again.
+- `flowmind agent pending --json` lists the proofs saved on this machine; `flowmind agent retry --json` sends them now.
 - After 20 minutes of unstaged agent time, each prompt in a linked repository carries a reminder with the unstaged minutes. Stage when the current unit of work is complete; a stage with explicit times also resets the count.
 - Add `--dry-run` to preview the project and minutes without staging.
 - Pass `--project`, `--minutes`, and `--started-at` only when no session record exists. Use observed times only. Never estimate time from tokens or tool calls.
 - Share `proposal.webReviewUrl` with the user. The user approves staged work in Flowmind Activity; **Approve all with links** approves every item with an artifact link at once. Approved agent time counts on the project, not as the user's personal effort or XP.
-- If staging fails, report the error. Never fall back to `flowmind log`, and never approve your own proposals.
+- If staging fails with an error, report it. Never fall back to `flowmind log`, and never approve your own proposals.
 
 ### Write the proof for a person