@ornexus/neocortex 4.59.1

package/packages/client/dist/agent/update-description.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * Build the banner version line with correct padding.
+ */
+export declare function buildBannerVersionLine(version: string): string;
+/**
+ * Build the banner tier line with correct padding.
+ */
+export declare function buildBannerTierLine(tier: string): string;
+/**
+ * Build the dynamic description string (without quotes/prefix).
+ */
+export declare function buildDescription(version: string, tier: string): string;
+/**
+ * Read the current tier from ~/.neocortex/config.json.
+ * Returns 'free' if config doesn't exist or tier is missing.
+ */
+export declare function readTierFromConfig(): string;
+/**
+ * Update agent descriptions across ALL known platform files:
+ *   1. Home-level files (Claude Code, Gemini CLI)
+ *   2. Project-level files (Cursor, VSCode, Codex, Antigravity) -- discovered via git root
+ *
+ * Never throws -- description update is non-critical.
+ * Returns count of files updated.
+ */
+export declare function updateAgentDescription(version: string, tier?: string): number;
+/**
+ * Update agent description for a specific file path (used by install scripts
+ * for project-level files where paths are dynamic).
+ *
+ * Never throws -- description update is non-critical.
+ */
+export declare function updateAgentDescriptionAt(filePath: string, type: 'yaml' | 'h1', version: string, tier?: string): boolean;

package/packages/client/dist/agent/update-description.js

@@ -0,0 +1 @@
+import{readFileSync as l,writeFileSync as _,existsSync as f}from"node:fs";import{execSync as A}from"node:child_process";import{join as c}from"node:path";import{homedir as p}from"node:os";const m=c(p(),".neocortex","config.json"),d={free:"Free",pro:"Pro",enterprise:"Enterprise"},I=60,L=25,N=/^description:\s*".*"$/m,E=/^# 🧠 Neocortex v[\d.]+(?:\s*\([^)]+\)\s*\| OrNexus Team|\s*-\s*Development Orchestrator \| OrNexus Team \([^)]+\))$/m,T=/^│      ###  ########      v[\d.]+\s*│$/m,x=/^│ ##   ###  ######  ##    OrNexus Team \([^)]*\)\s*│$/m,P=[{path:c(p(),".claude","agents","neocortex","neocortex.md"),type:"yaml"},{path:c(p(),".gemini","agents","agent.md"),type:"yaml"}],F=[{relativePath:c(".cursor","agents","neocortex.md"),type:"yaml"},{relativePath:c(".github","agents","neocortex.md"),type:"yaml"},{relativePath:"AGENTS.md",type:"h1"},{relativePath:c(".agent","skills","neocortex","SKILL.md"),type:"yaml"}];function O(){try{return A("git rev-parse --show-toplevel",{encoding:"utf-8",timeout:5e3,stdio:["pipe","pipe","pipe"]}).trim()||null}catch{return null}}function y(e,o){const t=I-L-o.length,r=t>0?" ".repeat(t):"";return`${e}${o}${r}\u2502`}function S(e){return y("\u2502      ###  ########      ",`v${e}`)}function $(e){const o=d[e.toLowerCase()]??"Free";return y("\u2502 ##   ###  ######  ##    ",`OrNexus Team (${o})`)}function g(e,o){const t=d[o.toLowerCase()]??"Free";return`\u{1F9E0} Neocortex v${e} (${t}) | OrNexus Team`}function R(){try{if(f(m)){const e=l(m,"utf-8");return JSON.parse(e).tier??"free"}}catch{}return"free"}function v(e,o,t){let r=e;return T.test(r)&&(r=r.replace(T,S(o))),x.test(r)&&(r=r.replace(x,$(t))),r}function u(e,o,t,r,i){try{if(!f(e))return!1;let n=l(e,"utf-8");const s=n;return o==="yaml"?N.test(n)&&(n=n.replace(N,`description: "${t}"`)):E.test(n)&&(n=n.replace(E,`# ${t}`)),n=v(n,r,i),n===s?!1:(_(e,n,"utf-8"),!0)}catch{return!1}}function w(e,o){const t=o??R(),r=g(e,t);let i=0;for(const{path:s,type:a}of P)u(s,a,r,e,t)&&i++;const n=O();if(n)for(const{relativePath:s,type:a}of F){const h=c(n,s);u(h,a,r,e,t)&&i++}return i}function j(e,o,t,r){const i=r??R(),n=g(t,i);return u(e,o,n,t,i)}export{$ as buildBannerTierLine,S as buildBannerVersionLine,g as buildDescription,R as readTierFromConfig,w as updateAgentDescription,j as updateAgentDescriptionAt};

package/packages/client/dist/cache/crypto-utils.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/** On-disk envelope format. expiresAt is inside the encrypted data payload. */
+export interface EncryptedEnvelope {
+    /** Base64-encoded initialization vector (12 bytes) */
+    iv: string;
+    /** Base64-encoded PBKDF2 salt */
+    salt: string;
+    /** Base64-encoded GCM auth tag */
+    tag: string;
+    /** Base64-encoded encrypted data (contains plaintext + expiresAt) */
+    data: string;
+}
+export declare function deriveKey(passphrase: string, salt: Buffer): Buffer;
+export declare function encrypt(plaintext: string, passphrase: string, ttlMs?: number): string;
+export interface DecryptResult {
+    plaintext: string;
+    expired: boolean;
+}
+export declare function decrypt(envelopeJson: string, passphrase: string): DecryptResult;

package/packages/client/dist/cache/crypto-utils.js

@@ -0,0 +1 @@
+import{randomBytes as d,pbkdf2Sync as h,createCipheriv as S,createDecipheriv as m}from"node:crypto";import{assertPublicSafeCachePayload as v}from"./protected-pi-boundary.js";const l="aes-256-gcm",b=12,A=32,B=32,g=16,N=1e5,x="sha512";function y(e,n){return h(e,n,N,B,x)}function _(e,n,t){v(e);const s=d(b),c=d(A),i=y(n,c),f=t!=null?Date.now()+t:null,a=JSON.stringify({plaintext:e,expiresAt:f}),o=S(l,i,s,{authTagLength:g}),r=Buffer.concat([o.update(a,"utf8"),o.final()]),p=o.getAuthTag(),T={iv:s.toString("base64"),salt:c.toString("base64"),tag:p.toString("base64"),data:r.toString("base64")};return JSON.stringify(T)}function G(e,n){const t=JSON.parse(e);if(!t.iv||!t.salt||!t.tag||!t.data)throw new Error("Invalid cache envelope: missing required fields");const s=Buffer.from(t.iv,"base64"),c=Buffer.from(t.salt,"base64"),i=Buffer.from(t.tag,"base64"),f=Buffer.from(t.data,"base64"),u=y(n,c),a=m(l,u,s,{authTagLength:g});a.setAuthTag(i);const o=Buffer.concat([a.update(f),a.final()]),r=JSON.parse(o.toString("utf8")),p=r.expiresAt!=null&&Date.now()>r.expiresAt;return{plaintext:r.plaintext,expired:p}}export{G as decrypt,y as deriveKey,_ as encrypt};

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

@@ -0,0 +1,30 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+import type { CacheProvider } from '../types/index.js';
+export interface EncryptedCacheOptions {
+    /** Directory where encrypted cache files are stored */
+    cacheDir: string;
+    /** Passphrase for encryption (typically the license key) */
+    passphrase: string;
+}
+export declare class EncryptedCache implements CacheProvider {
+    private readonly cacheDir;
+    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>;
+    private keyToPath;
+    private ensureDir;
+}

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

@@ -0,0 +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};

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

@@ -0,0 +1,62 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+/**
+ * InMemoryAssetCache - volatile LRU cache for asset content (Epic P70.06).
+ *
+ * Purpose: protect IP assets (step/skill/standard prompt content) from being
+ * persisted to the client filesystem. Unlike `EncryptedCache`, entries here
+ * live ONLY in the running process memory and are discarded on exit.
+ *
+ * Implements the {@link CacheProvider} interface so it can be drop-in
+ * substituted for `EncryptedCache` when resolving asset content, while
+ * `EncryptedCache` remains in use for JWTs and the menu cache.
+ *
+ * Configuration:
+ *  - `maxSize` entries (default 50) -- small bound keeps memory flat even
+ *     under heavy use.
+ *  - `ttlMs` milliseconds (default 5 min) -- defense-in-depth against stale
+ *    assets being reused after the server updates its version.
+ *  - Never writes to disk, never throws.
+ *  - P176.05: bounded volatile cache only; synthetic protected PI markers are
+ *    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';
+export interface InMemoryAssetCacheOptions {
+    /** Maximum number of entries before eviction (default: 50) */
+    readonly maxSize?: number;
+    /** Time-to-live in ms (default: 5 minutes) */
+    readonly ttlMs?: number;
+}
+export declare class InMemoryAssetCache implements CacheProvider {
+    private readonly store;
+    private readonly maxSize;
+    private readonly ttlMs;
+    constructor(options?: InMemoryAssetCacheOptions);
+    /**
+     * 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>;
+    /**
+     * 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>;
+    /** Drop all entries. Safe to call at any time. */
+    clear(): Promise<void>;
+    /** Internal: number of live entries (for diagnostics / tests). */
+    size(): number;
+}

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

@@ -0,0 +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};

package/packages/client/dist/cache/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+export { EncryptedCache, type EncryptedCacheOptions } from './encrypted-cache.js';

package/packages/client/dist/cache/index.js

@@ -0,0 +1 @@
+import{EncryptedCache as c}from"./encrypted-cache.js";export{c as EncryptedCache};

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

@@ -0,0 +1,19 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * Public-safe client cache PI boundary checks.
+ */
+/** Public reason code used when a synthetic protected PI marker is detected. */
+export declare const PROTECTED_CACHE_PAYLOAD_REASON = "protected-cache-payload-rejected";
+/**
+ * Returns true only for synthetic protected markers or explicit protected field
+ * names. Generic words like "prompt" or "workflow" are intentionally not
+ * rejected because cache keys and README-grade metadata may use them safely.
+ */
+export declare function hasProtectedCachePayloadMarker(value: string): boolean;
+export declare class ProtectedCachePayloadError extends Error {
+    readonly code = "protected-cache-payload-rejected";
+    constructor();
+}
+export declare function assertPublicSafeCachePayload(value: string): void;

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

@@ -0,0 +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};

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

@@ -0,0 +1,45 @@
+/**
+ * Epic P109.05: Checkpoint client-side reader (fail-soft).
+ *
+ * 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).
+ */
+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 interface ValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly string[];
+}
+/**
+ * Pure validation (zero I/O). Deterministic.
+ *
+ * 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).
+ */
+export declare function validateSnapshot(candidate: unknown): ValidationResult;
+/**
+ * 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.
+ */
+export declare function readAndConsumeCheckpoint(projectRoot: string): Promise<ImplementCheckpointSnapshot | undefined>;

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

@@ -0,0 +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};

package/packages/client/dist/checkpoint/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Epic P109.05: Checkpoint client-side module barrel.
+ *
+ * Exports the fail-soft reader + validator + canonical path const.
+ * Re-exports wire-format types from local SSoT-Shadow inline (P117.01) so
+ * the published client tarball never references `@neocortex/shared` at
+ * runtime. Type identity stays in sync with `@neocortex/shared` via
+ * `checkpoint-shared-sync.test.ts` drift test.
+ */
+export * from './checkpoint-client-reader.js';
+export type { ImplementCheckpoint, ImplementCheckpointSnapshot, CheckpointPhase, CheckpointResumeContext, } from './shared-checkpoint-types.js';
+export { MAX_SNAPSHOT_SIZE_BYTES } from './shared-checkpoint-types.js';

package/packages/client/dist/checkpoint/index.js

@@ -0,0 +1 @@
+export*from"./checkpoint-client-reader.js";import{MAX_SNAPSHOT_SIZE_BYTES as _}from"./shared-checkpoint-types.js";export{_ as MAX_SNAPSHOT_SIZE_BYTES};

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

@@ -0,0 +1,85 @@
+/**
+ * P117.01: Inlined byte-identical types from `@neocortex/shared/checkpoints`.
+ *
+ * SSoT-Shadow pattern (P92.01 server precedent — server `shared-types.ts` does
+ * the same for tier-config). Client tarball is published standalone via
+ * `@ornexus/neocortex` and does NOT include `@neocortex/shared` as a runtime
+ * dependency (workspace package, excluded from tarball per `.npmignore` +
+ * `tsconfig.build.json`). Any non-erased import of `@neocortex/shared` in
+ * `packages/client/dist/**` causes runtime `ERR_MODULE_NOT_FOUND` on globally
+ * installed `@ornexus/neocortex`.
+ *
+ * Live regression reproduced 2026-04-25 (Epic P117 origin):
+ *   `[Neocortex] checkpoint hook failed: Cannot find package '@neocortex/shared'
+ *    imported from .../checkpoint/checkpoint-client-reader.js. Proceeding without
+ *    checkpoint.`
+ *
+ * Sync responsibility: `shared-types-sync.test.ts` (P117.01 describe block) +
+ * `checkpoint-shared-sync.test.ts` (client-side drift test). Drift test fails
+ * CI if these diverge from SSoT.
+ *
+ * Defense-in-depth: `validate-pre-publish.js` ships
+ * `validateClientNoSharedImport()` (P117.01) scanning client dist for
+ * `@neocortex/shared` runtime references — match = exit 1 (publish blocked).
+ *
+ * DO NOT EDIT WITHOUT also editing `packages/shared/src/checkpoints/types.ts`.
+ */
+/**
+ * 4-phase state machine mirroring step-c-06-implement Double Diamond phases.
+ * Auto-detected from prompt progression (P109.04 wires).
+ *
+ * Canonical mapping:
+ * - FASE_1: Discovery/Analysis
+ * - FASE_2: Implementation/Test writing
+ * - FASE_3: Validation/Refactor
+ * - FASE_4: Cleanup/Update memory
+ */
+export type CheckpointPhase = 'FASE_1' | 'FASE_2' | 'FASE_3' | 'FASE_4';
+/**
+ * Full checkpoint record (server → DB persistence shape).
+ * Mirror of implement_checkpoints table (P109.01).
+ * Wire-format uses ISO strings for timestamps (NOT Date objects).
+ */
+export interface ImplementCheckpoint {
+    readonly id: string;
+    readonly licenseId: string;
+    readonly storyId: string;
+    readonly turn: number;
+    readonly filesModified: readonly string[];
+    readonly testsModified: readonly string[];
+    readonly currentPhase: CheckpointPhase;
+    readonly snapshotMd: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+/**
+ * Client → Server payload (POST /api/v1/invoke body enrichment).
+ * Omits id, licenseId, createdAt, updatedAt (server-set, never trust client).
+ */
+export interface ImplementCheckpointSnapshot {
+    readonly storyId: string;
+    readonly turn: number;
+    readonly filesModified: readonly string[];
+    readonly testsModified: readonly string[];
+    readonly currentPhase: CheckpointPhase;
+    readonly snapshotMd: string;
+}
+/**
+ * Server → Client resume injection shape.
+ * Server builds this from latest checkpoint row; client-facing prompt gets `summary`.
+ */
+export interface CheckpointResumeContext {
+    readonly storyId: string;
+    readonly turn: number;
+    readonly maxTurns: number;
+    readonly currentPhase: CheckpointPhase;
+    readonly filesModifiedCount: number;
+    readonly testsModifiedCount: number;
+    readonly summary: string;
+    readonly resumeAt: string;
+}
+/**
+ * Snapshot size guard: prevents PG bloat from pathological code-paste scenarios.
+ * Truncate snapshot_md at this byte count (P109.06 enforces).
+ */
+export declare const MAX_SNAPSHOT_SIZE_BYTES: 50000;

package/packages/client/dist/checkpoint/shared-checkpoint-types.js

@@ -0,0 +1 @@
+const S=5e4;export{S as MAX_SNAPSHOT_SIZE_BYTES};

package/packages/client/dist/cli.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+export {};

package/packages/client/dist/cli.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import{readFileSync as u}from"node:fs";import{fileURLToPath as m}from"node:url";import{dirname as l,join as d}from"node:path";function g(){try{const r=m(import.meta.url);let e=l(r);for(let s=0;s<5;s++){try{const o=JSON.parse(u(d(e,"package.json"),"utf-8"));if(o.name==="@ornexus/neocortex"||o.name==="@neocortex/client")return o.version??"0.0.0"}catch{}e=l(e)}}catch{}return"0.0.0"}const p=`
+neocortex-client - Neocortex Client CLI
+
+Usage:
+  neocortex-client <command> [options]
+
+Commands:
+  invoke         Send orchestration request to server
+  activate       Activate license key
+  refresh-memory Create/repair canonical NEOCORTEX.md links and wrappers
+  cache-status   Show cache and circuit breaker status
+  update         Update to latest version (use 'neocortex update' instead)
+
+Options:
+  --help, -h     Show this help message
+  --version, -v  Show version number
+
+Invoke Options:
+  --args <string>        Raw args to send (e.g., "*status")
+  --stdin                Read raw args as UTF-8 text from stdin
+  --args-file <path>     Read raw args as UTF-8 text from a local file
+  --project-root <path>  Project root directory (default: cwd; Git repo not required)
+  --format <type>        Output format: json | plain (default: plain)
+  --server-url <url>     Server URL override
+
+Refresh Memory Options:
+  --project-root <path>  Project root directory (default: cwd)
+  --targets <csv>        Target ids (default: all project-memory targets)
+  --dry-run, --preview   Print files that would change without writing
+
+Activate Options:
+  <license-key>          License key (e.g., NX-PRO-ABC-123)
+  --server-url <url>     Server URL override
+  --non-interactive      Skip interactive prompts
+
+Examples:
+  neocortex-client invoke --args "*status"
+  neocortex-client invoke --args "*yolo @docs/stories/1.1.story.md" --format json
+  neocortex-client invoke --stdin < synthetic.story.md
+  neocortex-client invoke --args-file ./synthetic.story.md
+  neocortex-client activate NX-PRO-ABC-123
+  neocortex-client cache-status
+
+License:
+  Licensed under BSL-1.1 (Business Source License 1.1)
+`.trim(),h=new Set(["pm","install","postinstall","preinstall","prepublish","postpublish","preuninstall","postuninstall","preprepare","prepare","postprepare"]);async function f(){const r=process.argv.slice(2),e=r[0];e&&h.has(e.toLowerCase())&&process.exit(0),(!e||e==="--help"||e==="-h")&&(console.log(p),process.exit(0)),(e==="--version"||e==="-v")&&(console.log(g()),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:o}=await import("./commands/invoke.js"),i=await o(s);process.exit(i);break}case"activate":{const{activate:o}=await import("./commands/activate.js");let i,c,a=!1;for(let t=0;t<s.length;t++){const n=s[t];n==="--server-url"?c=s[++t]:n==="--non-interactive"?a=!0:n==="--help"||n==="-h"?(console.log(p),process.exit(0)):n.startsWith("-")||(i=n)}i||(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 t=await o({licenseKey:i,serverUrl:c,nonInteractive:a});t.success?(console.log(t.message),process.exit(0)):(console.error(t.message),process.exit(1))}catch(t){const n=t instanceof Error?t.message:String(t);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:o}=await import("./commands/refresh-memory.js"),i=await o(s);process.exit(i);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)}}f().catch(r=>{console.error(`Fatal error: ${r instanceof Error?r.message:String(r)}`),process.exit(1)});

package/packages/client/dist/commands/activate.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+export interface ActivateOptions {
+    /** License key or API key to activate */
+    readonly licenseKey?: string;
+    /** Server URL override (default: production server) */
+    readonly serverUrl?: string;
+    /** Skip interactive prompt */
+    readonly nonInteractive?: boolean;
+}
+export interface ActivateResult {
+    readonly success: boolean;
+    readonly message: string;
+    readonly tier?: string;
+    readonly serverUrl?: string;
+    readonly configPath?: string;
+}
+/**
+ * Validate license key format.
+ * Format: NX-{TIER}-{random}-{random}
+ * Tiers: FREE, PRO, ENT
+ */
+export declare function validateLicenseKeyFormat(key: string): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Validate API key format.
+ * Format: nxk_{tier}_{random}_{check}
+ */
+export declare function validateApiKeyFormat(key: string): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Activate a Neocortex license.
+ *
+ * Flow:
+ * 1. Validate license key format
+ * 2. Call IP Protection Server to activate
+ * 3. Cache JWT token via LicenseClient
+ * 4. Create/update ~/.neocortex/config.json
+ * 5. Return result with feedback
+ */
+export declare function activate(options: ActivateOptions): Promise<ActivateResult>;

package/packages/client/dist/commands/activate.js

@@ -0,0 +1,8 @@
+import{existsSync as $,mkdirSync as C,writeFileSync as V,readFileSync as x}from"node:fs";import{join as a,dirname as P}from"node:path";import{homedir as Y}from"node:os";import{fileURLToPath as X}from"node:url";import{LicenseClient as M}from"../license/license-client.js";import{EncryptedCache as S}from"../cache/encrypted-cache.js";import{getMachineFingerprint as E}from"../machine/fingerprint.js";import{updateAgentDescription as N}from"../agent/update-description.js";import{refreshStubs as h}from"../agent/refresh-stubs.js";import{updateAgentYaml as _}from"../agent/update-agent-yaml.js";import{saveSecureConfig as W,setSecureDirPermissions as w}from"../config/secure-config.js";import{DEFAULT_SERVER_URL as J}from"../constants.js";function b(){try{const e=X(import.meta.url);let t=P(e);for(let r=0;r<5;r++){try{const n=JSON.parse(x(a(t,"package.json"),"utf-8"));if(n.name==="@ornexus/neocortex"||n.name==="@neocortex/client")return n.version??"0.0.0"}catch{}t=P(t)}}catch{}return"0.0.0"}const i=a(Y(),".neocortex"),c=a(i,"config.json"),B=/^NX-(F|P|E)-[a-f0-9]+-[a-f0-9]+$/i,G=/^nxk_(?:[a-z]+_)?[a-f0-9]+_[a-f0-9]+$/;function z(e){if(!e||e.trim().length===0)return{valid:!1,error:"License key cannot be empty"};const t=e.trim().toUpperCase();return t.startsWith("NX-")?B.test(t)?{valid:!0}:{valid:!1,error:"Invalid license key format. Expected: NX-{TIER}-{ID} (e.g., NX-PRO-ABC-123)"}:{valid:!1,error:'License key must start with "NX-"'}}function q(e){if(!e||e.trim().length===0)return{valid:!1,error:"API key cannot be empty"};const t=e.trim();return t.startsWith("nxk_")?t.length<20?{valid:!1,error:"API key is too short"}:G.test(t)?{valid:!0}:{valid:!1,error:"Invalid API key format. Expected: nxk_{id}_{check} (e.g., nxk_abc123def456...)"}:{valid:!1,error:'API key must start with "nxk_"'}}function pe(){try{if($(c)){const e=x(c,"utf-8");return JSON.parse(e)}}catch{}return null}function A(e){C(i,{recursive:!0}),w(i);const t=a(i,"cache");if(C(t,{recursive:!0}),w(t),e.licenseKey||e.apiKey)W({serverUrl:e.serverUrl,mode:e.mode,machineId:e.machineId,activatedAt:e.activatedAt,tier:e.tier,licenseKey:e.licenseKey??e.apiKey});else{const r={configVersion:1,...e};V(c,JSON.stringify(r,null,2)+`
+`,"utf-8")}}async function he(e){const{licenseKey:t,serverUrl:r=J}=e;if(!t)return{success:!1,message:["No key provided.","","Get your license key at https://neocortex.sh/portal/login","","Usage:","  neocortex activate YOUR-LICENSE-KEY","  neocortex activate YOUR-API-KEY"].join(`
+`)};const n=t.trim();if(n.startsWith("nxk_")){const o=q(n);if(!o.valid)return{success:!1,message:`Invalid API key: ${o.error}`};const k=n.match(/^nxk_(free|pro|ent)_/),O={free:"free",pro:"pro",ent:"enterprise"},R=k?.[1]?O[k[1]]??"unknown":"unknown",I=E(),l=b();let m;try{const s=await fetch(`${r}/api/v1/license/activate-key`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({api_key:n,machine_id:I,client_version:l})});if(!s.ok)return{success:!1,message:`API key activation failed: ${(await s.json().catch(()=>({}))).message??`HTTP ${s.status}`}`};m=await s.json()}catch{return{success:!1,message:["Failed to connect to IP Protection Server.","","Possible causes:",`  - Server at ${r} is unreachable`,"  - Network connectivity issue","","Workaround: Use --local flag to run in local mode"].join(`
+`)}}const p=m.tier??R,T=a(i,"cache");try{await new S({cacheDir:T,passphrase:n}).set("neocortex:jwt:token",m.token,m.expires_in*1e3)}catch{}const L={serverUrl:r,mode:"remote",machineId:I,activatedAt:new Date().toISOString(),tier:p,apiKey:n};try{A(L)}catch(s){return{success:!1,message:`Failed to save configuration: ${s instanceof Error?s.message:"unknown error"}`}}const Z=h(l,{forceCreate:!0,targetFilter:"claude-code"});return h(l),N(l,p),_(l,p),{success:!0,message:["Neocortex activated successfully.","","Open your preferred platform (Claude Code, Cursor, VS Code, etc.)","and reference the Neocortex agent.","","Use *menu to see available commands or check the Docs in your Dashboard."].join(`
+`),tier:p,serverUrl:r,configPath:c}}const y=z(n);if(!y.valid)return{success:!1,message:`Invalid license key: ${y.error}`};const u=n,v=u.match(/^NX-(F|P|E)-/i),F={F:"free",P:"pro",E:"enterprise"},d=v?.[1]?F[v[1].toUpperCase()]??"unknown":"unknown",K=a(i,"cache"),U=new S({cacheDir:K,passphrase:u}),j=new M({serverUrl:r,licenseKey:u,cacheProvider:U});let g;try{g=await j.activate()}catch{return{success:!1,message:["Failed to connect to IP Protection Server.","","Possible causes:",`  - Server at ${r} is unreachable`,"  - Network connectivity issue","  - Server is still being deployed","","Workaround: Use --local flag to run in local mode"].join(`
+`)}}if(!g)return{success:!1,message:["License activation failed.","","Possible causes:","  - Invalid or expired license key","  - License already activated on another machine","  - Server rejected the activation request","","Check your license key and try again.","Contact support if the problem persists."].join(`
+`)};const D={serverUrl:r,mode:"remote",machineId:E(),activatedAt:new Date().toISOString(),tier:d,licenseKey:u};try{A(D)}catch(o){return{success:!1,message:`Failed to save config to ${c}: ${o instanceof Error?o.message:String(o)}`}}const f=b(),Q=h(f,{forceCreate:!0,targetFilter:"claude-code"});return h(f),N(f,d),_(f,d),{success:!0,message:["Neocortex activated successfully.","","Open your preferred platform (Claude Code, Cursor, VS Code, etc.)","and reference the Neocortex agent.","","Use *menu to see available commands or check the Docs in your Dashboard."].join(`
+`),tier:d,serverUrl:r,configPath:c}}export{he as activate,q as validateApiKeyFormat,z as validateLicenseKeyFormat};

package/packages/client/dist/commands/cache-status.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license FSL-1.1
+ * Copyright (c) 2026 OrNexus AI
+ *
+ * This file is part of Neocortex CLI, licensed under the
+ * Functional Source License, Version 1.1 (FSL-1.1).
+ *
+ * Change Date: February 20, 2029
+ * Change License: MIT
+ *
+ * See the LICENSE file in the project root for full license text.
+ */
+import type { ClientCircuitBreaker, CircuitState } from '../resilience/circuit-breaker.js';
+import type { OfflineTelemetryQueue } from '../telemetry/offline-queue.js';
+export interface CacheStatusInfo {
+    totalEntries: number;
+    totalSizeBytes: number;
+    totalSizeFormatted: string;
+    oldestEntry: Date | null;
+    newestEntry: Date | null;
+    staleEntries: number;
+    circuitState: CircuitState;
+    lastSync: Date | null;
+    telemetryQueueSize: number;
+}
+export interface CacheStatusOptions {
+    cacheDir: string;
+    circuitBreaker: ClientCircuitBreaker;
+    telemetryQueue: OfflineTelemetryQueue;
+    staleThresholdMs?: number;
+}
+/**
+ * Gather comprehensive cache status information.
+ */
+export declare function getCacheStatus(options: CacheStatusOptions): Promise<CacheStatusInfo>;
+/**
+ * Format cache status as a human-readable string for terminal output.
+ */
+export declare function formatCacheStatus(info: CacheStatusInfo): string;

package/packages/client/dist/commands/cache-status.js

@@ -0,0 +1,2 @@
+import{readdir as y,stat as g}from"node:fs/promises";import{join as f}from"node:path";async function T(t){const r=t.staleThresholdMs??864e5;let e=0,s=0,c=0,i=null,a=null;try{const u=(await y(t.cacheDir)).filter(l=>l.endsWith(".enc"));e=u.length;const h=Date.now();for(const l of u)try{const m=f(t.cacheDir,l),d=await g(m);s+=d.size;const n=d.mtime;(!i||n<i)&&(i=n),(!a||n>a)&&(a=n),h-n.getTime()>r&&c++}catch{}}catch{}const S=t.circuitBreaker.getState().state;let o=0;try{o=(await t.telemetryQueue.getStats()).count}catch{}return{totalEntries:e,totalSizeBytes:s,totalSizeFormatted:$(s),oldestEntry:i,newestEntry:a,staleEntries:c,circuitState:S,lastSync:a,telemetryQueueSize:o}}function B(t){return["+-------------------------------------------------+","|  NEOCORTEX CACHE STATUS                         |","+-------------------------------------------------+",`|  Total entries:    ${String(t.totalEntries).padEnd(29)}|`,`|  Total size:       ${t.totalSizeFormatted.padEnd(29)}|`,`|  Oldest entry:     ${(t.oldestEntry?.toISOString()??"N/A").padEnd(29)}|`,`|  Newest entry:     ${(t.newestEntry?.toISOString()??"N/A").padEnd(29)}|`,`|  Stale entries:    ${String(t.staleEntries).padEnd(29)}|`,"|-------------------------------------------------|",`|  Circuit breaker:  ${t.circuitState.padEnd(29)}|`,`|  Last sync:        ${(t.lastSync?.toISOString()??"N/A").padEnd(29)}|`,`|  Telemetry queue:  ${(t.telemetryQueueSize+" events").padEnd(29)}|`,"+-------------------------------------------------+"].join(`
+`)}function $(t){if(t===0)return"0 B";const r=["B","KB","MB","GB"],e=Math.floor(Math.log(t)/Math.log(1024));return`${(t/Math.pow(1024,e)).toFixed(e===0?0:1)} ${r[e]}`}export{B as formatCacheStatus,T as getCacheStatus};