@skillstate/core 2.1.0 → 2.2.1

package/dist/atomic-write.d.ts

@@ -30,6 +30,23 @@ export interface LockHandle {
  * - Unreadable/missing locations (stat fails) → `null`, never throws.
  */
 export declare function acquireLock(lockPath: string, ttlMs?: number): Promise<LockHandle | null>;
+/** Default retry count for {@link withStateLock} (~10s at 50ms per try). */
+export declare const DEFAULT_LOCK_RETRIES = 200;
+/** Delay between {@link withStateLock} acquisition retries (50ms). */
+export declare const LOCK_RETRY_DELAY_MS = 50;
+/**
+ * Run `fn` while holding an exclusive cross-process lock on
+ * `statePath + '.lock'` ({@link acquireLock}, default TTL). Waits for a
+ * live holder: up to `retries` (default {@link DEFAULT_LOCK_RETRIES})
+ * attempts {@link LOCK_RETRY_DELAY_MS} apart, so 2-3 concurrent agent
+ * processes serialize instead of failing. The lock is acquired before
+ * `fn` starts and ALWAYS released in the `finally` block; the `fn`
+ * result (or failure) propagates after the release. Throws when the lock
+ * cannot be acquired within the retry budget. This is the async
+ * hot-path serialization primitive for the MCP server writes
+ * (patch/rollback/checkpoint/merge) and the host adapters.
+ */
+export declare function withStateLock<T>(statePath: string, fn: () => Promise<T> | T, ttlMs?: number, retries?: number): Promise<T>;
 /**
  * Resolve `name` inside `root` and return the absolute path. Throws when
  * the result escapes `root` (`..` traversal or an absolute outsider).

package/dist/atomic-write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"atomic-write.d.ts","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"AAkBA,4DAA4D;AAC5D,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GAAG,UAAU,GAC3B,OAAO,CAAC,IAAI,CAAC,CAYf;AAED,oEAAoE;AACpE,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAUD;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAwB5B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAOnE"}
+{"version":3,"file":"atomic-write.d.ts","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"AAkBA,4DAA4D;AAC5D,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GAAG,UAAU,GAC3B,OAAO,CAAC,IAAI,CAAC,CAYf;AAED,oEAAoE;AACpE,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAUD;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAwB5B;AAED,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,sEAAsE;AACtE,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACxB,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,GAAE,MAA6B,GACrC,OAAO,CAAC,CAAC,CAAC,CAgBZ;AAeD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAOnE"}

package/dist/atomic-write.js

@@ -80,6 +80,53 @@ export async function acquireLock(lockPath, ttlMs) {
         return makeHandle(lockPath);
     }
 }
+/** Default retry count for {@link withStateLock} (~10s at 50ms per try). */
+export const DEFAULT_LOCK_RETRIES = 200;
+/** Delay between {@link withStateLock} acquisition retries (50ms). */
+export const LOCK_RETRY_DELAY_MS = 50;
+/**
+ * Run `fn` while holding an exclusive cross-process lock on
+ * `statePath + '.lock'` ({@link acquireLock}, default TTL). Waits for a
+ * live holder: up to `retries` (default {@link DEFAULT_LOCK_RETRIES})
+ * attempts {@link LOCK_RETRY_DELAY_MS} apart, so 2-3 concurrent agent
+ * processes serialize instead of failing. The lock is acquired before
+ * `fn` starts and ALWAYS released in the `finally` block; the `fn`
+ * result (or failure) propagates after the release. Throws when the lock
+ * cannot be acquired within the retry budget. This is the async
+ * hot-path serialization primitive for the MCP server writes
+ * (patch/rollback/checkpoint/merge) and the host adapters.
+ */
+export async function withStateLock(statePath, fn, ttlMs, retries = DEFAULT_LOCK_RETRIES) {
+    const lockPath = `${statePath}.lock`;
+    await fs.promises.mkdir(path.dirname(lockPath), { recursive: true });
+    let handle = await acquireLockSafely(lockPath, ttlMs);
+    for (let attempt = 0; handle === null && attempt < retries; attempt++) {
+        await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_DELAY_MS));
+        handle = await acquireLockSafely(lockPath, ttlMs);
+    }
+    if (!handle) {
+        throw new Error(`skillstate: could not acquire the state lock: ${lockPath}`);
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        handle.release();
+    }
+}
+/**
+ * {@link acquireLock} with the stale-takeover race collapsed to `null`:
+ * between `unlink` and the re-`writeFile`, another waiter may recreate
+ * the lockfile (`EEXIST`) — that loser must retry, never crash.
+ */
+async function acquireLockSafely(lockPath, ttlMs) {
+    try {
+        return await acquireLock(lockPath, ttlMs);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Resolve `name` inside `root` and return the absolute path. Throws when
  * the result escapes `root` (`..` traversal or an absolute outsider).

package/dist/atomic-write.js.map

@@ -1 +1 @@
-{"version":3,"file":"atomic-write.js","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"atomic-write.js","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"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"}

package/dist/hook-runtime.d.ts

@@ -26,12 +26,30 @@
  */
 /** True for plain (non-null, non-array) objects. */
 export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Agent-id sanitization: keep `[A-Za-z0-9_-]` runs, collapse everything
+ * else into single `-`, trim edge dashes, cap at 64 chars. Garbage input
+ * sanitizes to `''` — callers treat that as "no agent" (the main state).
+ */
+export declare function sanitizeAgentId(agentId: string): string;
+/**
+ * Agent id from a host session id (Claude Code / Codex hook stdin carry
+ * `session_id`; opencode hooks carry `sessionID`): the short prefix — the
+ * first 8 characters — keeps agent directories bounded while remaining
+ * unique enough per session. Non-string/empty input yields `''`.
+ */
+export declare function resolveAgentIdFromSession(sessionId: unknown): string;
 /**
  * Resolve the per-project state file for a working directory — the pure,
  * dependency-free mirror of `resolveHostStateForCwd`
  * (`<cwd>/.skillstate/skillstate.json`; the global bucket
  * `<home>/.skillstate/global/skillstate.json` when cwd equals home).
  *
+ * AGENT-SCOPED STATE: a non-empty `agentId` (sanitized via
+ * {@link sanitizeAgentId}) scopes the file under an isolated
+ * `agents/<agentId>/` copy — parallel sub-agents (hook sessions) never
+ * share the main state file.
+ *
  * String arithmetic only (POSIX): absolute paths are normalized like
  * `path.resolve` (empty/`.` segments dropped, `..` popped, trailing
  * slashes trimmed); relative inputs stay relative because there is no
@@ -40,7 +58,7 @@ export declare function isPlainObject(value: unknown): value is Record<string, u
  * that. `home` must be provided to detect the global bucket; when it is
  * omitted the project path is returned.
  */
-export declare function resolveStatePathForCwd(cwd: string, home?: string): string;
+export declare function resolveStatePathForCwd(cwd: string, home?: string, agentId?: string): string;
 /**
  * Read the state file through the injected `readFile` (real `fs` in
  * generated scripts, mocks in tests). The on-disk envelope is
@@ -56,6 +74,39 @@ export declare function readStateEnvelope(statePath: string, readFile: (p: strin
  * plugin) or surface a `systemMessage` (PostToolUse hooks).
  */
 export declare function saveStateEnvelope(statePath: string, state: object, writeFile: (p: string, data: string) => void): void;
+/**
+ * Minimal `node:fs` surface {@link lockStateWrite} needs. Injections keep
+ * the hook-runtime pure: real `node:fs` in generated scripts and the
+ * plugin, mocks in tests (the established hook-runtime dependency style).
+ */
+export interface StateLockFs {
+    openSync(path: string, flags: string): number;
+    closeSync(fd: number): void;
+    statSync(path: string): {
+        mtimeMs: number;
+    };
+    unlinkSync(path: string): void;
+    mkdirSync(path: string): unknown;
+}
+/**
+ * Block the current thread for `ms` milliseconds — the sync sleep for the
+ * {@link lockStateWrite} retry loop. Prefers `Atomics.wait` on a shared
+ * integer (a real sleep); falls back to a busy spin when the primitive is
+ * unavailable. Plain JS — survives `fn.toString()` inlining.
+ */
+export declare function sleepSync(ms: number): void;
+/**
+ * Cross-process state lock for the SELF-CONTAINED hook scripts (sync,
+ * no imports): exclusive `O_EXCL` lockfile at `statePath + '.lock'`,
+ * stale-TTL takeover (10s — crashed hook holders), and a retry loop
+ * (50ms × 40 ≈ 2s) while a live holder runs its critical section. The
+ * injected `fs` (real `node:fs` in generated scripts and the plugin,
+ * mocks in tests) performs the lockfile I/O and creates the parent
+ * directory. The injected `fn` runs inside the lock; the lockfile is
+ * ALWAYS removed in the `finally` block. `fn` failures propagate AFTER
+ * the release; lock exhaustion throws.
+ */
+export declare function lockStateWrite(statePath: string, fs: StateLockFs, fn: () => unknown): unknown;
 /**
  * Paper ⊕ merge: `null` deletes a key, nested plain objects merge
  * recursively, everything else replaces. Pure — neither `state` nor
@@ -92,6 +143,15 @@ export declare function findFencedPatch(text: string): PatchLookup;
  * holding a non-object is an invalid attempt.
  */
 export declare function findRawPatch(text: string): PatchLookup;
+/**
+ * Read the session-meta sidecar's status (`<dir>/.session-meta.json`,
+ * sibling of the state file). Plain JS — inlined into the generated
+ * SessionStart hooks via `fn.toString()`. Returns the `status` string for
+ * a readable object-shaped sidecar, else `null` (missing/corrupt/other
+ * shape — no lifecycle marker). The `readFile` dependency is injected at
+ * the call site (real `node:fs` in hooks, mocks in tests).
+ */
+export declare function readSessionMetaStatus(metaPath: string, readFile: (p: string) => string): string | null;
 /**
  * Assemble the CJS snippet embedded into every generated hook script:
  * all sibling functions of this module, source-verbatim via

package/dist/hook-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hook-runtime.d.ts","sourceRoot":"","sources":["../src/hook-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,oDAAoD;AACpD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAyBzE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAC9B,OAAO,CAaT;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,GAC3C,IAAI,CAEN;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAazB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAQ1D;AAED,gFAAgF;AAChF,MAAM,MAAM,WAAW,GACnB;IAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAClC;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GACjB;IAAE,MAAM,EAAE,IAAI,CAAA;CAAE,CAAC;AAErB;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAczD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CA4BtD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAa3C"}
+{"version":3,"file":"hook-runtime.d.ts","sourceRoot":"","sources":["../src/hook-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,oDAAoD;AACpD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKvD;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,CAGpE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CA+B3F;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAC9B,OAAO,CAaT;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,GAC3C,IAAI,CAEN;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9C,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAW1C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,OAAO,GAAG,OAAO,CA8C7F;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAazB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAQ1D;AAED,gFAAgF;AAChF,MAAM,MAAM,WAAW,GACnB;IAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAClC;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GACjB;IAAE,MAAM,EAAE,IAAI,CAAA;CAAE,CAAC;AAErB;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAczD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CA4BtD;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAC9B,MAAM,GAAG,IAAI,CAUf;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAkB3C"}

package/dist/hook-runtime.js

@@ -28,12 +28,39 @@
 export function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/**
+ * Agent-id sanitization: keep `[A-Za-z0-9_-]` runs, collapse everything
+ * else into single `-`, trim edge dashes, cap at 64 chars. Garbage input
+ * sanitizes to `''` — callers treat that as "no agent" (the main state).
+ */
+export function sanitizeAgentId(agentId) {
+    return agentId
+        .replace(/[^A-Za-z0-9_-]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 64);
+}
+/**
+ * Agent id from a host session id (Claude Code / Codex hook stdin carry
+ * `session_id`; opencode hooks carry `sessionID`): the short prefix — the
+ * first 8 characters — keeps agent directories bounded while remaining
+ * unique enough per session. Non-string/empty input yields `''`.
+ */
+export function resolveAgentIdFromSession(sessionId) {
+    if (typeof sessionId !== 'string' || sessionId.length === 0)
+        return '';
+    return sessionId.slice(0, 8);
+}
 /**
  * Resolve the per-project state file for a working directory — the pure,
  * dependency-free mirror of `resolveHostStateForCwd`
  * (`<cwd>/.skillstate/skillstate.json`; the global bucket
  * `<home>/.skillstate/global/skillstate.json` when cwd equals home).
  *
+ * AGENT-SCOPED STATE: a non-empty `agentId` (sanitized via
+ * {@link sanitizeAgentId}) scopes the file under an isolated
+ * `agents/<agentId>/` copy — parallel sub-agents (hook sessions) never
+ * share the main state file.
+ *
  * String arithmetic only (POSIX): absolute paths are normalized like
  * `path.resolve` (empty/`.` segments dropped, `..` popped, trailing
  * slashes trimmed); relative inputs stay relative because there is no
@@ -42,7 +69,7 @@ export function isPlainObject(value) {
  * that. `home` must be provided to detect the global bucket; when it is
  * omitted the project path is returned.
  */
-export function resolveStatePathForCwd(cwd, home) {
+export function resolveStatePathForCwd(cwd, home, agentId) {
     const normalize = (p) => {
         const isAbsolute = p.startsWith('/');
         const segments = [];
@@ -65,10 +92,14 @@ export function resolveStatePathForCwd(cwd, home) {
     const rootless = (p) => (p === '/' ? '' : p);
     const resolvedCwd = normalize(cwd);
     const resolvedHome = home === undefined || home === null ? '' : normalize(home);
-    if (resolvedCwd === resolvedHome) {
-        return `${rootless(resolvedHome)}/.skillstate/global/skillstate.json`;
+    const agent = typeof agentId === 'string' && agentId.length > 0 ? sanitizeAgentId(agentId) : '';
+    const base = resolvedCwd === resolvedHome
+        ? `${rootless(resolvedHome)}/.skillstate/global`
+        : `${rootless(resolvedCwd)}/.skillstate`;
+    if (agent.length > 0) {
+        return `${base}/agents/${agent}/skillstate.json`;
     }
-    return `${rootless(resolvedCwd)}/.skillstate/skillstate.json`;
+    return `${base}/skillstate.json`;
 }
 /**
  * Read the state file through the injected `readFile` (real `fs` in
@@ -101,6 +132,90 @@ export function readStateEnvelope(statePath, readFile) {
 export function saveStateEnvelope(statePath, state, writeFile) {
     writeFile(statePath, `${JSON.stringify({ version: 1, state }, null, 2)}\n`);
 }
+/**
+ * Block the current thread for `ms` milliseconds — the sync sleep for the
+ * {@link lockStateWrite} retry loop. Prefers `Atomics.wait` on a shared
+ * integer (a real sleep); falls back to a busy spin when the primitive is
+ * unavailable. Plain JS — survives `fn.toString()` inlining.
+ */
+export function sleepSync(ms) {
+    try {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+        return;
+    }
+    catch (error) {
+        // Atomics.wait unavailable in this host — spin below.
+    }
+    const end = Date.now() + ms;
+    while (Date.now() < end) {
+        // Spin — hook scripts must stay synchronous.
+    }
+}
+/**
+ * Cross-process state lock for the SELF-CONTAINED hook scripts (sync,
+ * no imports): exclusive `O_EXCL` lockfile at `statePath + '.lock'`,
+ * stale-TTL takeover (10s — crashed hook holders), and a retry loop
+ * (50ms × 40 ≈ 2s) while a live holder runs its critical section. The
+ * injected `fs` (real `node:fs` in generated scripts and the plugin,
+ * mocks in tests) performs the lockfile I/O and creates the parent
+ * directory. The injected `fn` runs inside the lock; the lockfile is
+ * ALWAYS removed in the `finally` block. `fn` failures propagate AFTER
+ * the release; lock exhaustion throws.
+ */
+export function lockStateWrite(statePath, fs, fn) {
+    const lockPath = `${statePath}.lock`;
+    const ttl = 10_000;
+    const retries = 40;
+    const dir = lockPath.replace(/\/[^/]+$/, '');
+    try {
+        fs.mkdirSync(dir);
+    }
+    catch (error) {
+        // Exists already — only the lockfile itself must be exclusive.
+    }
+    let acquired = false;
+    for (let attempt = 0; attempt < retries; attempt++) {
+        try {
+            fs.closeSync(fs.openSync(lockPath, 'wx'));
+            acquired = true;
+            break;
+        }
+        catch (error) {
+            let mtimeMs = 0;
+            try {
+                mtimeMs = fs.statSync(lockPath).mtimeMs;
+            }
+            catch (error) {
+                // Vanished between the failed create and the stat — retry at once.
+            }
+            if (Date.now() - mtimeMs > ttl) {
+                try {
+                    fs.unlinkSync(lockPath);
+                }
+                catch (error) {
+                    // Another waiter removed it first — retry from the top.
+                }
+            }
+            else {
+                sleepSync(50);
+            }
+        }
+    }
+    if (!acquired) {
+        throw new Error(`skillstate: could not acquire the state lock: ${lockPath}`);
+    }
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            fs.unlinkSync(lockPath);
+        }
+        catch (error) {
+            // Lock already removed (stale takeover raced us) — nothing to release.
+        }
+    }
+}
 /**
  * Paper ⊕ merge: `null` deletes a key, nested plain objects merge
  * recursively, everything else replaces. Pure — neither `state` nor
@@ -200,6 +315,26 @@ export function findRawPatch(text) {
     }
     return { absent: true };
 }
+/**
+ * Read the session-meta sidecar's status (`<dir>/.session-meta.json`,
+ * sibling of the state file). Plain JS — inlined into the generated
+ * SessionStart hooks via `fn.toString()`. Returns the `status` string for
+ * a readable object-shaped sidecar, else `null` (missing/corrupt/other
+ * shape — no lifecycle marker). The `readFile` dependency is injected at
+ * the call site (real `node:fs` in hooks, mocks in tests).
+ */
+export function readSessionMetaStatus(metaPath, readFile) {
+    try {
+        const parsed = JSON.parse(readFile(metaPath));
+        if (isPlainObject(parsed) && typeof parsed.status === 'string') {
+            return parsed.status;
+        }
+    }
+    catch (error) {
+        // Missing or corrupt sidecar — no lifecycle marker.
+    }
+    return null;
+}
 /**
  * Assemble the CJS snippet embedded into every generated hook script:
  * all sibling functions of this module, source-verbatim via
@@ -210,6 +345,8 @@ export function findRawPatch(text) {
 export function hookRuntimeSnippet() {
     return [
         isPlainObject,
+        resolveAgentIdFromSession,
+        sanitizeAgentId,
         resolveStatePathForCwd,
         readStateEnvelope,
         saveStateEnvelope,
@@ -217,6 +354,9 @@ export function hookRuntimeSnippet() {
         readResponseText,
         findFencedPatch,
         findRawPatch,
+        sleepSync,
+        lockStateWrite,
+        readSessionMetaStatus,
     ]
         .map((fn) => fn.toString())
         .join('\n\n');

package/dist/hook-runtime.js.map

@@ -1 +1 @@
-{"version":3,"file":"hook-runtime.js","sourceRoot":"","sources":["../src/hook-runtime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hook-runtime.js","sourceRoot":"","sources":["../src/hook-runtime.ts"],"names":[],"mappings":"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"}

package/dist/host-state.d.ts

@@ -2,7 +2,8 @@
  * Resolve the per-project state file for a working directory —
  * `<cwd>/.skillstate/skillstate.json`, or the global bucket
  * `<home>/.skillstate/global/skillstate.json` when cwd equals home
- * (`home` defaults to `os.homedir()`).
+ * (`home` defaults to `os.homedir()`). A non-empty `agentId` scopes the
+ * file under `<bucket>/agents/<sanitized agentId>/skillstate.json`.
  */
-export declare function resolveHostStateForCwd(cwd: string, home?: string): string;
+export declare function resolveHostStateForCwd(cwd: string, home?: string, agentId?: string): string;
 //# sourceMappingURL=host-state.d.ts.map

package/dist/host-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host-state.d.ts","sourceRoot":"","sources":["../src/host-state.ts"],"names":[],"mappings":"AAiBA;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAOzE"}
+{"version":3,"file":"host-state.d.ts","sourceRoot":"","sources":["../src/host-state.ts"],"names":[],"mappings":"AAyBA;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAa3F"}

package/dist/host-state.js

@@ -1,31 +1,44 @@
 /**
  * @non-paper Wave-4 DX helper — the canonical per-project state resolver
  * shared by every host adapter (OpenCode plugin, Codex hooks/fork-trim,
- * Claude Code hooks).
+ * Claude Code hooks, MCP).
  *
  * Semantics: the state file for a working directory is
  * `<cwd>/.skillstate/skillstate.json`; a session opened directly in the
  * user's home resolves to the global bucket
- * `<home>/.skillstate/global/skillstate.json`. Pure path arithmetic — no
- * filesystem access. Host-embedded hook scripts (self-contained `.cjs`)
- * keep a byte-equivalent copy of this logic because they must run without
- * importing `@skillstate/*`; this function is the single source of truth
- * the copies mirror.
+ * `<home>/.skillstate/global/skillstate.json`. AGENT-SCOPED STATE: a
+ * non-empty `agentId` (sanitized `[A-Za-z0-9_-]`, ≤64 chars) scopes the
+ * file under an isolated copy — `agents/<agentId>/skillstate.json` inside
+ * the same bucket — so 2-3 parallel sub-agents (hook sessions) never
+ * last-writer-win over each other; the main agent keeps the unscoped
+ * path and merges sub-agent copies explicitly (MCP `agent.merge`).
+ *
+ * Pure path arithmetic — no filesystem access. Host-embedded hook scripts
+ * (self-contained `.cjs`) keep a behavior-equivalent copy of this logic in
+ * the hook-runtime `resolveStatePathForCwd` because they must run without
+ * importing `@skillstate/*`; that function is the parity mirror. The agent
+ * id sanitizer is shared verbatim from the hook-runtime module.
  */
 import * as os from 'node:os';
 import * as path from 'node:path';
+import { sanitizeAgentId } from './hook-runtime.js';
 /**
  * Resolve the per-project state file for a working directory —
  * `<cwd>/.skillstate/skillstate.json`, or the global bucket
  * `<home>/.skillstate/global/skillstate.json` when cwd equals home
- * (`home` defaults to `os.homedir()`).
+ * (`home` defaults to `os.homedir()`). A non-empty `agentId` scopes the
+ * file under `<bucket>/agents/<sanitized agentId>/skillstate.json`.
  */
-export function resolveHostStateForCwd(cwd, home) {
+export function resolveHostStateForCwd(cwd, home, agentId) {
     const resolvedCwd = path.resolve(cwd);
     const resolvedHome = path.resolve(home ?? os.homedir());
-    if (resolvedCwd === resolvedHome) {
-        return path.join(resolvedHome, '.skillstate', 'global', 'skillstate.json');
+    const bucket = resolvedCwd === resolvedHome
+        ? path.join(resolvedHome, '.skillstate', 'global')
+        : path.join(resolvedCwd, '.skillstate');
+    const agent = typeof agentId === 'string' && agentId.length > 0 ? sanitizeAgentId(agentId) : '';
+    if (agent.length > 0) {
+        return path.join(bucket, 'agents', agent, 'skillstate.json');
     }
-    return path.join(resolvedCwd, '.skillstate', 'skillstate.json');
+    return path.join(bucket, 'skillstate.json');
 }
 //# sourceMappingURL=host-state.js.map

package/dist/host-state.js.map

@@ -1 +1 @@
-{"version":3,"file":"host-state.js","sourceRoot":"","sources":["../src/host-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAW,EAAE,IAAa;IAC/D,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACtC,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;IACxD,IAAI,WAAW,KAAK,YAAY,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,iBAAiB,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,aAAa,EAAE,iBAAiB,CAAC,CAAC;AAClE,CAAC"}
+{"version":3,"file":"host-state.js","sourceRoot":"","sources":["../src/host-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAW,EAAE,IAAa,EAAE,OAAgB;IACjF,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACtC,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;IACxD,MAAM,MAAM,GACV,WAAW,KAAK,YAAY;QAC1B,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,aAAa,EAAE,QAAQ,CAAC;QAClD,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;IAC5C,MAAM,KAAK,GACT,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACpF,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,iBAAiB,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAC9C,CAAC"}

package/dist/index.d.ts

@@ -20,5 +20,6 @@ export * from './hook-runtime.js';
 export * from './adapter-shared.js';
 export * from './prompt-contract.js';
 export * from './shutdown.js';
+export * from './session-meta.js';
 export * from './schemas/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AAErC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAElC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAE5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,qBAAqB,CAAC;AAEpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AAErC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAElC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAE5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,qBAAqB,CAAC;AAEpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAE9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -33,5 +33,7 @@ export * from './adapter-shared.js';
 // @non-paper Wave-5 deduplicated prompt texts (shared adapter vocabulary).
 export * from './prompt-contract.js';
 export * from './shutdown.js';
+// @non-paper release-2.3.0 session lifecycle marker (orchestration meta).
+export * from './session-meta.js';
 export * from './schemas/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,EAAE;AACF,0EAA0E;AAC1E,6EAA6E;AAC7E,qDAAqD;AACrD,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,qEAAqE;AACrE,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,0EAA0E;AAC1E,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,mDAAmD;AACnD,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,uEAAuE;AACvE,yCAAyC;AACzC,cAAc,mBAAmB,CAAC;AAClC,wEAAwE;AACxE,wCAAwC;AACxC,cAAc,qBAAqB,CAAC;AACpC,2EAA2E;AAC3E,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,EAAE;AACF,0EAA0E;AAC1E,6EAA6E;AAC7E,qDAAqD;AACrD,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,qEAAqE;AACrE,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,0EAA0E;AAC1E,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,mDAAmD;AACnD,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,uEAAuE;AACvE,yCAAyC;AACzC,cAAc,mBAAmB,CAAC;AAClC,wEAAwE;AACxE,wCAAwC;AACxC,cAAc,qBAAqB,CAAC;AACpC,2EAA2E;AAC3E,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,0EAA0E;AAC1E,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC"}

package/dist/prompt-contract.d.ts

@@ -40,6 +40,15 @@ export declare const STATE_PATCH_CONTRACT: string;
  * hosts, so the Bash-carried patch option can no longer drift away.
  */
 export declare const HISTORY_UNRELIABLE_NOTE = "\nHistory is not reliable. Persist anything you need via the skillstate MCP tools (state.summary / state.patch) or a fenced ```json state_patch block.";
+/**
+ * The interrupted-session hint injected by the SessionStart hooks
+ * (claude + codex alike) when the session-meta sidecar carries
+ * `status: "interrupted"` — a previous run of this session was killed
+ * (SIGINT/SIGTERM) mid-procedure. The hook appends the preserved state
+ * path so the agent can review progress/blockers before continuing.
+ * A fresh launch overwrites the status back to `running`.
+ */
+export declare const INTERRUPTED_SESSION_NOTE = "\nPrevious session was interrupted; state preserved at <path>; review progress/blockers before continuing.";
 /**
  * Render a state schema as the shared `## Schema` markdown block used by
  * every prompt formatter and adapter `injectState`. Fields without a
@@ -48,14 +57,27 @@ export declare const HISTORY_UNRELIABLE_NOTE = "\nHistory is not reliable. Persi
 export declare function describeSchema(schema: StateSchema): string;
 /** Options for {@link skillMdBody}. */
 export interface SkillMdBodyOptions {
-    /** Brand label woven into the hooks intro ("Claude Code", "Codex"). */
+    /** Brand label woven into the hooks intro ("Claude Code", "Codex", "OpenCode"). */
     hostLabel: string;
     /**
      * How the injected state reaches the model, as a predicate:
      * "injected into your context via hooks" (claude) /
-     * "provided as developer context" (codex).
+     * "provided as developer context" (codex) /
+     * "injected into the message list before every model call" (opencode).
      */
     injectionPhrase: string;
+    /**
+     * The hook names this host wires, verbatim as they appear in the bullets:
+     * claude/codex use UserPromptSubmit + `SessionStart` + `PostToolUse`;
+     * opencode uses `messages.transform` + `session.compacting` +
+     * `tool.execute.after`. The merge-bullet is omitted when `patchHook` is
+     * undefined.
+     */
+    hooks: {
+        inject: string;
+        reInject: string;
+        patchHook?: string;
+    };
     /** The skill spec — name/instructions/version fill the frontmatter. */
     spec: ProceduralSpec;
     /** State path written into the frontmatter and the body (default `./.skillstate/skillstate.json`). */
@@ -68,6 +90,10 @@ export interface SkillMdBodyOptions {
  * and `injectionPhrase` (how the state reaches the model). OpenCode keeps
  * its own body — its history is trimmed by the plugin, not by hooks, so
  * its Execution Context and Process genuinely differ.
+ *
+ * HOOK-NEUTRAL: the injected bullets are driven by `options.hooks` so ANY
+ * harness (claude/codex hook-wiring, opencode plugin transforms) renders the
+ * same canonical Process without forking the body.
  */
 export declare function skillMdBody(options: SkillMdBodyOptions): string;
 //# sourceMappingURL=prompt-contract.d.ts.map

package/dist/prompt-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-contract.d.ts","sourceRoot":"","sources":["../src/prompt-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9D;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,oHAC2E,CAAC;AAEpH,uEAAuE;AACvE,eAAO,MAAM,wBAAwB,QAOzB,CAAC;AAEb,mFAAmF;AACnF,eAAO,MAAM,iBAAiB,oIACqG,CAAC;AAEpI;;;GAGG;AACH,eAAO,MAAM,wBAAwB,uGAC4D,CAAC;AAElG;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,QAOrB,CAAC;AAEb;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,2JACsH,CAAC;AAE3J;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAQ1D;AAED,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,IAAI,EAAE,cAAc,CAAC;IACrB,sGAAsG;IACtG,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAmD/D"}
+{"version":3,"file":"prompt-contract.d.ts","sourceRoot":"","sources":["../src/prompt-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9D;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,oHAC2E,CAAC;AAEpH,uEAAuE;AACvE,eAAO,MAAM,wBAAwB,QAOzB,CAAC;AAEb,mFAAmF;AACnF,eAAO,MAAM,iBAAiB,oIACqG,CAAC;AAEpI;;;GAGG;AACH,eAAO,MAAM,wBAAwB,uGAC4D,CAAC;AAElG;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,QAOrB,CAAC;AAEb;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,2JACsH,CAAC;AAE3J;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,+GACyE,CAAC;AAE/G;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAQ1D;AAED,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC,mFAAmF;IACnF,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAChE,uEAAuE;IACvE,IAAI,EAAE,cAAc,CAAC;IACrB,sGAAsG;IACtG,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAyE/D"}

package/dist/prompt-contract.js

@@ -41,6 +41,15 @@ export const STATE_PATCH_CONTRACT = [
  * hosts, so the Bash-carried patch option can no longer drift away.
  */
 export const HISTORY_UNRELIABLE_NOTE = '\nHistory is not reliable. Persist anything you need via the skillstate MCP tools (state.summary / state.patch) or a fenced ```json state_patch block.';
+/**
+ * The interrupted-session hint injected by the SessionStart hooks
+ * (claude + codex alike) when the session-meta sidecar carries
+ * `status: "interrupted"` — a previous run of this session was killed
+ * (SIGINT/SIGTERM) mid-procedure. The hook appends the preserved state
+ * path so the agent can review progress/blockers before continuing.
+ * A fresh launch overwrites the status back to `running`.
+ */
+export const INTERRUPTED_SESSION_NOTE = '\nPrevious session was interrupted; state preserved at <path>; review progress/blockers before continuing.';
 /**
  * Render a state schema as the shared `## Schema` markdown block used by
  * every prompt formatter and adapter `injectState`. Fields without a
@@ -59,10 +68,15 @@ export function describeSchema(schema) {
  * and `injectionPhrase` (how the state reaches the model). OpenCode keeps
  * its own body — its history is trimmed by the plugin, not by hooks, so
  * its Execution Context and Process genuinely differ.
+ *
+ * HOOK-NEUTRAL: the injected bullets are driven by `options.hooks` so ANY
+ * harness (claude/codex hook-wiring, opencode plugin transforms) renders the
+ * same canonical Process without forking the body.
  */
 export function skillMdBody(options) {
     const resolvedStatePath = options.statePath ?? './.skillstate/skillstate.json';
-    return [
+    const patchHook = options.hooks.patchHook;
+    const body = [
         '---',
         `name: ${JSON.stringify(options.spec.name)}`,
         `description: ${JSON.stringify(options.spec.instructions)}`,
@@ -80,36 +94,23 @@ export function skillMdBody(options) {
         '',
         `Your execution state lives at \`${resolvedStatePath}\` (per project; a`,
         'session started in $HOME uses `~/.skillstate/global/skillstate.json`).',
-        `The skillstate ${options.hostLabel} hooks:`,
+        `The skillstate ${options.hostLabel} integration:`,
         '',
         `- the CURRENT state is ${options.injectionPhrase} on every prompt submit`,
-        '  (`UserPromptSubmit`) and is re-injected after compaction',
-        '  (`SessionStart` matcher `^compact$`);',
-        '- watch every Bash tool result and merge a fenced ```json block carrying',
-        '  a `state_patch` into the state file (`PostToolUse`).',
-        '',
-        'The injected state is authoritative — history is not reliable. Never',
-        'reconstruct execution context from the conversation.',
-        '',
-        '## Process',
-        '',
-        '1. Orient yourself: read the injected state, or call the skillstate MCP',
-        '   tools `state.summary` (compact) / `state.get` (full dump).',
-        '2. Observe the result of your last action.',
-        '3. Reason about what to do next, given the state and the observation.',
-        '4. Persist progress with the skillstate MCP tool `state.patch` (sparse',
-        '   patch; set a key to `null` to delete it; dry-run first with',
-        '   `state.validate` when unsure; `state.diff` shows what changed since',
-        '   your last look), and/or emit a fenced JSON block with exactly two',
-        '   keys inside a Bash tool call so the `PostToolUse` hook merges it:',
-        '',
-        STATE_PATCH_EXAMPLE_JSON,
-        '',
-        `- ${STATE_PATCH_RULES}`,
-        '- Put anything you need to survive into `state_patch`; never rely on',
-        '  the conversation remembering it.',
-        '- `action` names what you will do next (e.g. "continue", "done").',
-        '',
-    ].join('\n');
+        `  (\`${options.hooks.inject}\`) and is re-injected after compaction`,
+        `  (\`${options.hooks.reInject}\`);`,
+    ];
+    if (patchHook !== undefined) {
+        body.push('- watch every Bash tool result and merge a fenced ```json block carrying', `  a \`state_patch\` into the state file (\`${patchHook}\`).`);
+    }
+    body.push('', 'Sub-agents automatically get isolated state copies (agents/<session-id>);', 'merge them with `agent.merge` when their task completes.', '', 'The injected state is authoritative — history is not reliable. Never', 'reconstruct execution context from the conversation.', '', '## Process', '', '1. Orient yourself: read the injected state, or call the skillstate MCP', '   tools `state.summary` (compact) / `state.get` (full dump).', '2. Observe the result of your last action.', '3. Reason about what to do next, given the state and the observation.', '4. Persist progress with the skillstate MCP tool `state.patch` (sparse', '   patch; set a key to `null` to delete it; dry-run first with', '   `state.validate` when unsure; `state.diff` shows what changed since', '   your last look)');
+    if (patchHook !== undefined) {
+        body.push('   , and/or emit a fenced JSON block with exactly two', '   keys inside a Bash tool call so the `PostToolUse` hook merges it:', '', STATE_PATCH_EXAMPLE_JSON, '', `- ${STATE_PATCH_RULES}`);
+    }
+    else {
+        body.push(':', '', STATE_PATCH_EXAMPLE_JSON, '', `- ${STATE_PATCH_RULES}`);
+    }
+    body.push('- Put anything you need to survive into `state_patch`; never rely on', '  the conversation remembering it.', '- `action` names what you will do next (e.g. "continue", "done").', '- When the task is done, call state.finalize {status:"completed"} so the', '  orchestrator knows (state.finalize {status:"failed"} on failure).', '');
+    return body.join('\n');
 }
 //# sourceMappingURL=prompt-contract.js.map

package/dist/prompt-contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-contract.js","sourceRoot":"","sources":["../src/prompt-contract.ts"],"names":[],"mappings":"AAcA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2BAA2B,GACtC,iHAAiH,CAAC;AAEpH,uEAAuE;AACvE,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,SAAS;IACT,GAAG;IACH,gEAAgE;IAChE,gCAAgC;IAChC,GAAG;IACH,KAAK;CACN,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,mFAAmF;AACnF,MAAM,CAAC,MAAM,iBAAiB,GAC5B,iIAAiI,CAAC;AAEpI;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GACnC,+FAA+F,CAAC;AAElG;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,+DAA+D;IAC/D,MAAM,2BAA2B,EAAE;IACnC,EAAE;IACF,wBAAwB;IACxB,EAAE;IACF,iBAAiB;CAClB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAClC,wJAAwJ,CAAC;AAE3J;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,MAAmB;IAChD,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;SAClC,GAAG,CACF,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAChB,KAAK,IAAI,KAAK,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,WAAW,IAAI,gBAAgB,EAAE,CACxE;SACA,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,OAAO,cAAc,MAAM,EAAE,CAAC;AAChC,CAAC;AAkBD;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,OAA2B;IACrD,MAAM,iBAAiB,GAAG,OAAO,CAAC,SAAS,IAAI,+BAA+B,CAAC;IAC/E,OAAO;QACL,KAAK;QACL,SAAS,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;QAC5C,gBAAgB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE;QAC3D,YAAY,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE;QAClC,oBAAoB;QACpB,iBAAiB,iBAAiB,EAAE;QACpC,gBAAgB;QAChB,KAAK;QACL,EAAE;QACF,KAAK,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE;QACxB,EAAE;QACF,OAAO,CAAC,IAAI,CAAC,YAAY;QACzB,EAAE;QACF,sBAAsB;QACtB,EAAE;QACF,mCAAmC,iBAAiB,oBAAoB;QACxE,wEAAwE;QACxE,kBAAkB,OAAO,CAAC,SAAS,SAAS;QAC5C,EAAE;QACF,0BAA0B,OAAO,CAAC,eAAe,yBAAyB;QAC1E,4DAA4D;QAC5D,yCAAyC;QACzC,0EAA0E;QAC1E,wDAAwD;QACxD,EAAE;QACF,sEAAsE;QACtE,sDAAsD;QACtD,EAAE;QACF,YAAY;QACZ,EAAE;QACF,yEAAyE;QACzE,+DAA+D;QAC/D,4CAA4C;QAC5C,uEAAuE;QACvE,wEAAwE;QACxE,gEAAgE;QAChE,wEAAwE;QACxE,sEAAsE;QACtE,sEAAsE;QACtE,EAAE;QACF,wBAAwB;QACxB,EAAE;QACF,KAAK,iBAAiB,EAAE;QACxB,sEAAsE;QACtE,oCAAoC;QACpC,mEAAmE;QACnE,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}
+{"version":3,"file":"prompt-contract.js","sourceRoot":"","sources":["../src/prompt-contract.ts"],"names":[],"mappings":"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"}

package/dist/session-meta.d.ts

@@ -0,0 +1,58 @@
+/** Every lifecycle status the session meta sidecar may carry. */
+export type SessionStatus = 'running' | 'interrupted' | 'completed' | 'merged' | 'failed';
+/** All {@link SessionStatus} values. */
+export declare const SESSION_STATUSES: readonly ["running", "interrupted", "completed", "merged", "failed"];
+/** Sidecar file name living next to every state file. */
+export declare const SESSION_META_FILE = ".session-meta.json";
+/**
+ * A `running` session whose `lastActivityAt` is older than this (5 min)
+ * reports `stale` — the provider process died without a signal.
+ */
+export declare const STALE_MS: number;
+/** Session lifecycle metadata (the sidecar's JSON body). */
+export interface SessionMeta {
+    status?: SessionStatus;
+    /** ISO timestamp of the last state write (debounced to 5s by MCP). */
+    lastActivityAt?: string;
+    /** ISO timestamp stamped by `launch()` when the session starts. */
+    startedAt?: string;
+    /** ISO timestamp stamped by `state.finalize`. */
+    finishedAt?: string;
+    /** ISO timestamp stamped by `agent.merge` on the sub-agent copy. */
+    mergedAt?: string;
+    /** Free-text result carried by `state.finalize`. */
+    result?: string;
+    /** Sanitized agent scope the session runs under (`''` = main). */
+    agentId?: string;
+    /** MCP protocol revision the server session speaks. */
+    protocolVersion?: string;
+    /** Tolerated: unknown extra fields survive read/merge round-trips. */
+    [key: string]: unknown;
+}
+/** Sidecar path for a state directory: `<dir>/.session-meta.json`. */
+export declare function sessionMetaPath(dir: string): string;
+/**
+ * Read the session meta sidecar for `dir`. Returns `null` when the file
+ * is missing, unreadable, corrupt, or not a JSON object — callers treat
+ * that as "no lifecycle marker" (staleness `orphan`), never a crash.
+ */
+export declare function readSessionMeta(dir: string): SessionMeta | null;
+/**
+ * Merge `patch` into the session meta sidecar for `dir` and persist it
+ * atomically under the meta lock (`<metaPath>.lock`). Creates the file
+ * (and the directory) when absent; unknown existing fields survive.
+ * Returns the merged meta as written.
+ */
+export declare function writeSessionMeta(dir: string, patch: Partial<SessionMeta>): Promise<SessionMeta>;
+/** Staleness verdict for an agent session (see the module doc). */
+export type SessionStaleness = 'active' | 'stale' | 'orphan';
+/**
+ * Classify a session's liveness from its meta:
+ * `orphan` — no/corrupt meta; `stale` — status `running` but the last
+ * activity (falling back to `startedAt`) is older than {@link STALE_MS};
+ * `active` — everything else (fresh running sessions AND terminal
+ * statuses: completed/failed/merged/interrupted runs are not stale, their
+ * `status` already says so).
+ */
+export declare function sessionStaleness(meta: SessionMeta | null, nowMs?: number): SessionStaleness;
+//# sourceMappingURL=session-meta.d.ts.map

package/dist/session-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-meta.d.ts","sourceRoot":"","sources":["../src/session-meta.ts"],"names":[],"mappings":"AA8BA,iEAAiE;AACjE,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE1F,wCAAwC;AACxC,eAAO,MAAM,gBAAgB,sEAMgB,CAAC;AAE9C,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,uBAAuB,CAAC;AAEtD;;;GAGG;AACH,eAAO,MAAM,QAAQ,QAAgB,CAAC;AAEtC,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAU/D;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,CAAC,WAAW,CAAC,GAC1B,OAAO,CAAC,WAAW,CAAC,CAQtB;AAED,mEAAmE;AACnE,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE7D;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,GAAG,IAAI,EACxB,KAAK,GAAE,MAAmB,GACzB,gBAAgB,CAWlB"}

package/dist/session-meta.js

@@ -0,0 +1,101 @@
+/**
+ * @non-paper Session lifecycle marker (release 2.3.0).
+ *
+ * The state envelope (`<stateDir>/skillstate.json`) belongs to the
+ * PROCEDURE (paper §3.2) — the agent's data, nothing else. The session
+ * lifecycle is ORCHESTRATION metadata and lives in a separate sidecar:
+ * `<stateDir>/.session-meta.json`, written with `atomicWriteFile` under
+ * the same cross-process `withStateLock` primitive (its own lock file,
+ * `<metaPath>.lock` — never the state lock, so meta writes cannot
+ * deadlock against state writes).
+ *
+ * Statuses:
+ * - `running`     — a live session (MCP `launch()` stamps it at start);
+ * - `interrupted` — SIGINT/SIGTERM hit the server before a final status
+ *   (the interrupt handler flushes this + the diff baseline);
+ * - `completed` / `failed` — the agent called MCP `state.finalize`;
+ * - `merged` — the orchestrator folded the sub-agent state into the main
+ *   state via `agent.merge`.
+ *
+ * STALE DETECTION: a `running` meta whose `lastActivityAt` is older than
+ * {@link STALE_MS} (5 min) is `stale` (the provider died without a
+ * signal); missing/corrupt meta next to an existing state file is
+ * `orphan`. Everything else is `active`.
+ *
+ * Zero dependencies, Node >= 20, ESM.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { atomicWriteFile, withStateLock } from './atomic-write.js';
+/** All {@link SessionStatus} values. */
+export const SESSION_STATUSES = [
+    'running',
+    'interrupted',
+    'completed',
+    'merged',
+    'failed',
+];
+/** Sidecar file name living next to every state file. */
+export const SESSION_META_FILE = '.session-meta.json';
+/**
+ * A `running` session whose `lastActivityAt` is older than this (5 min)
+ * reports `stale` — the provider process died without a signal.
+ */
+export const STALE_MS = 5 * 60 * 1000;
+/** Sidecar path for a state directory: `<dir>/.session-meta.json`. */
+export function sessionMetaPath(dir) {
+    return path.join(dir, SESSION_META_FILE);
+}
+/**
+ * Read the session meta sidecar for `dir`. Returns `null` when the file
+ * is missing, unreadable, corrupt, or not a JSON object — callers treat
+ * that as "no lifecycle marker" (staleness `orphan`), never a crash.
+ */
+export function readSessionMeta(dir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(sessionMetaPath(dir), 'utf-8'));
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Missing or corrupt sidecar — no lifecycle marker.
+    }
+    return null;
+}
+/**
+ * Merge `patch` into the session meta sidecar for `dir` and persist it
+ * atomically under the meta lock (`<metaPath>.lock`). Creates the file
+ * (and the directory) when absent; unknown existing fields survive.
+ * Returns the merged meta as written.
+ */
+export async function writeSessionMeta(dir, patch) {
+    const metaPath = sessionMetaPath(dir);
+    return withStateLock(metaPath, async () => {
+        const current = readSessionMeta(dir);
+        const merged = { ...(current ?? {}), ...patch };
+        await atomicWriteFile(metaPath, `${JSON.stringify(merged, null, 2)}\n`);
+        return merged;
+    });
+}
+/**
+ * Classify a session's liveness from its meta:
+ * `orphan` — no/corrupt meta; `stale` — status `running` but the last
+ * activity (falling back to `startedAt`) is older than {@link STALE_MS};
+ * `active` — everything else (fresh running sessions AND terminal
+ * statuses: completed/failed/merged/interrupted runs are not stale, their
+ * `status` already says so).
+ */
+export function sessionStaleness(meta, nowMs = Date.now()) {
+    if (meta === null) {
+        return 'orphan';
+    }
+    if (meta.status === 'running') {
+        const last = Date.parse(meta.lastActivityAt ?? meta.startedAt ?? '');
+        if (Number.isNaN(last) || nowMs - last > STALE_MS) {
+            return 'stale';
+        }
+    }
+    return 'active';
+}
+//# sourceMappingURL=session-meta.js.map

package/dist/session-meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-meta.js","sourceRoot":"","sources":["../src/session-meta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAKnE,wCAAwC;AACxC,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,SAAS;IACT,aAAa;IACb,WAAW;IACX,QAAQ;IACR,QAAQ;CACmC,CAAC;AAE9C,yDAAyD;AACzD,MAAM,CAAC,MAAM,iBAAiB,GAAG,oBAAoB,CAAC;AAEtD;;;GAGG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;AAuBtC,sEAAsE;AACtE,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC;AAC3C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,eAAe,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QACnF,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5E,OAAO,MAAqB,CAAC;QAC/B,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,oDAAoD;IACtD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,GAAW,EACX,KAA2B;IAE3B,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IACtC,OAAO,aAAa,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;QACxC,MAAM,OAAO,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;QACrC,MAAM,MAAM,GAAgB,EAAE,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC;QAC7D,MAAM,eAAe,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QACxE,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC,CAAC;AACL,CAAC;AAKD;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAwB,EACxB,KAAK,GAAW,IAAI,CAAC,GAAG,EAAE;IAE1B,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;QACrE,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,GAAG,IAAI,GAAG,QAAQ,EAAE,CAAC;YAClD,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillstate/core",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Paper-exact skillstate runtime core (A.4 byte-verbatim formatPaper, §4.3 token tracker).",
   "type": "module",
   "main": "dist/index.js",