Area P: complete developer-facing interface and protocol suite (P1-P15)

.github/workflows/claude-review.yml

@@ -0,0 +1,51 @@
+# Automated PR review via the official Claude Code action. Reports findings as
+# PR comments; like every lane here it is advisory and never a required check
+# (AGENTS.md §4). Requires secrets.ANTHROPIC_API_KEY (or the OIDC federation
+# vars from anthropics/claude-code-action docs). Draft PRs and bot-authored
+# pushes are skipped to avoid loops.
+name: review
+
+on:
+  pull_request:
+    types: [opened, synchronize, ready_for_review, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: read
+  id-token: write
+
+concurrency:
+  group: review-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  claude-review:
+    if: |
+      github.event.pull_request.draft == false &&
+      github.actor != 'github-actions[bot]' &&
+      github.actor != 'coderabbitai[bot]' &&
+      github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          fetch-depth: 1
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            Review this pull request against the repository rules in AGENTS.md:
+            the Disposable/WAL/synchronous=OFF persistence profile, the
+            core < engine < api dependency direction, the production-file size
+            ceilings, the no-retry/one-attempt rule, and per-commit production
+            LOC accounting. Focus on real defects, contract violations and
+            boundary breaches, not style. Note: the PR branch is already
+            checked out. Post findings only as PR comments.
+          claude_args: |
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"
+            --max-turns 30

.github/workflows/publish.yml

@@ -0,0 +1,71 @@
+# npm publish lane: packs and publishes the @layerfs/* packages from api/.
+# Like every lane here it is a report, not a gate (AGENTS.md §4); a failed
+# publish never blocks a merge.
+#
+# Authentication: npm trusted publishing (OIDC). No NPM_TOKEN secret is used.
+# Each package must have a trusted publisher configured on npmjs.com naming:
+#   organization/user: Ephemeral-AI-Lab
+#   repository:        layerfs
+#   workflow filename: publish.yml
+#   environment:       npm-publish
+# The workflow and environment names must match exactly. Provenance
+# attestations are generated automatically (requires a public repo and a
+# public package).
+name: publish
+
+on:
+  # Publish manually for the version already committed in api/*/package.json.
+  workflow_dispatch:
+  # Or by tagging one release: v1.1.0 publishes all four packages.
+  push:
+    tags: ["v*"]
+
+permissions:
+  id-token: write # required for OIDC trusted publishing
+  contents: read
+
+concurrency:
+  group: publish
+  cancel-in-progress: false
+
+jobs:
+  verify:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+      # Offline tarball pack + import smoke test for all four packages.
+      - run: node api/scripts/prepare-publish.mjs
+
+  publish:
+    needs: verify
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    environment: npm-publish
+    strategy:
+      fail-fast: false
+      matrix:
+        package: [agent, backend, runtime, cli]
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24" # npm >= 11.5.1 for trusted publishing
+          registry-url: "https://registry.npmjs.org"
+          package-manager-cache: false
+      # A version already on the registry is reported and skipped, not an error:
+      # re-running the workflow for the same tag must be idempotent.
+      - name: Publish @layerfs/${{ matrix.package }}
+        run: |
+          set -e
+          cd "api/${{ matrix.package }}"
+          name="$(node -p "require('./package.json').name")"
+          version="$(node -p "require('./package.json').version")"
+          if npm view "$name@$version" version --silent 2>/dev/null | grep -q .; then
+            echo "::notice::$name@$version is already published; skipping"
+            exit 0
+          fi
+          npm publish --access public

.gitignore

@@ -1,6 +1,7 @@
 target/
 # The Node addon that api/scripts/build-native.mjs builds beside its crate.
 /engine/crates/layerfs-node/layerfs.node
+/engine/crates/layerfs-python/python/layerfs/_native.so
 /target-linux/
 /eval/runs/
 /eval/datasets/
@@ -13,3 +14,8 @@ benchmark-results/*
 !benchmark-results/fs-bench-pro/
 benchmark-results/fs-bench-pro/*
 !benchmark-results/fs-bench-pro/optimization-history.md
+
+# Area P build MCP dependencies and transient local agent state.
+tools/build-mcp/node_modules/
+.omc/
+

.omc/project-memory.json

@@ -0,0 +1,174 @@
+{
+  "version": "1.0.0",
+  "lastScanned": 1793199244010,
+  "projectRoot": "E:\\layerfs-connect\\layerfs",
+  "techStack": {
+    "languages": [
+      {
+        "name": "Rust",
+        "version": "1.85",
+        "confidence": "high",
+        "markers": [
+          "Cargo.toml"
+        ]
+      }
+    ],
+    "frameworks": [],
+    "packageManager": "cargo",
+    "runtime": null
+  },
+  "build": {
+    "buildCommand": "cargo build",
+    "testCommand": "cargo test",
+    "lintCommand": "cargo clippy",
+    "devCommand": "cargo run",
+    "scripts": {}
+  },
+  "conventions": {
+    "namingStyle": null,
+    "importStyle": null,
+    "testPattern": null,
+    "fileOrganization": null
+  },
+  "structure": {
+    "isMonorepo": false,
+    "workspaces": [],
+    "mainDirectories": [
+      "docs"
+    ],
+    "gitBranches": null
+  },
+  "customNotes": [],
+  "directoryMap": {
+    "api": {
+      "path": "api",
+      "purpose": "API routes",
+      "fileCount": 5,
+      "lastAccessed": 1793199243987,
+      "keyFiles": [
+        "AGENTS.md",
+        "package.json",
+        "README.md"
+      ]
+    },
+    "core": {
+      "path": "core",
+      "purpose": null,
+      "fileCount": 2,
+      "lastAccessed": 1793199243987,
+      "keyFiles": [
+        "AGENTS.md",
+        "README.md"
+      ]
+    },
+    "docs": {
+      "path": "docs",
+      "purpose": "Documentation",
+      "fileCount": 1,
+      "lastAccessed": 1793199243988,
+      "keyFiles": [
+        "README.md"
+      ]
+    },
+    "engine": {
+      "path": "engine",
+      "purpose": null,
+      "fileCount": 1,
+      "lastAccessed": 1793199243988,
+      "keyFiles": [
+        "AGENTS.md"
+      ]
+    },
+    "plugins": {
+      "path": "plugins",
+      "purpose": null,
+      "fileCount": 0,
+      "lastAccessed": 1793199243988,
+      "keyFiles": []
+    },
+    "tools": {
+      "path": "tools",
+      "purpose": null,
+      "fileCount": 32,
+      "lastAccessed": 1793199243988,
+      "keyFiles": [
+        "check_fuser_integrity.py",
+        "check_product_boundary.py",
+        "ci_tests.py",
+        "cleanup-scope.example.json",
+        "cleanup.py"
+      ]
+    },
+    "api\\docs": {
+      "path": "api\\docs",
+      "purpose": "Documentation",
+      "fileCount": 3,
+      "lastAccessed": 1793199243989,
+      "keyFiles": [
+        "agent.md",
+        "backend.md",
+        "runtime.md"
+      ]
+    },
+    "core\\docs": {
+      "path": "core\\docs",
+      "purpose": "Documentation",
+      "fileCount": 0,
+      "lastAccessed": 1793199243989,
+      "keyFiles": []
+    },
+    "docs\\assets": {
+      "path": "docs\\assets",
+      "purpose": "Static assets",
+      "fileCount": 0,
+      "lastAccessed": 1793199243989,
+      "keyFiles": []
+    },
+    "engine\\vendor": {
+      "path": "engine\\vendor",
+      "purpose": "Third-party code",
+      "fileCount": 0,
+      "lastAccessed": 1793199243989,
+      "keyFiles": []
+    }
+  },
+  "hotPaths": [
+    {
+      "path": "tools/worktree.py",
+      "accessCount": 2,
+      "lastAccessed": 1793199282040,
+      "type": "directory"
+    },
+    {
+      "path": "",
+      "accessCount": 2,
+      "lastAccessed": 1793200733326,
+      "type": "directory"
+    },
+    {
+      "path": "tools/worktree_run.py",
+      "accessCount": 1,
+      "lastAccessed": 1793199269103,
+      "type": "file"
+    },
+    {
+      "path": "tools/production_loc.py",
+      "accessCount": 1,
+      "lastAccessed": 1793199269157,
+      "type": "file"
+    },
+    {
+      "path": "docs/superpowers/specs/2026-10-28-area-p-design.md",
+      "accessCount": 1,
+      "lastAccessed": 1793199296007,
+      "type": "directory"
+    },
+    {
+      "path": ".superpowers/sdd/2026-10-28-area-p-foundation/progress.md",
+      "accessCount": 1,
+      "lastAccessed": 1793200843472,
+      "type": "file"
+    }
+  ],
+  "userDirectives": []
+}

.omc/ultragoal/plans/area-p-20261028/brief.md

@@ -0,0 +1,49 @@
+# LayerFS Area P (P1–P15) implementation brief
+
+Date: 2026-10-28
+Source: Ephemeral-AI-Lab/layerfs-connect#14 and its sub-issues; P2 is Ephemeral-AI-Lab/layerfs#484.
+Code repository: E:/layerfs-connect/layerfs
+Baseline: main at 582bc786f9e17a6993a147cc165e3e4a75366a9e (shallow clone after full-clone index-pack OOM).
+
+## Objective
+
+Build Area P without weakening LayerFS's core contracts. Before product code, establish a reproducible Linux-first build/test environment on the current Windows + Docker Desktop host, dedicated project-local build MCP/skills where they add value beyond the existing tools/worktree.py launcher, and a clean Git rollback/checkpoint procedure. Verify changed scope directly; CI is informational, not a completion gate.
+
+## Required outcome
+
+Each of Node, Python, CLI and MCP can mount, run a command, commit, read history, and push or pull, subject to explicitly resolved upstream dependencies. All work uses Disposable/WAL/synchronous=OFF only; Durable execution remains disabled. Linux owns real Store/FUSE E2E; Windows uses the existing worker route. No retired server or host-mediated Store route.
+
+## Task inventory
+
+- P1 (#53): Node SDK history calls — commit graph with Layers, merge parents, fork points, publish state, branch commits to fork point, changed paths per commit.
+- P2 (layerfs#484): explicit JS constructor/open/init configuration with environment fallback and lifetime-stable resolution.
+- P3 (#54): CLI history, push and pull; blocked by P1 and R7 (#42), which is open and itself blocked by R2/R3.
+- P4 (#55): Python SDK; blocked by D10 (#20), native Rust binding versus worker-only client.
+- P5 (#56): MCP server; blocked by D11 (#21), Node versus Python and stdio versus HTTP.
+- P6 (#57): contract tests shared by Node, Python, CLI and MCP.
+- P7 (#58): commit author/agent and labels.
+- P8 (#59): list/stat/read at any Commit or Layer, including binary flag.
+- P9 (#60): event stream for commits, branches, workspaces, sandboxes and init progress.
+- P10 (#61): per-call results API with method, duration, error code and write outcomes.
+- P11 (#62): Store statistics building on get_storage.
+- P12 (#63): Store summary for project lists.
+- P13 (#64): folder-scoped client with isolated folder and Branch namespace.
+- P14 (#65): fix list_branches short pages and list_workspaces Branch names beyond 64 (layerfs#480).
+- P15 (#66): publish @layerfs/* packages to npm; outward-facing release requires separate explicit approval before publishing.
+
+## Execution order and gates
+
+1. Complete read-only recon and obtain approval for the full design, including D10/D11 choices or explicitly defer blocked implementation.
+2. Pin the clean baseline and create the reproducible build/test/rollback tooling. Prove stand-in tests and the smallest real Linux Store/Workspace smoke path before feature work.
+3. Implement shared Rust/API primitives and contract fixtures before duplicating behavior across SDKs.
+4. Implement Node, Python, CLI and MCP in dependency order. Do not claim P3 push/pull complete while R7 is unavailable.
+5. Run scoped tests with explicit <=120-second test ceilings, build before test, preserve failure evidence, and run real Linux E2E through isolated resources.
+6. Finish with independent review, ai-slop-cleaner, full changed-scope verification, and the cross-client mount/exec/commit/history/push-or-pull evidence matrix. Publishing is not implied by local completion.
+
+## Constraints
+
+- Follow AGENTS.md plus core/engine/api guides and preserve core < engine < api layering.
+- No new dependency where an existing crate/package provides the capability.
+- One attempted operation; no automatic retry/replay.
+- No automatic commits, pushes, issue edits, or npm publication without explicit user request.
+- Preserve unrelated files and existing Docker/WSL state; use per-worktree caches and per-run Store/container ownership.

.omc/ultragoal/plans/area-p-20261028/claude-goal-snapshot.json

@@ -0,0 +1,6 @@
+{
+  "goal": {
+    "objective": "Complete all ultragoal stories in .omc/ultragoal/plans/area-p-20261028/goals.json: G001-recon-and-design Recon and design; G002-build-test-rollback-environment Build test rollback environment; G003-p1-node-history P1 Node history; G004-p2-constructor-configuration P2 Constructor configuration; G005-p6-shared-contract-tests P6 Shared contract tests; G006-p7-commit-metadata P7 Commit metadata; G007-p8-historical-file-reads P8 Historical file reads; G008-p9-event-stream P9 Event stream; G009-p10-per-call-results P10 Per-call results; G010-p11-store-statistics P11 Store statistics; G011-p12-store-summary P12 Store summary; G012-p13-folder-scoped-client P13 Folder-scoped client; G013-p14-pagination-fixes P14 Pagination fixes; G014-p3-cli-history-push-pull P3 CLI history push pull; G015-p4-python-sdk P4 Python SDK; G016-p5-mcp-server P5 MCP server; G017-p15-package-publishing P15 Package publishing; G018-final-cross-client-verification Final cross-client verification",
+    "status": "active"
+  }
+}