@ornexus/neocortex 4.60.16 → 4.63.4

package/install.sh

@@ -4,7 +4,7 @@
 # Development Orchestrator
 
 # Versao do instalador
-VERSION="4.60.16"
+VERSION="4.63.4"
 
 # Flags
 MIGRATION_DETECTED=false
@@ -14,7 +14,8 @@ LEGACY_ITEMS=""
 LEGACY_WARNINGS=0
 SELECTED_TARGETS=""
 VALID_TARGETS="claude-code cursor vscode gemini gemini-cli codex antigravity opencode kimi openclaw"
-# LOCAL_MODE removed (Epic 50): thin-client ALWAYS, zero IP on client
+# LOCAL_MODE removed: thin-client mode is mandatory. Customer installer paths never read core/ or
+# development targets/ from a source checkout.
 # SSoT: packages/client/src/constants.ts DEFAULT_SERVER_URL
 NEOCORTEX_SERVER_URL="${NEOCORTEX_SERVER_URL:-$(printf '%s://%s.%s.%s' 'https' 'api' 'neocortex' 'sh')}"
 
@@ -303,7 +304,6 @@ is_neocortex_source_project() {
 
     [ -f "$package_file" ] || return 1
     grep -q '"name"[[:space:]]*:[[:space:]]*"@ornexus/neocortex"' "$package_file" 2>/dev/null || return 1
-    [ -d "$candidate_dir/core" ] || return 1
     [ -d "$candidate_dir/packages/server" ] || return 1
     [ -d "$candidate_dir/targets-stubs" ] || return 1
     [ -f "$candidate_dir/install.sh" ] || return 1
@@ -314,22 +314,15 @@ is_neocortex_source_project() {
 resolve_target_dir() {
     local target="$1"
     local stub_dir="$SOURCE_DIR/targets-stubs/$target"
-    local dev_dir="$SOURCE_DIR/targets/$target"
 
-    [ "$target" = "gemini" ] && stub_dir="$SOURCE_DIR/targets-stubs/gemini-cli" && dev_dir="$SOURCE_DIR/targets/gemini-cli"
+    [ "$target" = "gemini" ] && stub_dir="$SOURCE_DIR/targets-stubs/gemini-cli"
 
     if [ -d "$stub_dir" ]; then
         printf '%s\n' "$stub_dir"
         return 0
     fi
 
-    if is_neocortex_source_project "$SOURCE_DIR" && [ -d "$dev_dir" ]; then
-        debug "Fallback dev targets/ para $target: $dev_dir"
-        printf '%s\n' "$dev_dir"
-        return 0
-    fi
-
-    warn "$target ${DIM}(adapter nao encontrado; paths tentados: $stub_dir, $dev_dir)${NC}"
+    warn "$target ${DIM}(adapter publico nao encontrado: $stub_dir)${NC}"
     return 1
 }
 
@@ -1015,36 +1008,9 @@ install_core() {
 # =============================================================================
 
 install_skills() {
-    local errors=0
-
-    SKILLS_DIR="${CLAUDE_DIR}/skills"
-    SKILLS_DEST="${SKILLS_DIR}/neocortex"
-    SKILLS_SOURCE="${SOURCE_DIR}/core/skills"
-
     # Thin-client: skills delivered by remote server, never copied
     ok "Skills: delivered by remote server"
     return 0
-
-    mkdir -p "$SKILLS_DIR" 2>/dev/null || { fail "Falha ao criar $SKILLS_DIR"; return 1; }
-
-    # Clean previous
-    [ -d "$SKILLS_DEST" ] && rm -rf "$SKILLS_DEST" 2>/dev/null
-
-    if cp -r "$SKILLS_SOURCE" "$SKILLS_DEST" 2>/dev/null; then
-        # Count skills
-        local skill_count=0
-        for skill_file in "$SKILLS_DEST"/step-skills/*/*.md "$SKILLS_DEST"/domain-skills/*/*.md; do
-            if [ -f "$skill_file" ] && [[ "$(basename "$skill_file")" != "_template.md" ]]; then
-                ((skill_count++))
-            fi
-        done
-        ok "Skills instaladas ${DIM}($skill_count skills) [modo local]${NC}"
-    else
-        fail "Falha ao copiar skills"
-        ((errors++))
-    fi
-
-    return $errors
 }
 
 # =============================================================================
@@ -1055,9 +1021,6 @@ install_agent() {
     local errors=0
 
     CLAUDE_TARGET_DIR="$SOURCE_DIR/targets-stubs/claude-code"
-    if [ ! -d "$CLAUDE_TARGET_DIR" ] && is_neocortex_source_project "$SOURCE_DIR" && [ -d "$SOURCE_DIR/targets/claude-code" ]; then
-        CLAUDE_TARGET_DIR="$SOURCE_DIR/targets/claude-code"
-    fi
     if [ ! -d "$CLAUDE_TARGET_DIR" ]; then
         CLAUDE_TARGET_DIR="$SOURCE_DIR"
     fi
@@ -1487,56 +1450,26 @@ verify_installation() {
         fi
     done
 
-    if false; then
-        # ─── Layer 3: Step directories (removed - thin-client only) ──────
-        for dir in steps-c steps-e steps-p steps-r steps-u; do
-            local dir_path="$DEST_DIR/$dir"
-            if [ ! -d "$dir_path" ]; then
-                report="${report}FAIL ${dir}/ (diretorio nao encontrado)\n"
-                fails=$((fails + 1))
-            else
-                local md_count=0
-                for f in "$dir_path"/*.md; do
-                    [ -f "$f" ] && md_count=$((md_count + 1))
-                done
-                if [ $md_count -eq 0 ]; then
-                    report="${report}WARN ${dir}/ (vazio - nenhum arquivo .md)\n"
-                    warns=$((warns + 1))
-                else
-                    report="${report}OK   ${dir}/ (${md_count} arquivos)\n"
-                fi
-            fi
-        done
-
-        # ─── Layer 3b: Core directory (local mode only) ──────────────────
-        if [ ! -d "$DEST_DIR/core" ]; then
-            report="${report}FAIL core/ (diretorio nao encontrado)\n"
-            fails=$((fails + 1))
-        else
-            report="${report}OK   core/\n"
-        fi
+    # ─── Layer 3: Thin client config (remote mode) ─────────────────────
+    local config_file="${HOME}/.neocortex/config.json"
+    if [ -f "$config_file" ]; then
+        report="${report}OK   ~/.neocortex/config.json (thin client configured)\n"
     else
-        # ─── Layer 3: Thin client config (remote mode) ───────────────────
-        local config_file="${HOME}/.neocortex/config.json"
-        if [ -f "$config_file" ]; then
-            report="${report}OK   ~/.neocortex/config.json (thin client configured)\n"
-        else
-            report="${report}WARN ~/.neocortex/config.json (nao encontrado)\n"
-            warns=$((warns + 1))
-        fi
+        report="${report}WARN ~/.neocortex/config.json (nao encontrado)\n"
+        warns=$((warns + 1))
+    fi
 
-        # Verify NO IP directories exist
-        local ip_found=false
-        for dir in core steps-c steps-e steps-p steps-r steps-u; do
-            if [ -d "$DEST_DIR/$dir" ]; then
-                report="${report}WARN ${dir}/ ainda existe (deveria ter sido removido)\n"
-                warns=$((warns + 1))
-                ip_found=true
-            fi
-        done
-        if [ "$ip_found" = false ]; then
-            report="${report}OK   Zero IP no filesystem (modo remoto)\n"
+    # Verify NO IP directories exist
+    local ip_found=false
+    for dir in core steps-c steps-e steps-p steps-r steps-u; do
+        if [ -d "$DEST_DIR/$dir" ]; then
+            report="${report}WARN ${dir}/ ainda existe (deveria ter sido removido)\n"
+            warns=$((warns + 1))
+            ip_found=true
         fi
+    done
+    if [ "$ip_found" = false ]; then
+        report="${report}OK   Zero IP no filesystem (modo remoto)\n"
     fi
 
     # ─── Display report ─────────────────────────────────────────────────
@@ -1680,10 +1613,15 @@ create_project_dirs() {
                  "$project_dir/docs/epics" \
                  "$project_dir/docs/proposals" 2>/dev/null
 
-        # Copy state template if needed
+        # Create a public state shell if needed. Never source it from core/.
         if [ ! -f "$project_dir/.neocortex/state.json" ]; then
-            [ -f "$SOURCE_DIR/core/data/state-template.json" ] && \
-                cp "$SOURCE_DIR/core/data/state-template.json" "$project_dir/.neocortex/state.json"
+            cat > "$project_dir/.neocortex/state.json" <<'EOFSTATE'
+{
+  "schema_version": 1,
+  "stories": {},
+  "epics": {}
+}
+EOFSTATE
         fi
 
         # Thin-client: never copy core/ to project

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ornexus/neocortex",
-  "version": "4.60.16",
-  "description": "Neocortex v4.60.16 - Orquestrador de Desenvolvimento de Epics & Stories para Claude Code",
+  "version": "4.63.4",
+  "description": "Neocortex v4.63.4 - Orquestrador de Desenvolvimento de Epics & Stories para Claude Code",
   "keywords": [
     "claude",
     "claude-code",
@@ -67,6 +67,9 @@
   ],
   "scripts": {
     "test": "node scripts/test-root.mjs",
+    "test:fast": "npm --prefix packages/server test -- public-output-ip-dlp protected-execution-worker invoke-e2e arch-plan-brownfield-ux arch-plan-product-experience p201-zero-pi-arch-plan-e2e && npm --prefix packages/client test -- platform-detector invoke project-evidence-collector public-execution/dispatch && npm --prefix packages/shared test -- public-execution-contract project-evidence-contract",
+    "test:pr": "npm run test:fast && npm --prefix packages/shared run build && npm --prefix packages/client run build && npm --prefix packages/client test -- tarball-validation stubs-integrity p155-install-regression-suite && npm --prefix packages/server run build -- --noEmit",
+    "test:release": "npx vitest run --config vitest.config.ts packages/shared/src packages/core/src && npm run build && npm --prefix packages/client test && npm test -- --runInBand && npm run test:fast && npm --prefix packages/server test -- p201-zero-pi-public-safety p201-downstream-ux-propagation p201-encrypted-asset-bundle p201-encrypted-production-deploy shared-types-sync quota-v2-flags && npm --prefix packages/server run build -- --noEmit && npm --prefix packages/server run bundle && npm run storybook:build && npm run storybook:smoke && npm run sbom && npm run validate && bash scripts/ip-leak-scan.sh --skip-docker --check=1 --version $(node -p \"require('./package.json').version\")",
     "build": "npm run build -w packages/shared && npm run build -w packages/client && node scripts/strip-source-map-comments.js && node scripts/minify-client-dist.mjs",
     "build:clean": "rm -rf packages/shared/dist packages/client/dist && npm run build",
     "build:client": "npm run build -w packages/client",

package/packages/client/dist/adapters/platform-detector.d.ts

@@ -10,13 +10,14 @@
  *
  * Detection priority:
  * 1. --target flag (explicit override)
- * 2. CODEX_ env var + AGENTS.md file -> Codex
- * 3. .cursorrules file -> Cursor
- * 4. CLAUDE.md file -> Claude Code
- * 5. .vscode/ directory -> VS Code
+ * 2. OPENCODE=1 runtime marker -> OpenCode
+ * 3. CODEX_CLI=1 or non-empty CODEX_THREAD_ID -> Codex
+ * 4. Claude Code runtime marker -> Claude Code
+ * 5. .cursorrules file -> Cursor
  * 6. GEMINI_CLI env var -> Gemini CLI
- * 7. CODEX_ env var prefix -> Codex
- * 8. Default fallback -> Claude Code
+ * 7. CLAUDE.md file -> Claude Code
+ * 8. .vscode/ directory -> VS Code
+ * 9. Default fallback -> Claude Code
  *
  * Story 42.8
  */

package/packages/client/dist/adapters/platform-detector.js

@@ -1 +1 @@
-import{existsSync as n}from"node:fs";import{join as i}from"node:path";const t=new Set(["claude-code","cursor","vscode","gemini","codex","opencode","github-copilot-cli","kimi","antigravity"]),d=Object.freeze({claude:"claude-code","claude-code":"claude-code",cursor:"cursor",vscode:"vscode","vscode-copilot":"vscode",gemini:"gemini","gemini-cli":"gemini",codex:"codex","codex-cli":"codex",opencode:"opencode","copilot-cli":"github-copilot-cli","github-copilot-cli":"github-copilot-cli",kimi:"kimi",antigravity:"antigravity"});function f(e){return t.has(e)}function a(e){return d[e.trim().toLowerCase()]??null}const u=e=>n(e);function g(e,r=u){if(e.targetFlag){const o=a(e.targetFlag);if(o)return{targetId:o,confidence:1,reason:`Explicit --target=${o} flag`}}const c=Object.keys(e.env).some(o=>o.startsWith("CODEX_"));return c&&r(i(e.cwd,"AGENTS.md"))?{targetId:"codex",confidence:.96,reason:"Found CODEX_ environment variable and uppercase AGENTS.md in project root"}:r(i(e.cwd,".cursorrules"))?{targetId:"cursor",confidence:.95,reason:"Found .cursorrules file in project root"}:r(i(e.cwd,"CLAUDE.md"))?{targetId:"claude-code",confidence:.9,reason:"Found CLAUDE.md file in project root"}:r(i(e.cwd,".vscode"))?{targetId:"vscode",confidence:.7,reason:"Found .vscode/ directory in project root"}:e.env.GEMINI_CLI!==void 0?{targetId:"gemini",confidence:.9,reason:"GEMINI_CLI environment variable is set"}:c?{targetId:"codex",confidence:.85,reason:"Found environment variable with CODEX_ prefix"}:{targetId:"claude-code",confidence:.5,reason:"Default fallback (no platform markers detected)"}}export{g as detectPlatform,f as isValidTargetId,a as normalizeTargetId};
+import{existsSync as t}from"node:fs";import{join as r}from"node:path";const a=new Set(["claude-code","cursor","vscode","gemini","codex","opencode","github-copilot-cli","kimi","antigravity"]),u=Object.freeze({claude:"claude-code","claude-code":"claude-code",cursor:"cursor",vscode:"vscode","vscode-copilot":"vscode",gemini:"gemini","gemini-cli":"gemini",codex:"codex","codex-cli":"codex",opencode:"opencode","copilot-cli":"github-copilot-cli","github-copilot-cli":"github-copilot-cli",kimi:"kimi",antigravity:"antigravity"});function g(e){return a.has(e)}function l(e){return u[e.trim().toLowerCase()]??null}const s=e=>t(e);function p(e,o=s){if(e.targetFlag){const n=l(e.targetFlag);if(n)return{targetId:n,confidence:1,reason:`Explicit --target=${n} flag`}}const d=e.env.OPENCODE==="1",i=e.env.CODEX_CLI==="1"||!!e.env.CODEX_THREAD_ID?.trim(),c=!!(e.env.CLAUDECODE||e.env.CLAUDE_CODE||e.env.CLAUDE_AGENT);return d?{targetId:"opencode",confidence:.95,reason:"Found OpenCode runtime environment marker"}:i&&o(r(e.cwd,"AGENTS.md"))?{targetId:"codex",confidence:.96,reason:"Found Codex runtime marker and uppercase AGENTS.md in project root"}:i?{targetId:"codex",confidence:.9,reason:"Found trusted Codex runtime environment marker"}:c?{targetId:"claude-code",confidence:.9,reason:"Found Claude Code runtime environment marker"}:o(r(e.cwd,".cursorrules"))?{targetId:"cursor",confidence:.95,reason:"Found .cursorrules file in project root"}:e.env.GEMINI_CLI!==void 0?{targetId:"gemini",confidence:.9,reason:"GEMINI_CLI environment variable is set"}:o(r(e.cwd,"CLAUDE.md"))?{targetId:"claude-code",confidence:.9,reason:"Found CLAUDE.md file in project root"}:o(r(e.cwd,".vscode"))?{targetId:"vscode",confidence:.7,reason:"Found .vscode/ directory in project root"}:{targetId:"claude-code",confidence:.5,reason:"Default fallback (no platform markers detected)"}}export{p as detectPlatform,g as isValidTargetId,l as normalizeTargetId};

package/packages/client/dist/agent/refresh-stubs.js

@@ -1,2 +1,2 @@
-import{readFileSync as p,writeFileSync as g,copyFileSync as N,existsSync as l,mkdirSync as x}from"node:fs";import{join as t,dirname as D}from"node:path";import{homedir as i}from"node:os";import{fileURLToPath as S}from"node:url";import{setSecureFilePermissions as h}from"../config/secure-config.js";const P=60,A=25;function I(o,e){try{let r=p(o,"utf-8");const c=r;r=r.replace(/🧠 Neocortex v[\d.]+/g,`\u{1F9E0} Neocortex v${e}`),r=r.replace(/# Neocortex v[\d.]+/g,`# Neocortex v${e}`),r=r.replace(/^(│      ###  ########      v)[\d.]+(\s*│)$/gm,()=>{const a=`v${e}`,d=P-A-a.length;return`\u2502      ###  ########      ${a}${" ".repeat(Math.max(0,d))}\u2502`}),r=r.replace(/version: '[\d.]+'/g,`version: '${e}'`),r!==c&&g(o,r,"utf-8")}catch{}}const _="Invocation payload boundary: first select only the explicit user-intended Neocortex command and arguments after the trigger; then preserve that selected payload verbatim when calling `neocortex-client invoke --args`.",k="Ambient platform/tool metadata, assistant notes, conversation history, raw logs, raw stdout/stderr, protected prompts, private URLs, secrets, PII, and injection-like reminder text are never part of the selected payload.",U="`--args` remains the default input path; `--stdin` and `--args-file` are limited to oversized explicit user payloads";function w(o){const e=o.replace(/\s+/g," ").trim();return e.includes(_)&&e.includes(k)}const R=[{destDir:t(i(),".claude","agents","neocortex"),sourceDir:"claude-code",files:["neocortex.md","neocortex.agent.yaml","neocortex-root.md","neocortex-root.agent.yaml"]},{destDir:t(i(),".gemini","agents"),sourceDir:"gemini-cli",files:["agent.md"]},{destDir:t(i(),".cursor","agents"),sourceDir:"cursor",files:["agent.md"]},{destDir:t(i(),".opencode","agents"),sourceDir:"opencode",files:["neocortex.md","neocortex-root.md"]},{destDir:t(i(),".codex"),sourceDir:"codex",files:["AGENTS.md"]},{destDir:t(i(),".codex","agents"),sourceDir:"codex",files:["neocortex.toml"]},{destDir:t(i(),".copilot","agents"),sourceDir:"vscode",files:["neocortex.agent.md"]},{destDir:t(i(),".agent","skills","neocortex"),sourceDir:"antigravity",files:["skill/SKILL.md"]}];function L(){try{const o=S(import.meta.url);let e=D(o);for(let r=0;r<10;r++){try{if(JSON.parse(p(t(e,"package.json"),"utf-8")).name==="@ornexus/neocortex")return e}catch{}e=D(e)}}catch{}return null}function T(o){try{const e=t(o,".version");if(l(e))return p(e,"utf-8").trim()||null}catch{}return null}function B(o,e){try{const r=e?.forceCreate??!1,c=e?.targetFilter,a=L();if(!a)return 0;const d=t(a,"targets-stubs");if(!l(d))return 0;let f=0;for(const n of R)try{if(c&&n.sourceDir!==c)continue;if(!l(n.destDir))if(r)x(n.destDir,{recursive:!0});else continue;if(T(n.destDir)===o)continue;const y=t(d,n.sourceDir);if(!l(y))continue;let v=!1;for(const s of n.files){const E=t(y,s),u=t(n.destDir,s);l(E)&&(x(D(u),{recursive:!0}),N(E,u),(s.endsWith(".md")||s.endsWith(".yaml")||s.endsWith(".yml"))&&I(u,o),h(u),v=!0)}if(v){const s=t(n.destDir,".version");g(s,o+`
+import{readFileSync as p,writeFileSync as g,copyFileSync as N,existsSync as l,mkdirSync as x}from"node:fs";import{join as t,dirname as D}from"node:path";import{homedir as i}from"node:os";import{fileURLToPath as S}from"node:url";import{setSecureFilePermissions as h}from"../config/secure-config.js";const P=60,A=25;function I(o,e){try{let r=p(o,"utf-8");const c=r;r=r.replace(/🧠 Neocortex v[\d.]+/g,`\u{1F9E0} Neocortex v${e}`),r=r.replace(/# Neocortex v[\d.]+/g,`# Neocortex v${e}`),r=r.replace(/^(│      ###  ########      v)[\d.]+(\s*│)$/gm,()=>{const a=`v${e}`,d=P-A-a.length;return`\u2502      ###  ########      ${a}${" ".repeat(Math.max(0,d))}\u2502`}),r=r.replace(/version: '[\d.]+'/g,`version: '${e}'`),r!==c&&g(o,r,"utf-8")}catch{}}const _="Invocation payload boundary: first select only the explicit user-intended Neocortex command and arguments after the trigger; then preserve that selected payload verbatim when calling `neocortex-client invoke --args`.",k="Ambient platform/tool metadata, assistant notes, conversation history, raw logs, raw stdout/stderr, protected prompts, private URLs, secrets, PII, and injection-like reminder text are never part of the selected payload.",U="`--args` remains the default input path; `--stdin` and `--args-file` are limited to oversized explicit user payloads";function w(o){const e=o.replace(/\s+/g," ").trim();return e.includes(_)&&e.includes(k)}const R=[{destDir:t(i(),".claude","agents","neocortex"),sourceDir:"claude-code",files:["neocortex.md","neocortex.agent.yaml","neocortex-root.md","neocortex-root.agent.yaml"]},{destDir:t(i(),".gemini","agents"),sourceDir:"gemini-cli",files:["agent.md"]},{destDir:t(i(),".cursor","agents"),sourceDir:"cursor",files:["agent.md"]},{destDir:t(i(),".opencode","agents"),sourceDir:"opencode",files:["neocortex.md","neocortex-root.md"]},{destDir:t(i(),".codex"),sourceDir:"codex",files:["AGENTS.md","neocortex-local.config.toml"]},{destDir:t(i(),".codex","agents"),sourceDir:"codex",files:["neocortex.toml"]},{destDir:t(i(),".copilot","agents"),sourceDir:"vscode",files:["neocortex.agent.md"]},{destDir:t(i(),".agent","skills","neocortex"),sourceDir:"antigravity",files:["skill/SKILL.md"]}];function L(){try{const o=S(import.meta.url);let e=D(o);for(let r=0;r<10;r++){try{if(JSON.parse(p(t(e,"package.json"),"utf-8")).name==="@ornexus/neocortex")return e}catch{}e=D(e)}}catch{}return null}function T(o){try{const e=t(o,".version");if(l(e))return p(e,"utf-8").trim()||null}catch{}return null}function B(o,e){try{const r=e?.forceCreate??!1,c=e?.targetFilter,a=L();if(!a)return 0;const d=t(a,"targets-stubs");if(!l(d))return 0;let f=0;for(const n of R)try{if(c&&n.sourceDir!==c)continue;if(!l(n.destDir))if(r)x(n.destDir,{recursive:!0});else continue;if(T(n.destDir)===o)continue;const y=t(d,n.sourceDir);if(!l(y))continue;let v=!1;for(const s of n.files){const E=t(y,s),u=t(n.destDir,s);l(E)&&(x(D(u),{recursive:!0}),N(E,u),(s.endsWith(".md")||s.endsWith(".yaml")||s.endsWith(".yml"))&&I(u,o),h(u),v=!0)}if(v){const s=t(n.destDir,".version");g(s,o+`
 `,"utf-8"),h(s),f++}}catch{}if(f>0)try{const n=t(i(),".neocortex");x(n,{recursive:!0});const m=t(n,".update-check");g(m,"",{flag:"w"}),h(m)}catch{}return f}catch{return 0}}export{_ as SELECTED_PAYLOAD_BOUNDARY_SNIPPET,k as SELECTED_PAYLOAD_EXCLUSION_SNIPPET,U as SELECTED_PAYLOAD_LARGE_INPUT_SNIPPET,R as STUB_TARGETS,w as containsSelectedPayloadBoundary,L as findPackageRoot,I as patchVersionInFile,B as refreshStubs};

package/packages/client/dist/cache/encrypted-cache.d.ts

@@ -10,7 +10,7 @@
  *
  * See the LICENSE file in the project root for full license text.
  */
-import type { CacheProvider } from '../types/index.js';
+import type { CacheOperationOptions, CacheProvider } from '../types/index.js';
 export interface EncryptedCacheOptions {
     /** Directory where encrypted cache files are stored */
     cacheDir: string;
@@ -22,9 +22,15 @@ export declare class EncryptedCache implements CacheProvider {
     private readonly passphrase;
     private initPromise;
     constructor(options: EncryptedCacheOptions);
-    get(key: string): Promise<string | null>;
-    set(key: string, value: string, ttlMs?: number): Promise<void>;
-    clear(): Promise<void>;
+    get(key: string, options?: CacheOperationOptions): Promise<string | null>;
+    set(key: string, value: string, ttlMs?: number, options?: CacheOperationOptions): Promise<void>;
+    compareAndSet(key: string, expectedValue: string | null, value: string, ttlMs?: number, options?: CacheOperationOptions): Promise<boolean>;
+    private setUnlocked;
+    clear(options?: CacheOperationOptions): Promise<void>;
     private keyToPath;
+    private withKeyLock;
+    private withFileLock;
+    private waitForLockRetry;
     private ensureDir;
+    private secureFile;
 }

package/packages/client/dist/cache/encrypted-cache.js

@@ -1 +1 @@
-import{mkdir as n,writeFile as o,readFile as p,rm as s,readdir as m}from"node:fs/promises";import{join as a}from"node:path";import{createHash as u}from"node:crypto";import{encrypt as l,decrypt as f}from"./crypto-utils.js";import{setSecureFilePermissions as d}from"../config/secure-config.js";import{hasProtectedCachePayloadMarker as y}from"./protected-pi-boundary.js";const c=".enc";class F{cacheDir;passphrase;initPromise=null;constructor(t){this.cacheDir=t.cacheDir,this.passphrase=t.passphrase}async get(t){try{const r=this.keyToPath(t),e=await p(r,"utf8"),i=f(e,this.passphrase);return i.expired?(s(r,{force:!0}).catch(()=>{}),null):i.plaintext}catch{return null}}async set(t,r,e){try{if(y(r))return;await this.ensureDir();const i=this.keyToPath(t),h=l(r,this.passphrase,e);await o(i,h,"utf8"),d(i)}catch{}}async clear(){try{const r=(await m(this.cacheDir).catch(()=>[])).filter(e=>e.endsWith(c)).map(e=>s(a(this.cacheDir,e),{force:!0}).catch(()=>{}));await Promise.all(r)}catch{}}keyToPath(t){const r=u("sha256").update(t).digest("hex");return a(this.cacheDir,`${r}${c}`)}ensureDir(){return this.initPromise||(this.initPromise=n(this.cacheDir,{recursive:!0}).then(()=>{}).catch(t=>{throw this.initPromise=null,t})),this.initPromise}}export{F as EncryptedCache};
+import{chmod as d,mkdir as P,open as x,writeFile as b,readFile as w,rename as D,rm as l,readdir as T}from"node:fs/promises";import{join as m}from"node:path";import{createHash as F,randomUUID as E}from"node:crypto";import{encrypt as L,decrypt as _}from"./crypto-utils.js";import{setSecureDirPermissions as S,setSecureFilePermissions as y}from"../config/secure-config.js";import{isPublicSafePersistentCacheEntry as g}from"./protected-pi-boundary.js";const M=".enc",o=3600*1e3,f=24*o,u=7*f,k=10,I=2e3;function U(c){return c==="neocortex:auth:generation"?{defaultMs:u,maxMs:u}:c==="neocortex:jwt:refresh_token"?{defaultMs:u,maxMs:u}:c==="neocortex:jwt:token"?{defaultMs:o,maxMs:f}:c==="neocortex:menu:cache"?{defaultMs:f,maxMs:f}:c==="neocortex:tier"?{defaultMs:o,maxMs:o}:c.startsWith("neocortex:quota:")?{defaultMs:300*1e3,maxMs:300*1e3}:{defaultMs:o,maxMs:o}}class N{cacheDir;passphrase;initPromise=null;constructor(t){this.cacheDir=t.cacheDir,this.passphrase=t.passphrase}async get(t,a){try{if(a?.signal?.aborted)return null;const i=this.keyToPath(t);if(await this.secureFile(i),a?.signal?.aborted)return null;const e=await w(i,{encoding:"utf8",signal:a?.signal});if(a?.signal?.aborted)return null;const r=_(e,this.passphrase);return r.expired?(l(i,{force:!0}).catch(()=>{}),null):g(t,r.plaintext)?r.plaintext:(await l(i,{force:!0}).catch(()=>{}),null)}catch{return null}}async set(t,a,i,e){await this.withKeyLock(t,e?.signal,async()=>{await this.setUnlocked(t,a,i,e)})}async compareAndSet(t,a,i,e,r){return await this.withKeyLock(t,r?.signal,async()=>{const n=await this.get(t,r);return r?.signal?.aborted||n!==a?!1:this.setUnlocked(t,i,e,r)})??!1}async setUnlocked(t,a,i,e){let r=null;try{if(e?.signal?.aborted||!g(t,a))return!1;const s=U(t),n=i??s.defaultMs;if(!Number.isFinite(n)||n<=0||n>s.maxMs||n>u||(await this.ensureDir(),e?.signal?.aborted))return!1;const h=this.keyToPath(t);r=`${h}.${process.pid}.${E()}.tmp`;const p=L(a,this.passphrase,n);return e?.signal?.aborted||(await b(r,p,{encoding:"utf8",mode:384,flag:"w",signal:e?.signal}),e?.signal?.aborted)||(await this.secureFile(r),e?.signal?.aborted)?!1:(await D(r,h),r=null,await this.secureFile(h),y(h),!0)}catch{return!1}finally{r&&await l(r,{force:!0}).catch(()=>{})}}async clear(t){try{if(t?.signal?.aborted)return;const a=await T(this.cacheDir).catch(()=>[]),i=await Promise.all(a.filter(e=>e.endsWith(M)).map(async e=>{const r=m(this.cacheDir,e),s=await w(r,"utf8").catch(()=>null);return{filePath:r,raw:s}}));for(const{filePath:e,raw:r}of i){if(t?.signal?.aborted)return;r!==null&&await this.withFileLock(e,t?.signal,async()=>{const s=await w(e,"utf8").catch(()=>null);!t?.signal?.aborted&&s===r&&await l(e,{force:!0}).catch(()=>{})})}}catch{}}keyToPath(t){const a=F("sha256").update(t).digest("hex");return m(this.cacheDir,`${a}${M}`)}async withKeyLock(t,a,i){return await this.ensureDir().catch(()=>{}),this.withFileLock(this.keyToPath(t),a,i)}async withFileLock(t,a,i){const e=`${t}.lock`;let r=null;const s=Date.now()+I;for(;!a?.aborted&&Date.now()<s;)try{r=await x(e,"wx",384);break}catch(n){if(n.code!=="EEXIST")return null;await this.waitForLockRetry(a)}if(!r||a?.aborted)return await r?.close().catch(()=>{}),r&&await l(e,{force:!0}).catch(()=>{}),null;try{return await i()}finally{await r.close().catch(()=>{}),await l(e,{force:!0}).catch(()=>{})}}async waitForLockRetry(t){await new Promise(a=>{let i;const e=()=>{i&&clearTimeout(i),t?.removeEventListener("abort",e),a()};i=setTimeout(e,k),t?.addEventListener("abort",e,{once:!0})})}ensureDir(){return this.initPromise||(this.initPromise=P(this.cacheDir,{recursive:!0,mode:448}).then(async()=>{process.platform==="win32"?S(this.cacheDir):await d(this.cacheDir,448)}).catch(t=>{throw this.initPromise=null,t})),this.initPromise}async secureFile(t){if(process.platform==="win32"){y(t);return}await d(t,384)}}export{N as EncryptedCache};

package/packages/client/dist/cache/in-memory-asset-cache.d.ts

@@ -31,7 +31,7 @@
  *    rejected so tests cannot turn it into a public distribution path. Exact
  *    production asset TTL policy beyond the default remains [TBD].
  */
-import type { CacheProvider } from '../types/index.js';
+import type { CacheOperationOptions, CacheProvider } from '../types/index.js';
 export interface InMemoryAssetCacheOptions {
     /** Maximum number of entries before eviction (default: 50) */
     readonly maxSize?: number;
@@ -47,16 +47,17 @@ export declare class InMemoryAssetCache implements CacheProvider {
      * Retrieve a value by key. Returns null if missing or expired.
      * Accessing a key moves it to the end of the LRU ordering.
      */
-    get(key: string): Promise<string | null>;
+    get(key: string, options?: CacheOperationOptions): Promise<string | null>;
     /**
      * Store a value by key. Evicts the least-recently-used entry if the
      * cache is at capacity.
      *
      * @param ttlMs - optional override of the default TTL
      */
-    set(key: string, value: string, ttlMs?: number): Promise<void>;
+    set(key: string, value: string, ttlMs?: number, options?: CacheOperationOptions): Promise<void>;
+    compareAndSet(key: string, expectedValue: string | null, value: string, ttlMs?: number, options?: CacheOperationOptions): Promise<boolean>;
     /** Drop all entries. Safe to call at any time. */
-    clear(): Promise<void>;
+    clear(options?: CacheOperationOptions): Promise<void>;
     /** Internal: number of live entries (for diagnostics / tests). */
     size(): number;
 }

package/packages/client/dist/cache/in-memory-asset-cache.js

@@ -1 +1 @@
-import{hasProtectedCachePayloadMarker as n}from"./protected-pi-boundary.js";const a=50,h=300*1e3;class u{store=new Map;maxSize;ttlMs;constructor(t={}){this.maxSize=t.maxSize??a,this.ttlMs=t.ttlMs??h}async get(t){const e=this.store.get(t);return e?Date.now()>=e.expiresAt?(this.store.delete(t),null):(this.store.delete(t),this.store.set(t,e),e.value):null}async set(t,e,r){if(n(e))return;const i=r??this.ttlMs,o=Date.now()+i;if(this.store.has(t))this.store.delete(t);else if(this.store.size>=this.maxSize){const s=this.store.keys().next().value;s!==void 0&&this.store.delete(s)}this.store.set(t,{value:e,expiresAt:o})}async clear(){this.store.clear()}size(){return this.store.size}}export{u as InMemoryAssetCache};
+import{hasProtectedCachePayloadMarker as u}from"./protected-pi-boundary.js";const o=50,l=300*1e3,h=64*1024,c=300*1e3,f=100;class g{store=new Map;maxSize;ttlMs;constructor(t={}){const s=t.maxSize??o,e=t.ttlMs??l;this.maxSize=Number.isInteger(s)&&s>0?Math.min(s,f):o,this.ttlMs=Number.isFinite(e)&&e>0?Math.min(e,c):l}async get(t,s){if(s?.signal?.aborted)return null;const e=this.store.get(t);return e?Date.now()>=e.expiresAt?(this.store.delete(t),null):(this.store.delete(t),this.store.set(t,e),e.value):null}async set(t,s,e,i){if(i?.signal?.aborted||u(s))return;const r=e??this.ttlMs;if(typeof t!="string"||t.length===0||t.length>128||Buffer.byteLength(s,"utf8")>h||!Number.isFinite(r)||r<=0||r>c)return;const n=Date.now()+r;if(this.store.has(t))this.store.delete(t);else if(this.store.size>=this.maxSize){const a=this.store.keys().next().value;a!==void 0&&this.store.delete(a)}this.store.set(t,{value:s,expiresAt:n})}async compareAndSet(t,s,e,i,r){if(r?.signal?.aborted)return!1;const n=this.store.get(t);return(n&&Date.now()<n.expiresAt?n.value:null)!==s?!1:(await this.set(t,e,i,r),!r?.signal?.aborted)}async clear(t){t?.signal?.aborted||this.store.clear()}size(){return this.store.size}}export{g as InMemoryAssetCache};

package/packages/client/dist/cache/protected-pi-boundary.d.ts

@@ -6,6 +6,10 @@
  */
 /** Public reason code used when a synthetic protected PI marker is detected. */
 export declare const PROTECTED_CACHE_PAYLOAD_REASON = "protected-cache-payload-rejected";
+export declare const CACHE_SCHEMA_REJECTION_REASON = "client-cache-schema-rejected";
+/** Validate a value against its explicitly allowlisted persistent destination. */
+export declare function isPublicSafePersistentCacheEntry(key: string, value: string): boolean;
+export declare function assertPublicSafePersistentCacheEntry(key: string, value: string): void;
 /**
  * Returns true only for synthetic protected markers or explicit protected field
  * names. Generic words like "prompt" or "workflow" are intentionally not
@@ -13,7 +17,7 @@ export declare const PROTECTED_CACHE_PAYLOAD_REASON = "protected-cache-payload-r
  */
 export declare function hasProtectedCachePayloadMarker(value: string): boolean;
 export declare class ProtectedCachePayloadError extends Error {
-    readonly code = "protected-cache-payload-rejected";
-    constructor();
+    readonly code: string;
+    constructor(code?: string);
 }
 export declare function assertPublicSafeCachePayload(value: string): void;

package/packages/client/dist/cache/protected-pi-boundary.js

@@ -1 +1 @@
-const t="protected-cache-payload-rejected",a=/P176_SYNTHETIC_PROTECTED_(?:PROMPT|PROMPT_BODY|WORKFLOW|WORKFLOW_GRAPH|STEP_BODY|RAW_LOG|PRIVATE_URL|SECRET|PROPRIETARY_ASSET)/i,n=/^(?:promptBody|workflowBody|workflowGraph|stepBody|privateUrl|rawLog|secret|credential|licenseKey|apiKey|internalRouting|serverOnly|proprietary|protected)$/i;function r(e){return!e||typeof e!="object"?!1:Array.isArray(e)?e.some(r):Object.entries(e).some(([o,c])=>n.test(o)||r(c))}function s(e){if(a.test(e))return!0;try{return r(JSON.parse(e))}catch{return!1}}class E extends Error{code=t;constructor(){super(t),this.name="ProtectedCachePayloadError"}}function P(e){if(s(e))throw new E}export{t as PROTECTED_CACHE_PAYLOAD_REASON,E as ProtectedCachePayloadError,P as assertPublicSafeCachePayload,s as hasProtectedCachePayloadMarker};
+const l="protected-cache-payload-rejected",_="client-cache-schema-rejected",f=/P176_SYNTHETIC_PROTECTED_(?:PROMPT|PROMPT_BODY|WORKFLOW|WORKFLOW_GRAPH|STEP_BODY|RAW_LOG|PRIVATE_URL|SECRET|PROPRIETARY_ASSET)/i,u=new Set(["apikey","authorization","cookie","credential","email","internalrouting","ipaddress","licensekey","password","privateurl","promptbody","proprietary","protected","rawlog","requestbody","secret","serveronly","stepbody","tokenpayload","workflowbody","workflowgraph"]),m=64*1024,P=6,g=256,p=/^[A-Za-z0-9_-]{1,4096}\.[A-Za-z0-9_-]{1,8192}\.[A-Za-z0-9_-]{1,4096}$/,d=/^[A-Za-z0-9._-]{0,8192}$/;function h(t){return t.replace(/[^a-z0-9]/gi,"").toLowerCase()}function o(t){return!t||typeof t!="object"?!1:Array.isArray(t)?t.some(o):Object.entries(t).some(([e,r])=>u.has(h(e))||o(r))}function s(t,e=0,r={remaining:g}){if(r.remaining--<=0||e>P)return!1;if(t===null||typeof t=="boolean")return!0;if(typeof t=="number")return Number.isFinite(t);if(typeof t=="string")return Buffer.byteLength(t,"utf8")<=2048&&!f.test(t);if(!t||typeof t!="object")return!1;if(Array.isArray(t))return t.length<=64&&t.every(n=>s(n,e+1,r));try{const n=Object.entries(t);return n.length>64?!1:n.every(([c,E])=>/^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/.test(c)&&!u.has(h(c))&&s(E,e+1,r))}catch{return!1}}function T(t){return t==="neocortex:auth:generation"?"auth":t==="neocortex:jwt:token"?"jwt":t==="neocortex:jwt:refresh_token"?"refresh":t==="neocortex:tier"?"tier":/^neocortex:quota:\d{4}-\d{2}-\d{2}$/.test(t)?"quota":t==="neocortex:menu:cache"?"menu":t==="registry"?"registry":null}function i(t){try{const e=JSON.parse(t);return e&&typeof e=="object"&&!Array.isArray(e)?e:null}catch{return null}}function a(t,e){const r=new Set(e);return Object.keys(t).every(n=>r.has(n))}function R(t){const e=i(t);return!e||!a(e,["stepsRemaining","invocationsRemaining","stepsLimit","invocationsLimit","cachedAt"])?!1:["stepsRemaining","invocationsRemaining","stepsLimit","invocationsLimit","cachedAt"].every(r=>typeof e[r]=="number"&&Number.isFinite(e[r]))}function O(t){const e=i(t);return!e||!a(e,["instructions","metadata","cachedAt","version"])||typeof e.instructions!="string"||Buffer.byteLength(e.instructions,"utf8")>32*1024||typeof e.cachedAt!="number"||!Number.isFinite(e.cachedAt)||e.version!==void 0&&(typeof e.version!="string"||e.version.length>64)?!1:s(e.metadata)}function b(t){const e=i(t);return!e||!a(e,["schema","generation","jwt","refresh","expiresAt"])?!1:e.schema===1&&typeof e.generation=="string"&&/^[A-Za-z0-9-]{16,64}$/.test(e.generation)&&typeof e.jwt=="string"&&p.test(e.jwt)&&(e.refresh===null||typeof e.refresh=="string"&&d.test(e.refresh))&&typeof e.expiresAt=="number"&&Number.isFinite(e.expiresAt)}function C(t,e){if(typeof t!="string"||typeof e!="string"||Buffer.byteLength(e,"utf8")>m||A(e))return!1;switch(T(t)){case"auth":return b(e);case"jwt":return p.test(e);case"refresh":return d.test(e);case"tier":return e==="free"||e==="pro"||e==="enterprise";case"quota":return R(e);case"menu":return O(e);case"registry":{const r=i(e);return r!==null&&s(r)}default:return!1}}function S(t,e){if(!C(t,e))throw new y(_)}function A(t){if(f.test(t))return!0;try{return o(JSON.parse(t))}catch{return!1}}class y extends Error{code;constructor(e=l){super(e),this.name="ProtectedCachePayloadError",this.code=e}}function w(t){if(A(t))throw new y}export{_ as CACHE_SCHEMA_REJECTION_REASON,l as PROTECTED_CACHE_PAYLOAD_REASON,y as ProtectedCachePayloadError,w as assertPublicSafeCachePayload,S as assertPublicSafePersistentCacheEntry,A as hasProtectedCachePayloadMarker,C as isPublicSafePersistentCacheEntry};

package/packages/client/dist/checkpoint/checkpoint-client-reader.d.ts

@@ -1,45 +1,46 @@
 /**
- * Epic P109.05: Checkpoint client-side reader (fail-soft).
+ * Durable client-side checkpoint claim protocol.
  *
- * Reads `.neocortex/checkpoint-pending.json` (written by agent per P109.04
- * step prompt instructions), validates shape against ImplementCheckpointSnapshot
- * (P109.02), and consumes (deletes) the file to prevent re-send.
- *
- * Cross-refs: P107.02 (architecture-policy reader pattern), P101.06 (atomic
- * file ops), P63.01 (UTF-8 BOM strip), P103.06 (CRLF normalize).
+ * A pending checkpoint is atomically renamed to an owner/lease claim. The
+ * caller must explicitly ack after a server persistence acknowledgement or
+ * release it for retry. Expired claims are recovered only after their local
+ * process owner is no longer alive.
  */
 import type { ImplementCheckpointSnapshot } from './shared-checkpoint-types.js';
-/**
- * Canonical pending-checkpoint path (relative to projectRoot).
- * Matches P109.04 step prompt instruction literal.
- */
 export declare const CHECKPOINT_PENDING_PATH = ".neocortex/checkpoint-pending.json";
+export declare const CHECKPOINT_ACK_HEADER = "x-neocortex-checkpoint-ack";
+export declare const CHECKPOINT_CLAIM_LEASE_MS = 60000;
 export interface ValidationResult {
     readonly valid: boolean;
     readonly errors: readonly string[];
 }
+export interface ClaimedCheckpointSnapshot extends ImplementCheckpointSnapshot {
+    readonly deliveryId: string;
+}
+export interface CheckpointClaim {
+    readonly snapshot: ClaimedCheckpointSnapshot;
+    readonly deliveryId: string;
+    readonly leaseExpiresAt: number;
+    readonly ack: () => Promise<void>;
+    readonly release: () => Promise<void>;
+}
+export interface ClaimCheckpointOptions {
+    readonly leaseMs?: number;
+    readonly now?: () => number;
+    readonly ownerPid?: number;
+    readonly ownerToken?: string;
+    readonly isOwnerAlive?: (pid: number) => boolean;
+}
+export declare function validateSnapshot(candidate: unknown): ValidationResult;
 /**
- * Pure validation (zero I/O). Deterministic.
+ * Atomically claim one pending/released checkpoint.
  *
- * Checks all required fields of ImplementCheckpointSnapshot shape. Extra fields
- * are ignored (forward-compat). Does NOT enforce MAX_SNAPSHOT_SIZE_BYTES on
- * snapshotMd length -- that is the reader's responsibility and server's
- * final truncation (P109.06).
+ * No valid checkpoint is permanently deleted here. The returned owner-bound
+ * handle is the only API that can ack or release this claim.
  */
-export declare function validateSnapshot(candidate: unknown): ValidationResult;
+export declare function claimCheckpoint(projectRoot: string, options?: ClaimCheckpointOptions): Promise<CheckpointClaim | undefined>;
 /**
- * Read + validate + consume (delete) the pending checkpoint file.
- *
- * Fail-soft contract:
- * - ENOENT (common case -- no checkpoint pending) -> undefined, silent.
- * - Any other read error -> undefined + console.warn.
- * - Malformed JSON or schema invalid -> undefined + console.warn.
- * - Oversized file -> undefined + console.warn.
- * - Unlink failure -> caller still receives snapshot; warn logged.
- *
- * **File consume is critical (AC4)**: after first successful read (regardless
- * of validation outcome), the file is deleted to prevent re-send on next
- * invoke. This avoids infinite checkpoint-loop scenarios from malformed
- * agent-produced content.
+ * Legacy explicit consume helper. Invoke uses claimCheckpoint directly and
+ * never calls this before receiving the durable server acknowledgement.
  */
 export declare function readAndConsumeCheckpoint(projectRoot: string): Promise<ImplementCheckpointSnapshot | undefined>;

package/packages/client/dist/checkpoint/checkpoint-client-reader.js

@@ -1,2 +1,2 @@
-import{promises as c}from"node:fs";import f from"node:path";import{MAX_SNAPSHOT_SIZE_BYTES as d}from"./shared-checkpoint-types.js";const u=".neocortex/checkpoint-pending.json",p=1e4,a=["FASE_1","FASE_2","FASE_3","FASE_4"];function l(o){if(o===null||typeof o!="object")return{valid:!1,errors:["payload must be object"]};const e=o,t=[];return(typeof e.storyId!="string"||e.storyId.length===0)&&t.push("storyId must be non-empty string"),(typeof e.turn!="number"||!Number.isFinite(e.turn)||e.turn<0)&&t.push("turn must be non-negative finite number"),(!Array.isArray(e.filesModified)||!e.filesModified.every(n=>typeof n=="string"))&&t.push("filesModified must be string[]"),(!Array.isArray(e.testsModified)||!e.testsModified.every(n=>typeof n=="string"))&&t.push("testsModified must be string[]"),(typeof e.currentPhase!="string"||!a.includes(e.currentPhase))&&t.push(`currentPhase must be one of ${a.join("|")}`),typeof e.snapshotMd!="string"&&t.push("snapshotMd must be string"),{valid:t.length===0,errors:Object.freeze(t)}}async function y(o){const e=f.join(o,u);let t;try{t=await c.readFile(e,"utf-8")}catch(r){if(r.code==="ENOENT")return;console.warn(`[Neocortex] checkpoint read failed: ${r instanceof Error?r.message:String(r)}`);return}c.unlink(e).catch(r=>{console.warn(`[Neocortex] checkpoint unlink failed: ${r instanceof Error?r.message:String(r)}`)});const n=t.replace(/^/,"").replace(/\r\n/g,`
-`);if(n.length>d+p){console.warn(`[Neocortex] checkpoint oversized (${n.length} bytes), skipping`);return}let s;try{s=JSON.parse(n)}catch(r){console.warn(`[Neocortex] checkpoint malformed JSON: ${r instanceof Error?r.message:String(r)}`);return}const i=l(s);if(!i.valid){console.warn(`[Neocortex] checkpoint schema invalid: ${i.errors.join("; ")}`);return}return s}export{u as CHECKPOINT_PENDING_PATH,y as readAndConsumeCheckpoint,l as validateSnapshot};
+import{createHash as x,randomUUID as S}from"node:crypto";import{promises as f}from"node:fs";import s from"node:path";import{MAX_SNAPSHOT_SIZE_BYTES as j}from"./shared-checkpoint-types.js";const F=".neocortex/checkpoint-pending.json",Y="x-neocortex-checkpoint-ack",D=6e4,L=1e4,R=1440*6e4,O=["FASE_1","FASE_2","FASE_3","FASE_4"],q=/\.claim-v1-(\d+)-(\d+)-([a-f0-9-]+)$/;function H(t){if(t===null||typeof t!="object")return{valid:!1,errors:["payload must be object"]};const e=t,n=[];return(typeof e.storyId!="string"||e.storyId.length===0)&&n.push("storyId must be non-empty string"),(!Number.isSafeInteger(e.turn)||Number(e.turn)<0||Number(e.turn)>2147483647)&&n.push("turn must be non-negative safe integer within storage bounds"),(!Array.isArray(e.filesModified)||!e.filesModified.every(r=>typeof r=="string"))&&n.push("filesModified must be string[]"),(!Array.isArray(e.testsModified)||!e.testsModified.every(r=>typeof r=="string"))&&n.push("testsModified must be string[]"),(typeof e.currentPhase!="string"||!O.includes(e.currentPhase))&&n.push(`currentPhase must be one of ${O.join("|")}`),typeof e.snapshotMd!="string"&&n.push("snapshotMd must be string"),{valid:n.length===0,errors:Object.freeze(n)}}function B(t){const e=JSON.stringify({storyId:t.storyId,turn:t.turn,filesModified:t.filesModified,testsModified:t.testsModified,currentPhase:t.currentPhase,snapshotMd:t.snapshotMd});return`ckpt-${x("sha256").update(e).digest("hex")}`}function U(t){if(!Number.isSafeInteger(t)||t<=0)return!1;try{return process.kill(t,0),!0}catch(e){return e.code==="EPERM"}}function d(t,e){const n=e===void 0?"":`: ${e instanceof Error?e.message:String(e)}`;console.warn(`[Neocortex] ${t}${n}`)}async function A(t,e){for(const n of t){try{await f.rename(n,e)}catch(r){if(r.code!=="ENOENT"){d("checkpoint claim failed",r);return}continue}try{await E(s.dirname(e))}catch(r){d("checkpoint claim directory sync failed",r)}return e}}async function E(t){let e;try{e=await f.open(t,"r"),await e.sync()}catch(n){const r=n.code;if(!["EINVAL","ENOTSUP","EISDIR","EPERM"].includes(r??""))throw n}finally{await e?.close().catch(()=>{})}}async function z(t,e,n,r){const u=await A([t],e);if(u)return u;let l;try{l=await f.readdir(s.dirname(t))}catch(a){a.code!=="ENOENT"&&d("checkpoint queue scan failed",a);return}const p=s.basename(t),c=l.filter(a=>a.startsWith(`${p}.released-`)).sort().map(a=>s.join(s.dirname(t),a)),m=await A(c,e);if(m)return m;const o=l.map(a=>({entry:a,match:a.match(q)})).filter(({entry:a,match:h})=>{if(!a.startsWith(`${p}.claim-v1-`)||!h)return!1;const w=Number(h[1]),N=Number(h[2]);return Number.isSafeInteger(w)&&w<=n&&!r(N)}).map(({entry:a})=>s.join(s.dirname(t),a));return A(o,e)}async function _(t,e){const n=`${e}.rejected-${Date.now()}-${S()}`;try{await f.rename(t,n),await E(s.dirname(t))}catch(r){r.code!=="ENOENT"&&d("checkpoint quarantine failed",r)}}async function K(t,e={}){const n=e.now??Date.now,r=n(),u=e.leaseMs??D;if(!Number.isSafeInteger(u)||u<=0||u>R)throw new RangeError("checkpoint claim lease is outside the supported bound");const l=e.ownerPid??process.pid;if(!Number.isSafeInteger(l)||l<=0)throw new RangeError("checkpoint claim owner pid is invalid");const p=e.ownerToken??S();if(!/^[a-f0-9-]{8,64}$/i.test(p))throw new RangeError("checkpoint claim owner token is invalid");const c=s.join(t,F),m=r+u;if(!Number.isSafeInteger(r)||!Number.isSafeInteger(m))throw new RangeError("checkpoint claim time is outside the supported bound");const o=`${c}.claim-v1-${m}-${l}-${p.toLowerCase()}`;if(!await z(c,o,r,e.isOwnerAlive??U))return;let h;try{h=await f.readFile(o,"utf8")}catch(i){d("checkpoint read failed",i);try{await f.rename(o,`${c}.released-${r}-${S()}`),await E(s.dirname(o))}catch(k){k.code!=="ENOENT"&&d("checkpoint read recovery failed",k)}return}const w=h.replace(/^/,"").replace(/\r\n/g,`
+`),N=Buffer.byteLength(w,"utf8");if(N>j+L){d(`checkpoint oversized (${N} bytes), quarantining`),await _(o,c);return}let g;try{g=JSON.parse(w)}catch(i){d("checkpoint malformed JSON",i),await _(o,c);return}const M=H(g);if(!M.valid){d(`checkpoint schema invalid: ${M.errors.join("; ")}`),await _(o,c);return}const $=g,v=B($),P={...$,deliveryId:v};let I="claimed",b,y;const C=(i,k)=>I===i?Promise.resolve():I!=="claimed"||b&&b!==i?Promise.reject(new Error(i==="acked"?"checkpoint claim was already released":"checkpoint claim was already acknowledged")):y||(b=i,y=k().then(()=>{I=i}).catch(T=>{throw b=void 0,y=void 0,T}),y);return{snapshot:P,deliveryId:v,leaseExpiresAt:m,ack:()=>C("acked",async()=>{await f.unlink(o).catch(i=>{if(i.code!=="ENOENT")throw i}),await E(s.dirname(o))}),release:()=>C("released",async()=>{await f.rename(o,`${c}.released-${n()}-${S()}`).catch(i=>{if(i.code!=="ENOENT")throw i}),await E(s.dirname(o))})}}async function Z(t){const e=await K(t);if(e)return await e.ack(),e.snapshot}export{Y as CHECKPOINT_ACK_HEADER,D as CHECKPOINT_CLAIM_LEASE_MS,F as CHECKPOINT_PENDING_PATH,K as claimCheckpoint,Z as readAndConsumeCheckpoint,H as validateSnapshot};

package/packages/client/dist/checkpoint/shared-checkpoint-types.d.ts

@@ -57,6 +57,8 @@ export interface ImplementCheckpoint {
  * Omits id, licenseId, createdAt, updatedAt (server-set, never trust client).
  */
 export interface ImplementCheckpointSnapshot {
+    /** Stable, content-derived idempotency key assigned by the client claim. */
+    readonly deliveryId?: string;
     readonly storyId: string;
     readonly turn: number;
     readonly filesModified: readonly string[];

package/packages/client/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import{readFileSync as d}from"node:fs";import{fileURLToPath as u}from"node:url";import{dirname as l,join as m}from"node:path";function h(){try{const r=u(import.meta.url);let e=l(r);for(let s=0;s<5;s++){try{const t=JSON.parse(d(m(e,"package.json"),"utf-8"));if(t.name==="@ornexus/neocortex"||t.name==="@neocortex/client")return t.version??"0.0.0"}catch{}e=l(e)}}catch{}return"0.0.0"}const p=`
+import{readFileSync as p}from"node:fs";import{fileURLToPath as d}from"node:url";import{dirname as c,join as u}from"node:path";function m(){try{const e=d(import.meta.url);let r=c(e);for(let s=0;s<5;s++){try{const t=JSON.parse(p(u(r,"package.json"),"utf-8"));if(t.name==="@ornexus/neocortex"||t.name==="@neocortex/client")return t.version??"0.0.0"}catch{}r=c(r)}}catch{}return"0.0.0"}const l=`
 neocortex-client - Neocortex Client CLI
 
 Usage:
@@ -77,5 +77,5 @@ Invocation payload boundary:
 
 License:
   Licensed under BSL-1.1 (Business Source License 1.1)
-`.trim(),g=new Set(["pm","install","postinstall","preinstall","prepublish","postpublish","preuninstall","postuninstall","preprepare","prepare","postprepare"]);async function v(){const r=process.argv.slice(2),e=r[0];e&&g.has(e.toLowerCase())&&process.exit(0),(!e||e==="--help"||e==="-h")&&(console.log(p),process.exit(0)),(e==="--version"||e==="-v")&&(console.log(h()),process.stderr.write(`Licensed under BSL-1.1 (Business Source License 1.1)
-`),process.exit(0));const s=r.slice(1);switch(e){case"invoke":{const{invokeCliHandler:t}=await import("./commands/invoke.js"),a=await t(s);process.exit(a);break}case"activate":{const{activate:t}=await import("./commands/activate.js");let a,i,c=!1;for(let o=0;o<s.length;o++){const n=s[o];n==="--server-url"?i=s[++o]:n==="--non-interactive"?c=!0:n==="--help"||n==="-h"?(console.log(p),process.exit(0)):n.startsWith("-")||(a=n)}a||(console.error("Error: License key is required."),console.error("Usage: neocortex-client activate <license-key>"),console.error("Example: neocortex-client activate NX-PRO-ABC-123"),process.exit(1));try{const o=await t({licenseKey:a,serverUrl:i,nonInteractive:c});o.success?(console.log(o.message),process.exit(0)):(console.error(o.message),process.exit(1))}catch(o){const n=o instanceof Error?o.message:String(o);console.error(`Activation failed: ${n}`),process.exit(1)}break}case"cache-status":{console.log("Cache status requires an active client session."),console.log("Use this command within a running Neocortex client context."),process.exit(0);break}case"refresh-memory":{const{refreshMemoryCliHandler:t}=await import("./commands/refresh-memory.js"),a=await t(s);process.exit(a);break}case"update":{console.log("To update Neocortex, run:"),console.log("  neocortex update"),console.log(""),console.log("Or manually:"),console.log("  npm install -g @ornexus/neocortex@latest"),process.exit(0);break}default:console.error(`Unknown command: ${e}`),console.error('Run "neocortex-client --help" for usage information.'),process.exit(1)}}v().catch(r=>{console.error(`Fatal error: ${r instanceof Error?r.message:String(r)}`),process.exit(1)});
+`.trim(),h=new Set(["pm","install","postinstall","preinstall","prepublish","postpublish","preuninstall","postuninstall","preprepare","prepare","postprepare"]);async function g(){const[e,...r]=process.argv.slice(2);switch(e&&h.has(e.toLowerCase())&&process.exit(0),(!e||e==="--help"||e==="-h")&&(console.log(l),process.exit(0)),(e==="--version"||e==="-v")&&(console.log(m()),process.stderr.write(`Licensed under BSL-1.1 (Business Source License 1.1)
+`),process.exit(0)),e){case"invoke":{const{invokeCliHandler:s}=await import("./commands/invoke.js"),t=await s(r);process.exit(t);break}case"activate":{const{activate:s}=await import("./commands/activate.js");let t,a,i=!1;for(let o=0;o<r.length;o++){const n=r[o];n==="--server-url"?a=r[++o]:n==="--non-interactive"?i=!0:n==="--help"||n==="-h"?(console.log(l),process.exit(0)):n.startsWith("-")||(t=n)}t||(console.error("Error: License key is required."),console.error("Usage: neocortex-client activate <license-key>"),console.error("Example: neocortex-client activate NX-PRO-ABC-123"),process.exit(1));try{const o=await s({licenseKey:t,serverUrl:a,nonInteractive:i});o.success?(console.log(o.message),process.exit(0)):(console.error(o.message),process.exit(1))}catch(o){const n=o instanceof Error?o.message:String(o);console.error(`Activation failed: ${n}`),process.exit(1)}break}case"cache-status":{console.log("Cache status requires an active client session."),console.log("Use this command within a running Neocortex client context."),process.exit(0);break}case"refresh-memory":{const{refreshMemoryCliHandler:s}=await import("./commands/refresh-memory.js"),t=await s(r);process.exit(t);break}case"update":{console.log("To update Neocortex, run:"),console.log("  neocortex update"),console.log(""),console.log("Or manually:"),console.log("  npm install -g @ornexus/neocortex@latest"),process.exit(0);break}default:console.error(`Unknown command: ${e}`),console.error('Run "neocortex-client --help" for usage information.'),process.exit(1)}}g().catch(e=>{console.error(`Fatal error: ${e instanceof Error?e.message:String(e)}`),process.exit(1)});