Skip to content

Codex Lid Keeper v0.1.0-alpha — Public Alpha / 首个公开测试版

Pre-release
Pre-release

Choose a tag to compare

View all tags
@Apex-Studio-He Apex-Studio-He released this 29 Jul 15:51
· 5 commits to main since this release
v0.1.0-alpha
8c2d210
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Codex Lid Keeper v0.1.0-alpha

Public Alpha / 首个公开测试版

Warning

This is an experimental, source-only Alpha for macOS. It installs privileged
system integration and uses the undocumented pmset disablesleep setting.
Review the source and testing guide before installation. Never place a
running, closed MacBook in a bag or other poorly ventilated space.

这是公开 Alpha，只提供源码。安装后会加入需要 root 权限的系统项，并用到 macOS
没有公开文档的 pmset disablesleep。动手前请先看代码和测试指南。合盖运行时
一定别把 MacBook 塞进包里或放到不通风的地方。

English

What is this?

Codex Lid Keeper tracks actual local Codex task activity through lifecycle
Hooks. While at least one eligible task is active, the MacBook is connected to
AC power, and battery level is safe, it owns an AC-only sleep override. After
the final task finishes—or when a safety condition fails—it restores the
captured prior AC setting.

This is a headless engineering preview, not a polished end-user application.
There is no menu-bar UI, signed app, notarized installer, DMG, or automatic
update channel.

Why this design is safer than a simple pmset 1/0 wrapper

  • Non-blocking Hooks: Hook execution only decodes minimal fields and
    atomically queues an event. It never waits for sudo or power reconciliation.
  • Concurrent leases: overlapping sessions and turns remain independent;
    restoration happens only after the last lease ends.
  • Prior-state ownership: the root helper captures whether AC
    disablesleep was already enabled. Restoration writes that captured value,
    not an assumed 0.
  • AC-only changes: battery-profile policy is never modified.
  • Independent watchdog: a root LaunchDaemon restores owned state after a
    stale heartbeat, missing AC power, unknown power state, or low battery.
  • Hard expiry: missing terminal Hook events cannot create a permanent lease.
  • Narrow privilege: sudoers permits only two exact command vectors against
    a root-owned executable.
  • Privacy-minimal persistence: prompts, transcripts, model responses, tool
    inputs, and tool outputs are not stored.

Included in v0.1.0-alpha

  • Swift 6 macOS command-line helper and reusable core module
  • five Codex lifecycle Hook integrations
  • private, atomic, idempotent lifecycle event spool
  • renewable multi-task leases with delayed release
  • native IOKit AC and battery sampling
  • root-owned AC prior-state record
  • user LaunchAgent and root recovery LaunchDaemon
  • exact-command sudoers integration
  • status, pause, resume, clear, emergency restore, and uninstall workflows
  • bounded queue, state, configuration, and rotating log behavior
  • English and Simplified Chinese documentation
  • bilingual bug/feature templates and contribution guidance

Verification evidence

The release commit was validated before tagging with:

  • release build with Swift warnings treated as errors
  • 35/35 native Swift self-tests
  • 5/5 Hook configuration tests
  • isolated non-blocking dry-run lifecycle test
  • idle-daemon no-rewrite regression
  • concurrent queue, crash replay, malformed event, future timestamp, clock
    rollback, AC removal, low battery, and ownership restoration regressions
  • launchd plist validation
  • exact sudoers fragment validation with visudo
  • shell syntax and whitespace checks
  • before/after comparison proving the automated suite did not change live
    pmset configuration

These checks do not replace real closed-lid acceptance on each Mac model.

How to test

  1. Read TESTING.md.

  2. Clone the repository and check out the tag:

    git clone https://github.com/Apex-Studio-He/codex-lid-keeper.git
cd codex-lid-keeper
git checkout v0.1.0-alpha

  3. Run the non-privileged checks:

    ./scripts/build.sh
/usr/bin/python3 scripts/test_hooks_config.py
/usr/bin/python3 scripts/test_e2e.py --binary .build/release/codex-lid-keeper

  4. Review the installer, uninstaller, launchd files, and security model.

  5. Install with ./scripts/install.sh.

  6. Open /hooks in Codex, review the five new handlers, and trust them.

  7. Complete the open-lid matrix before attempting the controlled closed-lid
    test.

Emergency restore

From the repository:

./scripts/emergency-restore.sh

Or after installation:

/Library/PrivilegedHelperTools/com.zundu.codex-lid-keeper emergency-restore

Keep this command available during the first hardware test.

Known limitations

  • Depends on undocumented macOS behavior that Apple may change.
  • Source build requires Command Line Tools and administrator access.
  • The installed executable is locally built and not code-signed or notarized.
  • Closed-lid networking and thermal behavior varies by Mac model.
  • Hosted tool coverage depends on which lifecycle Hooks Codex emits.
  • No UI, notifications, automatic updates, or compatibility database.
  • Not suitable for unattended deployment in this Alpha.

Reporting feedback

Use the bilingual GitHub Issue forms and include:

  • Mac model, macOS version, architecture, and Codex version
  • AC/battery state and test-case identifier
  • sanitized status --json output
  • expected vs observed behavior
  • whether emergency restore worked
  • whether live power settings changed unexpectedly

Do not upload prompts, transcripts, secrets, full Hook files, or personal paths.
Report vulnerabilities privately through GitHub Security Advisories.

中文说明

先用一句话讲清楚

Codex Lid Keeper 会在本地 Codex 任务运行时临时接管合盖睡眠，让任务继续跑；
最后一个任务结束以后，再把 Mac 原来的设置恢复回来。

它不是一个成熟 App，而是第一版公开测试代码。现在没有菜单栏界面、签名安装包、
DMG 或自动更新。我们先把最重要的三件事做好：判断任务、守住安全条件、可靠恢复。

为什么不直接写两行 pmset

因为“开始时写 1，结束时写 0”很容易把用户原来的设置盖掉，也扛不住任务并发、
进程崩溃和结束事件丢失。

这一版做了这些保护：

  • Hook 很轻。 只把任务事件写进本地队列，不在 Hook 里等 sudo。
  • 同时跑几个任务也没关系。 每个任务单独记账，最后一个结束才恢复。
  • 先记原值，再做修改。 AC 模式下原本就是 disablesleep 1 的话，恢复后仍然
    是 1，不会被我们强行改成 0。
  • 电池配置不动。 只修改接电时的配置。
  • 后台挂了还有兜底。 root watchdog 发现心跳断了、已经拔电或电量太低，会
    主动恢复。
  • 结束事件丢了也不会永久唤醒。 每个任务都有最长八小时的过期时间。
  • sudo 只开两条命令。 Hook 没法借这个权限去执行别的操作。
  • 聊天内容不落盘。 不保存提示词、模型回复、工具参数和工具输出。

这次发布里有什么

  • Swift 6 编写的 macOS CLI 和 Core
  • 五类 Codex 生命周期 Hook
  • 支持去重、排序和崩溃重放的私有事件队列
  • 支持并发任务、结束缓冲和强制过期的租约
  • IOKit 接电与电量检测
  • root 管理的 AC 原值记录
  • 用户 LaunchAgent 和 root 恢复 LaunchDaemon
  • 只允许固定参数的 sudoers 规则
  • 状态查看、暂停、恢复、清理、紧急恢复和卸载命令
  • 队列上限、日志轮转和空闲写盘优化
  • 中英文说明、测试手册和 Issue 模板

发出来之前做了哪些检查

标签对应的代码通过了：

  • release 构建，并把 Swift warning 当成错误处理
  • 35/35 项 Swift 自测
  • 5/5 项 Hook 配置测试
  • 在临时目录里完整跑了一遍 dry-run 流程
  • 空闲 daemon 不重复写状态文件的回归测试
  • 并发队列、崩溃重放、异常事件、系统时间回拨、拔电、低电量和恢复测试
  • launchd plist、sudoers、shell 语法和空白检查
  • 自动测试前后的真实 pmset 对比，结果没有变化

这些检查能证明代码路径正常，但不能替代真实 MacBook 的合盖、网络和散热测试。

怎么开始测试

先看一遍测试指南。
不要跳过安装前自测，也不要一安装就直接合盖。

git clone https://github.com/Apex-Studio-He/codex-lid-keeper.git
cd codex-lid-keeper
git checkout v0.1.0-alpha

./scripts/build.sh
/usr/bin/python3 scripts/test_hooks_config.py
/usr/bin/python3 scripts/test_e2e.py --binary .build/release/codex-lid-keeper

自测通过后：

  1. 看一遍安装、卸载脚本和安全说明；
  2. 执行 ./scripts/install.sh；
  3. 在 Codex 里打开 /hooks，确认并信任五个新增 Hook；
  4. 先做开盖测试、并发测试、拔电和紧急恢复；
  5. 最后才在通风桌面上做两到五分钟的合盖测试。

出问题先恢复

仓库目录里执行：

./scripts/emergency-restore.sh

或者使用安装后的完整路径：

/Library/PrivilegedHelperTools/com.zundu.codex-lid-keeper emergency-restore

第一次上真实机器测试前，请先把这条命令留在手边。

现在还不适合做什么

  • 不要放进背包、内胆包或其他不通风的地方运行；
  • 不要把这个 Alpha 当成无人值守工具；
  • 不要假设一台 Mac 测过，其他型号就一定一样；
  • 不要跳过系统大版本升级后的重新测试；
  • 不要把本地构建的 Helper 当成已经签名、notarized 的正式软件。

另外，Hosted tool 能不能续任务状态，取决于 Codex 实际会不会为它发出对应 Hook。

怎么反馈

用仓库里的双语 Issue 表单就行。请写上：

  • Mac 型号、macOS 版本、芯片架构和 Codex 版本
  • 当时是否接电、电量多少
  • 测到了哪一步
  • 打码后的 status --json
  • 预期发生什么、实际发生什么
  • 紧急恢复有没有成功
  • pmset 有没有出现意外变化

不要上传提示词、聊天记录、密钥、完整 Hook 文件或个人路径。安全漏洞请走 GitHub
Security Advisory，不要发公开 Issue。

Thank you for testing carefully. / 感谢你谨慎测试。

Assets 2
Loading