@oneharness/sdk 0.15.0 → 0.16.0

package/README.md

@@ -11,7 +11,7 @@ const checked: RunReport = RunReportSchema.parse(report);
 console.log(checked.results[0]?.text, checked.results[0]?.usage.input_tokens);
 ```
 
-The client covers every verb the CLI exposes, so nothing needs a hand-built command line: `run`, `runMock`, `runStream`, `list`, `detect`, `config`, `sync`, `init`, `usage`, `gate`, `mock`, `interrupt`, `history`, `historyList`, `historyWatch`, `historyClear`, and `historyMigrate`. That coverage is gated, not asserted here. `runMock` uses the deterministic responder shipped in the CLI; see [Testing patterns](../../docs/testing-patterns.md). Both streaming methods return async iterators:
+The client covers every verb the CLI exposes, so nothing needs a hand-built command line: `run`, `runMock`, `runStream`, `list`, `detect`, `config`, `sync`, `init`, `usage`, `gate`, `mock`, `interrupt`, `history`, `historyList`, `historyWatch`, `historyClear`, `historyMigrate`, and `historyPointers`. That coverage is gated, not asserted here. `runMock` uses the deterministic responder shipped in the CLI; see [Testing patterns](../../docs/testing-patterns.md). Both streaming methods return async iterators:
 
 ```ts
 for await (const envelope of oneharness.runStream({

package/dist/generated/capabilities.d.ts

@@ -250,6 +250,11 @@ export declare const CAPABILITIES: {
             readonly flag: "--history-dir";
             readonly kind: "value";
             readonly unless: null;
+        }, {
+            readonly option: "historyPointerFile";
+            readonly flag: "--history-pointer-file";
+            readonly kind: "value";
+            readonly unless: null;
         }, {
             readonly option: "historyName";
             readonly flag: "--history-name";
@@ -490,6 +495,11 @@ export declare const CAPABILITIES: {
             readonly flag: "--history-dir";
             readonly kind: "value";
             readonly unless: null;
+        }, {
+            readonly option: "historyPointerFile";
+            readonly flag: "--history-pointer-file";
+            readonly kind: "value";
+            readonly unless: null;
         }, {
             readonly option: "historyName";
             readonly flag: "--history-name";
@@ -1044,5 +1054,22 @@ export declare const CAPABILITIES: {
         }];
         readonly uncovered: readonly [];
     };
+    readonly historyPointers: {
+        readonly method: "historyPointers";
+        readonly argv: readonly ["history", "pointers"];
+        readonly options: "history_pointers_options";
+        readonly output: "history_pointers";
+        readonly stdout: "json";
+        readonly stdin: false;
+        readonly rust: "oneharness_core::io::history::read_pointers";
+        readonly always: readonly ["--compact", "--format", "json"];
+        readonly bindings: readonly [{
+            readonly option: "file";
+            readonly flag: "";
+            readonly kind: "positional";
+            readonly unless: null;
+        }];
+        readonly uncovered: readonly [];
+    };
 };
 export type CapabilityMethod = keyof typeof CAPABILITIES;

package/dist/generated/capabilities.js

@@ -253,6 +253,12 @@ export const CAPABILITIES = {
                 kind: "value",
                 unless: null,
             },
+            {
+                option: "historyPointerFile",
+                flag: "--history-pointer-file",
+                kind: "value",
+                unless: null,
+            },
             {
                 option: "historyName",
                 flag: "--history-name",
@@ -541,6 +547,12 @@ export const CAPABILITIES = {
                 kind: "value",
                 unless: null,
             },
+            {
+                option: "historyPointerFile",
+                flag: "--history-pointer-file",
+                kind: "value",
+                unless: null,
+            },
             {
                 option: "historyName",
                 flag: "--history-name",
@@ -1184,4 +1196,23 @@ export const CAPABILITIES = {
         ],
         uncovered: [],
     },
+    historyPointers: {
+        method: "historyPointers",
+        argv: ["history", "pointers"],
+        options: "history_pointers_options",
+        output: "history_pointers",
+        stdout: "json",
+        stdin: false,
+        rust: "oneharness_core::io::history::read_pointers",
+        always: ["--compact", "--format", "json"],
+        bindings: [
+            {
+                option: "file",
+                flag: "",
+                kind: "positional",
+                unless: null,
+            },
+        ],
+        uncovered: [],
+    },
 };

package/dist/generated/config-report.d.ts

@@ -56,6 +56,7 @@ export interface ConfigReport {
     history_labels: {
         [k: string]: Field3;
     };
+    history_pointer_file: Field3;
     hooks: Field10;
     max_parallel: Field8;
     mode: Field4;

package/dist/generated/contracts.d.ts

@@ -384,7 +384,7 @@ export interface RunResult {
      */
     bin: string;
     /**
-     * The exact argv oneharness built (argv[0] is the binary).
+     * The exact argv oneharness built; its first element is the binary.
      */
     command: string[];
     /**

package/dist/generated/history-pointers-options.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Options accepted by the language SDKs' `historyPointers()`: the pointer
+ * file a run was given as `historyPointerFile`.
+ */
+export interface HistoryPointersOptions {
+    /**
+     * The pointer file to read. A file that does not exist reads as empty.
+     */
+    file: string;
+}

package/dist/generated/history-pointers-options.js

@@ -0,0 +1,2 @@
+/* Generated from oneharness-core. Do not edit. */
+export {};

package/dist/generated/history-pointers.d.ts

@@ -0,0 +1,100 @@
+/**
+ * What [`read_pointers`] read: every well-formed [`HistoryPointer`] line in
+ * file order, and how many lines were not one.
+ */
+export interface HistoryPointers {
+    /**
+     * The pointer lines, in the order they were appended.
+     */
+    pointers: HistoryPointer[];
+    /**
+     * Lines that were not one complete pointer object — a torn tail left by
+     * an interrupted writer, or a foreign line — counted rather than failing
+     * the read.
+     */
+    skipped: number;
+    [k: string]: unknown;
+}
+/**
+ * One line of a run's **pointer file**: where one harness run's history went.
+ *
+ * A consumer that starts many `oneharness` processes (or in-process runs) names
+ * one file, and every run with history on appends one of these per harness run
+ * it begins — so "which sessions did this run launch, and where are they" is a
+ * read of that one small file rather than a scan of the whole store, wherever
+ * the store lives. `history_dir` / `history_project` / `history_session` are
+ * spelled as the `oneharness-session` artifact `oneagentgraph` publishes, so a
+ * reader already resolving that through `io::history::find_session_path`
+ * resolves these unchanged.
+ *
+ * Built only through [`HistoryPointer::new`] over a [`PointerSession`], and
+ * read back only through a deserialization that re-checks every invariant
+ * `new` establishes — the four session spellings compose into one file, the
+ * two identity spellings are the parsed [`HarnessIdentity`]'s own, the version
+ * is one this reader knows — so a line that parses IS a pointer, and a foreign
+ * object that happens to carry these keys is counted as skipped rather than
+ * read as one.
+ * The fields are read through accessors for the same reason: a Rust caller
+ * gets a line from one of those two doors, never assembles or edits one.
+ */
+export interface HistoryPointer {
+    /**
+     * The harness id's base, e.g. `claude-code`.
+     */
+    harness: string;
+    /**
+     * The whole configured id, e.g. `claude-code:primary` — always `harness`
+     * with `:variant` when there is one.
+     */
+    harness_id: string;
+    /**
+     * The store the session is under, absolute.
+     */
+    history_dir: string;
+    /**
+     * The session file, absolute; the same path the run report echoes, and
+     * always `<history_dir>/<history_project>/<history_session>.jsonl`.
+     */
+    history_file: string;
+    /**
+     * The history id of the record this harness run will close with — the
+     * exact id `history show <history-id>` resolves.
+     */
+    history_id: string;
+    /**
+     * The project slug — the session file's parent directory name.
+     */
+    history_project: string;
+    /**
+     * The session id — the session file's stem.
+     */
+    history_session: string;
+    labels?: HistoryLabels | undefined;
+    /**
+     * The session's human-meaningful name (see [`session_name`]).
+     */
+    name: string;
+    /**
+     * The project directory the run operates in, canonical.
+     */
+    project: string;
+    /**
+     * [`POINTER_SCHEMA_VERSION`]; a reader accepts any `1.<minor>`.
+     */
+    schema_version: string;
+    /**
+     * RFC 3339 UTC, when this harness run began.
+     */
+    started: string;
+    /**
+     * The variant, omitted for a bare harness.
+     */
+    variant?: string | null | undefined;
+    [k: string]: unknown;
+}
+/**
+ * The session's validated labels, omitted when empty.
+ */
+export interface HistoryLabels {
+    [k: string]: string;
+}

package/dist/generated/history-pointers.js

@@ -0,0 +1,2 @@
+/* Generated from oneharness-core. Do not edit. */
+export {};

package/dist/generated/options.d.ts

@@ -69,6 +69,14 @@ export interface RunOptions {
     historyDir?: string | undefined;
     historyLabels?: HistoryLabels | undefined;
     historyName?: string | undefined;
+    /**
+     * The run's pointer file: with history on, every harness run this run
+     * begins appends one `HistoryPointer` line here saying where its session
+     * went (see `historyPointers()`), the store itself staying where
+     * `historyDir` puts it. An empty path is refused rather than read as
+     * unset — leave the option out to name no file.
+     */
+    historyPointerFile?: string | undefined;
     /**
      * Maximum harnesses (or, in a batch, prompts) to run concurrently.
      */

package/dist/generated/run-stream-envelope.d.ts

@@ -458,7 +458,7 @@ export interface RunResult {
      */
     bin: string;
     /**
-     * The exact argv oneharness built (argv[0] is the binary).
+     * The exact argv oneharness built; its first element is the binary.
      */
     command: string[];
     /**

package/dist/generated/schemas.json

@@ -261,6 +261,12 @@
                     "kind": "value",
                     "unless": null
                 },
+                {
+                    "option": "historyPointerFile",
+                    "flag": "--history-pointer-file",
+                    "kind": "value",
+                    "unless": null
+                },
                 {
                     "option": "historyName",
                     "flag": "--history-name",
@@ -554,6 +560,12 @@
                     "kind": "value",
                     "unless": null
                 },
+                {
+                    "option": "historyPointerFile",
+                    "flag": "--history-pointer-file",
+                    "kind": "value",
+                    "unless": null
+                },
                 {
                     "option": "historyName",
                     "flag": "--history-name",
@@ -1272,6 +1284,32 @@
                 }
             ],
             "uncovered": []
+        },
+        {
+            "method": "historyPointers",
+            "argv": [
+                "history",
+                "pointers"
+            ],
+            "options": "history_pointers_options",
+            "output": "history_pointers",
+            "stdout": "json",
+            "stdin": false,
+            "rust": "oneharness_core::io::history::read_pointers",
+            "always": [
+                "--compact",
+                "--format",
+                "json"
+            ],
+            "bindings": [
+                {
+                    "option": "file",
+                    "flag": "",
+                    "kind": "positional",
+                    "unless": null
+                }
+            ],
+            "uncovered": []
         }
     ],
     "run_report": {
@@ -1842,7 +1880,7 @@
                         "const": "quota"
                     },
                     {
-                        "description": "The session this run asked to continue does not exist for the identity it\nran as, so the harness refused before doing any work (see\n[`unknown_session_rejection`]). Distinct from every other kind because the\ntask itself is fine: another identity — or a fresh session on this one —\ncan still run it.",
+                        "description": "The session this run asked to continue does not exist for the identity\nit ran as, so the harness refused before doing any work (see the private\n`unknown_session_rejection` rule). Distinct from every other kind\nbecause the task itself is fine: another identity — or a fresh session\non this one — can still run it.",
                         "type": "string",
                         "const": "session_not_found"
                     },
@@ -2057,7 +2095,7 @@
                         "type": "string"
                     },
                     "command": {
-                        "description": "The exact argv oneharness built (argv[0] is the binary).",
+                        "description": "The exact argv oneharness built; its first element is the binary.",
                         "type": "array",
                         "items": {
                             "type": "string"
@@ -2923,7 +2961,7 @@
                         "const": "quota"
                     },
                     {
-                        "description": "The session this run asked to continue does not exist for the identity it\nran as, so the harness refused before doing any work (see\n[`unknown_session_rejection`]). Distinct from every other kind because the\ntask itself is fine: another identity — or a fresh session on this one —\ncan still run it.",
+                        "description": "The session this run asked to continue does not exist for the identity\nit ran as, so the harness refused before doing any work (see the private\n`unknown_session_rejection` rule). Distinct from every other kind\nbecause the task itself is fine: another identity — or a fresh session\non this one — can still run it.",
                         "type": "string",
                         "const": "session_not_found"
                     },
@@ -3302,7 +3340,7 @@
                         "type": "string"
                     },
                     "command": {
-                        "description": "The exact argv oneharness built (argv[0] is the binary).",
+                        "description": "The exact argv oneharness built; its first element is the binary.",
                         "type": "array",
                         "items": {
                             "type": "string"
@@ -3798,6 +3836,11 @@
             "historyName": {
                 "type": "string"
             },
+            "historyPointerFile": {
+                "description": "The run's pointer file: with history on, every harness run this run\nbegins appends one `HistoryPointer` line here saying where its session\nwent (see `historyPointers()`), the store itself staying where\n`historyDir` puts it. An empty path is refused rather than read as\nunset — leave the option out to name no file.",
+                "type": "string",
+                "minLength": 1
+            },
             "maxParallel": {
                 "description": "Maximum harnesses (or, in a batch, prompts) to run concurrently.",
                 "type": "integer",
@@ -5974,7 +6017,7 @@
                         "const": "quota"
                     },
                     {
-                        "description": "The session this run asked to continue does not exist for the identity it\nran as, so the harness refused before doing any work (see\n[`unknown_session_rejection`]). Distinct from every other kind because the\ntask itself is fine: another identity — or a fresh session on this one —\ncan still run it.",
+                        "description": "The session this run asked to continue does not exist for the identity\nit ran as, so the harness refused before doing any work (see the private\n`unknown_session_rejection` rule). Distinct from every other kind\nbecause the task itself is fine: another identity — or a fresh session\non this one — can still run it.",
                         "type": "string",
                         "const": "session_not_found"
                     },
@@ -8976,7 +9019,7 @@
                         "const": "quota"
                     },
                     {
-                        "description": "The session this run asked to continue does not exist for the identity it\nran as, so the harness refused before doing any work (see\n[`unknown_session_rejection`]). Distinct from every other kind because the\ntask itself is fine: another identity — or a fresh session on this one —\ncan still run it.",
+                        "description": "The session this run asked to continue does not exist for the identity\nit ran as, so the harness refused before doing any work (see the private\n`unknown_session_rejection` rule). Distinct from every other kind\nbecause the task itself is fine: another identity — or a fresh session\non this one — can still run it.",
                         "type": "string",
                         "const": "session_not_found"
                     },
@@ -9360,7 +9403,7 @@
                         "const": "quota"
                     },
                     {
-                        "description": "The session this run asked to continue does not exist for the identity it\nran as, so the harness refused before doing any work (see\n[`unknown_session_rejection`]). Distinct from every other kind because the\ntask itself is fine: another identity — or a fresh session on this one —\ncan still run it.",
+                        "description": "The session this run asked to continue does not exist for the identity\nit ran as, so the harness refused before doing any work (see the private\n`unknown_session_rejection` rule). Distinct from every other kind\nbecause the task itself is fine: another identity — or a fresh session\non this one — can still run it.",
                         "type": "string",
                         "const": "session_not_found"
                     },
@@ -12482,7 +12525,7 @@
                         "const": "quota"
                     },
                     {
-                        "description": "The session this run asked to continue does not exist for the identity it\nran as, so the harness refused before doing any work (see\n[`unknown_session_rejection`]). Distinct from every other kind because the\ntask itself is fine: another identity — or a fresh session on this one —\ncan still run it.",
+                        "description": "The session this run asked to continue does not exist for the identity\nit ran as, so the harness refused before doing any work (see the private\n`unknown_session_rejection` rule). Distinct from every other kind\nbecause the task itself is fine: another identity — or a fresh session\non this one — can still run it.",
                         "type": "string",
                         "const": "session_not_found"
                     },
@@ -15958,6 +16001,9 @@
                     "$ref": "#/$defs/Field3"
                 }
             },
+            "history_pointer_file": {
+                "$ref": "#/$defs/Field3"
+            },
             "hooks": {
                 "$ref": "#/$defs/Field10"
             },
@@ -16035,6 +16081,7 @@
             "require_available",
             "history",
             "history_dir",
+            "history_pointer_file",
             "history_labels",
             "allowed_tools",
             "denied_tools",
@@ -16760,7 +16807,7 @@
     "usage_report": {
         "$schema": "https://json-schema.org/draft/2020-12/schema",
         "title": "UsageReport",
-        "description": "One usage report: every probed identity, stamped with a single observation\ntime supplied by the caller (this module reads no clock).\n\nDeserializing is a consumer boundary — `oneharness-core` is published for\nsibling tools — so the envelope is validated on the way in rather than\ntrusted: see [`UsageReportWire`].",
+        "description": "One usage report: every probed identity, stamped with a single observation\ntime supplied by the caller (this module reads no clock).\n\nDeserializing is a consumer boundary — `oneharness-core` is published for\nsibling tools — so the envelope is validated on the way in rather than\ntrusted: see the private `UsageReportWire` shape.",
         "type": "object",
         "properties": {
             "identities": {
@@ -17057,7 +17104,7 @@
                 ]
             },
             "UsageIdentity": {
-                "description": "One harness identity's headroom.\n\nDeserializing is a consumer boundary like the envelope's, so every string an\nidentity carries is flattened through [`without_control_chars`] on the way in\n— see [`UsageIdentityWire`].",
+                "description": "One harness identity's headroom.\n\nDeserializing is a consumer boundary like the envelope's, so every string an\nidentity carries is flattened through the private `without_control_chars`\nfilter on the way in — see the private `UsageIdentityWire` shape.",
                 "type": "object",
                 "properties": {
                     "auth_mode": {
@@ -17634,5 +17681,149 @@
                 ]
             }
         }
+    },
+    "history_pointers_options": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "title": "HistoryPointersOptions",
+        "description": "Options accepted by the language SDKs' `historyPointers()`: the pointer\nfile a run was given as `historyPointerFile`.",
+        "type": "object",
+        "properties": {
+            "file": {
+                "description": "The pointer file to read. A file that does not exist reads as empty.",
+                "type": "string",
+                "minLength": 1
+            }
+        },
+        "additionalProperties": false,
+        "required": [
+            "file"
+        ]
+    },
+    "history_pointers": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "title": "HistoryPointers",
+        "description": "What [`read_pointers`] read: every well-formed [`HistoryPointer`] line in\nfile order, and how many lines were not one.",
+        "type": "object",
+        "properties": {
+            "pointers": {
+                "description": "The pointer lines, in the order they were appended.",
+                "type": "array",
+                "items": {
+                    "$ref": "#/$defs/HistoryPointer"
+                }
+            },
+            "skipped": {
+                "description": "Lines that were not one complete pointer object — a torn tail left by\nan interrupted writer, or a foreign line — counted rather than failing\nthe read.",
+                "type": "integer",
+                "format": "uint",
+                "minimum": 0
+            }
+        },
+        "required": [
+            "pointers",
+            "skipped"
+        ],
+        "$defs": {
+            "HistoryLabels": {
+                "type": "object",
+                "additionalProperties": {
+                    "type": "string",
+                    "maxLength": 256,
+                    "minLength": 1,
+                    "not": {
+                        "pattern": "[\\u0000-\\u001f\\u007f-\\u009f]"
+                    }
+                },
+                "propertyNames": {
+                    "type": "string",
+                    "maxLength": 64,
+                    "not": {
+                        "pattern": "[^A-Za-z0-9._-]"
+                    },
+                    "pattern": "^[A-Za-z0-9]"
+                }
+            },
+            "HistoryPointer": {
+                "description": "One line of a run's **pointer file**: where one harness run's history went.\n\nA consumer that starts many `oneharness` processes (or in-process runs) names\none file, and every run with history on appends one of these per harness run\nit begins — so \"which sessions did this run launch, and where are they\" is a\nread of that one small file rather than a scan of the whole store, wherever\nthe store lives. `history_dir` / `history_project` / `history_session` are\nspelled as the `oneharness-session` artifact `oneagentgraph` publishes, so a\nreader already resolving that through `io::history::find_session_path`\nresolves these unchanged.\n\nBuilt only through [`HistoryPointer::new`] over a [`PointerSession`], and\nread back only through a deserialization that re-checks every invariant\n`new` establishes — the four session spellings compose into one file, the\ntwo identity spellings are the parsed [`HarnessIdentity`]'s own, the version\nis one this reader knows — so a line that parses IS a pointer, and a foreign\nobject that happens to carry these keys is counted as skipped rather than\nread as one.\nThe fields are read through accessors for the same reason: a Rust caller\ngets a line from one of those two doors, never assembles or edits one.",
+                "type": "object",
+                "properties": {
+                    "harness": {
+                        "description": "The harness id's base, e.g. `claude-code`.",
+                        "type": "string"
+                    },
+                    "harness_id": {
+                        "description": "The whole configured id, e.g. `claude-code:primary` — always `harness`\nwith `:variant` when there is one.",
+                        "type": "string"
+                    },
+                    "history_dir": {
+                        "description": "The store the session is under, absolute.",
+                        "type": "string"
+                    },
+                    "history_file": {
+                        "description": "The session file, absolute; the same path the run report echoes, and\nalways `<history_dir>/<history_project>/<history_session>.jsonl`.",
+                        "type": "string"
+                    },
+                    "history_id": {
+                        "description": "The history id of the record this harness run will close with — the\nexact id `history show <history-id>` resolves.",
+                        "type": "string",
+                        "maxLength": 36,
+                        "minLength": 36,
+                        "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
+                    },
+                    "history_project": {
+                        "description": "The project slug — the session file's parent directory name.",
+                        "type": "string"
+                    },
+                    "history_session": {
+                        "description": "The session id — the session file's stem.",
+                        "type": "string"
+                    },
+                    "labels": {
+                        "description": "The session's validated labels, omitted when empty.",
+                        "$ref": "#/$defs/HistoryLabels"
+                    },
+                    "name": {
+                        "description": "The session's human-meaningful name (see [`session_name`]).",
+                        "type": "string"
+                    },
+                    "project": {
+                        "description": "The project directory the run operates in, canonical.",
+                        "type": "string"
+                    },
+                    "schema_version": {
+                        "description": "[`POINTER_SCHEMA_VERSION`]; a reader accepts any `1.<minor>`.",
+                        "type": "string"
+                    },
+                    "started": {
+                        "description": "RFC 3339 UTC, when this harness run began.",
+                        "$ref": "#/$defs/UtcInstant"
+                    },
+                    "variant": {
+                        "description": "The variant, omitted for a bare harness.",
+                        "type": [
+                            "string",
+                            "null"
+                        ]
+                    }
+                },
+                "required": [
+                    "schema_version",
+                    "history_id",
+                    "history_dir",
+                    "history_project",
+                    "history_session",
+                    "history_file",
+                    "name",
+                    "project",
+                    "harness",
+                    "harness_id",
+                    "started"
+                ]
+            },
+            "UtcInstant": {
+                "description": "An RFC 3339 timestamp in UTC (`Z`), in oneharness's canonical spelling.",
+                "type": "string"
+            }
+        }
     }
 }

package/dist/generated/usage-report.d.ts

@@ -145,7 +145,7 @@ export type UnknownReason = {
  *
  * Deserializing is a consumer boundary — `oneharness-core` is published for
  * sibling tools — so the envelope is validated on the way in rather than
- * trusted: see [`UsageReportWire`].
+ * trusted: see the private `UsageReportWire` shape.
  */
 export interface UsageReport {
     identities: UsageIdentity[];
@@ -163,8 +163,8 @@ export interface UsageReport {
  * One harness identity's headroom.
  *
  * Deserializing is a consumer boundary like the envelope's, so every string an
- * identity carries is flattened through [`without_control_chars`] on the way in
- * — see [`UsageIdentityWire`].
+ * identity carries is flattened through the private `without_control_chars`
+ * filter on the way in — see the private `UsageIdentityWire` shape.
  */
 export interface UsageIdentity {
     auth_mode: AuthMode;

package/dist/generated/zod.d.ts

@@ -14,6 +14,8 @@ import type { HistoryListOptions } from "./history-list-options.js";
 import type { HistoryLookup, HistoryLookupByLast, HistoryLookupBySession } from "./history-lookup.js";
 import type { HistoryMigrateOptions } from "./history-migrate-options.js";
 import type { HistoryMigrateReport, MigrationSummary } from "./history-migrate-report.js";
+import type { HistoryPointer, HistoryPointers } from "./history-pointers.js";
+import type { HistoryPointersOptions } from "./history-pointers-options.js";
 import type { HistoryRecords } from "./history-records.js";
 import type { HistoryEventLine, HistoryStreamEnvelope } from "./history-stream-envelope.js";
 import type { HistoryWatchOptions } from "./history-watch-options.js";
@@ -83,6 +85,9 @@ export declare const HistoryLookupByLastSchema: z.ZodType<HistoryLookupByLast>;
 export declare const HistoryLookupBySessionSchema: z.ZodType<HistoryLookupBySession>;
 export declare const HistoryMigrateOptionsSchema: z.ZodType<HistoryMigrateOptions>;
 export declare const HistoryMigrateReportSchema: z.ZodType<HistoryMigrateReport>;
+export declare const HistoryPointerSchema: z.ZodType<HistoryPointer>;
+export declare const HistoryPointersSchema: z.ZodType<HistoryPointers>;
+export declare const HistoryPointersOptionsSchema: z.ZodType<HistoryPointersOptions>;
 export declare const HistoryRecordSchema: z.ZodType<HistoryRecord>;
 export declare const HistoryRecordsSchema: z.ZodType<HistoryRecords>;
 export declare const HistorySessionSummarySchema: z.ZodType<HistorySessionSummary>;

package/dist/generated/zod.js

@@ -57,6 +57,7 @@ export const ConfigReportSchema = z.looseObject({
     history_labels: z
         .record(z.string(), z.lazy(() => Field3Schema))
         .refine((value) => value !== undefined, { message: "Required" }),
+    history_pointer_file: z.lazy(() => Field3Schema).refine((value) => value !== undefined, { message: "Required" }),
     hooks: z.lazy(() => Field10Schema).refine((value) => value !== undefined, { message: "Required" }),
     max_parallel: z.lazy(() => Field8Schema).refine((value) => value !== undefined, { message: "Required" }),
     mode: z.lazy(() => Field4Schema).refine((value) => value !== undefined, { message: "Required" }),
@@ -1134,6 +1135,39 @@ export const HistoryMigrateReportSchema = z.looseObject({
         .gte(0)
         .refine((value) => value !== undefined, { message: "Required" }),
 });
+export const HistoryPointerSchema = z.looseObject({
+    harness: z.string().refine((value) => value !== undefined, { message: "Required" }),
+    harness_id: z.string().refine((value) => value !== undefined, { message: "Required" }),
+    history_dir: z.string().refine((value) => value !== undefined, { message: "Required" }),
+    history_file: z.string().refine((value) => value !== undefined, { message: "Required" }),
+    history_id: z
+        .string()
+        .min(36)
+        .regex(new RegExp("^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$", "u"))
+        .refine((value) => [...value].length <= 36, { message: "Too long: expected at most 36 characters" })
+        .refine((value) => value !== undefined, { message: "Required" }),
+    history_project: z.string().refine((value) => value !== undefined, { message: "Required" }),
+    history_session: z.string().refine((value) => value !== undefined, { message: "Required" }),
+    labels: z.lazy(() => HistoryLabelsSchema).optional(),
+    name: z.string().refine((value) => value !== undefined, { message: "Required" }),
+    project: z.string().refine((value) => value !== undefined, { message: "Required" }),
+    schema_version: z.string().refine((value) => value !== undefined, { message: "Required" }),
+    started: z.lazy(() => UtcInstantSchema).refine((value) => value !== undefined, { message: "Required" }),
+    variant: z.union([z.string(), z.null()]).optional(),
+});
+export const HistoryPointersSchema = z.looseObject({
+    pointers: z.array(z.lazy(() => HistoryPointerSchema)).refine((value) => value !== undefined, { message: "Required" }),
+    skipped: z
+        .int()
+        .gte(0)
+        .refine((value) => value !== undefined, { message: "Required" }),
+});
+export const HistoryPointersOptionsSchema = z.strictObject({
+    file: z
+        .string()
+        .min(1)
+        .refine((value) => value !== undefined, { message: "Required" }),
+});
 export const HistoryRecordSchema = z.intersection(z.intersection(z.intersection(z.intersection(z.intersection(z.union([
     z.looseObject({
         duration_ms: z
@@ -2321,6 +2355,7 @@ export const RunOptionsSchema = z.strictObject({
     historyDir: z.string().optional(),
     historyLabels: z.lazy(() => HistoryLabelsSchema).optional(),
     historyName: z.string().optional(),
+    historyPointerFile: z.string().min(1).optional(),
     maxParallel: z.int().gte(0).optional(),
     mockHarnesses: z.array(z.string()).optional(),
     mockRules: z.string().optional(),

package/dist/index.d.ts

@@ -12,6 +12,8 @@ import type { HistoryListOptions } from "./generated/history-list-options.js";
 import type { HistoryLookup } from "./generated/history-lookup.js";
 import type { HistoryMigrateOptions } from "./generated/history-migrate-options.js";
 import type { HistoryMigrateReport } from "./generated/history-migrate-report.js";
+import type { HistoryPointers } from "./generated/history-pointers.js";
+import type { HistoryPointersOptions } from "./generated/history-pointers-options.js";
 import type { HistoryStreamEnvelope } from "./generated/history-stream-envelope.js";
 import type { HistoryWatchOptions } from "./generated/history-watch-options.js";
 import type { InitOptions } from "./generated/init-options.js";
@@ -42,6 +44,8 @@ export type { HistoryListOptions } from "./generated/history-list-options.js";
 export type { HistoryLookup, HistoryLookupByLast, HistoryLookupBySession, } from "./generated/history-lookup.js";
 export type { HistoryMigrateOptions } from "./generated/history-migrate-options.js";
 export type { HistoryMigrateReport } from "./generated/history-migrate-report.js";
+export type { HistoryPointer, HistoryPointers, } from "./generated/history-pointers.js";
+export type { HistoryPointersOptions } from "./generated/history-pointers-options.js";
 export type { HistoryRecords } from "./generated/history-records.js";
 export type { HistoryStreamEnvelope } from "./generated/history-stream-envelope.js";
 export type { HistoryWatchOptions } from "./generated/history-watch-options.js";
@@ -146,5 +150,13 @@ export declare class OneHarness {
     historyClear(options?: HistoryClearOptions): Promise<HistoryClearReport>;
     /** Rewrite legacy session files to the current record version. */
     historyMigrate(options?: HistoryMigrateOptions): Promise<HistoryMigrateReport>;
+    /**
+     * Read a run's pointer file (`historyPointerFile` on `run()`): one line per
+     * harness run begun with history on, naming where its session went.
+     *
+     * A missing file reads as empty; a torn or foreign line is counted in
+     * `skipped` rather than failing the read.
+     */
+    historyPointers(options: HistoryPointersOptions): Promise<HistoryPointers>;
     historyWatch(options?: HistoryWatchOptions): AsyncGenerator<HistoryStreamEnvelope>;
 }

package/dist/index.js

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
 import { createInterface } from "node:readline";
 import { CAPABILITIES, } from "./generated/capabilities.js";
-import { ConfigOptionsSchema, ConfigReportSchema, DetectOptionsSchema, DetectReportSchema, GateOptionsSchema, HistoryClearOptionsSchema, HistoryClearReportSchema, HistoryListOptionsSchema, HistoryListSchema, HistoryLookupSchema, HistoryMigrateOptionsSchema, HistoryMigrateReportSchema, HistoryRecordsSchema, HistoryStreamEnvelopeSchema, HistoryWatchOptionsSchema, InitOptionsSchema, InterruptOptionsSchema, InterruptResponseSchema, ListReportSchema, MockOptionsSchema, RunOptionsSchema, RunReportSchema, RunStreamEnvelopeSchema, SyncOptionsSchema, SyncReportSchema, UsageOptionsSchema, UsageReportSchema, } from "./generated/zod.js";
+import { ConfigOptionsSchema, ConfigReportSchema, DetectOptionsSchema, DetectReportSchema, GateOptionsSchema, HistoryClearOptionsSchema, HistoryClearReportSchema, HistoryListOptionsSchema, HistoryListSchema, HistoryLookupSchema, HistoryMigrateOptionsSchema, HistoryMigrateReportSchema, HistoryPointersOptionsSchema, HistoryPointersSchema, HistoryRecordsSchema, HistoryStreamEnvelopeSchema, HistoryWatchOptionsSchema, InitOptionsSchema, InterruptOptionsSchema, InterruptResponseSchema, ListReportSchema, MockOptionsSchema, RunOptionsSchema, RunReportSchema, RunStreamEnvelopeSchema, SyncOptionsSchema, SyncReportSchema, UsageOptionsSchema, UsageReportSchema, } from "./generated/zod.js";
 export { CAPABILITIES } from "./generated/capabilities.js";
 export * from "./generated/zod.js";
 /** A non-zero exit from the oneharness subprocess. */
@@ -482,6 +482,16 @@ export class OneHarness {
     async historyMigrate(options = {}) {
         return await this.call("historyMigrate", options, HistoryMigrateOptionsSchema, HistoryMigrateReportSchema);
     }
+    /**
+     * Read a run's pointer file (`historyPointerFile` on `run()`): one line per
+     * harness run begun with history on, naming where its session went.
+     *
+     * A missing file reads as empty; a torn or foreign line is counted in
+     * `skipped` rather than failing the read.
+     */
+    async historyPointers(options) {
+        return await this.call("historyPointers", options, HistoryPointersOptionsSchema, HistoryPointersSchema);
+    }
     historyWatch(options = {}) {
         const input = parseContract(HistoryWatchOptionsSchema, options, "invalid oneharness history watch options");
         return invokeStreamWith(this.options, capabilityArguments("historyWatch", input), HistoryStreamEnvelopeSchema, "invalid oneharness history watch contract", undefined, true);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneharness/sdk",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Typed Node.js SDK for oneharness",
   "type": "module",
   "main": "dist/index.js",
@@ -19,7 +19,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "oneharness-cli": "0.15.0",
+    "oneharness-cli": "0.16.0",
     "zod": "^4.4.3"
   }
 }