feat: native transparent session filesystem preview

.github/CODEOWNERS

@@ -0,0 +1,8 @@
+* @jstar0
+
+/docs/superpowers/specs/ @jstar0
+/internal/fold/ @jstar0
+/internal/pack/ @jstar0
+/internal/storage/ @jstar0
+/internal/vfs/ @jstar0
+/platform/darwin/fskit/ @jstar0

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,58 @@
+name: Bug report
+description: Report a reproducible CodexFold defect using synthetic or redacted data.
+title: "bug: "
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: Do not attach real Codex rollouts, databases, credentials, private prompts, or unredacted logs. Use GitHub Security Advisories for vulnerabilities.
+  - type: input
+    id: version
+    attributes:
+      label: Version or commit
+      placeholder: v0.2.1 or commit SHA
+    validations:
+      required: true
+  - type: dropdown
+    id: platform
+    attributes:
+      label: Platform
+      options:
+        - macOS
+        - Linux
+        - Windows
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: behavior
+    attributes:
+      label: Observed behavior
+      description: Include the command, sanitized error, and whether storage-only or filesystem-preview behavior was involved.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Synthetic reproduction
+      description: Provide minimal steps using generated or redacted fixtures.
+    validations:
+      required: true
+  - type: textarea
+    id: verification
+    attributes:
+      label: Verification already attempted
+      description: List doctor, tests, hashes, restart checks, or rollback attempts without private data.
+  - type: checkboxes
+    id: hygiene
+    attributes:
+      label: Data hygiene
+      options:
+        - label: I removed real session content, credentials, private prompts, local paths, and unredacted logs.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/jstar0/codexfold/security/advisories/new
+    about: Report vulnerabilities and sensitive findings privately.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,29 @@
+name: Feature request
+description: Propose a product behavior or engineering improvement.
+title: "feat: "
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: Describe the concrete workflow or limitation, not only the proposed implementation.
+    validations:
+      required: true
+  - type: textarea
+    id: outcome
+    attributes:
+      label: Required outcome
+      description: State observable acceptance criteria.
+    validations:
+      required: true
+  - type: textarea
+    id: constraints
+    attributes:
+      label: Safety and compatibility constraints
+      description: Note byte identity, rollback, privacy, platform, performance, or release-gate implications.
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Include simpler options and why they are insufficient.

.github/pull_request_template.md

@@ -0,0 +1,21 @@
+## Outcome
+
+Describe the user-visible or maintainer-visible result.
+
+## Safety Impact
+
+Describe effects on session bytes, routing, storage, filesystem behavior, service lifecycle, compatibility, and rollback. Write `None` only when none apply.
+
+## Verification
+
+List the exact commands and real environments used. Distinguish unit, synthetic, mounted-adapter, real-client, restart, and production evidence.
+
+## Checklist
+
+- [ ] The change matches the product contract and does not weaken a release gate.
+- [ ] Tests cover the behavior or regression.
+- [ ] `go test ./...`, race tests, vet, formatting, and required cross-builds pass.
+- [ ] Platform-specific validation was run when platform code changed.
+- [ ] Documentation and readiness language match the available evidence.
+- [ ] No real rollout, credential, private prompt, local path, database, log, build artifact, or Xcode user state is included.
+- [ ] Production Codex data and production service definitions were not used for development validation.

.github/workflows/ci.yml

@@ -4,21 +4,92 @@ on:
   push:
     branches: [main]
   pull_request:
+  workflow_dispatch:
 
 permissions:
   contents: read
 
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
+  quality:
+    name: quality
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+      - name: Check formatting
+        shell: bash
+        run: |
+          files="$(gofmt -l .)"
+          if [ -n "$files" ]; then
+            printf '%s\n' "$files"
+            exit 1
+          fi
+      - name: Check module files
+        run: |
+          go mod tidy
+          git diff --exit-code -- go.mod go.sum
+      - run: go vet ./...
+
   test:
+    name: test (${{ matrix.os }})
     strategy:
+      fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os: [ubuntu-latest, macos-latest]
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-go@v5
         with:
-          go-version: "1.26.x"
+          go-version-file: go.mod
           cache: true
       - run: go test ./... -count=1
       - run: go build ./cmd/codexfold
+
+  windows-compile:
+    name: windows-compile
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+      - name: Compile all test packages without claiming runtime validation
+        run: go test ./... -run '^$' -count=1
+      - run: go build ./cmd/codexfold
+
+  race:
+    name: race
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+      - run: go test -race ./... -count=1
+
+  cross-build:
+    name: cross-build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+      - name: Build Linux and Windows artifacts
+        shell: bash
+        run: |
+          CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o "$RUNNER_TEMP/codexfold-linux-amd64" ./cmd/codexfold
+          CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -o "$RUNNER_TEMP/codexfold-windows-amd64.exe" ./cmd/codexfold
+          CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go test -c -o "$RUNNER_TEMP/codexfold-testfs-linux.test" ./internal/testfs
+          CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go test -c -o "$RUNNER_TEMP/codexfold-testfs-windows.test.exe" ./internal/testfs

.gitignore

@@ -1,8 +1,11 @@
 /codexfold
+/codexfold.exe
 /*.sqlite
 /*.sqlite-shm
 /*.sqlite-wal
 *.prof
 *.test
 .DS_Store
 .worktrees/
+xcuserdata/
+*.xcuserstate

CODE_OF_CONDUCT.md

@@ -0,0 +1,22 @@
+# Code of Conduct
+
+CodexFold contributors are expected to collaborate professionally, focus review on technical behavior and evidence, and respect the privacy and safety constraints of a project that handles local conversation data.
+
+## Expected Behavior
+
+- Be direct, respectful, and specific about technical concerns.
+- Critique code, design, tests, and claims rather than people.
+- Disclose uncertainty and distinguish observed evidence from inference.
+- Protect private data and report sensitive findings through a private channel.
+- Accept maintainer decisions on safety gates, even when they delay a feature or release.
+
+## Unacceptable Behavior
+
+- Harassment, personal attacks, discrimination, threats, or sustained disruption.
+- Publishing private session content, credentials, personal information, or security details without authorization.
+- Misrepresenting test coverage, readiness, provenance, or compatibility evidence.
+- Pressuring contributors to bypass review, rollback, privacy, or production-safety requirements.
+
+## Enforcement
+
+Maintainers may edit or remove contributions, comments, or access that violate this policy. Report sensitive conduct issues privately to the repository owner through GitHub; use a private Security Advisory when the report also involves confidential data or a vulnerability.

CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing to CodexFold
+
+CodexFold handles private local session data and implements storage and filesystem behavior where a silent mismatch is unacceptable. Contributions should be small enough to review, explicit about safety boundaries, and backed by evidence that matches the claim.
+
+## Before You Start
+
+- Read the [product contract](docs/superpowers/specs/2026-07-11-transparent-session-filesystem-design.md), the [implementation alignment](docs/superpowers/specs/2026-07-14-transparent-session-filesystem-implementation-alignment.md), and the [maintainer guide](docs/maintainer-guide.md).
+- Open an issue for product behavior, format, compatibility, or architecture changes before implementing a large change.
+- Never use a real rollout, state database, credential, signing export, or private prompt as a fixture.
+- Do not weaken a release gate to make an implementation pass.
+
+## Development Setup
+
+Requirements:
+
+- Go version declared in `go.mod`.
+- Git.
+- Xcode 27 and XcodeGen for native macOS FSKit work.
+- Platform prerequisites only when testing the corresponding preview adapter.
+
+Run the common quality gate:
+
+```bash
+./scripts/test-cross-platform.sh
+git diff --check
+```
+
+For a focused change, run the smallest relevant package tests first, then the common gate before requesting review.
+
+Windows currently has compile and cross-build gates only. Do not describe those checks as real WinFsp or Windows Service runtime validation.
+
+## Branches and Commits
+
+- Create a branch from current `main`; use a descriptive prefix such as `feat/`, `fix/`, `docs/`, or `test/`.
+- Use conventional, imperative commit subjects such as `fix: reject stale native writer state`.
+- Keep generated files, binaries, user-specific Xcode state, local databases, and test artifacts out of commits.
+- Update `platform/darwin/fskit/project.yml` first and regenerate the Xcode project; do not hand-maintain personal Xcode state.
+
+## Pull Requests
+
+- Explain the user-visible outcome, safety impact, and exact evidence.
+- Distinguish unit, synthetic, mounted-adapter, real-client, host-restart, and production evidence. One category never substitutes for another.
+- Add or update tests before changing a status or readiness claim.
+- Keep production Codex homes and production service definitions untouched during development validation.
+- Resolve review conversations and keep the branch current with `main` before merge.
+
+## Filesystem Changes
+
+Native filesystem work must remain isolated until every relevant gate passes. Use disposable homes, stores, native roots, mount points, and service labels. A test may not route a production SQLite record or remove a production JSONL source.
+
+The macOS terminal architecture is:
+
+```text
+Codex CLI / Desktop
+        -> Apple-native Swift FSKit extension
+        -> versioned binary UDS IPC
+        -> Go CodexFold daemon
+        -> packfile + index + manifest + append delta + COW backing
+```
+
+NFS and FUSE-T are development fallback or historical evidence only. They are not acceptable replacements for native FSKit release gates.
+
+## Security
+
+Report vulnerabilities through GitHub Security Advisories. Public issues and pull requests must contain only synthetic or fully redacted data; see [SECURITY.md](SECURITY.md).

README.md

@@ -12,6 +12,16 @@ It finds exact duplicate raw JSON string tokens, complete JSONL records, and con
 
 The requirements and release gates for normal JSONL paths backed transparently by shared storage are defined in [the transparent filesystem product contract](docs/superpowers/specs/2026-07-11-transparent-session-filesystem-design.md). No release may claim `随点随开`, transparent session access, or production-ready virtual sessions before the platform-specific gates in that contract pass.
 
+The unreleased transparent-filesystem branch remains `fs-engine-preview`:
+
+- macOS now targets an Apple-native Swift FSKit extension connected over a versioned Unix-domain-socket protocol to the Go CodexFold daemon. Isolated mounted behavior, service crash recovery, and atomic app/binary rollback gates pass; read-ahead performance/coherency and full real Codex CLI/Desktop product acceptance remain open.
+- The earlier synchronous FUSE-T NFS route remains historical validation evidence and a development fallback only. FUSE-T's third-party FSKit backend remains rejected after deterministic byte-loss and cache-invalidation failures; it is not the Apple-native FSKit implementation in this repository.
+- Linux FUSE3 has real unprivileged read, append, copy-on-write, truncate, archive rename, crash recovery, remount, performance, and `systemd --user` lifecycle evidence.
+- Windows has a WinFsp adapter and native Windows Service host that cross-compile, but no real Windows/WinFsp host has validated them yet.
+- The production service and production Codex home remain disabled. Native FSKit performance/coherency, real CLI/Desktop acceptance, retention, actual in-flight power loss, and the remaining platform-specific client and upgrade gates still block promotion.
+
+See [the Linux FUSE3 validation](docs/validation-linux-fuse3.md) and [the macOS canary validation](docs/validation-macos-canary.md) for the evidence boundary. The default build remains storage-only; platform mounts require explicit build tags and installed host prerequisites.
+
 ## Install
 
 ```bash
@@ -81,6 +91,27 @@ codexfold remove-contained <contained-session-id> <container-session-id> --apply
 
 The first command is proof-only. `--apply` additionally requires an existing verified fold, a current source SHA-256 match, and a successful temporary unfold. It then isolates the source file, removes the archived thread and associated local state in one SQLite transaction, cleans exact thread-ID references from Codex global state, and finally deletes the isolated source. A tombstone and fold manifest remain for byte-level recovery. Concurrent global-state changes abort the operation instead of being overwritten.
 
+## Fork Families And Archival
+
+Inspect the explicit Codex spawn graph and compare two selected rollouts without mutation:
+
+```bash
+codexfold fork-family show <session-id>
+codexfold fork-family compare <left-session-id> <right-session-id>
+```
+
+The report keeps graph ancestry separate from exact content evidence. It can identify identical applicable records, complete containment, shared prefixes with independent tails, other exact shared records, or an unknown relationship. It never labels a branch useless from ancestry, age, title, or size.
+
+Preview and explicitly archive one active session:
+
+```bash
+codexfold archive <session-id>
+codexfold archive <session-id> --apply
+codexfold archive recover <session-id> --apply
+```
+
+Archive is dry-run-first and preserves the rollout bytes. Apply requires the native writer probe, revalidates the selected SQLite route and complete source SHA-256, moves the rollout to Codex's flat `archived_sessions` path, and updates the official archive fields in one guarded transaction. A durable journal supports deterministic recovery if file and database commit acknowledgement are interrupted. Archive never deletes a session; exact-contained deletion remains the separate archived-only `remove-contained` operation.
+
 ## Maintenance
 
 Verify every manifest and referenced object:
@@ -107,6 +138,7 @@ codexfold gc --apply
 - Restore writes to a temporary file, verifies the complete SHA-256, then atomically replaces the target.
 - Existing indexes, manifests, and restore targets are never replaced without an explicit overwrite flag.
 - Contained-session removal is archived-only, proof-first, transaction-guarded, and retains recovery evidence.
+- Fork-family reporting is evidence-only, archive is explicit and recoverable, and neither operation triggers deletion.
 
 ## Development
 
@@ -117,4 +149,4 @@ go vet ./...
 go build ./cmd/codexfold
 ```
 
-See [the architecture](docs/design.md), [Fold V1 format](docs/fold-v1.md), [v0.2 validation](docs/validation-v0.2.md), and [the transparent filesystem product contract](docs/superpowers/specs/2026-07-11-transparent-session-filesystem-design.md).
+See [the architecture](docs/design.md), [Fold V1 format](docs/fold-v1.md), [v0.2 validation](docs/validation-v0.2.md), [the transparent filesystem product contract](docs/superpowers/specs/2026-07-11-transparent-session-filesystem-design.md), and [the maintainer guide](docs/maintainer-guide.md).

SECURITY.md

@@ -2,4 +2,16 @@
 
 CodexFold processes local conversation rollouts that may contain secrets or private data. The project does not transmit scan inputs or report field contents.
 
-Please report vulnerabilities privately through GitHub Security Advisories. Do not include real session files, credentials, or private prompts in public issues.
+## Supported Code
+
+Security fixes target the latest release and the current `main` branch. Preview filesystem branches may change quickly and must not be treated as production-safe unless the repository explicitly publishes a platform readiness claim.
+
+## Reporting
+
+Please report vulnerabilities privately through GitHub Security Advisories. Do not include real session files, credentials, private prompts, local filesystem paths, service tokens, or unredacted logs in public issues.
+
+Include the affected version or commit, operating system, impact, and a minimal synthetic reproducer when possible. Maintainers will acknowledge the report, assess whether private coordination is required, and publish remediation details after a safe fix is available.
+
+## Data Handling
+
+Tests and bug reports must use generated or redacted fixtures. A contributor must never commit a real Codex rollout, Codex state database, credential, signing identity export, provisioning profile, or production service definition.