Preserve v4 approval.resolve callers

When a still-supported v4 client sends the previous approval.resolve payload with the formerly required kind field, validateApprovalResolveParams now rejects it because the schema only allows id and decision; this line then treats that as forceMalformedDeny, permanently denying the pending approval instead of letting the user approve it. Since the protocol version/minimum were not bumped, existing paired clients generated from the prior schema can still connect but their approval buttons will fail closed until every client is upgraded; either keep accepting the old field during v4 or reject older protocol versions explicitly.

Useful? React with 👍 / 👎.

Restore SQLite snapshot verification

When a backup contains state or agent SQLite snapshots, this new non-extracting verifier returns ok after only manifest and hardlink checks; it never opens the *.sqlite payloads or runs integrity/role validation. A truncated or corrupt state/openclaw.sqlite that is present in the manifest now passes openclaw backup verify and therefore backup create --verify, leaving operators with a "verified" archive that may not restore OpenClaw state.

Useful? React with 👍 / 👎.

Check WAL checkpoint busy result

When another OpenClaw process or reader still has the session DB open, PRAGMA wal_checkpoint(TRUNCATE) reports a nonzero busy result instead of throwing; this helper discards that row, so doctor --session-sqlite compact can report success while the WAL was not truncated and the DB was compacted under a live connection. Please read the checkpoint result and fail closed on busy != 0, as the previous shared compaction helper did.

Useful? React with 👍 / 👎.

Keep agent DB schema version monotonic

If a user has an agent database created by the immediately previous code (it wrote PRAGMA user_version = 6), lowering the supported version to 4 makes assertSupportedAgentSchemaVersion treat that DB as a future schema and refuse to open it. There is no migration/doctor path accepting v5/v6 here, so updating to this commit can strand existing agent state until the version is restored or the older shapes are explicitly handled.

Useful? React with 👍 / 👎.

Serialize CAS writes before saving workspace files

When two sessions.files.set requests for the same file and expectedHash arrive concurrently, both can pass the handler’s hash check before reaching this write, and then the later write overwrites the earlier one while both calls report success. The API and UI still present this as hash-based CAS/conflict detection, so the check and write need to be serialized (as the removed update queue did) or made atomic to avoid lost edits between two gateway clients.

Useful? React with 👍 / 👎.

Read terminal transcript freshness from SQLite

For SQLite-backed sessions, this now stats the legacy transcript file instead of reading the transcript rows, so a terminal main session whose SQLite transcript advanced after its registry row looks not-newer whenever the JSONL file is missing or stale. The callers in src/auto-reply/reply/session.ts, src/agents/command/session.ts, and src/gateway/server-methods/agent.ts treat false as permission to reuse the terminal main session, so new work can be admitted into a closed session instead of rotating or recovering; keep this gate on the SQLite transcript stats used before.

Useful? React with 👍 / 👎.

Honor structured context-overflow failover

When a provider or CLI layer throws a structured FailoverError with reason: "context_overflow" but a generic message such as provider rejected the request payload, this line no longer classifies it as context overflow because it only string-matches the message. That skips the dedicated context-overflow recovery copy below and surfaces a generic pre-reply failure instead, even though the typed reason is the dependency contract used by FailoverError.

Useful? React with 👍 / 👎.

Keep retrying structured transient failovers

Structured FailoverError timeouts and server errors no longer reach the transient retry path unless their message happens to match isTransientHttpError. Several callers, for example the CLI watchdog errors in src/agents/cli-runner/execute.ts, throw reason: "timeout" with messages like CLI produced no output... that do not contain HTTP status tokens, so this skips the once-only retry block below and immediately fails recoverable turns.

Useful? React with 👍 / 👎.

Don’t show clear state while approval details load

When the iPhone app snapshot reports pendingApprovalCount > 0 but the approval snapshot has not arrived yet, activeExecApproval is nil while approvalCount is still positive. This branch now renders the clear-state hero during loading or unavailable states, so a watch user can be told there is nothing to review even though the paired iPhone has already reported a pending approval; keep the previous loading/not-loaded branch for approvalCount > 0.

Useful? React with 👍 / 👎.

Match version tags during SHA provenance checks

In the exact-SHA path this now asks Git for the literal ref refs/tags/v, not the v* tag namespace; checked git for-each-ref behavior shows refs/tags/v only returns a tag named exactly v, while normal release tags such as v2026... require refs/tags/v*. A workflow dispatched with target_ref equal to the candidate SHA will therefore reject a SHA trusted only by its release tag, and the same replacement appears in the later revalidation step.

Useful? React with 👍 / 👎.

Align approval stream auth with method dispatch

When a paired approval client connects with only operator.approvals (the new handler test covers that exact scope set), this branch would accept includeApprovals, but live Gateway dispatch rejects the request before the handler because sessions.messages.subscribe is still registered as operator.read in src/gateway/methods/core-descriptors.ts:180. That makes approval-only clients unable to use the new session.approval replay/stream despite the handler and error text advertising approval-scope access; make the method dynamic/read+approvals-aware or require/read-test operator.read consistently.

Useful? React with 👍 / 👎.

Honor timeoutBehavior through deprecation

When a shipped plugin still sets requireApproval.timeoutBehavior: "allow" and no reviewer answers before the approval times out, this path now only logs a deprecation warning; both approval wait paths then fall through to the timed_out blocked result. Since the field remains in the public PluginHookBeforeToolCallResult API and the docs deprecate rather than remove it, existing plugins that intentionally allowed low-risk tools during approval outages will start blocking until they are rewritten; keep honoring the field through the deprecation window or make the breaking fail-closed contract explicit.

Useful? React with 👍 / 👎.

Pass canonical decisions to embedded approvals

When an embedded-mode plugin sets requireApproval.allowedDecisions without deny (for example ['allow-once']), this canonicalized set is only used to classify the result; the embedded broker request below still carries the original list. The embedded TUI renders its selector from request.allowedDecisions and its cancel path only denies when deny is present, so these prompts become allow-only/dismiss-only even though the new fail-closed contract and broker resolution logic treat deny as valid. Please send the canonical allowedDecisions into the embedded request as the gateway path does.

Useful? React with 👍 / 👎.

Preserve the agent scope in approval subscribe responses

When a global-scope session is subscribed through an agent-scoped key such as agent:work:main, this handler subscribes the connection to agent:work:global and replays approvals for that exact stream, but the response still tells the client the key is just global. A client that follows the returned key when later calling sessions.messages.unsubscribe will resolve global against the default agent and unsubscribe agent:main:global, leaving the agent:work:global approval subscription active until disconnect; this is newly sensitive with includeApprovals because it can keep delivering approval events after the UI believes it unsubscribed. Return the scoped subscription key (or enough agent metadata) for this response path so unsubscribe can target the same stream.

Useful? React with 👍 / 👎.