@theokit/sdk 4.63.4 → 5.0.0-next.2

package/dist/permission-engine.d.ts

@@ -27,7 +27,8 @@ export type PermissionAction = "allow" | "deny" | "ask";
  *   `allow` EXCEPT an explicit `deny` rule. Never asks. a peer project
  *   `dangerously-skip-permissions` / Codex `Never` / Anthropic `bypassPermissions`.
  */
-export type PermissionMode = "default" | "plan" | "acceptEdits" | "bypass" | "bypassPermissions";
+import type { PermissionMode } from "./types/agent-prims.js";
+export type { PermissionMode };
 /**
  * SE1 — apply a {@link PermissionMode} to a rule-engine verdict. Pure.
  *
@@ -60,23 +61,15 @@ export type ArgMatcher = string | RegExp | ((value: unknown) => boolean);
  * `{ tool: "shell", args: { command: /rm\s+-rf/ }, action: "deny" }` blocks the destructive call and
  * leaves `ls` to fall through to a later rule. Every declared matcher must pass.
  *
- * **A missing argument is NOT handled uniformly, and the difference bites in the unsafe direction.**
- * For a string or RegExp matcher, an argument the call did not supply fails the matcher, so the rule
- * does not match and evaluation continues. For a PREDICATE matcher the function is called anyway,
- * with `undefined`:
+ * **A rule that declares an argument the call did not supply does not match**, whatever form the
+ * matcher takes — string, RegExp or predicate. The predicate is not invoked with `undefined`; the
+ * guard runs first, for every matcher form. Evaluation continues to the next rule.
  *
- * ```ts
- * { tool: "shell", args: { command: (v) => v !== "prod" }, action: "allow" }
- * // evaluate("shell", {}) → the predicate gets `undefined`, returns true, the rule MATCHES,
- * // and a call that supplied no arguments at all is authorized.
- *
- * { tool: "shell", args: { command: (v) => v.includes("rm") }, action: "deny" }
- * // evaluate("shell", {}) → TypeError thrown out of the permission gate.
- * ```
- *
- * Until that is fixed (issue #367), guard the parameter in every predicate you write —
- * `(v) => typeof v === "string" && v !== "prod"` — rather than relying on the matcher never being
- * reached.
+ * That was not always true, and the fix is the reason this paragraph is explicit (#367). A predicate
+ * used to be called anyway, so `(v) => v !== "prod"` returned true for a missing argument and an
+ * ALLOW rule authorized a call that supplied nothing, while `(v) => v.includes("rm")` threw a
+ * TypeError out of the permission gate. This docblock told consumers to guard every predicate by
+ * hand for months after `argMatches` stopped needing it — you do not have to.
  *
  * A rule that matches yields an EXPLICIT verdict, and that is what makes it survive a permissive
  * `PermissionMode`: `acceptEdits` auto-approves the unmatched default but still honours an explicit

package/dist/persistence.cjs

@@ -1,16 +1,15 @@
 'use strict';
 
 var chunkVTYY7XL5_cjs = require('./chunk-VTYY7XL5.cjs');
-var chunkI6HGWHPU_cjs = require('./chunk-I6HGWHPU.cjs');
-var chunk5HEG4CQH_cjs = require('./chunk-5HEG4CQH.cjs');
+var chunkZ3NTRKIC_cjs = require('./chunk-Z3NTRKIC.cjs');
+var chunkGZV6AVRL_cjs = require('./chunk-GZV6AVRL.cjs');
 var chunkA4RAL2ER_cjs = require('./chunk-A4RAL2ER.cjs');
-var chunk5VB22SYX_cjs = require('./chunk-5VB22SYX.cjs');
-var chunkUU36SHFY_cjs = require('./chunk-UU36SHFY.cjs');
+var chunkDQZU7JK6_cjs = require('./chunk-DQZU7JK6.cjs');
+var chunkBJUJT5ED_cjs = require('./chunk-BJUJT5ED.cjs');
 var chunkZF2LDKQQ_cjs = require('./chunk-ZF2LDKQQ.cjs');
-var chunkUALX2J2Q_cjs = require('./chunk-UALX2J2Q.cjs');
-var chunk4ZHTIJNE_cjs = require('./chunk-4ZHTIJNE.cjs');
-require('./chunk-XL7Q7HB2.cjs');
-require('./chunk-EG4QM7ZJ.cjs');
+var chunkJLRLCBJ4_cjs = require('./chunk-JLRLCBJ4.cjs');
+var chunkJ7J7J2GN_cjs = require('./chunk-J7J7J2GN.cjs');
+require('./chunk-6LHQPOMI.cjs');
 var fs = require('fs');
 
 // src/internal/persistence/session-artifacts.ts
@@ -19,10 +18,10 @@ function classifySessionArtifact(name, isDirectory) {
   if (isDirectory) return void 0;
   if (name.endsWith(".jsonl")) return "transcript";
   if (name.endsWith(".writer.lock")) return "writer-lock";
-  if (chunkUALX2J2Q_cjs.atomicWriteTempTarget(name) !== void 0) return "temp";
+  if (chunkJLRLCBJ4_cjs.atomicWriteTempTarget(name) !== void 0) return "temp";
   return void 0;
 }
-var LiveSessionError = class extends chunk4ZHTIJNE_cjs.TheokitAgentError {
+var LiveTranscriptError = class extends chunkJ7J7J2GN_cjs.TheokitAgentError {
   constructor(path) {
     super(
       `refusing to write over a live session transcript: ${path}. Fork to a new id instead \u2014 the live pointer, the most recent transcript and any active registry entry are never overwritten (audit-trail rotation, M60).`,
@@ -31,11 +30,11 @@ var LiveSessionError = class extends chunk4ZHTIJNE_cjs.TheokitAgentError {
     this.path = path;
   }
   path;
-  name = "LiveSessionError";
+  name = "LiveTranscriptError";
 };
 function forkTranscript(src, dst, options = {}) {
   for (const live of options.liveSessionPaths ?? []) {
-    if (live === dst) throw new LiveSessionError(dst);
+    if (live === dst) throw new LiveTranscriptError(dst);
   }
   const lines = fs.readFileSync(src, "utf8").split("\n").filter((l) => l.trim().length > 0);
   const kept = options.beforeRecordIndex === void 0 ? lines : lines.slice(0, options.beforeRecordIndex);
@@ -103,27 +102,27 @@ Object.defineProperty(exports, "PersistenceSchema", {
 });
 Object.defineProperty(exports, "SessionBusyError", {
   enumerable: true,
-  get: function () { return chunkI6HGWHPU_cjs.SessionBusyError; }
+  get: function () { return chunkZ3NTRKIC_cjs.SessionBusyError; }
 });
 Object.defineProperty(exports, "acquireSessionWriter", {
   enumerable: true,
-  get: function () { return chunkI6HGWHPU_cjs.acquireSessionWriter; }
+  get: function () { return chunkZ3NTRKIC_cjs.acquireSessionWriter; }
 });
 Object.defineProperty(exports, "sessionHasWriter", {
   enumerable: true,
-  get: function () { return chunkI6HGWHPU_cjs.sessionHasWriter; }
+  get: function () { return chunkZ3NTRKIC_cjs.sessionHasWriter; }
 });
 Object.defineProperty(exports, "encodeProjectDir", {
   enumerable: true,
-  get: function () { return chunk5HEG4CQH_cjs.encodeProjectDir; }
+  get: function () { return chunkGZV6AVRL_cjs.encodeProjectDir; }
 });
 Object.defineProperty(exports, "transcriptPath", {
   enumerable: true,
-  get: function () { return chunk5HEG4CQH_cjs.transcriptPath; }
+  get: function () { return chunkGZV6AVRL_cjs.transcriptPath; }
 });
 Object.defineProperty(exports, "transcriptRoot", {
   enumerable: true,
-  get: function () { return chunk5HEG4CQH_cjs.transcriptRoot; }
+  get: function () { return chunkGZV6AVRL_cjs.transcriptRoot; }
 });
 Object.defineProperty(exports, "sanitizeFts5Query", {
   enumerable: true,
@@ -131,35 +130,35 @@ Object.defineProperty(exports, "sanitizeFts5Query", {
 });
 Object.defineProperty(exports, "applyWalWithFallback", {
   enumerable: true,
-  get: function () { return chunk5VB22SYX_cjs.applyWalWithFallback; }
+  get: function () { return chunkDQZU7JK6_cjs.applyWalWithFallback; }
 });
 Object.defineProperty(exports, "isCorruptionError", {
   enumerable: true,
-  get: function () { return chunk5VB22SYX_cjs.isCorruptionError; }
+  get: function () { return chunkDQZU7JK6_cjs.isCorruptionError; }
 });
 Object.defineProperty(exports, "openSqliteResilient", {
   enumerable: true,
-  get: function () { return chunk5VB22SYX_cjs.openSqliteResilient; }
+  get: function () { return chunkDQZU7JK6_cjs.openSqliteResilient; }
 });
 Object.defineProperty(exports, "JsonlParseError", {
   enumerable: true,
-  get: function () { return chunkUU36SHFY_cjs.JsonlParseError; }
+  get: function () { return chunkBJUJT5ED_cjs.JsonlParseError; }
 });
 Object.defineProperty(exports, "appendJsonl", {
   enumerable: true,
-  get: function () { return chunkUU36SHFY_cjs.appendJsonl; }
+  get: function () { return chunkBJUJT5ED_cjs.appendJsonl; }
 });
 Object.defineProperty(exports, "loadJsonl", {
   enumerable: true,
-  get: function () { return chunkUU36SHFY_cjs.loadJsonl; }
+  get: function () { return chunkBJUJT5ED_cjs.loadJsonl; }
 });
 Object.defineProperty(exports, "readJsonlIds", {
   enumerable: true,
-  get: function () { return chunkUU36SHFY_cjs.readJsonlIds; }
+  get: function () { return chunkBJUJT5ED_cjs.readJsonlIds; }
 });
 Object.defineProperty(exports, "withFileLock", {
   enumerable: true,
-  get: function () { return chunkUU36SHFY_cjs.withFileLock; }
+  get: function () { return chunkBJUJT5ED_cjs.withFileLock; }
 });
 Object.defineProperty(exports, "withCwdMutex", {
   enumerable: true,
@@ -167,21 +166,22 @@ Object.defineProperty(exports, "withCwdMutex", {
 });
 Object.defineProperty(exports, "atomicWriteJson", {
   enumerable: true,
-  get: function () { return chunkUALX2J2Q_cjs.atomicWriteJson; }
+  get: function () { return chunkJLRLCBJ4_cjs.atomicWriteJson; }
 });
 Object.defineProperty(exports, "atomicWriteTempTarget", {
   enumerable: true,
-  get: function () { return chunkUALX2J2Q_cjs.atomicWriteTempTarget; }
+  get: function () { return chunkJLRLCBJ4_cjs.atomicWriteTempTarget; }
 });
 Object.defineProperty(exports, "atomicWriteText", {
   enumerable: true,
-  get: function () { return chunkUALX2J2Q_cjs.atomicWriteText; }
+  get: function () { return chunkJLRLCBJ4_cjs.atomicWriteText; }
 });
 Object.defineProperty(exports, "replaceFileAtomic", {
   enumerable: true,
-  get: function () { return chunkUALX2J2Q_cjs.replaceFileAtomic; }
+  get: function () { return chunkJLRLCBJ4_cjs.replaceFileAtomic; }
 });
-exports.LiveSessionError = LiveSessionError;
+exports.LiveSessionError = LiveTranscriptError;
+exports.LiveTranscriptError = LiveTranscriptError;
 exports.classifySessionArtifact = classifySessionArtifact;
 exports.forkTranscript = forkTranscript;
 exports.readJsonlTail = readJsonlTail;

package/dist/persistence.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/persistence/session-artifacts.ts","../src/internal/persistence/transcript-ops.ts"],"names":["atomicWriteTempTarget","TheokitAgentError","readFileSync","openSync","writeSync","closeSync","fstatSync","readSync"],"mappings":";;;;;;;;;;;;;;;;AA6BO,SAAS,uBAAA,CACd,MACA,WAAA,EAC6B;AAE7B,EAAA,IAAI,KAAK,QAAA,CAAS,aAAa,CAAA,EAAG,OAAO,cAAc,gBAAA,GAAmB,MAAA;AAC1E,EAAA,IAAI,aAAa,OAAO,MAAA;AACxB,EAAA,IAAI,IAAA,CAAK,QAAA,CAAS,QAAQ,CAAA,EAAG,OAAO,YAAA;AACpC,EAAA,IAAI,IAAA,CAAK,QAAA,CAAS,cAAc,CAAA,EAAG,OAAO,aAAA;AAC1C,EAAA,IAAIA,uCAAA,CAAsB,IAAI,CAAA,KAAM,MAAA,EAAW,OAAO,MAAA;AACtD,EAAA,OAAO,MAAA;AACT;ACNO,IAAM,gBAAA,GAAN,cAA+BC,mCAAA,CAAkB;AAAA,EAGtD,YAAqB,IAAA,EAAc;AACjC,IAAA,KAAA;AAAA,MACE,qDAAqD,IAAI,CAAA,+JAAA,CAAA;AAAA,MAGzD,EAAE,IAAA,EAAM,wBAAA,EAA0B,WAAA,EAAa,KAAA;AAAM,KACvD;AANmB,IAAA,IAAA,CAAA,IAAA,GAAA,IAAA;AAAA,EAOrB;AAAA,EAPqB,IAAA;AAAA,EAFH,IAAA,GAAO,kBAAA;AAU3B;AAmCO,SAAS,cAAA,CACd,GAAA,EACA,GAAA,EACA,OAAA,GAAiC,EAAC,EAC5B;AACN,EAAA,KAAA,MAAW,IAAA,IAAQ,OAAA,CAAQ,gBAAA,IAAoB,EAAC,EAAG;AACjD,IAAA,IAAI,IAAA,KAAS,GAAA,EAAK,MAAM,IAAI,iBAAiB,GAAG,CAAA;AAAA,EAClD;AAEA,EAAA,MAAM,KAAA,GAAQC,eAAA,CAAa,GAAA,EAAK,MAAM,EACnC,KAAA,CAAM,IAAI,CAAA,CACV,MAAA,CAAO,CAAC,CAAA,KAAM,CAAA,CAAE,IAAA,EAAK,CAAE,SAAS,CAAC,CAAA;AACpC,EAAA,MAAM,IAAA,GACJ,QAAQ,iBAAA,KAAsB,MAAA,GAAY,QAAQ,KAAA,CAAM,KAAA,CAAM,CAAA,EAAG,OAAA,CAAQ,iBAAiB,CAAA;AAC5F,EAAA,MAAM,IAAA,GAAO,KAAK,MAAA,GAAS,CAAA,GAAI,GAAG,IAAA,CAAK,IAAA,CAAK,IAAI,CAAC;AAAA,CAAA,GAAO,EAAA;AAIxD,EAAA,MAAM,KAAKC,WAAA,CAAS,GAAA,EAAK,IAAA,EAAM,OAAA,CAAQ,QAAQ,GAAK,CAAA;AACpD,EAAA,IAAI;AACF,IAAAC,YAAA,CAAU,IAAI,IAAI,CAAA;AAAA,EACpB,CAAA,SAAE;AACA,IAAAC,YAAA,CAAU,EAAE,CAAA;AAAA,EACd;AACF;AAiBA,IAAM,aAAa,EAAA,GAAK,IAAA;AASxB,SAAS,WAAA,CAAY,MAAc,IAAA,EAAsD;AAMvF,EAAA,MAAM,EAAA,GAAKF,WAAA,CAAS,IAAA,EAAM,GAAG,CAAA;AAC7B,EAAA,MAAM,IAAA,GAAOG,YAAA,CAAU,EAAE,CAAA,CAAE,IAAA;AAC3B,EAAA,IAAI,SAAA,GAAY,CAAA;AAChB,EAAA,IAAI,IAAA,GAAO,EAAA;AACX,EAAA,IAAI,GAAA,GAAM,IAAA;AACV,EAAA,IAAI;AACF,IAAA,OAAO,MAAM,CAAA,EAAG;AACd,MAAA,MAAM,GAAA,GAAM,IAAA,CAAK,GAAA,CAAI,UAAA,EAAY,GAAG,CAAA;AACpC,MAAA,GAAA,IAAO,GAAA;AACP,MAAA,MAAM,GAAA,GAAM,MAAA,CAAO,KAAA,CAAM,GAAG,CAAA;AAC5B,MAAAC,WAAA,CAAS,EAAA,EAAI,GAAA,EAAK,CAAA,EAAG,GAAA,EAAK,GAAG,CAAA;AAC7B,MAAA,SAAA,IAAa,GAAA;AACb,MAAA,IAAA,GAAO,GAAA,CAAI,QAAA,CAAS,MAAM,CAAA,GAAI,IAAA;AAC9B,MAAA,IAAI,aAAA,CAAc,IAAI,CAAA,CAAE,MAAA,GAAS,IAAA,EAAM;AAAA,IACzC;AAAA,EACF,CAAA,SAAE;AACA,IAAAF,YAAA,CAAU,EAAE,CAAA;AAAA,EACd;AACA,EAAA,MAAM,KAAA,GAAQ,cAAc,IAAI,CAAA;AAChC,EAAA,OAAO,EAAE,OAAO,GAAA,GAAM,CAAA,GAAI,MAAM,KAAA,CAAM,CAAC,CAAA,GAAI,KAAA,EAAO,SAAA,EAAU;AAC9D;AAGA,SAAS,cAAc,IAAA,EAAwB;AAC7C,EAAA,OAAO,IAAA,CAAK,KAAA,CAAM,IAAI,CAAA,CAAE,MAAA,CAAO,CAAC,CAAA,KAAM,CAAA,CAAE,IAAA,EAAK,CAAE,MAAA,GAAS,CAAC,CAAA;AAC3D;AAYA,SAAS,cAAA,CAAe,MAAc,MAAA,EAAyB;AAC7D,EAAA,IAAI,MAAA;AACJ,EAAA,IAAI;AACF,IAAA,MAAA,GAAS,IAAA,CAAK,MAAM,IAAI,CAAA;AAAA,EAC1B,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,KAAA;AAAA,EACT;AACA,EAAA,OAAO,MAAA,CAAO,OAAA,KAAY,MAAA,IAAU,MAAA,CAAO,IAAA,KAAS,MAAA;AACtD;AASO,SAAS,aAAA,CACd,IAAA,EACA,OAAA,GAAgC,EAAC,EAC5B;AACL,EAAA,MAAM,IAAA,GAAO,OAAA,CAAQ,UAAA,IAAc,MAAA,CAAO,iBAAA;AAC1C,EAAA,MAAM,EAAE,KAAA,EAAO,SAAA,EAAU,GAAI,WAAA,CAAY,MAAM,IAAI,CAAA;AAEnD,EAAA,IAAI,GAAA,GAAM,KAAA;AACV,EAAA,IAAI,OAAA,CAAQ,gBAAgB,MAAA,EAAW;AACrC,IAAA,MAAM,SAAS,OAAA,CAAQ,WAAA;AAOvB,IAAA,MAAM,GAAA,GAAM,IAAI,aAAA,CAAc,CAAC,MAAM,cAAA,CAAe,CAAA,EAAG,MAAM,CAAC,CAAA;AAC9D,IAAA,IAAI,OAAO,CAAA,EAAG,GAAA,GAAM,GAAA,CAAI,KAAA,CAAM,MAAM,CAAC,CAAA;AAAA,EACvC;AACA,EAAA,IAAI,MAAA,CAAO,SAAS,IAAI,CAAA,QAAS,GAAA,CAAI,KAAA,CAAM,CAAC,IAAI,CAAA;AAEhD,EAAA,MAAM,GAAA,GAAM,IAAI,GAAA,CAAI,CAAC,MAAM,IAAA,CAAK,KAAA,CAAM,CAAC,CAAM,CAAA;AAC7C,EAAA,OAAO,OAAA,CAAQ,WAAW,IAAA,GAAQ,MAAA,CAAO,OAAO,GAAA,EAAK,EAAE,SAAA,EAAW,CAAA,GAAY,GAAA;AAChF","file":"persistence.cjs","sourcesContent":["import { atomicWriteTempTarget } from \"./atomic-write.js\";\n\n/**\n * The kinds of file this SDK leaves in a project's transcript directory.\n *\n * - `transcript` — the session itself (`transcriptPath`).\n * - `writer-lock` — the cross-process writer lease (`session-writer.ts`, `<file>.writer.lock`).\n * - `lock-directory` — `withFileLock`'s companion, taken by `mkdir`, so it is a DIRECTORY.\n * - `temp` — what `replaceFileAtomic` leaves when a process dies between the open and the rename.\n */\nexport type SessionArtifact = \"transcript\" | \"writer-lock\" | \"lock-directory\" | \"temp\";\n\n/**\n * U-1 — what is this entry, if it is one of ours?\n *\n * The SDK writes four kinds of file into a project directory and reasons about none of them\n * afterwards: there is no retention, no collector, and there was no way even to ask what an entry\n * IS. A consumer wanting to reclaim disk had to re-derive the suffixes by reading this source — and\n * one did, which means a suffix changing here would have left its classifier silently mislabelling\n * files on a path that deletes them.\n *\n * This is deliberately NOT a garbage collector. Retention is policy — how many days, how many to\n * keep, which session is live, whether to delete at all — and policy belongs to the application,\n * which is the only one that can know. What belongs here is the half only the SDK can answer.\n *\n * `undefined` means \"not written by this SDK\", and it is the answer that matters most: a caller\n * deleting what it does not recognise is how an editor's swap file gets collected. The `temp` case\n * defers to {@link atomicWriteTempTarget} rather than matching `.tmp`, for exactly that reason.\n */\nexport function classifySessionArtifact(\n  name: string,\n  isDirectory: boolean,\n): SessionArtifact | undefined {\n  // `withFileLock` takes its lock by `mkdir`, so the same name as a plain file is not ours.\n  if (name.endsWith(\".jsonl.lock\")) return isDirectory ? \"lock-directory\" : undefined;\n  if (isDirectory) return undefined;\n  if (name.endsWith(\".jsonl\")) return \"transcript\";\n  if (name.endsWith(\".writer.lock\")) return \"writer-lock\";\n  if (atomicWriteTempTarget(name) !== undefined) return \"temp\";\n  return undefined;\n}\n","/**\n * M81 — transcript operations the consumer was doing by hand INSIDE the framework's own store.\n *\n * ## What this replaces\n *\n * `agents/lib/session/backtrack.ts:188` (agent-builder) wrote straight into the session store with a\n * bare `writeFileSync` — no atomicity, no lock, no API. 243 lines re-implementing parse, cut and\n * write for a format the framework owns. The consumer is not at fault: nothing here was reachable.\n *\n * ## The rule that travels WITH the operation\n *\n * `rules/audit-trail-rotation.md § Session transcripts (M60)` defines a NEVER-delete list — the live\n * pointer, the most recent transcript, and any active registry entry. That rule lived in the\n * CONSUMER. Moving the operation here without moving the rule would ship an API able to destroy\n * exactly what the rule protects — the same shape of defect as M80's `reconcileUpdateGoalStatus`:\n * critical knowledge outside the module that needs it, applied by convention.\n *\n * So `forkTranscript` takes `liveSessionPaths` and refuses, with a TYPED error, to write over any of\n * them. The caller supplies the list because only the caller knows which session is live; the\n * enforcement lives here because that is where the write happens.\n *\n * @internal\n */\n\nimport { closeSync, fstatSync, openSync, readFileSync, readSync, writeSync } from \"node:fs\";\n\nimport { TheokitAgentError } from \"../../errors.js\";\n\n/**\n * M81 — the target is a protected session (live pointer / most-recent transcript / active entry).\n *\n * Typed rather than a bare `Error` because the caller must distinguish \"this session is protected\"\n * from \"the disk is full\": the first is a correct refusal, the second is an incident.\n */\nexport class LiveSessionError extends TheokitAgentError {\n  override readonly name = \"LiveSessionError\";\n\n  constructor(readonly path: string) {\n    super(\n      `refusing to write over a live session transcript: ${path}. ` +\n        \"Fork to a new id instead — the live pointer, the most recent transcript and any active \" +\n        \"registry entry are never overwritten (audit-trail rotation, M60).\",\n      { code: \"live_session_protected\", isRetryable: false },\n    );\n  }\n}\n\n/** Options for {@link forkTranscript}. */\nexport interface ForkTranscriptOptions {\n  /** Keep records `[0, beforeRecordIndex)`. Omit to copy the whole transcript. */\n  readonly beforeRecordIndex?: number;\n  /**\n   * Paths that must never be written over — the live pointer, the most recent transcript, any active\n   * registry entry. The caller supplies them because only the caller knows which session is live.\n   */\n  readonly liveSessionPaths?: readonly string[];\n  /**\n   * M107 — permission bits for the created destination. Default: `0o600`.\n   *\n   * A transcript carries the conversation. Before M107 no mode was passed at all, so the file was\n   * born `0o666 & ~umask` — measured `0o664` (group-WRITABLE) on a `umask 002` machine, `0o644` on\n   * `umask 022`, `0o466` on `umask 0200`. This is a DEFAULT and not a required knob on purpose: a\n   * knob would reach zero consumers by omission, which is the failure mode that matters.\n   *\n   * As with any `open` mode, the `umask` may still CLEAR bits — under `umask 0200` the result is\n   * `0o400`. That is accepted: the invariant bought here is \"neither group nor others\", and `0o400`\n   * satisfies it more strictly. The SDK deliberately does not `fchmod` the default back, because\n   * that would hand back a bit the operator asked to remove.\n   */\n  readonly mode?: number;\n}\n\n/**\n * Copy `src` into `dst`, keeping the first `beforeRecordIndex` records. The SOURCE is never touched.\n *\n * Atomicity comes from `wx` (exclusive create): two concurrent forks to the same destination cannot\n * both succeed — the loser gets `EEXIST` rather than writing over a half-written file. That is also\n * why an existing destination is a refusal, not a silent overwrite: losing a transcript without an\n * error is the worst failure mode for an operation that touches user sessions.\n */\nexport function forkTranscript(\n  src: string,\n  dst: string,\n  options: ForkTranscriptOptions = {},\n): void {\n  for (const live of options.liveSessionPaths ?? []) {\n    if (live === dst) throw new LiveSessionError(dst);\n  }\n\n  const lines = readFileSync(src, \"utf8\")\n    .split(\"\\n\")\n    .filter((l) => l.trim().length > 0);\n  const kept =\n    options.beforeRecordIndex === undefined ? lines : lines.slice(0, options.beforeRecordIndex);\n  const body = kept.length > 0 ? `${kept.join(\"\\n\")}\\n` : \"\";\n\n  // `wx` — fails with EEXIST instead of truncating. The exclusivity IS the concurrency guarantee,\n  // and M107 only added the third argument: the mode. See `ForkTranscriptOptions.mode`.\n  const fd = openSync(dst, \"wx\", options.mode ?? 0o600);\n  try {\n    writeSync(fd, body);\n  } finally {\n    closeSync(fd);\n  }\n}\n\n/** Options for {@link readJsonlTail}. */\nexport interface ReadJsonlTailOptions {\n  /** Maximum records to return, counted from the END. */\n  readonly maxRecords?: number;\n  /**\n   * Start the window AFTER the last record whose `subtype` (or `type`) equals this.\n   *\n   * Matched STRUCTURALLY since T2.5. It used to be `line.includes(marker)`, so any message\n   * mentioning the marker in its text truncated the read — silently, with a successful return.\n   */\n  readonly sinceMarker?: string;\n  /** Test-only: also report how many bytes were read, to prove the read is not whole-file. */\n  readonly _stats?: boolean;\n}\n\nconst TAIL_CHUNK = 64 * 1024;\n\n/**\n * Reads chunks backwards until enough complete lines have accumulated.\n *\n * Extracted from `readJsonlTail` because the read loop and the record selection are two\n * responsibilities — and together they exceeded the complexity ceiling. The buffer's first line may\n * be cut in half when the read stopped before the start of the file; that is why it is discarded.\n */\nfunction readRawTail(path: string, want: number): { lines: string[]; bytesRead: number } {\n  // Opened FIRST, then sized through the descriptor. `statSync(path)` followed by\n  // `openSync(path)` resolves the name twice, and `size` is what drives every read offset below —\n  // so a path that changed between the two calls would have the loop seeking by one file's length\n  // inside another (CodeQL js/file-system-race #19). `fstat` on the open fd describes the file\n  // being read, by construction.\n  const fd = openSync(path, \"r\");\n  const size = fstatSync(fd).size;\n  let bytesRead = 0;\n  let tail = \"\";\n  let pos = size;\n  try {\n    while (pos > 0) {\n      const len = Math.min(TAIL_CHUNK, pos);\n      pos -= len;\n      const buf = Buffer.alloc(len);\n      readSync(fd, buf, 0, len, pos);\n      bytesRead += len;\n      tail = buf.toString(\"utf8\") + tail;\n      if (nonEmptyLines(tail).length > want) break;\n    }\n  } finally {\n    closeSync(fd);\n  }\n  const lines = nonEmptyLines(tail);\n  return { lines: pos > 0 ? lines.slice(1) : lines, bytesRead };\n}\n\n/** Non-empty lines, in file order. */\nfunction nonEmptyLines(text: string): string[] {\n  return text.split(\"\\n\").filter((l) => l.trim().length > 0);\n}\n\n/**\n * Whether a raw JSONL line IS the marker record, rather than a line that talks about it.\n *\n * Matches on the record's own discriminants (`subtype`, then `type`) — the fields that identify\n * what a record *is*. Free text is never consulted, which is the whole point: content is the user's\n * and must not steer the reader.\n *\n * A line that does not parse is not a marker. Deciding a window boundary from bytes that are not a\n * record would be guessing, and this function exists because guessing is what it replaced.\n */\nfunction isMarkerRecord(line: string, marker: string): boolean {\n  let record: { type?: unknown; subtype?: unknown };\n  try {\n    record = JSON.parse(line) as { type?: unknown; subtype?: unknown };\n  } catch {\n    return false;\n  }\n  return record.subtype === marker || record.type === marker;\n}\n\n/**\n * Read the LAST records of a JSONL file without loading the whole thing.\n *\n * Reads fixed-size chunks backwards from EOF until enough newlines have been seen. A session\n * transcript grows without bound; loading megabytes to show the last three turns is the cost this\n * exists to avoid — and a `slice` over a full read would be that same cost with a better name.\n */\nexport function readJsonlTail<T = Record<string, unknown>>(\n  path: string,\n  options: ReadJsonlTailOptions = {},\n): T[] {\n  const want = options.maxRecords ?? Number.POSITIVE_INFINITY;\n  const { lines, bytesRead } = readRawTail(path, want);\n\n  let sel = lines;\n  if (options.sinceMarker !== undefined) {\n    const marker = options.sinceMarker;\n    // STRUCTURAL, not `line.includes(marker)`.\n    //\n    // A raw substring match is true for any line that merely MENTIONS the marker — a user asking\n    // \"how does compact_boundary work?\" silently truncated the window to start at their question.\n    // The read then succeeded, returned fewer records than exist, and said nothing. That is the\n    // measured reason the only would-be consumer kept its own reader instead of this one.\n    const idx = sel.findLastIndex((l) => isMarkerRecord(l, marker));\n    if (idx >= 0) sel = sel.slice(idx + 1);\n  }\n  if (Number.isFinite(want)) sel = sel.slice(-want);\n\n  const out = sel.map((l) => JSON.parse(l) as T);\n  return options._stats === true ? (Object.assign(out, { bytesRead }) as T[]) : out;\n}\n"]}
+{"version":3,"sources":["../src/internal/persistence/session-artifacts.ts","../src/internal/persistence/transcript-ops.ts"],"names":["atomicWriteTempTarget","TheokitAgentError","readFileSync","openSync","writeSync","closeSync","fstatSync","readSync"],"mappings":";;;;;;;;;;;;;;;AA6BO,SAAS,uBAAA,CACd,MACA,WAAA,EAC6B;AAE7B,EAAA,IAAI,KAAK,QAAA,CAAS,aAAa,CAAA,EAAG,OAAO,cAAc,gBAAA,GAAmB,MAAA;AAC1E,EAAA,IAAI,aAAa,OAAO,MAAA;AACxB,EAAA,IAAI,IAAA,CAAK,QAAA,CAAS,QAAQ,CAAA,EAAG,OAAO,YAAA;AACpC,EAAA,IAAI,IAAA,CAAK,QAAA,CAAS,cAAc,CAAA,EAAG,OAAO,aAAA;AAC1C,EAAA,IAAIA,uCAAA,CAAsB,IAAI,CAAA,KAAM,MAAA,EAAW,OAAO,MAAA;AACtD,EAAA,OAAO,MAAA;AACT;ACGO,IAAM,mBAAA,GAAN,cAAkCC,mCAAA,CAAkB;AAAA,EAGzD,YAAqB,IAAA,EAAc;AACjC,IAAA,KAAA;AAAA,MACE,qDAAqD,IAAI,CAAA,+JAAA,CAAA;AAAA,MAGzD,EAAE,IAAA,EAAM,wBAAA,EAA0B,WAAA,EAAa,KAAA;AAAM,KACvD;AANmB,IAAA,IAAA,CAAA,IAAA,GAAA,IAAA;AAAA,EAOrB;AAAA,EAPqB,IAAA;AAAA,EAFH,IAAA,GAAO,qBAAA;AAU3B;AAmCO,SAAS,cAAA,CACd,GAAA,EACA,GAAA,EACA,OAAA,GAAiC,EAAC,EAC5B;AACN,EAAA,KAAA,MAAW,IAAA,IAAQ,OAAA,CAAQ,gBAAA,IAAoB,EAAC,EAAG;AACjD,IAAA,IAAI,IAAA,KAAS,GAAA,EAAK,MAAM,IAAI,oBAAoB,GAAG,CAAA;AAAA,EACrD;AAEA,EAAA,MAAM,KAAA,GAAQC,eAAA,CAAa,GAAA,EAAK,MAAM,EACnC,KAAA,CAAM,IAAI,CAAA,CACV,MAAA,CAAO,CAAC,CAAA,KAAM,CAAA,CAAE,IAAA,EAAK,CAAE,SAAS,CAAC,CAAA;AACpC,EAAA,MAAM,IAAA,GACJ,QAAQ,iBAAA,KAAsB,MAAA,GAAY,QAAQ,KAAA,CAAM,KAAA,CAAM,CAAA,EAAG,OAAA,CAAQ,iBAAiB,CAAA;AAC5F,EAAA,MAAM,IAAA,GAAO,KAAK,MAAA,GAAS,CAAA,GAAI,GAAG,IAAA,CAAK,IAAA,CAAK,IAAI,CAAC;AAAA,CAAA,GAAO,EAAA;AAIxD,EAAA,MAAM,KAAKC,WAAA,CAAS,GAAA,EAAK,IAAA,EAAM,OAAA,CAAQ,QAAQ,GAAK,CAAA;AACpD,EAAA,IAAI;AACF,IAAAC,YAAA,CAAU,IAAI,IAAI,CAAA;AAAA,EACpB,CAAA,SAAE;AACA,IAAAC,YAAA,CAAU,EAAE,CAAA;AAAA,EACd;AACF;AAiBA,IAAM,aAAa,EAAA,GAAK,IAAA;AASxB,SAAS,WAAA,CAAY,MAAc,IAAA,EAAsD;AAMvF,EAAA,MAAM,EAAA,GAAKF,WAAA,CAAS,IAAA,EAAM,GAAG,CAAA;AAC7B,EAAA,MAAM,IAAA,GAAOG,YAAA,CAAU,EAAE,CAAA,CAAE,IAAA;AAC3B,EAAA,IAAI,SAAA,GAAY,CAAA;AAChB,EAAA,IAAI,IAAA,GAAO,EAAA;AACX,EAAA,IAAI,GAAA,GAAM,IAAA;AACV,EAAA,IAAI;AACF,IAAA,OAAO,MAAM,CAAA,EAAG;AACd,MAAA,MAAM,GAAA,GAAM,IAAA,CAAK,GAAA,CAAI,UAAA,EAAY,GAAG,CAAA;AACpC,MAAA,GAAA,IAAO,GAAA;AACP,MAAA,MAAM,GAAA,GAAM,MAAA,CAAO,KAAA,CAAM,GAAG,CAAA;AAC5B,MAAAC,WAAA,CAAS,EAAA,EAAI,GAAA,EAAK,CAAA,EAAG,GAAA,EAAK,GAAG,CAAA;AAC7B,MAAA,SAAA,IAAa,GAAA;AACb,MAAA,IAAA,GAAO,GAAA,CAAI,QAAA,CAAS,MAAM,CAAA,GAAI,IAAA;AAC9B,MAAA,IAAI,aAAA,CAAc,IAAI,CAAA,CAAE,MAAA,GAAS,IAAA,EAAM;AAAA,IACzC;AAAA,EACF,CAAA,SAAE;AACA,IAAAF,YAAA,CAAU,EAAE,CAAA;AAAA,EACd;AACA,EAAA,MAAM,KAAA,GAAQ,cAAc,IAAI,CAAA;AAChC,EAAA,OAAO,EAAE,OAAO,GAAA,GAAM,CAAA,GAAI,MAAM,KAAA,CAAM,CAAC,CAAA,GAAI,KAAA,EAAO,SAAA,EAAU;AAC9D;AAGA,SAAS,cAAc,IAAA,EAAwB;AAC7C,EAAA,OAAO,IAAA,CAAK,KAAA,CAAM,IAAI,CAAA,CAAE,MAAA,CAAO,CAAC,CAAA,KAAM,CAAA,CAAE,IAAA,EAAK,CAAE,MAAA,GAAS,CAAC,CAAA;AAC3D;AAYA,SAAS,cAAA,CAAe,MAAc,MAAA,EAAyB;AAC7D,EAAA,IAAI,MAAA;AACJ,EAAA,IAAI;AACF,IAAA,MAAA,GAAS,IAAA,CAAK,MAAM,IAAI,CAAA;AAAA,EAC1B,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,KAAA;AAAA,EACT;AACA,EAAA,OAAO,MAAA,CAAO,OAAA,KAAY,MAAA,IAAU,MAAA,CAAO,IAAA,KAAS,MAAA;AACtD;AASO,SAAS,aAAA,CACd,IAAA,EACA,OAAA,GAAgC,EAAC,EAC5B;AACL,EAAA,MAAM,IAAA,GAAO,OAAA,CAAQ,UAAA,IAAc,MAAA,CAAO,iBAAA;AAC1C,EAAA,MAAM,EAAE,KAAA,EAAO,SAAA,EAAU,GAAI,WAAA,CAAY,MAAM,IAAI,CAAA;AAEnD,EAAA,IAAI,GAAA,GAAM,KAAA;AACV,EAAA,IAAI,OAAA,CAAQ,gBAAgB,MAAA,EAAW;AACrC,IAAA,MAAM,SAAS,OAAA,CAAQ,WAAA;AAOvB,IAAA,MAAM,GAAA,GAAM,IAAI,aAAA,CAAc,CAAC,MAAM,cAAA,CAAe,CAAA,EAAG,MAAM,CAAC,CAAA;AAC9D,IAAA,IAAI,OAAO,CAAA,EAAG,GAAA,GAAM,GAAA,CAAI,KAAA,CAAM,MAAM,CAAC,CAAA;AAAA,EACvC;AACA,EAAA,IAAI,MAAA,CAAO,SAAS,IAAI,CAAA,QAAS,GAAA,CAAI,KAAA,CAAM,CAAC,IAAI,CAAA;AAEhD,EAAA,MAAM,GAAA,GAAM,IAAI,GAAA,CAAI,CAAC,MAAM,IAAA,CAAK,KAAA,CAAM,CAAC,CAAM,CAAA;AAC7C,EAAA,OAAO,OAAA,CAAQ,WAAW,IAAA,GAAQ,MAAA,CAAO,OAAO,GAAA,EAAK,EAAE,SAAA,EAAW,CAAA,GAAY,GAAA;AAChF","file":"persistence.cjs","sourcesContent":["import { atomicWriteTempTarget } from \"./atomic-write.js\";\n\n/**\n * The kinds of file this SDK leaves in a project's transcript directory.\n *\n * - `transcript` — the session itself (`transcriptPath`).\n * - `writer-lock` — the cross-process writer lease (`session-writer.ts`, `<file>.writer.lock`).\n * - `lock-directory` — `withFileLock`'s companion, taken by `mkdir`, so it is a DIRECTORY.\n * - `temp` — what `replaceFileAtomic` leaves when a process dies between the open and the rename.\n */\nexport type SessionArtifact = \"transcript\" | \"writer-lock\" | \"lock-directory\" | \"temp\";\n\n/**\n * U-1 — what is this entry, if it is one of ours?\n *\n * The SDK writes four kinds of file into a project directory and reasons about none of them\n * afterwards: there is no retention, no collector, and there was no way even to ask what an entry\n * IS. A consumer wanting to reclaim disk had to re-derive the suffixes by reading this source — and\n * one did, which means a suffix changing here would have left its classifier silently mislabelling\n * files on a path that deletes them.\n *\n * This is deliberately NOT a garbage collector. Retention is policy — how many days, how many to\n * keep, which session is live, whether to delete at all — and policy belongs to the application,\n * which is the only one that can know. What belongs here is the half only the SDK can answer.\n *\n * `undefined` means \"not written by this SDK\", and it is the answer that matters most: a caller\n * deleting what it does not recognise is how an editor's swap file gets collected. The `temp` case\n * defers to {@link atomicWriteTempTarget} rather than matching `.tmp`, for exactly that reason.\n */\nexport function classifySessionArtifact(\n  name: string,\n  isDirectory: boolean,\n): SessionArtifact | undefined {\n  // `withFileLock` takes its lock by `mkdir`, so the same name as a plain file is not ours.\n  if (name.endsWith(\".jsonl.lock\")) return isDirectory ? \"lock-directory\" : undefined;\n  if (isDirectory) return undefined;\n  if (name.endsWith(\".jsonl\")) return \"transcript\";\n  if (name.endsWith(\".writer.lock\")) return \"writer-lock\";\n  if (atomicWriteTempTarget(name) !== undefined) return \"temp\";\n  return undefined;\n}\n","/**\n * M81 — transcript operations the consumer was doing by hand INSIDE the framework's own store.\n *\n * ## What this replaces\n *\n * `agents/lib/session/backtrack.ts:188` (agent-builder) wrote straight into the session store with a\n * bare `writeFileSync` — no atomicity, no lock, no API. 243 lines re-implementing parse, cut and\n * write for a format the framework owns. The consumer is not at fault: nothing here was reachable.\n *\n * ## The rule that travels WITH the operation\n *\n * `rules/audit-trail-rotation.md § Session transcripts (M60)` defines a NEVER-delete list — the live\n * pointer, the most recent transcript, and any active registry entry. That rule lived in the\n * CONSUMER. Moving the operation here without moving the rule would ship an API able to destroy\n * exactly what the rule protects — the same shape of defect as M80's `reconcileUpdateGoalStatus`:\n * critical knowledge outside the module that needs it, applied by convention.\n *\n * So `forkTranscript` takes `liveSessionPaths` and refuses, with a TYPED error, to write over any of\n * them. The caller supplies the list because only the caller knows which session is live; the\n * enforcement lives here because that is where the write happens.\n *\n * @internal\n */\n\nimport { closeSync, fstatSync, openSync, readFileSync, readSync, writeSync } from \"node:fs\";\n\nimport { TheokitAgentError } from \"../../errors.js\";\n\n/**\n * M81 — the target is a protected session (live pointer / most-recent transcript / active entry).\n *\n * Typed rather than a bare `Error` because the caller must distinguish \"this session is protected\"\n * from \"the disk is full\": the first is a correct refusal, the second is an incident.\n *\n * RENAMED from `LiveSessionError` (2026-09-01). `session-guard.ts` exports a DIFFERENT class of that\n * name from the root barrel, with an incompatible shape — `(sessionId, reason)` and a `reason`\n * field, against this one's `(path)` and `code: \"live_session_protected\"` — and `.` and\n * `./persistence` are both declared subpaths, so one consumer can hold both. `instanceof` never\n * crossed the pair, so a `catch` checking the root import silently missed this one and ran its\n * fallback for a condition it believed it handled; `err.name` matched BOTH, so a name check looked\n * right and then read `err.reason`, which only the other one has. The names now say what each\n * refusal is about: destroying a SESSION, versus overwriting a TRANSCRIPT file.\n */\nexport class LiveTranscriptError extends TheokitAgentError {\n  override readonly name = \"LiveTranscriptError\";\n\n  constructor(readonly path: string) {\n    super(\n      `refusing to write over a live session transcript: ${path}. ` +\n        \"Fork to a new id instead — the live pointer, the most recent transcript and any active \" +\n        \"registry entry are never overwritten (audit-trail rotation, M60).\",\n      { code: \"live_session_protected\", isRetryable: false },\n    );\n  }\n}\n\n/** Options for {@link forkTranscript}. */\nexport interface ForkTranscriptOptions {\n  /** Keep records `[0, beforeRecordIndex)`. Omit to copy the whole transcript. */\n  readonly beforeRecordIndex?: number;\n  /**\n   * Paths that must never be written over — the live pointer, the most recent transcript, any active\n   * registry entry. The caller supplies them because only the caller knows which session is live.\n   */\n  readonly liveSessionPaths?: readonly string[];\n  /**\n   * M107 — permission bits for the created destination. Default: `0o600`.\n   *\n   * A transcript carries the conversation. Before M107 no mode was passed at all, so the file was\n   * born `0o666 & ~umask` — measured `0o664` (group-WRITABLE) on a `umask 002` machine, `0o644` on\n   * `umask 022`, `0o466` on `umask 0200`. This is a DEFAULT and not a required knob on purpose: a\n   * knob would reach zero consumers by omission, which is the failure mode that matters.\n   *\n   * As with any `open` mode, the `umask` may still CLEAR bits — under `umask 0200` the result is\n   * `0o400`. That is accepted: the invariant bought here is \"neither group nor others\", and `0o400`\n   * satisfies it more strictly. The SDK deliberately does not `fchmod` the default back, because\n   * that would hand back a bit the operator asked to remove.\n   */\n  readonly mode?: number;\n}\n\n/**\n * Copy `src` into `dst`, keeping the first `beforeRecordIndex` records. The SOURCE is never touched.\n *\n * Atomicity comes from `wx` (exclusive create): two concurrent forks to the same destination cannot\n * both succeed — the loser gets `EEXIST` rather than writing over a half-written file. That is also\n * why an existing destination is a refusal, not a silent overwrite: losing a transcript without an\n * error is the worst failure mode for an operation that touches user sessions.\n */\nexport function forkTranscript(\n  src: string,\n  dst: string,\n  options: ForkTranscriptOptions = {},\n): void {\n  for (const live of options.liveSessionPaths ?? []) {\n    if (live === dst) throw new LiveTranscriptError(dst);\n  }\n\n  const lines = readFileSync(src, \"utf8\")\n    .split(\"\\n\")\n    .filter((l) => l.trim().length > 0);\n  const kept =\n    options.beforeRecordIndex === undefined ? lines : lines.slice(0, options.beforeRecordIndex);\n  const body = kept.length > 0 ? `${kept.join(\"\\n\")}\\n` : \"\";\n\n  // `wx` — fails with EEXIST instead of truncating. The exclusivity IS the concurrency guarantee,\n  // and M107 only added the third argument: the mode. See `ForkTranscriptOptions.mode`.\n  const fd = openSync(dst, \"wx\", options.mode ?? 0o600);\n  try {\n    writeSync(fd, body);\n  } finally {\n    closeSync(fd);\n  }\n}\n\n/** Options for {@link readJsonlTail}. */\nexport interface ReadJsonlTailOptions {\n  /** Maximum records to return, counted from the END. */\n  readonly maxRecords?: number;\n  /**\n   * Start the window AFTER the last record whose `subtype` (or `type`) equals this.\n   *\n   * Matched STRUCTURALLY since T2.5. It used to be `line.includes(marker)`, so any message\n   * mentioning the marker in its text truncated the read — silently, with a successful return.\n   */\n  readonly sinceMarker?: string;\n  /** Test-only: also report how many bytes were read, to prove the read is not whole-file. */\n  readonly _stats?: boolean;\n}\n\nconst TAIL_CHUNK = 64 * 1024;\n\n/**\n * Reads chunks backwards until enough complete lines have accumulated.\n *\n * Extracted from `readJsonlTail` because the read loop and the record selection are two\n * responsibilities — and together they exceeded the complexity ceiling. The buffer's first line may\n * be cut in half when the read stopped before the start of the file; that is why it is discarded.\n */\nfunction readRawTail(path: string, want: number): { lines: string[]; bytesRead: number } {\n  // Opened FIRST, then sized through the descriptor. `statSync(path)` followed by\n  // `openSync(path)` resolves the name twice, and `size` is what drives every read offset below —\n  // so a path that changed between the two calls would have the loop seeking by one file's length\n  // inside another (CodeQL js/file-system-race #19). `fstat` on the open fd describes the file\n  // being read, by construction.\n  const fd = openSync(path, \"r\");\n  const size = fstatSync(fd).size;\n  let bytesRead = 0;\n  let tail = \"\";\n  let pos = size;\n  try {\n    while (pos > 0) {\n      const len = Math.min(TAIL_CHUNK, pos);\n      pos -= len;\n      const buf = Buffer.alloc(len);\n      readSync(fd, buf, 0, len, pos);\n      bytesRead += len;\n      tail = buf.toString(\"utf8\") + tail;\n      if (nonEmptyLines(tail).length > want) break;\n    }\n  } finally {\n    closeSync(fd);\n  }\n  const lines = nonEmptyLines(tail);\n  return { lines: pos > 0 ? lines.slice(1) : lines, bytesRead };\n}\n\n/** Non-empty lines, in file order. */\nfunction nonEmptyLines(text: string): string[] {\n  return text.split(\"\\n\").filter((l) => l.trim().length > 0);\n}\n\n/**\n * Whether a raw JSONL line IS the marker record, rather than a line that talks about it.\n *\n * Matches on the record's own discriminants (`subtype`, then `type`) — the fields that identify\n * what a record *is*. Free text is never consulted, which is the whole point: content is the user's\n * and must not steer the reader.\n *\n * A line that does not parse is not a marker. Deciding a window boundary from bytes that are not a\n * record would be guessing, and this function exists because guessing is what it replaced.\n */\nfunction isMarkerRecord(line: string, marker: string): boolean {\n  let record: { type?: unknown; subtype?: unknown };\n  try {\n    record = JSON.parse(line) as { type?: unknown; subtype?: unknown };\n  } catch {\n    return false;\n  }\n  return record.subtype === marker || record.type === marker;\n}\n\n/**\n * Read the LAST records of a JSONL file without loading the whole thing.\n *\n * Reads fixed-size chunks backwards from EOF until enough newlines have been seen. A session\n * transcript grows without bound; loading megabytes to show the last three turns is the cost this\n * exists to avoid — and a `slice` over a full read would be that same cost with a better name.\n */\nexport function readJsonlTail<T = Record<string, unknown>>(\n  path: string,\n  options: ReadJsonlTailOptions = {},\n): T[] {\n  const want = options.maxRecords ?? Number.POSITIVE_INFINITY;\n  const { lines, bytesRead } = readRawTail(path, want);\n\n  let sel = lines;\n  if (options.sinceMarker !== undefined) {\n    const marker = options.sinceMarker;\n    // STRUCTURAL, not `line.includes(marker)`.\n    //\n    // A raw substring match is true for any line that merely MENTIONS the marker — a user asking\n    // \"how does compact_boundary work?\" silently truncated the window to start at their question.\n    // The read then succeeded, returned fewer records than exist, and said nothing. That is the\n    // measured reason the only would-be consumer kept its own reader instead of this one.\n    const idx = sel.findLastIndex((l) => isMarkerRecord(l, marker));\n    if (idx >= 0) sel = sel.slice(idx + 1);\n  }\n  if (Number.isFinite(want)) sel = sel.slice(-want);\n\n  const out = sel.map((l) => JSON.parse(l) as T);\n  return options._stats === true ? (Object.assign(out, { bytesRead }) as T[]) : out;\n}\n"]}

package/dist/persistence.d.cts

@@ -1,4 +1,6 @@
 /**
+ * Published as `@theokit/sdk/persistence`.
+ *
  * Public persistence primitives (V2-3 — Theo Harness Capability Map, Theme G).
  *
  * Promotes the consumer-grade persistence helpers from `internal/persistence`
@@ -28,5 +30,11 @@ export type { OpenSqliteResilientOptions, ResilientSqliteDb, } from "./internal/
 export { isCorruptionError, openSqliteResilient } from "./internal/persistence/sqlite-open.js";
 export type { WalApplyResult } from "./internal/persistence/sqlite-wal.js";
 export { applyWalWithFallback } from "./internal/persistence/sqlite-wal.js";
-export { type ForkTranscriptOptions, forkTranscript, LiveSessionError, type ReadJsonlTailOptions, readJsonlTail, } from "./internal/persistence/transcript-ops.js";
+/**
+ * @deprecated Renamed to {@link LiveTranscriptError}. The root barrel exports a DIFFERENT class
+ * under this name (`session-guard.ts`, about refusing to destroy a session), and a consumer holding
+ * both got two classes `instanceof` could not tell apart while `err.name` matched both. This alias
+ * keeps existing imports working; it will be removed in the next major.
+ */
+export { type ForkTranscriptOptions, forkTranscript, LiveTranscriptError, LiveTranscriptError as LiveSessionError, type ReadJsonlTailOptions, readJsonlTail, } from "./internal/persistence/transcript-ops.js";
 export type { TranscriptBlock, TranscriptMessage } from "./types/session-record.js";

package/dist/persistence.d.ts

@@ -1,4 +1,6 @@
 /**
+ * Published as `@theokit/sdk/persistence`.
+ *
  * Public persistence primitives (V2-3 — Theo Harness Capability Map, Theme G).
  *
  * Promotes the consumer-grade persistence helpers from `internal/persistence`
@@ -28,5 +30,11 @@ export type { OpenSqliteResilientOptions, ResilientSqliteDb, } from "./internal/
 export { isCorruptionError, openSqliteResilient } from "./internal/persistence/sqlite-open.js";
 export type { WalApplyResult } from "./internal/persistence/sqlite-wal.js";
 export { applyWalWithFallback } from "./internal/persistence/sqlite-wal.js";
-export { type ForkTranscriptOptions, forkTranscript, LiveSessionError, type ReadJsonlTailOptions, readJsonlTail, } from "./internal/persistence/transcript-ops.js";
+/**
+ * @deprecated Renamed to {@link LiveTranscriptError}. The root barrel exports a DIFFERENT class
+ * under this name (`session-guard.ts`, about refusing to destroy a session), and a consumer holding
+ * both got two classes `instanceof` could not tell apart while `err.name` matched both. This alias
+ * keeps existing imports working; it will be removed in the next major.
+ */
+export { type ForkTranscriptOptions, forkTranscript, LiveTranscriptError, LiveTranscriptError as LiveSessionError, type ReadJsonlTailOptions, readJsonlTail, } from "./internal/persistence/transcript-ops.js";
 export type { TranscriptBlock, TranscriptMessage } from "./types/session-record.js";

package/dist/persistence.js

@@ -1,15 +1,14 @@
 export { PersistenceSchema } from './chunk-HY66GLM6.js';
-export { SessionBusyError, acquireSessionWriter, sessionHasWriter } from './chunk-B3IMEBOA.js';
-export { encodeProjectDir, transcriptPath, transcriptRoot } from './chunk-UMP6OJIM.js';
+export { SessionBusyError, acquireSessionWriter, sessionHasWriter } from './chunk-VE6DFSKU.js';
+export { encodeProjectDir, transcriptPath, transcriptRoot } from './chunk-JOFVLOFY.js';
 export { sanitizeFts5Query } from './chunk-WE22OXQA.js';
-export { applyWalWithFallback, isCorruptionError, openSqliteResilient } from './chunk-LWGSI6M3.js';
-export { JsonlParseError, appendJsonl, loadJsonl, readJsonlIds, withFileLock } from './chunk-3O42QOMJ.js';
+export { applyWalWithFallback, isCorruptionError, openSqliteResilient } from './chunk-6PWOWXMC.js';
+export { JsonlParseError, appendJsonl, loadJsonl, readJsonlIds, withFileLock } from './chunk-TA3K7SBK.js';
 export { withCwdMutex } from './chunk-Q5EWJPRY.js';
-import { atomicWriteTempTarget } from './chunk-2GUYQR5P.js';
-export { atomicWriteJson, atomicWriteTempTarget, atomicWriteText, replaceFileAtomic } from './chunk-2GUYQR5P.js';
-import { TheokitAgentError } from './chunk-ZZMZWBR6.js';
-import './chunk-D4CUGAKZ.js';
-import './chunk-XEQ3TM66.js';
+import { atomicWriteTempTarget } from './chunk-3JHIFQ4I.js';
+export { atomicWriteJson, atomicWriteTempTarget, atomicWriteText, replaceFileAtomic } from './chunk-3JHIFQ4I.js';
+import { TheokitAgentError } from './chunk-ALUN2B4W.js';
+import './chunk-CZJ6Q7CW.js';
 import { readFileSync, openSync, writeSync, closeSync, fstatSync, readSync } from 'fs';
 
 // src/internal/persistence/session-artifacts.ts
@@ -21,7 +20,7 @@ function classifySessionArtifact(name, isDirectory) {
   if (atomicWriteTempTarget(name) !== void 0) return "temp";
   return void 0;
 }
-var LiveSessionError = class extends TheokitAgentError {
+var LiveTranscriptError = class extends TheokitAgentError {
   constructor(path) {
     super(
       `refusing to write over a live session transcript: ${path}. Fork to a new id instead \u2014 the live pointer, the most recent transcript and any active registry entry are never overwritten (audit-trail rotation, M60).`,
@@ -30,11 +29,11 @@ var LiveSessionError = class extends TheokitAgentError {
     this.path = path;
   }
   path;
-  name = "LiveSessionError";
+  name = "LiveTranscriptError";
 };
 function forkTranscript(src, dst, options = {}) {
   for (const live of options.liveSessionPaths ?? []) {
-    if (live === dst) throw new LiveSessionError(dst);
+    if (live === dst) throw new LiveTranscriptError(dst);
   }
   const lines = readFileSync(src, "utf8").split("\n").filter((l) => l.trim().length > 0);
   const kept = options.beforeRecordIndex === void 0 ? lines : lines.slice(0, options.beforeRecordIndex);
@@ -96,6 +95,6 @@ function readJsonlTail(path, options = {}) {
   return options._stats === true ? Object.assign(out, { bytesRead }) : out;
 }
 
-export { LiveSessionError, classifySessionArtifact, forkTranscript, readJsonlTail };
+export { LiveTranscriptError as LiveSessionError, LiveTranscriptError, classifySessionArtifact, forkTranscript, readJsonlTail };
 //# sourceMappingURL=persistence.js.map
 //# sourceMappingURL=persistence.js.map

package/dist/persistence.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/persistence/session-artifacts.ts","../src/internal/persistence/transcript-ops.ts"],"names":[],"mappings":"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","file":"persistence.js","sourcesContent":["import { atomicWriteTempTarget } from \"./atomic-write.js\";\n\n/**\n * The kinds of file this SDK leaves in a project's transcript directory.\n *\n * - `transcript` — the session itself (`transcriptPath`).\n * - `writer-lock` — the cross-process writer lease (`session-writer.ts`, `<file>.writer.lock`).\n * - `lock-directory` — `withFileLock`'s companion, taken by `mkdir`, so it is a DIRECTORY.\n * - `temp` — what `replaceFileAtomic` leaves when a process dies between the open and the rename.\n */\nexport type SessionArtifact = \"transcript\" | \"writer-lock\" | \"lock-directory\" | \"temp\";\n\n/**\n * U-1 — what is this entry, if it is one of ours?\n *\n * The SDK writes four kinds of file into a project directory and reasons about none of them\n * afterwards: there is no retention, no collector, and there was no way even to ask what an entry\n * IS. A consumer wanting to reclaim disk had to re-derive the suffixes by reading this source — and\n * one did, which means a suffix changing here would have left its classifier silently mislabelling\n * files on a path that deletes them.\n *\n * This is deliberately NOT a garbage collector. Retention is policy — how many days, how many to\n * keep, which session is live, whether to delete at all — and policy belongs to the application,\n * which is the only one that can know. What belongs here is the half only the SDK can answer.\n *\n * `undefined` means \"not written by this SDK\", and it is the answer that matters most: a caller\n * deleting what it does not recognise is how an editor's swap file gets collected. The `temp` case\n * defers to {@link atomicWriteTempTarget} rather than matching `.tmp`, for exactly that reason.\n */\nexport function classifySessionArtifact(\n  name: string,\n  isDirectory: boolean,\n): SessionArtifact | undefined {\n  // `withFileLock` takes its lock by `mkdir`, so the same name as a plain file is not ours.\n  if (name.endsWith(\".jsonl.lock\")) return isDirectory ? \"lock-directory\" : undefined;\n  if (isDirectory) return undefined;\n  if (name.endsWith(\".jsonl\")) return \"transcript\";\n  if (name.endsWith(\".writer.lock\")) return \"writer-lock\";\n  if (atomicWriteTempTarget(name) !== undefined) return \"temp\";\n  return undefined;\n}\n","/**\n * M81 — transcript operations the consumer was doing by hand INSIDE the framework's own store.\n *\n * ## What this replaces\n *\n * `agents/lib/session/backtrack.ts:188` (agent-builder) wrote straight into the session store with a\n * bare `writeFileSync` — no atomicity, no lock, no API. 243 lines re-implementing parse, cut and\n * write for a format the framework owns. The consumer is not at fault: nothing here was reachable.\n *\n * ## The rule that travels WITH the operation\n *\n * `rules/audit-trail-rotation.md § Session transcripts (M60)` defines a NEVER-delete list — the live\n * pointer, the most recent transcript, and any active registry entry. That rule lived in the\n * CONSUMER. Moving the operation here without moving the rule would ship an API able to destroy\n * exactly what the rule protects — the same shape of defect as M80's `reconcileUpdateGoalStatus`:\n * critical knowledge outside the module that needs it, applied by convention.\n *\n * So `forkTranscript` takes `liveSessionPaths` and refuses, with a TYPED error, to write over any of\n * them. The caller supplies the list because only the caller knows which session is live; the\n * enforcement lives here because that is where the write happens.\n *\n * @internal\n */\n\nimport { closeSync, fstatSync, openSync, readFileSync, readSync, writeSync } from \"node:fs\";\n\nimport { TheokitAgentError } from \"../../errors.js\";\n\n/**\n * M81 — the target is a protected session (live pointer / most-recent transcript / active entry).\n *\n * Typed rather than a bare `Error` because the caller must distinguish \"this session is protected\"\n * from \"the disk is full\": the first is a correct refusal, the second is an incident.\n */\nexport class LiveSessionError extends TheokitAgentError {\n  override readonly name = \"LiveSessionError\";\n\n  constructor(readonly path: string) {\n    super(\n      `refusing to write over a live session transcript: ${path}. ` +\n        \"Fork to a new id instead — the live pointer, the most recent transcript and any active \" +\n        \"registry entry are never overwritten (audit-trail rotation, M60).\",\n      { code: \"live_session_protected\", isRetryable: false },\n    );\n  }\n}\n\n/** Options for {@link forkTranscript}. */\nexport interface ForkTranscriptOptions {\n  /** Keep records `[0, beforeRecordIndex)`. Omit to copy the whole transcript. */\n  readonly beforeRecordIndex?: number;\n  /**\n   * Paths that must never be written over — the live pointer, the most recent transcript, any active\n   * registry entry. The caller supplies them because only the caller knows which session is live.\n   */\n  readonly liveSessionPaths?: readonly string[];\n  /**\n   * M107 — permission bits for the created destination. Default: `0o600`.\n   *\n   * A transcript carries the conversation. Before M107 no mode was passed at all, so the file was\n   * born `0o666 & ~umask` — measured `0o664` (group-WRITABLE) on a `umask 002` machine, `0o644` on\n   * `umask 022`, `0o466` on `umask 0200`. This is a DEFAULT and not a required knob on purpose: a\n   * knob would reach zero consumers by omission, which is the failure mode that matters.\n   *\n   * As with any `open` mode, the `umask` may still CLEAR bits — under `umask 0200` the result is\n   * `0o400`. That is accepted: the invariant bought here is \"neither group nor others\", and `0o400`\n   * satisfies it more strictly. The SDK deliberately does not `fchmod` the default back, because\n   * that would hand back a bit the operator asked to remove.\n   */\n  readonly mode?: number;\n}\n\n/**\n * Copy `src` into `dst`, keeping the first `beforeRecordIndex` records. The SOURCE is never touched.\n *\n * Atomicity comes from `wx` (exclusive create): two concurrent forks to the same destination cannot\n * both succeed — the loser gets `EEXIST` rather than writing over a half-written file. That is also\n * why an existing destination is a refusal, not a silent overwrite: losing a transcript without an\n * error is the worst failure mode for an operation that touches user sessions.\n */\nexport function forkTranscript(\n  src: string,\n  dst: string,\n  options: ForkTranscriptOptions = {},\n): void {\n  for (const live of options.liveSessionPaths ?? []) {\n    if (live === dst) throw new LiveSessionError(dst);\n  }\n\n  const lines = readFileSync(src, \"utf8\")\n    .split(\"\\n\")\n    .filter((l) => l.trim().length > 0);\n  const kept =\n    options.beforeRecordIndex === undefined ? lines : lines.slice(0, options.beforeRecordIndex);\n  const body = kept.length > 0 ? `${kept.join(\"\\n\")}\\n` : \"\";\n\n  // `wx` — fails with EEXIST instead of truncating. The exclusivity IS the concurrency guarantee,\n  // and M107 only added the third argument: the mode. See `ForkTranscriptOptions.mode`.\n  const fd = openSync(dst, \"wx\", options.mode ?? 0o600);\n  try {\n    writeSync(fd, body);\n  } finally {\n    closeSync(fd);\n  }\n}\n\n/** Options for {@link readJsonlTail}. */\nexport interface ReadJsonlTailOptions {\n  /** Maximum records to return, counted from the END. */\n  readonly maxRecords?: number;\n  /**\n   * Start the window AFTER the last record whose `subtype` (or `type`) equals this.\n   *\n   * Matched STRUCTURALLY since T2.5. It used to be `line.includes(marker)`, so any message\n   * mentioning the marker in its text truncated the read — silently, with a successful return.\n   */\n  readonly sinceMarker?: string;\n  /** Test-only: also report how many bytes were read, to prove the read is not whole-file. */\n  readonly _stats?: boolean;\n}\n\nconst TAIL_CHUNK = 64 * 1024;\n\n/**\n * Reads chunks backwards until enough complete lines have accumulated.\n *\n * Extracted from `readJsonlTail` because the read loop and the record selection are two\n * responsibilities — and together they exceeded the complexity ceiling. The buffer's first line may\n * be cut in half when the read stopped before the start of the file; that is why it is discarded.\n */\nfunction readRawTail(path: string, want: number): { lines: string[]; bytesRead: number } {\n  // Opened FIRST, then sized through the descriptor. `statSync(path)` followed by\n  // `openSync(path)` resolves the name twice, and `size` is what drives every read offset below —\n  // so a path that changed between the two calls would have the loop seeking by one file's length\n  // inside another (CodeQL js/file-system-race #19). `fstat` on the open fd describes the file\n  // being read, by construction.\n  const fd = openSync(path, \"r\");\n  const size = fstatSync(fd).size;\n  let bytesRead = 0;\n  let tail = \"\";\n  let pos = size;\n  try {\n    while (pos > 0) {\n      const len = Math.min(TAIL_CHUNK, pos);\n      pos -= len;\n      const buf = Buffer.alloc(len);\n      readSync(fd, buf, 0, len, pos);\n      bytesRead += len;\n      tail = buf.toString(\"utf8\") + tail;\n      if (nonEmptyLines(tail).length > want) break;\n    }\n  } finally {\n    closeSync(fd);\n  }\n  const lines = nonEmptyLines(tail);\n  return { lines: pos > 0 ? lines.slice(1) : lines, bytesRead };\n}\n\n/** Non-empty lines, in file order. */\nfunction nonEmptyLines(text: string): string[] {\n  return text.split(\"\\n\").filter((l) => l.trim().length > 0);\n}\n\n/**\n * Whether a raw JSONL line IS the marker record, rather than a line that talks about it.\n *\n * Matches on the record's own discriminants (`subtype`, then `type`) — the fields that identify\n * what a record *is*. Free text is never consulted, which is the whole point: content is the user's\n * and must not steer the reader.\n *\n * A line that does not parse is not a marker. Deciding a window boundary from bytes that are not a\n * record would be guessing, and this function exists because guessing is what it replaced.\n */\nfunction isMarkerRecord(line: string, marker: string): boolean {\n  let record: { type?: unknown; subtype?: unknown };\n  try {\n    record = JSON.parse(line) as { type?: unknown; subtype?: unknown };\n  } catch {\n    return false;\n  }\n  return record.subtype === marker || record.type === marker;\n}\n\n/**\n * Read the LAST records of a JSONL file without loading the whole thing.\n *\n * Reads fixed-size chunks backwards from EOF until enough newlines have been seen. A session\n * transcript grows without bound; loading megabytes to show the last three turns is the cost this\n * exists to avoid — and a `slice` over a full read would be that same cost with a better name.\n */\nexport function readJsonlTail<T = Record<string, unknown>>(\n  path: string,\n  options: ReadJsonlTailOptions = {},\n): T[] {\n  const want = options.maxRecords ?? Number.POSITIVE_INFINITY;\n  const { lines, bytesRead } = readRawTail(path, want);\n\n  let sel = lines;\n  if (options.sinceMarker !== undefined) {\n    const marker = options.sinceMarker;\n    // STRUCTURAL, not `line.includes(marker)`.\n    //\n    // A raw substring match is true for any line that merely MENTIONS the marker — a user asking\n    // \"how does compact_boundary work?\" silently truncated the window to start at their question.\n    // The read then succeeded, returned fewer records than exist, and said nothing. That is the\n    // measured reason the only would-be consumer kept its own reader instead of this one.\n    const idx = sel.findLastIndex((l) => isMarkerRecord(l, marker));\n    if (idx >= 0) sel = sel.slice(idx + 1);\n  }\n  if (Number.isFinite(want)) sel = sel.slice(-want);\n\n  const out = sel.map((l) => JSON.parse(l) as T);\n  return options._stats === true ? (Object.assign(out, { bytesRead }) as T[]) : out;\n}\n"]}
+{"version":3,"sources":["../src/internal/persistence/session-artifacts.ts","../src/internal/persistence/transcript-ops.ts"],"names":[],"mappings":"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","file":"persistence.js","sourcesContent":["import { atomicWriteTempTarget } from \"./atomic-write.js\";\n\n/**\n * The kinds of file this SDK leaves in a project's transcript directory.\n *\n * - `transcript` — the session itself (`transcriptPath`).\n * - `writer-lock` — the cross-process writer lease (`session-writer.ts`, `<file>.writer.lock`).\n * - `lock-directory` — `withFileLock`'s companion, taken by `mkdir`, so it is a DIRECTORY.\n * - `temp` — what `replaceFileAtomic` leaves when a process dies between the open and the rename.\n */\nexport type SessionArtifact = \"transcript\" | \"writer-lock\" | \"lock-directory\" | \"temp\";\n\n/**\n * U-1 — what is this entry, if it is one of ours?\n *\n * The SDK writes four kinds of file into a project directory and reasons about none of them\n * afterwards: there is no retention, no collector, and there was no way even to ask what an entry\n * IS. A consumer wanting to reclaim disk had to re-derive the suffixes by reading this source — and\n * one did, which means a suffix changing here would have left its classifier silently mislabelling\n * files on a path that deletes them.\n *\n * This is deliberately NOT a garbage collector. Retention is policy — how many days, how many to\n * keep, which session is live, whether to delete at all — and policy belongs to the application,\n * which is the only one that can know. What belongs here is the half only the SDK can answer.\n *\n * `undefined` means \"not written by this SDK\", and it is the answer that matters most: a caller\n * deleting what it does not recognise is how an editor's swap file gets collected. The `temp` case\n * defers to {@link atomicWriteTempTarget} rather than matching `.tmp`, for exactly that reason.\n */\nexport function classifySessionArtifact(\n  name: string,\n  isDirectory: boolean,\n): SessionArtifact | undefined {\n  // `withFileLock` takes its lock by `mkdir`, so the same name as a plain file is not ours.\n  if (name.endsWith(\".jsonl.lock\")) return isDirectory ? \"lock-directory\" : undefined;\n  if (isDirectory) return undefined;\n  if (name.endsWith(\".jsonl\")) return \"transcript\";\n  if (name.endsWith(\".writer.lock\")) return \"writer-lock\";\n  if (atomicWriteTempTarget(name) !== undefined) return \"temp\";\n  return undefined;\n}\n","/**\n * M81 — transcript operations the consumer was doing by hand INSIDE the framework's own store.\n *\n * ## What this replaces\n *\n * `agents/lib/session/backtrack.ts:188` (agent-builder) wrote straight into the session store with a\n * bare `writeFileSync` — no atomicity, no lock, no API. 243 lines re-implementing parse, cut and\n * write for a format the framework owns. The consumer is not at fault: nothing here was reachable.\n *\n * ## The rule that travels WITH the operation\n *\n * `rules/audit-trail-rotation.md § Session transcripts (M60)` defines a NEVER-delete list — the live\n * pointer, the most recent transcript, and any active registry entry. That rule lived in the\n * CONSUMER. Moving the operation here without moving the rule would ship an API able to destroy\n * exactly what the rule protects — the same shape of defect as M80's `reconcileUpdateGoalStatus`:\n * critical knowledge outside the module that needs it, applied by convention.\n *\n * So `forkTranscript` takes `liveSessionPaths` and refuses, with a TYPED error, to write over any of\n * them. The caller supplies the list because only the caller knows which session is live; the\n * enforcement lives here because that is where the write happens.\n *\n * @internal\n */\n\nimport { closeSync, fstatSync, openSync, readFileSync, readSync, writeSync } from \"node:fs\";\n\nimport { TheokitAgentError } from \"../../errors.js\";\n\n/**\n * M81 — the target is a protected session (live pointer / most-recent transcript / active entry).\n *\n * Typed rather than a bare `Error` because the caller must distinguish \"this session is protected\"\n * from \"the disk is full\": the first is a correct refusal, the second is an incident.\n *\n * RENAMED from `LiveSessionError` (2026-09-01). `session-guard.ts` exports a DIFFERENT class of that\n * name from the root barrel, with an incompatible shape — `(sessionId, reason)` and a `reason`\n * field, against this one's `(path)` and `code: \"live_session_protected\"` — and `.` and\n * `./persistence` are both declared subpaths, so one consumer can hold both. `instanceof` never\n * crossed the pair, so a `catch` checking the root import silently missed this one and ran its\n * fallback for a condition it believed it handled; `err.name` matched BOTH, so a name check looked\n * right and then read `err.reason`, which only the other one has. The names now say what each\n * refusal is about: destroying a SESSION, versus overwriting a TRANSCRIPT file.\n */\nexport class LiveTranscriptError extends TheokitAgentError {\n  override readonly name = \"LiveTranscriptError\";\n\n  constructor(readonly path: string) {\n    super(\n      `refusing to write over a live session transcript: ${path}. ` +\n        \"Fork to a new id instead — the live pointer, the most recent transcript and any active \" +\n        \"registry entry are never overwritten (audit-trail rotation, M60).\",\n      { code: \"live_session_protected\", isRetryable: false },\n    );\n  }\n}\n\n/** Options for {@link forkTranscript}. */\nexport interface ForkTranscriptOptions {\n  /** Keep records `[0, beforeRecordIndex)`. Omit to copy the whole transcript. */\n  readonly beforeRecordIndex?: number;\n  /**\n   * Paths that must never be written over — the live pointer, the most recent transcript, any active\n   * registry entry. The caller supplies them because only the caller knows which session is live.\n   */\n  readonly liveSessionPaths?: readonly string[];\n  /**\n   * M107 — permission bits for the created destination. Default: `0o600`.\n   *\n   * A transcript carries the conversation. Before M107 no mode was passed at all, so the file was\n   * born `0o666 & ~umask` — measured `0o664` (group-WRITABLE) on a `umask 002` machine, `0o644` on\n   * `umask 022`, `0o466` on `umask 0200`. This is a DEFAULT and not a required knob on purpose: a\n   * knob would reach zero consumers by omission, which is the failure mode that matters.\n   *\n   * As with any `open` mode, the `umask` may still CLEAR bits — under `umask 0200` the result is\n   * `0o400`. That is accepted: the invariant bought here is \"neither group nor others\", and `0o400`\n   * satisfies it more strictly. The SDK deliberately does not `fchmod` the default back, because\n   * that would hand back a bit the operator asked to remove.\n   */\n  readonly mode?: number;\n}\n\n/**\n * Copy `src` into `dst`, keeping the first `beforeRecordIndex` records. The SOURCE is never touched.\n *\n * Atomicity comes from `wx` (exclusive create): two concurrent forks to the same destination cannot\n * both succeed — the loser gets `EEXIST` rather than writing over a half-written file. That is also\n * why an existing destination is a refusal, not a silent overwrite: losing a transcript without an\n * error is the worst failure mode for an operation that touches user sessions.\n */\nexport function forkTranscript(\n  src: string,\n  dst: string,\n  options: ForkTranscriptOptions = {},\n): void {\n  for (const live of options.liveSessionPaths ?? []) {\n    if (live === dst) throw new LiveTranscriptError(dst);\n  }\n\n  const lines = readFileSync(src, \"utf8\")\n    .split(\"\\n\")\n    .filter((l) => l.trim().length > 0);\n  const kept =\n    options.beforeRecordIndex === undefined ? lines : lines.slice(0, options.beforeRecordIndex);\n  const body = kept.length > 0 ? `${kept.join(\"\\n\")}\\n` : \"\";\n\n  // `wx` — fails with EEXIST instead of truncating. The exclusivity IS the concurrency guarantee,\n  // and M107 only added the third argument: the mode. See `ForkTranscriptOptions.mode`.\n  const fd = openSync(dst, \"wx\", options.mode ?? 0o600);\n  try {\n    writeSync(fd, body);\n  } finally {\n    closeSync(fd);\n  }\n}\n\n/** Options for {@link readJsonlTail}. */\nexport interface ReadJsonlTailOptions {\n  /** Maximum records to return, counted from the END. */\n  readonly maxRecords?: number;\n  /**\n   * Start the window AFTER the last record whose `subtype` (or `type`) equals this.\n   *\n   * Matched STRUCTURALLY since T2.5. It used to be `line.includes(marker)`, so any message\n   * mentioning the marker in its text truncated the read — silently, with a successful return.\n   */\n  readonly sinceMarker?: string;\n  /** Test-only: also report how many bytes were read, to prove the read is not whole-file. */\n  readonly _stats?: boolean;\n}\n\nconst TAIL_CHUNK = 64 * 1024;\n\n/**\n * Reads chunks backwards until enough complete lines have accumulated.\n *\n * Extracted from `readJsonlTail` because the read loop and the record selection are two\n * responsibilities — and together they exceeded the complexity ceiling. The buffer's first line may\n * be cut in half when the read stopped before the start of the file; that is why it is discarded.\n */\nfunction readRawTail(path: string, want: number): { lines: string[]; bytesRead: number } {\n  // Opened FIRST, then sized through the descriptor. `statSync(path)` followed by\n  // `openSync(path)` resolves the name twice, and `size` is what drives every read offset below —\n  // so a path that changed between the two calls would have the loop seeking by one file's length\n  // inside another (CodeQL js/file-system-race #19). `fstat` on the open fd describes the file\n  // being read, by construction.\n  const fd = openSync(path, \"r\");\n  const size = fstatSync(fd).size;\n  let bytesRead = 0;\n  let tail = \"\";\n  let pos = size;\n  try {\n    while (pos > 0) {\n      const len = Math.min(TAIL_CHUNK, pos);\n      pos -= len;\n      const buf = Buffer.alloc(len);\n      readSync(fd, buf, 0, len, pos);\n      bytesRead += len;\n      tail = buf.toString(\"utf8\") + tail;\n      if (nonEmptyLines(tail).length > want) break;\n    }\n  } finally {\n    closeSync(fd);\n  }\n  const lines = nonEmptyLines(tail);\n  return { lines: pos > 0 ? lines.slice(1) : lines, bytesRead };\n}\n\n/** Non-empty lines, in file order. */\nfunction nonEmptyLines(text: string): string[] {\n  return text.split(\"\\n\").filter((l) => l.trim().length > 0);\n}\n\n/**\n * Whether a raw JSONL line IS the marker record, rather than a line that talks about it.\n *\n * Matches on the record's own discriminants (`subtype`, then `type`) — the fields that identify\n * what a record *is*. Free text is never consulted, which is the whole point: content is the user's\n * and must not steer the reader.\n *\n * A line that does not parse is not a marker. Deciding a window boundary from bytes that are not a\n * record would be guessing, and this function exists because guessing is what it replaced.\n */\nfunction isMarkerRecord(line: string, marker: string): boolean {\n  let record: { type?: unknown; subtype?: unknown };\n  try {\n    record = JSON.parse(line) as { type?: unknown; subtype?: unknown };\n  } catch {\n    return false;\n  }\n  return record.subtype === marker || record.type === marker;\n}\n\n/**\n * Read the LAST records of a JSONL file without loading the whole thing.\n *\n * Reads fixed-size chunks backwards from EOF until enough newlines have been seen. A session\n * transcript grows without bound; loading megabytes to show the last three turns is the cost this\n * exists to avoid — and a `slice` over a full read would be that same cost with a better name.\n */\nexport function readJsonlTail<T = Record<string, unknown>>(\n  path: string,\n  options: ReadJsonlTailOptions = {},\n): T[] {\n  const want = options.maxRecords ?? Number.POSITIVE_INFINITY;\n  const { lines, bytesRead } = readRawTail(path, want);\n\n  let sel = lines;\n  if (options.sinceMarker !== undefined) {\n    const marker = options.sinceMarker;\n    // STRUCTURAL, not `line.includes(marker)`.\n    //\n    // A raw substring match is true for any line that merely MENTIONS the marker — a user asking\n    // \"how does compact_boundary work?\" silently truncated the window to start at their question.\n    // The read then succeeded, returned fewer records than exist, and said nothing. That is the\n    // measured reason the only would-be consumer kept its own reader instead of this one.\n    const idx = sel.findLastIndex((l) => isMarkerRecord(l, marker));\n    if (idx >= 0) sel = sel.slice(idx + 1);\n  }\n  if (Number.isFinite(want)) sel = sel.slice(-want);\n\n  const out = sel.map((l) => JSON.parse(l) as T);\n  return options._stats === true ? (Object.assign(out, { bytesRead }) as T[]) : out;\n}\n"]}

package/dist/project.cjs

@@ -1,10 +1,9 @@
 'use strict';
 
 var chunkLKFET5A3_cjs = require('./chunk-LKFET5A3.cjs');
-var chunkUALX2J2Q_cjs = require('./chunk-UALX2J2Q.cjs');
-var chunk4ZHTIJNE_cjs = require('./chunk-4ZHTIJNE.cjs');
-require('./chunk-XL7Q7HB2.cjs');
-require('./chunk-EG4QM7ZJ.cjs');
+var chunkJLRLCBJ4_cjs = require('./chunk-JLRLCBJ4.cjs');
+var chunkJ7J7J2GN_cjs = require('./chunk-J7J7J2GN.cjs');
+require('./chunk-6LHQPOMI.cjs');
 var promises = require('fs/promises');
 var path = require('path');
 
@@ -32,12 +31,12 @@ function reduceContent(files, scope) {
 async function writeProjectInstructions(cwd, content, options) {
   const filename = options?.filename ?? DEFAULT_FILENAME;
   if (!chunkLKFET5A3_cjs.isSafePattern(filename)) {
-    throw new chunk4ZHTIJNE_cjs.ConfigurationError(
+    throw new chunkJ7J7J2GN_cjs.ConfigurationError(
       `writeProjectInstructions: unsafe filename ${JSON.stringify(filename)} (no path traversal, separators, or absolute paths)`,
       { code: "unsafe_filename" }
     );
   }
-  await chunkUALX2J2Q_cjs.replaceFileAtomic(path.join(cwd, filename), content);
+  await chunkJLRLCBJ4_cjs.replaceFileAtomic(path.join(cwd, filename), content);
 }
 
 exports.readProjectInstructions = readProjectInstructions;

package/dist/project.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/runtime/context/project-instructions.ts"],"names":["walkUpForFile","readFile","isSafePattern","ConfigurationError","replaceFileAtomic","join"],"mappings":";;;;;;;;;;AA8CA,IAAM,gBAAA,GAAmB,SAAA;AAiBzB,eAAsB,uBAAA,CACpB,KACA,OAAA,EAC8B;AAC9B,EAAA,MAAM,QAAA,GAAW,SAAS,QAAA,IAAY,gBAAA;AACtC,EAAA,MAAM,KAAA,GAAQ,SAAS,KAAA,IAAS,SAAA;AAChC,EAAA,MAAM,KAAA,GAAQA,+BAAA,CAAc,GAAA,EAAK,QAAA,EAAU,SAAS,OAAO,CAAA;AAE3D,EAAA,MAAM,QAAkC,EAAC;AACzC,EAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,IAAA,IAAI;AACF,MAAA,KAAA,CAAM,IAAA,CAAK,EAAE,IAAA,EAAM,OAAA,EAAS,MAAMC,iBAAA,CAAS,IAAA,EAAM,MAAM,CAAA,EAAG,CAAA;AAAA,IAC5D,CAAA,CAAA,MAAQ;AAAA,IAER;AAAA,EACF;AAEA,EAAA,OAAO,EAAE,KAAA,EAAO,OAAA,EAAS,aAAA,CAAc,KAAA,EAAO,KAAK,CAAA,EAAE;AACvD;AAEA,SAAS,aAAA,CACP,OACA,KAAA,EACoB;AACpB,EAAA,IAAI,KAAA,CAAM,MAAA,KAAW,CAAA,EAAG,OAAO,MAAA;AAC/B,EAAA,IAAI,UAAU,QAAA,EAAU;AACtB,IAAA,OAAO,CAAC,GAAG,KAAK,CAAA,CACb,OAAA,EAAQ,CACR,GAAA,CAAI,CAAC,CAAA,KAAM,CAAA,CAAE,OAAO,CAAA,CACpB,KAAK,MAAM,CAAA;AAAA,EAChB;AACA,EAAA,OAAO,KAAA,CAAM,CAAC,CAAA,EAAG,OAAA;AACnB;AAiBA,eAAsB,wBAAA,CACpB,GAAA,EACA,OAAA,EACA,OAAA,EACe;AACf,EAAA,MAAM,QAAA,GAAW,SAAS,QAAA,IAAY,gBAAA;AACtC,EAAA,IAAI,CAACC,+BAAA,CAAc,QAAQ,CAAA,EAAG;AAC5B,IAAA,MAAM,IAAIC,oCAAA;AAAA,MACR,CAAA,0CAAA,EAA6C,IAAA,CAAK,SAAA,CAAU,QAAQ,CAAC,CAAA,mDAAA,CAAA;AAAA,MACrE,EAAE,MAAM,iBAAA;AAAkB,KAC5B;AAAA,EACF;AACA,EAAA,MAAMC,mCAAA,CAAkBC,SAAA,CAAK,GAAA,EAAK,QAAQ,GAAG,OAAO,CAAA;AACtD","file":"project.cjs","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\n\nimport { ConfigurationError } from \"../../../errors.js\";\nimport { replaceFileAtomic } from \"../../persistence/atomic-write.js\";\nimport { isSafePattern, walkUpForFile } from \"./context-discovery.js\";\n\n/** How discovered instruction files are reduced to a single `content` string. */\nexport type ProjectInstructionScope = \"nearest\" | \"merged\";\n\n/** One discovered project-instruction file. */\nexport interface ProjectInstructionFile {\n  /** Absolute path to the file. */\n  path: string;\n  /** Full file content (never truncated — the caller bounds it). */\n  content: string;\n}\n\n/** Result of {@link readProjectInstructions}. */\nexport interface ProjectInstructions {\n  /** Found files, nearest-first (innermost directory first). Empty if none. */\n  files: ProjectInstructionFile[];\n  /**\n   * The `scope`-selected reduction: `nearest` → the innermost file's content;\n   * `merged` → all files joined root-first (nearest content last). `undefined`\n   * when no file was found.\n   */\n  content: string | undefined;\n}\n\n/** Options for {@link readProjectInstructions}. */\nexport interface ReadProjectInstructionsOptions {\n  /** Instruction filename to discover. Default `\"THEO.md\"`. */\n  filename?: string;\n  /** How to reduce the found files to `content`. Default `\"nearest\"`. */\n  scope?: ProjectInstructionScope;\n  /** Stop the upward walk at this directory (inclusive). Default: filesystem root. */\n  stopDir?: string;\n}\n\n/** Options for {@link writeProjectInstructions}. */\nexport interface WriteProjectInstructionsOptions {\n  /** Instruction filename to write. Default `\"THEO.md\"`. */\n  filename?: string;\n}\n\nconst DEFAULT_FILENAME = \"THEO.md\";\n\n/**\n * Read hierarchical project instructions by walking up from `cwd`.\n *\n * Discovers every `<dir>/<filename>` from `cwd` up to the filesystem root (or\n * `stopDir`), reads each, and returns them nearest-first in `files` plus a\n * `content` reduction chosen by `scope`. Composes the hardened internal\n * `walkUpForFile` (64-level cap, realpath dedup, FS-race tolerant).\n *\n * NEVER throws: a missing/unreadable directory or a path that exists but is not\n * a readable file is skipped; no instruction file → `{ files: [], content: undefined }`.\n *\n * Public via `@theokit/sdk/project`.\n *\n * @public\n */\nexport async function readProjectInstructions(\n  cwd: string,\n  options?: ReadProjectInstructionsOptions,\n): Promise<ProjectInstructions> {\n  const filename = options?.filename ?? DEFAULT_FILENAME;\n  const scope = options?.scope ?? \"nearest\";\n  const paths = walkUpForFile(cwd, filename, options?.stopDir);\n\n  const files: ProjectInstructionFile[] = [];\n  for (const path of paths) {\n    try {\n      files.push({ path, content: await readFile(path, \"utf8\") });\n    } catch {\n      // FS-race / unreadable / directory-named-like-file → skip (never-throw)\n    }\n  }\n\n  return { files, content: reduceContent(files, scope) };\n}\n\nfunction reduceContent(\n  files: ProjectInstructionFile[],\n  scope: ProjectInstructionScope,\n): string | undefined {\n  if (files.length === 0) return undefined;\n  if (scope === \"merged\") {\n    return [...files]\n      .reverse()\n      .map((f) => f.content)\n      .join(\"\\n\\n\");\n  }\n  return files[0]?.content;\n}\n\n/**\n * Write project instructions to `<cwd>/<filename>` atomically (temp + fsync +\n * rename, via the shipped `replaceFileAtomic`).\n *\n * Unlike the reader, this FAILS LOUD: an unsafe `filename` (path traversal,\n * separators, absolute) is rejected with `ConfigurationError`\n * (`code: \"unsafe_filename\"`) — symmetric with the reader, whose `filename`\n * flows through the same `isSafePattern` guard — and a write error (e.g. the\n * parent directory does not exist) propagates to the caller. A failed mutation\n * is a real error, never silently swallowed.\n *\n * Public via `@theokit/sdk/project`.\n *\n * @public\n */\nexport async function writeProjectInstructions(\n  cwd: string,\n  content: string,\n  options?: WriteProjectInstructionsOptions,\n): Promise<void> {\n  const filename = options?.filename ?? DEFAULT_FILENAME;\n  if (!isSafePattern(filename)) {\n    throw new ConfigurationError(\n      `writeProjectInstructions: unsafe filename ${JSON.stringify(filename)} (no path traversal, separators, or absolute paths)`,\n      { code: \"unsafe_filename\" },\n    );\n  }\n  await replaceFileAtomic(join(cwd, filename), content);\n}\n"]}
+{"version":3,"sources":["../src/internal/runtime/context/project-instructions.ts"],"names":["walkUpForFile","readFile","isSafePattern","ConfigurationError","replaceFileAtomic","join"],"mappings":";;;;;;;;;AA8CA,IAAM,gBAAA,GAAmB,SAAA;AAiBzB,eAAsB,uBAAA,CACpB,KACA,OAAA,EAC8B;AAC9B,EAAA,MAAM,QAAA,GAAW,SAAS,QAAA,IAAY,gBAAA;AACtC,EAAA,MAAM,KAAA,GAAQ,SAAS,KAAA,IAAS,SAAA;AAChC,EAAA,MAAM,KAAA,GAAQA,+BAAA,CAAc,GAAA,EAAK,QAAA,EAAU,SAAS,OAAO,CAAA;AAE3D,EAAA,MAAM,QAAkC,EAAC;AACzC,EAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,IAAA,IAAI;AACF,MAAA,KAAA,CAAM,IAAA,CAAK,EAAE,IAAA,EAAM,OAAA,EAAS,MAAMC,iBAAA,CAAS,IAAA,EAAM,MAAM,CAAA,EAAG,CAAA;AAAA,IAC5D,CAAA,CAAA,MAAQ;AAAA,IAER;AAAA,EACF;AAEA,EAAA,OAAO,EAAE,KAAA,EAAO,OAAA,EAAS,aAAA,CAAc,KAAA,EAAO,KAAK,CAAA,EAAE;AACvD;AAEA,SAAS,aAAA,CACP,OACA,KAAA,EACoB;AACpB,EAAA,IAAI,KAAA,CAAM,MAAA,KAAW,CAAA,EAAG,OAAO,MAAA;AAC/B,EAAA,IAAI,UAAU,QAAA,EAAU;AACtB,IAAA,OAAO,CAAC,GAAG,KAAK,CAAA,CACb,OAAA,EAAQ,CACR,GAAA,CAAI,CAAC,CAAA,KAAM,CAAA,CAAE,OAAO,CAAA,CACpB,KAAK,MAAM,CAAA;AAAA,EAChB;AACA,EAAA,OAAO,KAAA,CAAM,CAAC,CAAA,EAAG,OAAA;AACnB;AAiBA,eAAsB,wBAAA,CACpB,GAAA,EACA,OAAA,EACA,OAAA,EACe;AACf,EAAA,MAAM,QAAA,GAAW,SAAS,QAAA,IAAY,gBAAA;AACtC,EAAA,IAAI,CAACC,+BAAA,CAAc,QAAQ,CAAA,EAAG;AAC5B,IAAA,MAAM,IAAIC,oCAAA;AAAA,MACR,CAAA,0CAAA,EAA6C,IAAA,CAAK,SAAA,CAAU,QAAQ,CAAC,CAAA,mDAAA,CAAA;AAAA,MACrE,EAAE,MAAM,iBAAA;AAAkB,KAC5B;AAAA,EACF;AACA,EAAA,MAAMC,mCAAA,CAAkBC,SAAA,CAAK,GAAA,EAAK,QAAQ,GAAG,OAAO,CAAA;AACtD","file":"project.cjs","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\n\nimport { ConfigurationError } from \"../../../errors.js\";\nimport { replaceFileAtomic } from \"../../persistence/atomic-write.js\";\nimport { isSafePattern, walkUpForFile } from \"./context-discovery.js\";\n\n/** How discovered instruction files are reduced to a single `content` string. */\nexport type ProjectInstructionScope = \"nearest\" | \"merged\";\n\n/** One discovered project-instruction file. */\nexport interface ProjectInstructionFile {\n  /** Absolute path to the file. */\n  path: string;\n  /** Full file content (never truncated — the caller bounds it). */\n  content: string;\n}\n\n/** Result of {@link readProjectInstructions}. */\nexport interface ProjectInstructions {\n  /** Found files, nearest-first (innermost directory first). Empty if none. */\n  files: ProjectInstructionFile[];\n  /**\n   * The `scope`-selected reduction: `nearest` → the innermost file's content;\n   * `merged` → all files joined root-first (nearest content last). `undefined`\n   * when no file was found.\n   */\n  content: string | undefined;\n}\n\n/** Options for {@link readProjectInstructions}. */\nexport interface ReadProjectInstructionsOptions {\n  /** Instruction filename to discover. Default `\"THEO.md\"`. */\n  filename?: string;\n  /** How to reduce the found files to `content`. Default `\"nearest\"`. */\n  scope?: ProjectInstructionScope;\n  /** Stop the upward walk at this directory (inclusive). Default: filesystem root. */\n  stopDir?: string;\n}\n\n/** Options for {@link writeProjectInstructions}. */\nexport interface WriteProjectInstructionsOptions {\n  /** Instruction filename to write. Default `\"THEO.md\"`. */\n  filename?: string;\n}\n\nconst DEFAULT_FILENAME = \"THEO.md\";\n\n/**\n * Read hierarchical project instructions by walking up from `cwd`.\n *\n * Discovers every `<dir>/<filename>` from `cwd` up to the filesystem root (or\n * `stopDir`), reads each, and returns them nearest-first in `files` plus a\n * `content` reduction chosen by `scope`. Composes the hardened internal\n * `walkUpForFile` (64-level cap, realpath dedup, FS-race tolerant).\n *\n * NEVER throws: a missing/unreadable directory or a path that exists but is not\n * a readable file is skipped; no instruction file → `{ files: [], content: undefined }`.\n *\n * Public via `@theokit/sdk/project`.\n *\n * @public\n */\nexport async function readProjectInstructions(\n  cwd: string,\n  options?: ReadProjectInstructionsOptions,\n): Promise<ProjectInstructions> {\n  const filename = options?.filename ?? DEFAULT_FILENAME;\n  const scope = options?.scope ?? \"nearest\";\n  const paths = walkUpForFile(cwd, filename, options?.stopDir);\n\n  const files: ProjectInstructionFile[] = [];\n  for (const path of paths) {\n    try {\n      files.push({ path, content: await readFile(path, \"utf8\") });\n    } catch {\n      // FS-race / unreadable / directory-named-like-file → skip (never-throw)\n    }\n  }\n\n  return { files, content: reduceContent(files, scope) };\n}\n\nfunction reduceContent(\n  files: ProjectInstructionFile[],\n  scope: ProjectInstructionScope,\n): string | undefined {\n  if (files.length === 0) return undefined;\n  if (scope === \"merged\") {\n    return [...files]\n      .reverse()\n      .map((f) => f.content)\n      .join(\"\\n\\n\");\n  }\n  return files[0]?.content;\n}\n\n/**\n * Write project instructions to `<cwd>/<filename>` atomically (temp + fsync +\n * rename, via the shipped `replaceFileAtomic`).\n *\n * Unlike the reader, this FAILS LOUD: an unsafe `filename` (path traversal,\n * separators, absolute) is rejected with `ConfigurationError`\n * (`code: \"unsafe_filename\"`) — symmetric with the reader, whose `filename`\n * flows through the same `isSafePattern` guard — and a write error (e.g. the\n * parent directory does not exist) propagates to the caller. A failed mutation\n * is a real error, never silently swallowed.\n *\n * Public via `@theokit/sdk/project`.\n *\n * @public\n */\nexport async function writeProjectInstructions(\n  cwd: string,\n  content: string,\n  options?: WriteProjectInstructionsOptions,\n): Promise<void> {\n  const filename = options?.filename ?? DEFAULT_FILENAME;\n  if (!isSafePattern(filename)) {\n    throw new ConfigurationError(\n      `writeProjectInstructions: unsafe filename ${JSON.stringify(filename)} (no path traversal, separators, or absolute paths)`,\n      { code: \"unsafe_filename\" },\n    );\n  }\n  await replaceFileAtomic(join(cwd, filename), content);\n}\n"]}

package/dist/project.js

@@ -1,8 +1,7 @@
 import { walkUpForFile, isSafePattern } from './chunk-WFC26L6Y.js';
-import { replaceFileAtomic } from './chunk-2GUYQR5P.js';
-import { ConfigurationError } from './chunk-ZZMZWBR6.js';
-import './chunk-D4CUGAKZ.js';
-import './chunk-XEQ3TM66.js';
+import { replaceFileAtomic } from './chunk-3JHIFQ4I.js';
+import { ConfigurationError } from './chunk-ALUN2B4W.js';
+import './chunk-CZJ6Q7CW.js';
 import { readFile } from 'fs/promises';
 import { join } from 'path';
 

package/dist/project.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/runtime/context/project-instructions.ts"],"names":[],"mappings":";;;;;;;;AA8CA,IAAM,gBAAA,GAAmB,SAAA;AAiBzB,eAAsB,uBAAA,CACpB,KACA,OAAA,EAC8B;AAC9B,EAAA,MAAM,QAAA,GAAW,SAAS,QAAA,IAAY,gBAAA;AACtC,EAAA,MAAM,KAAA,GAAQ,SAAS,KAAA,IAAS,SAAA;AAChC,EAAA,MAAM,KAAA,GAAQ,aAAA,CAAc,GAAA,EAAK,QAAA,EAAU,SAAS,OAAO,CAAA;AAE3D,EAAA,MAAM,QAAkC,EAAC;AACzC,EAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,IAAA,IAAI;AACF,MAAA,KAAA,CAAM,IAAA,CAAK,EAAE,IAAA,EAAM,OAAA,EAAS,MAAM,QAAA,CAAS,IAAA,EAAM,MAAM,CAAA,EAAG,CAAA;AAAA,IAC5D,CAAA,CAAA,MAAQ;AAAA,IAER;AAAA,EACF;AAEA,EAAA,OAAO,EAAE,KAAA,EAAO,OAAA,EAAS,aAAA,CAAc,KAAA,EAAO,KAAK,CAAA,EAAE;AACvD;AAEA,SAAS,aAAA,CACP,OACA,KAAA,EACoB;AACpB,EAAA,IAAI,KAAA,CAAM,MAAA,KAAW,CAAA,EAAG,OAAO,MAAA;AAC/B,EAAA,IAAI,UAAU,QAAA,EAAU;AACtB,IAAA,OAAO,CAAC,GAAG,KAAK,CAAA,CACb,OAAA,EAAQ,CACR,GAAA,CAAI,CAAC,CAAA,KAAM,CAAA,CAAE,OAAO,CAAA,CACpB,KAAK,MAAM,CAAA;AAAA,EAChB;AACA,EAAA,OAAO,KAAA,CAAM,CAAC,CAAA,EAAG,OAAA;AACnB;AAiBA,eAAsB,wBAAA,CACpB,GAAA,EACA,OAAA,EACA,OAAA,EACe;AACf,EAAA,MAAM,QAAA,GAAW,SAAS,QAAA,IAAY,gBAAA;AACtC,EAAA,IAAI,CAAC,aAAA,CAAc,QAAQ,CAAA,EAAG;AAC5B,IAAA,MAAM,IAAI,kBAAA;AAAA,MACR,CAAA,0CAAA,EAA6C,IAAA,CAAK,SAAA,CAAU,QAAQ,CAAC,CAAA,mDAAA,CAAA;AAAA,MACrE,EAAE,MAAM,iBAAA;AAAkB,KAC5B;AAAA,EACF;AACA,EAAA,MAAM,iBAAA,CAAkB,IAAA,CAAK,GAAA,EAAK,QAAQ,GAAG,OAAO,CAAA;AACtD","file":"project.js","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\n\nimport { ConfigurationError } from \"../../../errors.js\";\nimport { replaceFileAtomic } from \"../../persistence/atomic-write.js\";\nimport { isSafePattern, walkUpForFile } from \"./context-discovery.js\";\n\n/** How discovered instruction files are reduced to a single `content` string. */\nexport type ProjectInstructionScope = \"nearest\" | \"merged\";\n\n/** One discovered project-instruction file. */\nexport interface ProjectInstructionFile {\n  /** Absolute path to the file. */\n  path: string;\n  /** Full file content (never truncated — the caller bounds it). */\n  content: string;\n}\n\n/** Result of {@link readProjectInstructions}. */\nexport interface ProjectInstructions {\n  /** Found files, nearest-first (innermost directory first). Empty if none. */\n  files: ProjectInstructionFile[];\n  /**\n   * The `scope`-selected reduction: `nearest` → the innermost file's content;\n   * `merged` → all files joined root-first (nearest content last). `undefined`\n   * when no file was found.\n   */\n  content: string | undefined;\n}\n\n/** Options for {@link readProjectInstructions}. */\nexport interface ReadProjectInstructionsOptions {\n  /** Instruction filename to discover. Default `\"THEO.md\"`. */\n  filename?: string;\n  /** How to reduce the found files to `content`. Default `\"nearest\"`. */\n  scope?: ProjectInstructionScope;\n  /** Stop the upward walk at this directory (inclusive). Default: filesystem root. */\n  stopDir?: string;\n}\n\n/** Options for {@link writeProjectInstructions}. */\nexport interface WriteProjectInstructionsOptions {\n  /** Instruction filename to write. Default `\"THEO.md\"`. */\n  filename?: string;\n}\n\nconst DEFAULT_FILENAME = \"THEO.md\";\n\n/**\n * Read hierarchical project instructions by walking up from `cwd`.\n *\n * Discovers every `<dir>/<filename>` from `cwd` up to the filesystem root (or\n * `stopDir`), reads each, and returns them nearest-first in `files` plus a\n * `content` reduction chosen by `scope`. Composes the hardened internal\n * `walkUpForFile` (64-level cap, realpath dedup, FS-race tolerant).\n *\n * NEVER throws: a missing/unreadable directory or a path that exists but is not\n * a readable file is skipped; no instruction file → `{ files: [], content: undefined }`.\n *\n * Public via `@theokit/sdk/project`.\n *\n * @public\n */\nexport async function readProjectInstructions(\n  cwd: string,\n  options?: ReadProjectInstructionsOptions,\n): Promise<ProjectInstructions> {\n  const filename = options?.filename ?? DEFAULT_FILENAME;\n  const scope = options?.scope ?? \"nearest\";\n  const paths = walkUpForFile(cwd, filename, options?.stopDir);\n\n  const files: ProjectInstructionFile[] = [];\n  for (const path of paths) {\n    try {\n      files.push({ path, content: await readFile(path, \"utf8\") });\n    } catch {\n      // FS-race / unreadable / directory-named-like-file → skip (never-throw)\n    }\n  }\n\n  return { files, content: reduceContent(files, scope) };\n}\n\nfunction reduceContent(\n  files: ProjectInstructionFile[],\n  scope: ProjectInstructionScope,\n): string | undefined {\n  if (files.length === 0) return undefined;\n  if (scope === \"merged\") {\n    return [...files]\n      .reverse()\n      .map((f) => f.content)\n      .join(\"\\n\\n\");\n  }\n  return files[0]?.content;\n}\n\n/**\n * Write project instructions to `<cwd>/<filename>` atomically (temp + fsync +\n * rename, via the shipped `replaceFileAtomic`).\n *\n * Unlike the reader, this FAILS LOUD: an unsafe `filename` (path traversal,\n * separators, absolute) is rejected with `ConfigurationError`\n * (`code: \"unsafe_filename\"`) — symmetric with the reader, whose `filename`\n * flows through the same `isSafePattern` guard — and a write error (e.g. the\n * parent directory does not exist) propagates to the caller. A failed mutation\n * is a real error, never silently swallowed.\n *\n * Public via `@theokit/sdk/project`.\n *\n * @public\n */\nexport async function writeProjectInstructions(\n  cwd: string,\n  content: string,\n  options?: WriteProjectInstructionsOptions,\n): Promise<void> {\n  const filename = options?.filename ?? DEFAULT_FILENAME;\n  if (!isSafePattern(filename)) {\n    throw new ConfigurationError(\n      `writeProjectInstructions: unsafe filename ${JSON.stringify(filename)} (no path traversal, separators, or absolute paths)`,\n      { code: \"unsafe_filename\" },\n    );\n  }\n  await replaceFileAtomic(join(cwd, filename), content);\n}\n"]}
+{"version":3,"sources":["../src/internal/runtime/context/project-instructions.ts"],"names":[],"mappings":";;;;;;;AA8CA,IAAM,gBAAA,GAAmB,SAAA;AAiBzB,eAAsB,uBAAA,CACpB,KACA,OAAA,EAC8B;AAC9B,EAAA,MAAM,QAAA,GAAW,SAAS,QAAA,IAAY,gBAAA;AACtC,EAAA,MAAM,KAAA,GAAQ,SAAS,KAAA,IAAS,SAAA;AAChC,EAAA,MAAM,KAAA,GAAQ,aAAA,CAAc,GAAA,EAAK,QAAA,EAAU,SAAS,OAAO,CAAA;AAE3D,EAAA,MAAM,QAAkC,EAAC;AACzC,EAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,IAAA,IAAI;AACF,MAAA,KAAA,CAAM,IAAA,CAAK,EAAE,IAAA,EAAM,OAAA,EAAS,MAAM,QAAA,CAAS,IAAA,EAAM,MAAM,CAAA,EAAG,CAAA;AAAA,IAC5D,CAAA,CAAA,MAAQ;AAAA,IAER;AAAA,EACF;AAEA,EAAA,OAAO,EAAE,KAAA,EAAO,OAAA,EAAS,aAAA,CAAc,KAAA,EAAO,KAAK,CAAA,EAAE;AACvD;AAEA,SAAS,aAAA,CACP,OACA,KAAA,EACoB;AACpB,EAAA,IAAI,KAAA,CAAM,MAAA,KAAW,CAAA,EAAG,OAAO,MAAA;AAC/B,EAAA,IAAI,UAAU,QAAA,EAAU;AACtB,IAAA,OAAO,CAAC,GAAG,KAAK,CAAA,CACb,OAAA,EAAQ,CACR,GAAA,CAAI,CAAC,CAAA,KAAM,CAAA,CAAE,OAAO,CAAA,CACpB,KAAK,MAAM,CAAA;AAAA,EAChB;AACA,EAAA,OAAO,KAAA,CAAM,CAAC,CAAA,EAAG,OAAA;AACnB;AAiBA,eAAsB,wBAAA,CACpB,GAAA,EACA,OAAA,EACA,OAAA,EACe;AACf,EAAA,MAAM,QAAA,GAAW,SAAS,QAAA,IAAY,gBAAA;AACtC,EAAA,IAAI,CAAC,aAAA,CAAc,QAAQ,CAAA,EAAG;AAC5B,IAAA,MAAM,IAAI,kBAAA;AAAA,MACR,CAAA,0CAAA,EAA6C,IAAA,CAAK,SAAA,CAAU,QAAQ,CAAC,CAAA,mDAAA,CAAA;AAAA,MACrE,EAAE,MAAM,iBAAA;AAAkB,KAC5B;AAAA,EACF;AACA,EAAA,MAAM,iBAAA,CAAkB,IAAA,CAAK,GAAA,EAAK,QAAQ,GAAG,OAAO,CAAA;AACtD","file":"project.js","sourcesContent":["import { readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\n\nimport { ConfigurationError } from \"../../../errors.js\";\nimport { replaceFileAtomic } from \"../../persistence/atomic-write.js\";\nimport { isSafePattern, walkUpForFile } from \"./context-discovery.js\";\n\n/** How discovered instruction files are reduced to a single `content` string. */\nexport type ProjectInstructionScope = \"nearest\" | \"merged\";\n\n/** One discovered project-instruction file. */\nexport interface ProjectInstructionFile {\n  /** Absolute path to the file. */\n  path: string;\n  /** Full file content (never truncated — the caller bounds it). */\n  content: string;\n}\n\n/** Result of {@link readProjectInstructions}. */\nexport interface ProjectInstructions {\n  /** Found files, nearest-first (innermost directory first). Empty if none. */\n  files: ProjectInstructionFile[];\n  /**\n   * The `scope`-selected reduction: `nearest` → the innermost file's content;\n   * `merged` → all files joined root-first (nearest content last). `undefined`\n   * when no file was found.\n   */\n  content: string | undefined;\n}\n\n/** Options for {@link readProjectInstructions}. */\nexport interface ReadProjectInstructionsOptions {\n  /** Instruction filename to discover. Default `\"THEO.md\"`. */\n  filename?: string;\n  /** How to reduce the found files to `content`. Default `\"nearest\"`. */\n  scope?: ProjectInstructionScope;\n  /** Stop the upward walk at this directory (inclusive). Default: filesystem root. */\n  stopDir?: string;\n}\n\n/** Options for {@link writeProjectInstructions}. */\nexport interface WriteProjectInstructionsOptions {\n  /** Instruction filename to write. Default `\"THEO.md\"`. */\n  filename?: string;\n}\n\nconst DEFAULT_FILENAME = \"THEO.md\";\n\n/**\n * Read hierarchical project instructions by walking up from `cwd`.\n *\n * Discovers every `<dir>/<filename>` from `cwd` up to the filesystem root (or\n * `stopDir`), reads each, and returns them nearest-first in `files` plus a\n * `content` reduction chosen by `scope`. Composes the hardened internal\n * `walkUpForFile` (64-level cap, realpath dedup, FS-race tolerant).\n *\n * NEVER throws: a missing/unreadable directory or a path that exists but is not\n * a readable file is skipped; no instruction file → `{ files: [], content: undefined }`.\n *\n * Public via `@theokit/sdk/project`.\n *\n * @public\n */\nexport async function readProjectInstructions(\n  cwd: string,\n  options?: ReadProjectInstructionsOptions,\n): Promise<ProjectInstructions> {\n  const filename = options?.filename ?? DEFAULT_FILENAME;\n  const scope = options?.scope ?? \"nearest\";\n  const paths = walkUpForFile(cwd, filename, options?.stopDir);\n\n  const files: ProjectInstructionFile[] = [];\n  for (const path of paths) {\n    try {\n      files.push({ path, content: await readFile(path, \"utf8\") });\n    } catch {\n      // FS-race / unreadable / directory-named-like-file → skip (never-throw)\n    }\n  }\n\n  return { files, content: reduceContent(files, scope) };\n}\n\nfunction reduceContent(\n  files: ProjectInstructionFile[],\n  scope: ProjectInstructionScope,\n): string | undefined {\n  if (files.length === 0) return undefined;\n  if (scope === \"merged\") {\n    return [...files]\n      .reverse()\n      .map((f) => f.content)\n      .join(\"\\n\\n\");\n  }\n  return files[0]?.content;\n}\n\n/**\n * Write project instructions to `<cwd>/<filename>` atomically (temp + fsync +\n * rename, via the shipped `replaceFileAtomic`).\n *\n * Unlike the reader, this FAILS LOUD: an unsafe `filename` (path traversal,\n * separators, absolute) is rejected with `ConfigurationError`\n * (`code: \"unsafe_filename\"`) — symmetric with the reader, whose `filename`\n * flows through the same `isSafePattern` guard — and a write error (e.g. the\n * parent directory does not exist) propagates to the caller. A failed mutation\n * is a real error, never silently swallowed.\n *\n * Public via `@theokit/sdk/project`.\n *\n * @public\n */\nexport async function writeProjectInstructions(\n  cwd: string,\n  content: string,\n  options?: WriteProjectInstructionsOptions,\n): Promise<void> {\n  const filename = options?.filename ?? DEFAULT_FILENAME;\n  if (!isSafePattern(filename)) {\n    throw new ConfigurationError(\n      `writeProjectInstructions: unsafe filename ${JSON.stringify(filename)} (no path traversal, separators, or absolute paths)`,\n      { code: \"unsafe_filename\" },\n    );\n  }\n  await replaceFileAtomic(join(cwd, filename), content);\n}\n"]}

package/dist/providers.cjs

@@ -1,23 +1,23 @@
 'use strict';
 
-var chunkJPBKYL3B_cjs = require('./chunk-JPBKYL3B.cjs');
-require('./chunk-HCZD23VS.cjs');
-require('./chunk-6HKGLTJI.cjs');
-require('./chunk-XJCXEKMD.cjs');
-require('./chunk-52NKC5HT.cjs');
-require('./chunk-4ZHTIJNE.cjs');
-require('./chunk-XL7Q7HB2.cjs');
-require('./chunk-EG4QM7ZJ.cjs');
+var chunkANMJJD6D_cjs = require('./chunk-ANMJJD6D.cjs');
+require('./chunk-QC55H6RJ.cjs');
+require('./chunk-NVXXWAU7.cjs');
+require('./chunk-4NLCWGH7.cjs');
+require('./chunk-EXTRW7GW.cjs');
+require('./chunk-HUFSABUZ.cjs');
+require('./chunk-J7J7J2GN.cjs');
+require('./chunk-6LHQPOMI.cjs');
 
 
 
 Object.defineProperty(exports, "getProviderProfile", {
   enumerable: true,
-  get: function () { return chunkJPBKYL3B_cjs.getProviderProfile; }
+  get: function () { return chunkANMJJD6D_cjs.getProviderProfile; }
 });
 Object.defineProperty(exports, "listProviders", {
   enumerable: true,
-  get: function () { return chunkJPBKYL3B_cjs.listProviders; }
+  get: function () { return chunkANMJJD6D_cjs.listProviders; }
 });
 //# sourceMappingURL=providers.cjs.map
 //# sourceMappingURL=providers.cjs.map

package/dist/providers.d.cts

@@ -1,4 +1,6 @@
 /**
+ * Published as `@theokit/sdk/providers`.
+ *
  * The provider registry, as public API.
  *
  * It was `@internal`, which meant the SDK was the only thing that could answer "which providers

package/dist/providers.d.ts

@@ -1,4 +1,6 @@
 /**
+ * Published as `@theokit/sdk/providers`.
+ *
  * The provider registry, as public API.
  *
  * It was `@internal`, which meant the SDK was the only thing that could answer "which providers