dev_plan_v0.13.md
Rama main · réplica de lectura del repositorio original.
# ServerFS v0.13.0 Development Plan — Native macOS 27 on Apple Silicon M-series
**Status:** RELEASED — v0.13.0
**Target:** v0.13.0
**Baseline:** released/frozen v0.12.0 on `main`
## Implementation & acceptance record (2026-10-10)
All phases 0–K are implemented on `feat/v0.13-macos27-arm64` and validated on the development
baseline machine (MacBook Air Mac16,12 / Apple M4 / macOS 27.0.1 build 26A434, native arm64,
not Rosetta):
- Phase 0 — `docs/phase-0-macos27-arm64-capability-probe-2026-10.md` (every
design-load-bearing primitive PROVEN or SUPPORTED VIA SMALL DARWIN WRAPPER with the wrapper
PROVEN).
- Phase A — `src/serverfs_mcp/posix_fdio.py` extraction; Linux call path unchanged.
- Phase B — `src/serverfs_mcp/darwin_backend.py` + explicit backend dispatch
(`NATIVE_PLATFORM_UNSUPPORTED` elsewhere); `search_scan.py`/`read_page.py` shared cores.
- Phase C — measured serve/bootstrap gates; `~/Library/Application Support/ServerFS` data
home; Darwin doctor diagnostics (APFS/network verdict, platform facts, TCC hint);
`native-wheel` refuses on macOS.
- Phase D — Bridge platform seams (LINUX/DARWIN/WINDOWS/POSIX), `getpeereid` peer identity,
validated runtime dir, sun_path budget enforcement before bind, §23 parity tests.
- Phase E — `serverfs agent-bridge …` launchd lifecycle; live LaunchAgent proof
(bootstrap/kickstart/bootout) in `tests/test_darwin_lifecycle.py` (opt-in live, PASS).
- Phase F — Codex adapter recognized POSIX-generic (`codex_posix.py`); live darwin probes:
codex 0.162.1 via the real managed daemon, claude 2.1.294, `model/list` 11 models.
- Phase G — Jev/proxy reused unchanged (zero Darwin-specific code); suites green.
- Phase H — native file-ingress helper over private AF_UNIX (`SERVERFS_FILE_INGRESS_SOCKET`,
parent guard, SIGTERM cleanup); real subprocess/socket tests.
- Phase I — `.github/workflows/macos-native.yml` with measured platform assertions.
- Phase J — `docs/phase-macos-native-acceptance-2026-10.md` (23/23 on APFS),
`docs/phase-macos-agent-acceptance-2026-10.md` (9/9), and
`docs/phase-macos-live-chatgpt-e2e-2026-10.md` (operator run book: the ChatGPT tunnel E2E
and live proxied egress need the operator's real tunnel credentials/proxy; a Qoder live run
needs a host with the Qoder CLI — the release statement narrows accordingly).
Automated gates at the acceptance commit: MCP suite 1118 passed / 0 failed (macOS 27 arm64),
Bridge suite 327 passed / 0 failed, ruff + ruff format clean, `git diff --check` clean. The
macOS Native CI workflow runs the same suites behind measured platform assertions.
### CI status at this record
- Hosted runners (Linux Container, Windows native, Windows Agent, site): **all green** on
PR #41 after the wheel-version alignment.
- Hosted `macos-27` runners remained queued for over an hour (free-account capacity), so the
plan's §16 fallback applies: the exact macOS workflow step sequence was executed on this
acceptance machine with identical measured assertions and recorded as
`docs/phase-i-macos-ci-local-equivalence-2026-10.md` — **all steps PASS**. The workflow now
also supports switching every job to an M-series self-hosted runner via the repository
variable `MACOS_RUNNER` without any other change; hosted runs stay queued and will execute
when capacity frees.
Release closeout is complete and **v0.13.0 is published**. The operator-assisted evidence and
release-gate results above remain the acceptance record for the released line; queued hosted
macOS runner notes are historical CI-capacity context, not a current release blocker.
## Supported platform — intentionally narrow
v0.13.0 supports exactly:
```text
Hardware:
Apple Mac with Apple M-series SoC
CPU architecture:
arm64 / AArch64
native execution only
Operating system:
macOS 27.x Golden Gate
Development baseline at plan creation:
macOS 27.0.1
```
The actual release acceptance must use the **latest publicly released macOS 27.x patch available at acceptance time**.
Explicitly unsupported in v0.13.0:
```text
Intel Macs
x86_64 processes
Rosetta-translated ServerFS/Python
macOS 26 Tahoe or older
macOS 28 or newer
Hackintosh
non-Apple ARM hardware
cross-platform Darwin derivatives
non-M-series Apple Silicon as a supported product target
```
Do not implement compatibility code for these environments.
---
# 1. Mission
Implement a first-class **native ServerFS deployment for M-series Macs running macOS 27 Golden Gate**.
The macOS implementation must reach functional parity with the current Linux product surface while using native Darwin security and lifecycle primitives.
Target architecture:
```text
ChatGPT
|
OpenAI Secure MCP Tunnel
|
official tunnel-client (darwin-arm64 only)
|
stdio
v
ServerFS MCP — native arm64 Python
|
+-- Darwin filesystem backend
+-- optional native isolated file-ingress helper
+-- Agent Bridge over authenticated AF_UNIX
|
+-- Codex
+-- Claude Code
+-- Qoder
+-- optional Jev advisors
```
No Docker.
No VM.
No Rosetta requirement.
No system-wide daemon.
No macOS-specific Rust kernel unless a Phase 0 measurement proves one unavoidable.
---
# 2. Platform contract
## 2.1 Runtime gate
Native macOS startup must explicitly verify the platform rather than treating all POSIX systems alike.
Required conditions:
```python
sys.platform == "darwin"
platform.machine() == "arm64"
macOS major version == 27
```
Additionally probe whether the current process is running under Rosetta translation.
The Phase 0 probe must establish the reliable Darwin mechanism, expected to include:
```text
sysctl.proc_translated
```
Required behavior:
```text
native arm64 + macOS 27.x
-> supported
x86_64 / Rosetta
-> NATIVE_PLATFORM_UNSUPPORTED
macOS < 27
-> NATIVE_PLATFORM_UNSUPPORTED
macOS > 27
-> NATIVE_PLATFORM_UNSUPPORTED
```
Do not silently execute on an unvalidated future major macOS release.
Patch releases inside macOS 27 remain allowed:
```text
27.0
27.0.1
27.1
...
```
but final v0.13 acceptance must be rerun on the newest available 27.x patch.
## 2.2 M-series support boundary
Do **not** build a large hard-coded M1/M2/M3/M4/M5 model database.
The product support statement is:
> M-series Macs running native arm64 macOS 27.
Runtime security depends on:
```text
Darwin
arm64
native execution
macOS major 27
```
rather than fragile marketing-model detection.
Live acceptance must nevertheless run on a real M-series Mac.
---
# 3. Core architectural decision
## 3.1 No macOS Rust kernel by default
Windows required a Rust/PyO3 native filesystem kernel because Win32/NT filesystem security primitives differ fundamentally from POSIX.
Darwin already provides:
```text
file descriptors
directory-relative filesystem operations
O_NOFOLLOW
fstat
flock
atomic rename
AF_UNIX
UID/GID identity
xattrs
ACLs
native metadata-copy APIs
```
Therefore:
> v0.13.0 should use Python + Darwin/POSIX primitives and only minimal libc bindings where Python does not expose the required API.
Acceptable narrow `ctypes` bindings include:
```text
getpeereid()
fcopyfile(..., COPYFILE_METADATA)
confstr(_CS_DARWIN_USER_TEMP_DIR)
```
Do not introduce:
```text
serverfs-macos-native
Rust
Swift
Objective-C
Xcode project
```
unless a security-critical Phase 0 result proves the Python/libc path inadequate.
---
# 4. Shared architecture
The intended platform split becomes:
```text
MCP tools / policy / limits / models
|
WorkdirSession
/ | \
Linux Darwin Windows
POSIX POSIX NT
```
Share product contracts.
Share POSIX primitives only where semantics genuinely match.
Do not create a fake universal syscall abstraction.
Explicit backend dispatch:
```text
linux
-> LinuxWorkdirSession
darwin + arm64 + macOS 27
-> DarwinWorkdirSession
win32
-> WindowsWorkdirSession
anything else
-> PLATFORM_UNSUPPORTED
```
The current implicit:
```text
win32 -> Windows
everything else -> Linux
```
must disappear.
---
# 5. Product parity target
macOS must support the current ServerFS product surface.
## Filesystem tools
```text
list_workdirs
list_directory
find_files
search_text
read_text_file
stat_file
create_text_file
edit_text_file
delete_file
create_directory
delete_directory
```
Optional binary surface:
```text
download_binary_file
upload_binary_file
```
Preserve existing tool-count contracts:
```text
11 filesystem
13 filesystem + binary
21 filesystem + Agent
23 filesystem + binary + Agent
```
## Filesystem semantics
Preserve:
```text
read-only by default
per-workdir policy
hidden-file policy
deny globs
bounded reads/writes
bounded search
binary limits
opaque revisions
expected-revision CAS
atomic publication
hard-link protection
symlink refusal
stable error codes
audit logging
no shell execution
no recursive delete
```
## Agent functionality
Support all existing provider-neutral Agent behavior:
```text
Codex
Claude Code
Qoder
runtime model discovery where supported
request-scoped model override
approvals
questions
cancellation
idempotency
correlation_id
immutable execution manifest
task deadlines
interaction deadlines
writer leases
recovery guards
event retrieval
result spool
read_agent_task_result
retention
provider-aware recovery
```
## Jev
Preserve:
```text
Task Preflight
Runtime Router
Model Advisor
Approval Advisor
```
Jev remains:
```text
optional
advisory
fail-open
automatic=false
```
## Proxy
Support independent routing for:
```text
OpenAI Tunnel
Agent runtimes
Jev
```
using the existing proxy contracts rather than another proxy model.
## File ingress
Support ChatGPT/OpenAI `fileParams` through an isolated native helper.
---
# 6. Frozen non-regression boundaries
Do not redesign:
1. MCP public tool schemas.
2. Agent Bridge protocol.
3. runtime authorization.
4. revision/CAS semantics.
5. writer-lease authority.
6. Jev authority.
7. default read-only behavior.
8. binary size semantics.
9. task idempotency.
10. 8 MiB spool maximum.
11. 256 KiB default spool threshold.
12. provider-native approval behavior.
13. Linux Docker topology.
14. Windows native topology.
15. Windows Rust filesystem kernel.
16. Linux transport security.
17. existing Windows release packages.
macOS is an additive platform implementation.
---
# 7. Phase 0 — Real M-series / macOS 27 capability probe
This phase is mandatory.
Use a real M-series Mac running the latest macOS 27.x available.
Create:
```text
docs/phase-0-macos27-arm64-capability-probe-2026-10.md
```
Record:
```text
Mac model
M-series generation
uname -m
Python architecture
macOS version
Darwin kernel version
Rosetta state
filesystem type
```
## 0A — native architecture
Verify:
```text
uname -m -> arm64
platform.machine() -> arm64
Python itself is arm64
sysctl.proc_translated indicates native execution
```
Run a negative test under Rosetta if possible and prove the runtime gate rejects it.
## 0B — POSIX filesystem primitives
With the actual Python >= 3.12 environment, verify:
```text
os.open + dir_fd
O_DIRECTORY
O_NOFOLLOW
os.stat(dir_fd=..., follow_symlinks=False)
os.scandir(fd)
os.mkdir(dir_fd=...)
os.unlink(dir_fd=...)
os.rmdir(dir_fd=...)
os.link(src_dir_fd, dst_dir_fd)
os.rename / os.replace with dir_fd
os.fchmod
os.fchown
os.listxattr(fd)
os.getxattr(fd)
os.setxattr(fd)
directory fsync
```
Do not infer API availability from Linux behavior.
## 0C — APFS behavior
Use local APFS.
Measure:
```text
st_dev
st_ino
st_mode
st_uid
st_gid
st_size
st_mtime_ns
st_ctime_ns
st_nlink
```
Verify:
```text
same-directory atomic rename
FD identity after pathname replacement
hard-link behavior
concurrent readers during replace
```
## 0D — Darwin metadata
Create test files containing:
```text
POSIX mode
custom xattrs
macOS xattrs
extended ACL
Finder/resource metadata where practical
```
Verify:
```c
fcopyfile(src_fd, dst_fd, NULL, COPYFILE_METADATA)
```
preserves metadata without replacing the new file content.
This should become the preferred Darwin replacement metadata primitive.
No silent metadata loss is acceptable.
## 0E — AF_UNIX peer identity
Test real:
```c
getpeereid()
```
over AF_UNIX `SOCK_STREAM`.
Server must obtain authoritative:
```text
peer euid
peer egid
```
Darwin does not need to fabricate Linux `SO_PEERCRED`.
Do not invent peer PID evidence.
## 0F — flock
Two independent native arm64 processes:
```text
process A -> LOCK_EX success
process B -> LOCK_EX|LOCK_NB blocked
A releases
B -> success
```
## 0G — Darwin user runtime directory
Resolve the operating-system-provided user runtime/temp location using:
```text
_CS_DARWIN_USER_TEMP_DIR
```
Verify:
```text
owned by current UID
not shared with another user
private child directory can be 0700
Unix socket path remains below sun_path limit
```
Do not trust an arbitrary inherited `$TMPDIR` string as the security boundary without validating it.
## 0H — official OpenAI Tunnel
Test only:
```text
darwin-arm64
```
Do not test or retain a v0.13 requirement for:
```text
darwin-amd64
```
Verify:
```text
download
manifest verification
asset SHA-256
executable mode
launch
stdio child
termination
```
## 0I — Agent runtimes
Record current native ARM versions of:
```text
codex
claude
qodercli
```
Verify they execute natively on arm64.
Do not knowingly use x86_64 runtime binaries through Rosetta.
For Codex probe:
```text
managed daemon
Unix socket transport
standalone app-server Unix listener
multiple clients
model/list
model override
approval
interrupt
```
## 0J — launchd
Test a real per-user LaunchAgent:
```text
bootstrap
print
kickstart
bootout
restart
SIGTERM
logout/login behavior where practical
```
Measure descendant process behavior.
Do not infer Windows Job Object semantics.
### Phase 0 exit gate
Every relevant primitive must be classified:
```text
PROVEN
SUPPORTED VIA SMALL DARWIN WRAPPER
UNSUPPORTED
NOT VERIFIED
```
Implementation cannot rely on `NOT VERIFIED`.
---
# 8. Phase A — POSIX boundary extraction
Existing Linux `fdio.py` contains both POSIX and Linux-specific behavior.
Extract only genuinely shared code.
Recommended:
```text
src/serverfs_mcp/posix_fdio.py
```
Candidate shared primitives:
```text
root FD
component traversal
open regular file
open directory
stat_at
unlink_at
parent traversal
same-directory temp creation
bounded FD reads
directory fsync
```
Linux-specific code remains Linux-specific.
Especially:
```text
/proc/self/fd
```
must never appear in Darwin implementation.
Run full Linux tests immediately after extraction.
No Darwin feature work continues until Linux remains green.
---
# 9. Phase B — Darwin filesystem backend
Create:
```text
src/serverfs_mcp/darwin_backend.py
```
Implement the complete `WorkdirSession` contract.
## B1 — path security
Never implement security as:
```python
Path(root, relative).resolve()
```
Every request path must remain descriptor-relative.
Reject request-controlled symlinks regardless of whether their targets remain inside the workdir.
Test:
```text
root symlink
parent symlink
final symlink
inside-target symlink
outside-target symlink
rename/symlink races
```
## B2 — read/list/stat/find
Reuse POSIX implementation where semantics truly match.
`find_files` keeps bounded FD usage by reopening one branch at a time.
Preserve:
```text
RESOURCE_EXHAUSTED
truncation
hidden policy
deny policy
```
## B3 — search
Do not use:
```text
/proc/self/fd
Linux-only rg cwd tricks
path re-resolution
```
Implement Darwin search using:
```text
FD-secure directory walk
-> bounded regular-file read
-> literal UTF-8 scan
```
Match current public behavior:
```text
fixed string
case sensitivity
glob
max file size
deadline
match limit
truncation
hidden policy
deny policy
VCS exclusions
binary/NUL behavior
```
Extract reusable scanning helpers from Windows implementation if doing so is surgical.
Do not rewrite Linux search.
## B4 — mutation
Preserve:
```text
same-directory temp
write payload
metadata copy
fsync temp
revision recheck
atomic rename
directory durability attempt
```
Darwin metadata path should prefer:
```text
fcopyfile(..., COPYFILE_METADATA)
```
Fail before publication if required metadata cannot be preserved.
## B5 — revisions
Keep:
```text
v1:<digest>
```
Do not expose:
```text
inode
UID/GID
APFS identifiers
host path
```
## B6 — support boundary
v0.13 GA filesystem support:
> Local APFS workdirs on an M-series Mac running macOS 27.
Out of scope:
```text
SMB
NFS
FUSE
network volumes
cloud placeholder behavior
unusual filesystem extensions
```
Do not reject them arbitrarily unless needed for safety, but do not claim support.
## B7 — TCC
ServerFS must not attempt to bypass macOS privacy controls.
For protected paths:
```text
fail cleanly
surface redacted access-denied diagnostics
doctor identifies likely TCC denial
documentation explains operator action
```
---
# 10. Phase C — Native CLI and Tunnel
## C1 — native serve
`serverfs serve` gains Darwin support only through the strict platform gate:
```text
darwin
arm64
macOS 27
not Rosetta
```
## C2 — data home
Use:
```text
~/Library/Application Support/ServerFS
```
unless explicitly overridden by:
```text
SERVERFS_DATA_HOME
```
Do not use Linux XDG defaults on macOS.
## C3 — tunnel bootstrap
For Darwin v0.13:
```text
official asset = darwin-arm64 only
```
Do not include `darwin-amd64` as a supported target.
Preserve:
```text
manifest digest pin
asset SHA-256 verification
GitHub host restrictions
project-local install
no PATH modification
```
## C4 — native-wheel command
`serverfs bootstrap native-wheel` remains Windows-specific.
On macOS:
```text
refuse clearly as not required
```
Do not create a dummy macOS native package.
## C5 — doctor
Add:
```text
macOS version
Darwin version
arm64/native status
Rosetta status
APFS
workdir access
symlink checks
metadata-copy support
TCC diagnostics
tunnel-client architecture/version
Bridge endpoint
Bridge readiness
runtime executables
Agent proxy configuration
private-state ownership/modes
```
Doctor stays read-only.
---
# 11. Phase D — Darwin Agent Bridge seams
## D1 — platform constants
Introduce explicit semantics:
```python
LINUX
DARWIN
WINDOWS
POSIX = LINUX or DARWIN
```
Audit every existing Linux guard manually.
Classify it as:
```text
POSIX
Linux-specific
Windows-specific
```
Never replace Linux checks mechanically with `not WINDOWS`.
## D2 — local IPC
Use:
```text
AF_UNIX SOCK_STREAM
```
Endpoint location:
```text
<Darwin per-user runtime dir>/
serverfs-agent-bridge-v1/
bridge.sock
```
ServerFS-created directory:
```text
0700
owned by current UID
not symlinked
```
Validate socket length before bind.
## D3 — peer authentication
Use:
```text
getpeereid()
```
Authorize measured UID/GID.
Create a Darwin peer type if needed.
Do not fake:
```text
pid
SO_PEERCRED
Windows SID
```
## D4 — writer lease
Use existing POSIX:
```text
flock(LOCK_EX | LOCK_NB)
```
MCP mutation and Agent workspace-write must share the same lease identity and artifact.
## D5 — private state
Darwin private state:
```text
directory 0700
file 0600
owned by current UID
unsafe symlinks rejected
```
No Windows ACL code.
## D6 — Bridge data home
Use:
```text
~/Library/Application Support/ServerFS/agent-bridge
```
for persistent:
```text
SQLite
results
recovery
locks
generated config
```
Socket remains in runtime storage.
---
# 12. Phase E — launchd Agent lifecycle
Use only a current-user LaunchAgent.
No root.
No LaunchDaemon.
Recommended label:
```text
com.ntlx.serverfs.agent-bridge
```
Location:
```text
~/Library/LaunchAgents/com.ntlx.serverfs.agent-bridge.plist
```
## E1 — lifecycle commands
Use modern:
```text
launchctl bootstrap
launchctl print
launchctl kickstart
launchctl bootout
```
Do not build new deployment flows around legacy `load/unload`.
## E2 — generated plist
Generate deployment-specific paths.
Do not commit machine-specific paths.
Do not put secrets in plist.
Provider credentials and Jev/proxy secrets stay in private runtime/config material.
## E3 — no shell-profile dependency
A LaunchAgent must work without:
```text
.zshrc
.bashrc
interactive shell
Terminal.app
```
Resolve runtime binaries explicitly or through controlled configuration.
## E4 — containment
Measure actual launchd descendant behavior.
If shutdown cannot prove all provider descendants have stopped:
```text
do not claim containment
retain recovery guard
mark provider state unknown
fail closed for workspace write
```
Do not emulate Windows Job Objects without evidence.
## E5 — supervisor shape
Windows path remains unchanged.
macOS recommended topology:
```text
launchd
-> persistent Agent Bridge
OpenAI tunnel
-> stdio supervisor
-> ServerFS MCP child
-> connect to Bridge UDS
```
Do not start a second Bridge from every Tunnel/MCP process.
## E6 — single policy source and private Bridge state
The native operator policy has exactly one source:
```text
serverfs.toml
```
The launchd Bridge still needs a private 0600 JSON document because Jev/proxy material must stay
outside every exposed workdir. That document is **derived/private state**, not a second operator
configuration. Therefore:
- workdir, runtime and lifecycle policy is always derived from `serverfs.toml`;
- `agent-bridge configure` creates/refreshes private state from TOML policy plus the narrow private
Agent/Jev/proxy environment values;
- a TOML-only change can be synchronized without rewriting existing private material;
- `doctor` reports policy drift as FAIL and a newly started Darwin `serve`/tunnel refuses stale
Bridge policy;
- the release does **not** add hot reload: long-lived processes still freeze validated policy at
startup and configuration changes take effect through an explicit synchronize/restart boundary.
This prevents MCP and Bridge from entering different workdir/lease namespaces while preserving the
existing secret boundary and simple process-lifecycle model.
---
# 13. Phase F — Agent runtimes
All provider runtimes must be tested natively on ARM64.
No Rosetta runtime is part of v0.13 acceptance.
## Claude
Verify:
```text
normal task
workspace-write
approval callback
question callback
cancellation
proxy direct
proxy enabled
result spool
restart recovery
```
Keep provider permission mode behavior from v0.12.
## Qoder
Verify:
```text
task
model discovery
request-scoped model override
approval
proxy
cancellation
recovery
```
No static model/pricing catalog.
## Codex
Prefer reuse in this order:
1. existing Unix transport;
2. shared POSIX managed-daemon implementation;
3. shared POSIX standalone app-server implementation for proxy mode;
4. Darwin-specific lifecycle only for proven differences.
If current `codex_linux.py` is actually POSIX-generic after testing, extract/rename it rather than copying it.
Preserve:
```text
approvalPolicy="on-request"
model/list
model override
interrupt
```
## Agent proxy
Agent proxy remains credentialless-only where credentials would become visible to provider/tool child processes.
Authenticated unsafe configuration:
```text
fail before provider start
```
No process-global proxy credential leakage.
---
# 14. Phase G — Jev
No Darwin-specific Jev implementation.
Reuse v0.12:
```text
explicit HTTP client
optional authenticated proxy
fail-open network behavior
advisory authority only
```
Verify direct and proxied traffic on the real Mac.
---
# 15. Phase H — Native file ingress
Keep the security property:
> ServerFS MCP itself does not retrieve ChatGPT temporary HTTPS files.
Run a separate native helper.
Reuse existing validation logic:
```text
HTTPS only
443 only
allowed host rules
OpenAI Blob constrained family
DNS validation
global IP only
IP pinning
original hostname TLS
redirect revalidation
size limit
```
For local MCP <-> helper communication prefer:
```text
private AF_UNIX socket
```
rather than a public TCP listener.
Supervisor owns helper lifecycle.
Never silently fall back to downloading inside the MCP process.
---
# 16. Phase I — macOS 27 ARM64 CI
There is **no x86_64 macOS CI requirement** in v0.13.
There is **no macOS 26 matrix**.
There is **no Intel compatibility matrix**.
Use an ARM64 macOS 27 runner.
At the beginning of every macOS job assert:
```text
uname -m == arm64
macOS major == 27
ServerFS Python process == arm64
not Rosetta translated
```
Do not trust runner labels alone.
Current suitable hosted infrastructure may use the ARM64 Xcode 27/macOS 27 runner, but the assertions above are authoritative.
If hosted CI does not satisfy them, use an M-series self-hosted runner.
## Required CI
```text
Darwin filesystem backend
mutation
binary
search
xattrs
ACL metadata
getpeereid
flock
native CLI
doctor
tunnel bootstrap
Agent fake-provider harnesses
launchd-related pure logic
proxy
spool
recovery
```
## Non-regression
Also keep green:
```text
Linux CI
Linux container
Windows native
Windows Agent
ruff
site
git diff --check
```
---
# 17. Phase J — Live M-series/macOS 27 acceptance
CI is insufficient.
Run final acceptance on an actual M-series Mac with the newest available macOS 27.x.
Record:
```text
hardware
chip
OS build
Python build/architecture
ServerFS commit
runtime versions
tunnel-client version
```
## Filesystem
Exercise all:
```text
11 filesystem tools
13-tool binary surface
revision conflicts
read-only enforcement
hidden/deny policy
hard links
symlink attacks
atomic replacement
ACL/xattr preservation
large files
Unicode paths
FD pressure
```
## Tunnel / ChatGPT
Real:
```text
ChatGPT
-> official darwin-arm64 tunnel-client
-> native ServerFS
```
Verify filesystem operations end-to-end.
## Agent
Real live acceptance for:
```text
Codex
Claude
Qoder
```
including:
```text
task
workspace-write
model discovery where supported
model override where supported
approval
deny
question
cancellation
writer lease
restart/recovery
```
## Result spool
Use temporary low threshold:
```text
1024 or 2048 bytes
```
Prove:
```text
real result -> spool
bounded preview
chunked read
byte-exact reconstruction
```
Restore 256 KiB production default.
## Proxy
Prove independently:
```text
Tunnel direct/proxy
Agent direct/proxy
Jev direct/proxy
```
No credential leakage.
## File ingress
Use a real ChatGPT file parameter and verify:
```text
temporary URL
-> native ingress helper
-> upload_binary_file
-> SHA-256 exact
```
Temporary URL must not appear in logs.
---
# 18. Deployment assets
Keep macOS deployment minimal:
```text
deployment/macos/
```
Possible contents:
```text
README.md
LaunchAgent template/generator
install helper
update helper
uninstall helper
```
Do not make v0.13 depend on:
```text
Homebrew formula
DMG
.pkg
GUI
Xcode
Swift
root helper
```
Development/install target should remain approximately:
```text
uv sync
uv sync --project agent_bridge
serverfs bootstrap tunnel-client
serverfs doctor --config serverfs.toml
```
plus user LaunchAgent installation when Agent delegation is enabled.
---
# 19. Packaging
Expected distributions remain:
```text
serverfs-mcp
serverfs-agent-bridge
serverfs-windows-native
```
Do not add:
```text
serverfs-macos-native
```
unless Phase 0 proves compiled Darwin code indispensable.
macOS product/Bridge wheels should remain ordinary Python packages where possible.
No x86_64 macOS wheel/artifact is required.
No universal2 binary is required merely for compatibility.
Any compiled dependency introduced in the future must have an arm64-native execution path.
---
# 20. Documentation
Before release update:
```text
README.md
AGENTS.md
dev_plan_v0.13.md
deployment docs
website English
website zh-cn
architecture diagrams
getting started
upgrade docs
release docs
```
Platform descriptions must be precise:
```text
Linux
Docker / Linux POSIX / systemd user Bridge
Windows
Windows native / NTFS Rust kernel / Named Pipe / Windows lifecycle
macOS v0.13
M-series only
native arm64 only
macOS 27 Golden Gate only
Darwin FD backend
AF_UNIX + getpeereid
flock
launchd user Bridge
```
Do not write generic claims such as:
```text
macOS supported
Apple Silicon supported
Darwin supported
```
without the v0.13 boundary.
Preferred wording:
> ServerFS v0.13 supports native arm64 execution on Apple M-series Macs running macOS 27 Golden Gate.
---
# 21. Explicit non-goals
v0.13.0 does not support or optimize for:
```text
Intel Macs
x86_64 macOS
Rosetta
macOS 26
macOS 28+
universal binary compatibility
older Python solely for older macOS
Hackintosh
non-M Apple Silicon as a claimed target
cross-compilation to Intel
darwin-amd64 tunnel-client
Docker Desktop for Mac
Swift GUI
macOS app bundle
.pkg installer
Homebrew formula
root LaunchDaemon
```
Also do not add:
```text
shell MCP
generic argv execution
recursive delete
automatic symlink following
automatic runtime routing
automatic model selection
automatic approval
generic URL fetcher
```
---
# 22. Development order
Use this order:
```text
Phase 0
M-series macOS 27 capability probes
Phase A
POSIX extraction
Phase B
Darwin filesystem backend
Phase C
native CLI / doctor / darwin-arm64 tunnel
Phase D
Darwin Bridge seams
Phase E
launchd lifecycle
Phase F
Codex / Claude / Qoder
Phase G
Jev
Phase H
native file ingress
Phase I
ARM64 macOS 27 CI
Phase J
real M-series acceptance
Phase K
docs / release closeout
```
Recommended branch:
```text
feat/v0.13-macos27-arm64
```
Keep commits phase-sized.
Do not force-push shared `main`.
Linux and Windows may be under simultaneous development elsewhere; synchronize carefully before merge.
---
# 23. Release gates
v0.13.0 cannot be tagged until all are true.
## Platform
```text
real M-series Mac
native arm64 process
latest macOS 27.x
Rosetta disabled/not used
```
## Filesystem
```text
complete WorkdirSession
all 11 filesystem tools
binary surface
APFS live acceptance
symlink confinement
revision/CAS
atomic replace
ACL/xattr preservation
read-only enforcement
```
## Connectivity
```text
official darwin-arm64 tunnel-client
manifest verification
native ChatGPT E2E
```
## Agent
```text
launchd Bridge
getpeereid auth
flock writer lease
Codex live
Claude live
Qoder live
approvals
questions
cancellation
idempotency
spool
restart recovery
```
## Network
```text
Tunnel proxy evidence
Agent proxy evidence
Jev proxy evidence
no credential leakage
```
## File ingress
```text
native isolated helper
real ChatGPT fileParam
exact bytes
security restrictions preserved
```
## CI
```text
macOS 27 arm64 green
Linux green
Windows native green
Windows Agent green
site green
ruff green
git diff --check clean
```
## Release
```text
package versions aligned to 0.13.0
release-time docs described v0.13.0 as current (historical checkpoint)
acceptance evidence committed
main clean
all required CI green
```
Then and only then:
```text
tag v0.13.0
push tag
verify GitHub Release
verify release assets
verify Linux GHCR release
verify docs/site
```
---
# 24. Definition of done
The final product claim must be supportable verbatim:
> **ServerFS v0.13.0 adds first-class native macOS support specifically for Apple M-series Macs running macOS 27 Golden Gate. It runs natively as arm64 without Docker or Rosetta and provides the existing ServerFS filesystem, binary-transfer and Agent delegation capabilities using Darwin descriptor-relative filesystem operations, metadata-preserving atomic mutation, authenticated Unix-domain IPC via peer credentials, flock writer leases and a user-scoped launchd Agent Bridge. Codex, Claude Code, Qoder, Jev advisors, proxy routing, approvals, recovery, result spooling and ChatGPT file ingress are supported on this validated platform.**
If any clause cannot be demonstrated on the actual M-series/macOS 27 acceptance machine, narrow the release statement rather than inferring compatibility.