Prepare v0.5.0 version and release documentation

CHANGELOG.md

@@ -2,11 +2,33 @@
 
 Notable changes to AskKey are documented here, grouped by release and change type.
 
-## [Unreleased]
+## [0.5.0] - 2026-11-03
+
+### Added
+
+- Read cards for grouped credentials offer one timed allowance for the eligible credentials listed in Details. Later additions to the group are excluded, and an earlier member expiry limits the whole allowance.
+- The library lists active timed allowances at the top, with remaining time and revocation actions, even when a search or group filter hides their credentials. A group grant appears once with all covered credentials.
+- **End Timed Allow on Lock** in Settings is off by default. Turning it on or off requires system authentication.
+
+### Changed
+
+- Clicking a pending-request reminder while management is locked opens the approval prompt directly, keeping management locked on its remembered page. With no pending requests, the click only brings the window forward. This replaces the 0.4.0 behavior of opening Pending requests after management unlocks.
+- A credential covered by a group allowance shows **Revoke Group Allowance**; revoking from any member ends the whole grant.
+
+### Fixed
+
+- Clicking an agent write-failure notification brings Ask Key forward without opening Pending requests.
+
+### Security
+
+- Once this process adopts **End Timed Allow on Lock** as enabled, screen lock, sleep and user switch end single and group timed allowances, cancel unconsumed timed approvals and invalidate prepared timed runtime authorizations. A prepared run containing a timed credential is cancelled as a whole. New timed grants are refused while locked, asleep or switched out, including an unknown screen state. Turning the setting off does not revive revoked authority.
+- A remote opt-in not yet adopted is checked at the next ending event through a Keychain policy read, which can fail, or at the next agent request. Allow credentials, once-only approvals, pending requests and management sessions keep their existing behavior, except for prepared runs that also contain a timed credential. Already delivered material cannot be retracted.
+- A group allowance covers the approved snapshot of visible, unexpired credentials outside the Recycle Bin, bound by credential ID and component metadata, for the whole local macOS user. Its shared deadline is capped by the configured duration and earliest member expiry. A member's metadata, permission or group change removes that member; explicit revocation, expiry, revoke-all and pause end the whole grant. Writes still need separate approval. See [SECURITY.md](SECURITY.md) for the full boundaries, including sleep and cross-process limitations.
 
 ### Upgrade notes
 
-- After enabling the option to end timed allowances on screen lock or sleep, downgrading to an older build makes Agent access settings fail verification and requires authenticated recovery in that build.
+- Upgrading from 0.4.0 does not migrate the library. Credentials, permissions and valid Agent access settings are kept without a Resume step; **End Timed Allow on Lock** starts off.
+- Downgrading to 0.4.0 with the setting off changes nothing. With it on, 0.4.0 cannot verify the saved Agent access settings and pauses Agent access. Its authenticated **Resume Agent Access** restores all Agent access settings to defaults. Upgrading again before Resume preserves the saved settings. Turn the setting off before downgrading.
 
 ## [0.4.0] - 2026-10-28
 

README.md

@@ -93,7 +93,9 @@ Each credential has one permission:
 | Ask every time (default) | Every use waits for your approval. |
 | Hidden | Not in the agent catalog; agents cannot request it. |
 
-When you approve a read, you choose **Once** or a **Timed allowance**: a number of minutes during which that credential can be read without asking again, until it ends or you revoke it. Pending requests expire after five minutes.
+When you approve a read, you choose **Allow Once** or a timed allowance: a number of minutes during which that credential can be read without asking again, until it ends or you revoke it. For a grouped credential, you can also allow the eligible credentials listed in **Details** together. Later additions are excluded, and the whole allowance ends at the earliest member expiry if that is sooner. Active allowances appear at the top of the library with remaining time and revocation actions; **Revoke Group Allowance** ends the whole grant. Pending requests expire after five minutes.
+
+In **Settings**, **End Timed Allow on Lock** is off by default and requires system authentication to turn on or off. Once enabled in this process, screen lock, sleep or user switch ends single and group timed allowances and unconsumed timed approvals, and cancels prepared runs containing a timed credential. New timed grants are refused while locked, asleep or switched out, including when the screen state is unknown. See [SECURITY.md](SECURITY.md) for the adoption and sleep limitations.
 
 Agents can also write: create, modify or delete a credential, set its usage instructions and group, or move credentials and create, rename or delete groups in one batch. Every write needs your approval for that operation (a batch is approved once), the approval is tied to the exact content you were shown, and it cannot be reused for another change. Permanent deletion stays in the app.
 
@@ -131,17 +133,17 @@ What Ask Key does not guarantee:
 - An approved target can print, copy or forward what it receives.
 - Caller names and purposes are declared by the agent. They help you read a request; they are not verified identity.
 - Another process running as the same macOS user may be able to read material after an approved delivery. Hidden keeps a credential out of the agent catalog but does not defend against that.
-- A timed allowance covers the credential for the whole local user, not one agent client.
+- A timed allowance covers one credential or the explicitly approved group snapshot for the whole local user, not one agent client. Later group additions are excluded; writes still need separate approval.
 
 ## Upgrade
 
-Before updating to 0.4.0, quit Ask Key and back up the library folder at `~/Library/Application Support/AskKey`. Download and verify the new DMG as described in [Install](#install), replace `/Applications/Ask Key.app` with the app from the new DMG, then open Ask Key from Applications.
+Before updating to 0.5.0, quit Ask Key. Download and verify the new DMG as described in [Install](#install), replace `/Applications/Ask Key.app` with the app from the new DMG, then open Ask Key from Applications.
 
-On first launch, 0.4.0 migrates the library once, including Hidden credentials and those in the Recycle Bin. Your credentials and their permissions are kept; valid 0.3.2 Agent access settings are preserved without a Resume step. **A migrated library cannot be opened by 0.3.2, and there is no reverse migration.** Ask Key has no built-in backup or recovery; keep the originals of your credentials elsewhere as well.
+Upgrading from 0.4.0 does not migrate the library or require a library backup for this upgrade. Credentials, permissions and valid Agent access settings are kept without a Resume step. **End Timed Allow on Lock** starts off. Ask Key has no built-in backup or recovery; keep the originals of your credentials elsewhere as well.
 
-If a credential cannot be migrated, management stays available and names it after unlock. Fix it in the editor or permanently delete it from the Recycle Bin, then reopen Ask Key. Agent access stays off until the migration completes.
+Downgrading to 0.4.0 with the setting off changes nothing. **Turn it off before downgrading.** With it on, 0.4.0 cannot verify the saved Agent access settings and pauses Agent access; choosing **Resume Agent Access** there and authenticating restores all Agent access settings to defaults. Upgrading again before Resume preserves the saved settings.
 
-MCP clients must now pass an absolute `cwd` to `run`, including when resuming an approval. CLI `run` continues to use the terminal's current directory.
+For upgrades from 0.3.2 or earlier, also read the migration and compatibility notes for the intervening versions in [CHANGELOG.md](CHANGELOG.md#040---2026-10-28).
 
 Watch [GitHub Releases](https://github.com/sudoHG/AskKey/releases) for new versions; there is no automatic update.
 

README.zh-CN.md

@@ -93,7 +93,9 @@ helper 位于应用包内的 `Contents/Helpers/askkey`。目标进程只会拿
 | 每次询问（默认） | 每次使用都要等你批准。 |
 | 隐藏 | 不出现在 Agent 目录里，Agent 无法请求。 |
 
-批准读取时，你可以选择“仅本次”或“限时允许”：在设定的分钟数内，这份凭证可以不再询问直接读取，到期或被你撤销后失效。待处理的请求 5 分钟后过期。
+批准读取时，你可以选择“允许本次”或“限时允许”：在设定的分钟数内，这份凭证可以不再询问直接读取，到期或被你撤销后失效。如果凭证属于某个分组，还可以一次允许“详细信息”中列出的所有符合条件的凭证，之后加入分组的凭证不在其中。如果某份凭证更早到期，整个分组的限时允许也会同时结束。凭证库顶部会列出有效的限时允许、剩余时间和撤销按钮；“撤销分组限时允许”会结束整个分组的这次授权。待处理的请求 5 分钟后过期。
+
+“设置”中的“锁屏时结束限时允许”默认关闭，开启和关闭都需要系统验证。本次运行采用开启状态后，锁屏、睡眠或切换用户会结束单份凭证和分组的限时允许，取消尚未使用的限时批准，以及包含限时凭证的待执行命令。锁屏、睡眠、用户已切换或屏幕状态不明时，不能授予新的限时允许。设置何时生效及睡眠检测的限制见 [SECURITY.md](SECURITY.md)。
 
 Agent 也能写入：新建、修改或删除凭证，设置使用说明和分组，或者一次性批量移动凭证、新建、重命名和删除分组。每次写入都要你对这一次操作批准（批量操作批准一次即可）。批准绑定的是你看到的那份具体内容，不能挪用到另一次修改上。永久删除只能在应用里进行。
 
@@ -131,17 +133,17 @@ Claude Code、Codex、Cursor 和 Grok CLI。在应用的 **Agent 接入**页面
 - 获准的目标程序可以把收到的内容打印、复制或转发出去。
 - 调用方名称和用途由 Agent 自行声明，只是帮你看懂请求，不是经过验证的身份。
 - 同一 macOS 用户下的其他进程，可能在交付之后读取到相关内容。“隐藏”只是让凭证不进入 Agent 目录，防不住这类旁路。
-- 限时允许针对的是整个本机用户下的这份凭证，而不是某一个 Agent 客户端。
+- 限时允许针对的是整个本机用户下的一份凭证或明确批准的分组凭证快照，而不是某一个 Agent 客户端。之后加入分组的凭证不在其中；写操作仍需单独批准。
 
 ## 升级
 
-更新到 0.4.0 前，先退出请旨，并备份 `~/Library/Application Support/AskKey` 凭证库文件夹。按[安装](#安装)中的步骤下载并校验新版 DMG，用其中的应用替换 `/Applications/Ask Key.app`，然后从“应用程序”打开请旨。
+更新到 0.5.0 前，先退出请旨。按[安装](#安装)中的步骤下载并校验新版 DMG，用其中的应用替换 `/Applications/Ask Key.app`，然后从“应用程序”打开请旨。
 
-首次启动时，0.4.0 会迁移一次凭证库，包括隐藏的凭证和回收站中的凭证。凭证及其权限会保留；有效的 0.3.2 Agent 访问设置也会保留，无需恢复 Agent 访问。**迁移后的凭证库无法再用 0.3.2 打开，也无法反向迁移。** 请旨没有内置的备份和恢复功能，请同时在其他地方保留凭证原件。
+从 0.4.0 升级不会迁移凭证库，也无需为本次升级备份凭证库。凭证、权限和有效的 Agent 访问设置会保留，无需“恢复 Agent 访问”；“锁屏时结束限时允许”初始为关闭。请旨没有内置的备份和恢复功能，请同时在其他地方保留凭证原件。
 
-如果某份凭证无法迁移，管理功能仍然可用，解锁后会列出受影响的凭证名称。请在编辑器中修复，或从回收站中永久删除，再重新打开请旨。迁移完成前，Agent 访问会保持关闭。
+关闭该设置后降级到 0.4.0，不会改变现有状态。**请先关闭，再降级。** 如果开启着降级，0.4.0 会因无法验证已保存的 Agent 访问设置而暂停 Agent 访问；在 0.4.0 中选择“恢复 Agent 访问”并完成系统验证，会把所有 Agent 访问设置恢复为默认值。在执行“恢复 Agent 访问”之前重新升级，已保存的设置不会丢失。
 
-MCP 客户端调用 `run` 时，现在必须传入绝对路径 `cwd`，等待批准后继续请求时也一样。CLI `run` 仍使用终端的当前目录。
+如果从 0.3.2 或更早版本升级，还需阅读 [CHANGELOG.md](CHANGELOG.md#040---2026-10-28) 中间各版本的迁移和兼容性说明。
 
 请关注 [GitHub Releases](https://github.com/sudoHG/AskKey/releases) 获取新版本；应用没有自动更新功能。
 

Sources/AskKeyBroker/AskKeyVersion.swift

@@ -1,4 +1,4 @@
 // Product version read by scripts/product-version.sh; distinct from the Broker protocol version.
 public enum AskKeyVersion {
-    public static let current = "0.4.0"
+    public static let current = "0.5.0"
 }

docs/adr/0002-broker-and-approval-protocol.md

@@ -15,7 +15,7 @@ Local agents need discovery, approved runtime delivery and separately approved w
 - The App's local Broker exposes only metadata catalog, runtime execution, frozen credential write/upload/commit, request status/cancel, health and version operations. Permission/group management, access records, stored-value reveal, permanent deletion, local erase and resuming paused access remain authenticated App operations.
 - Use the existing versioned, length-prefixed socket protocol. Incompatible versions fail closed. Frames, responses, fields, connections, request counts, queues and I/O deadlines have hard limits in [BrokerLimits](../../Sources/AskKeyBroker/BrokerLimits.swift).
 - Bind approvals to operation ID, request ID, target, operation, immutable payload digest and deadlines. Query and cancellation require the request's unpredictable capability with its ID. Only an identical retransmission reuses an existing operation; changed content is rejected and a new operation requires a new ID. Denial creates no cooldown.
-- Pending requests expire after five minutes or an earlier credential deadline. Approval can be consumed at most once for its bound payload. Timed allowances authorize reads of one credential globally for the local macOS user, never agent writes or one particular client. Read approval uses system authentication by default with an explicitly confirmed opt-out; every agent write still requires separate system authentication.
+- Pending requests expire after five minutes or an earlier credential deadline. Approval can be consumed at most once for its bound payload. Timed allowances authorize reads of one credential or an explicitly approved group snapshot (see the [group amendment](#amendment-group-timed-read-allowances-240)) globally for the local macOS user, never agent writes or one particular client. Read approval uses system authentication by default with an explicitly confirmed opt-out; every agent write still requires separate system authentication.
 - Treat caller names, paths, signatures and purposes as unverified display context. Present approval independently of the management session; protect request details when the screen is locked. Opening or expiring management does not itself grant or revoke agent access.
 - Preserve original authorization through the synchronized final launch check. Revocation, mutation, pause or expiry that wins this boundary prevents launch and cleans temporary material. Reallowing access cannot revive a consumed authorization. Once launch wins, revocation cannot retract delivered material or promise termination of that target.
 - Commit agent CRUD and its operation receipt in one database transaction. External process execution does not have crash-level exactly-once semantics: retained completion receipts can return status without respawning, while an uncertain outcome is `outcome_unknown` and must not trigger automatic retry.