@caupulican/pi-adaptative 0.81.41 → 0.81.42

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [0.81.42] - 2026-07-27
+
+### Changed
+
+- Rebuilt delegated workers around immutable owner-authored execution contracts, durable logical-agent identities, resumable conversations and mailboxes, fenced write reservations, bounded resource materialization, verified model-pinned compaction, and event-driven terminal handoffs.
+- Consolidated session-owned orchestration events, actions, mailboxes, conversations, and deletion under one bounded artifact bundle while keeping cross-session write reservations globally coordinated.
+
+### Fixed
+
+- Made the Windows shell engine preserve `$?`, support controlled `exit`, and accept `head`/`tail -N`, so diagnostic-capture command chains complete with a terminal result instead of losing status or treating `exit` as an external command.
+- Added a provider- and tool-neutral WSL incident collector that packages the latest human session, recovery and orchestration records, explicitly requested command logs, TUI evidence, boot identity, installed-runtime hashes, bounded kernel diagnostics, and relevant Windows host events without collecting credential stores or emitting false missing-log warnings.
+- Made pre-start worker failures publish exactly one durable terminal handoff, rejected malformed typed result envelopes, and handled null or Buffer filesystem watcher filenames on Windows.
+- Made orchestration session paths portable across Windows and POSIX and bounded profile, process, event, result, and cumulative usage payloads at their owning contracts.
+- Kept explicit empty worker tool surfaces inside the repair loop and persisted immediate or argument-repaired tool requests in durable execution order, preventing unavailable-tool calls from collapsing into completion errors or divergent transcripts.
+- Preserved bounded host-observed changed-file progress when an agent-bound worker is suspended, so owner-session disposal remains resumable without fabricating terminal parent-session records.
+
 ## [0.81.41] - 2026-07-27
 
 ### Added

package/dist/bundled-resources/runtimes/pi-shell-engine/commands/text.py

@@ -97,7 +97,7 @@ def cat(ctx: "BuiltinContext") -> int:
 
 
 def _parse_n_flag(name: str, argv: list[str]) -> tuple[int, list[str]]:
-    """Parse `[-n N] [FILE]` only. Any other flag/form -> unsupported-flag."""
+    """Parse `[-n N|-N] [FILE]`. Any other flag/form -> unsupported-flag."""
     n = 10
     operands: list[str] = []
     args = argv[1:]
@@ -118,6 +118,10 @@ def _parse_n_flag(name: str, argv: list[str]) -> tuple[int, list[str]]:
             n = _parse_int_operand(name, a[2:])
             i += 1
             continue
+        if len(a) > 1 and a[0] == "-" and a[1:].isdigit():
+            n = int(a[1:])
+            i += 1
+            continue
         if a.startswith("-") and a != "-":
             _refuse_flag(name, a)
         operands.append(a)

package/dist/bundled-resources/runtimes/pi-shell-engine/context.py

@@ -46,7 +46,7 @@ class ExecContext:
     stderr: BinaryIO | int | None = None
 
 
-# Frozen inline sets: state mutators and the runner builtin are NOT in commands/REGISTRY;
-# exec.py handles them inline because they need ShellState / the executor.
-STATE_BUILTINS = {"cd", "export", "unset"}
+# Executor-owned builtins are NOT in commands/REGISTRY: state mutators and `exit`
+# need ShellState/control-flow access, while the runner needs the executor.
+STATE_BUILTINS = {"cd", "export", "unset", "exit"}
 RUNNER_BUILTINS = {"xargs"}

package/dist/bundled-resources/runtimes/pi-shell-engine/errors.py

@@ -47,3 +47,11 @@ class UnsupportedConstruct(Exception):
         self.code = "unsupported"
         self.construct = construct
         self.message = message
+
+
+class ShellExit(Exception):
+    """Controlled `exit` request carried to the nearest shell boundary."""
+
+    def __init__(self, exit_code: int) -> None:
+        super().__init__(exit_code)
+        self.exit_code = exit_code

package/dist/bundled-resources/runtimes/pi-shell-engine/exec.py

@@ -17,7 +17,7 @@ import parser as parser_module
 import proc
 import tokens as tokens_module
 from context import RUNNER_BUILTINS, STATE_BUILTINS, BuiltinContext, ExecContext
-from errors import UnsupportedConstruct
+from errors import ShellExit, UnsupportedConstruct
 from state import ShellState
 
 DEVNULL = os.devnull
@@ -209,6 +209,7 @@ def execute(list_node: nodes.CommandList, ctx: ExecContext) -> int:
     exit_code = 0
     for entry in list_node.entries:
         exit_code = _execute_andor(entry, ctx)
+        ctx.state.last_exit_code = exit_code
     return exit_code
 
 
@@ -222,6 +223,7 @@ def _execute_andor(andor: nodes.AndOr, ctx: ExecContext) -> int:
             if operator == "||" and exit_code == 0:
                 continue
         exit_code = _execute_pipeline(pipeline, ctx)
+        ctx.state.last_exit_code = exit_code
     return exit_code
 
 
@@ -310,6 +312,8 @@ def _run_pipeline_elements(elements: list, ctx: ExecContext) -> int:
                     # fabricated exit-0/empty-output success.
                     refusals[idx] = exc
                     results[idx] = 1
+                except ShellExit as exc:
+                    results[idx] = exc.exit_code
                 except BaseException as exc:  # noqa: BLE001 - any other stage failure must not crash the engine
                     # Any OTHER exception is a real per-stage failure, not a refusal: it
                     # gets a named, actionable one-line message on the merged sink (never
@@ -477,7 +481,10 @@ def _execute_subshell(node: nodes.Subshell, ctx: ExecContext, stdin_stream, stdo
         )
         isolated_state = ctx.state.copy()
         inner_ctx = _sub_ctx(ctx, isolated_state, r_in, r_out, r_err)
-        return execute(node.body, inner_ctx)
+        try:
+            return execute(node.body, inner_ctx)
+        except ShellExit as exc:
+            return exc.exit_code
     finally:
         tracker.close()
 
@@ -569,6 +576,19 @@ def _as_stream(fd_or_stream: BinaryIO | int, mode: str) -> BinaryIO:
 
 
 def _run_state_builtin(name: str, argv: list[str], ctx: ExecContext, out_stream: BinaryIO | int) -> int:
+    if name == "exit":
+        if len(argv) > 2:
+            _write_merged(out_stream, b"exit: too many arguments\n", ctx)
+            raise ShellExit(1)
+        if len(argv) == 1:
+            raise ShellExit(ctx.state.last_exit_code)
+        try:
+            exit_code = int(argv[1], 10)
+        except ValueError:
+            _write_merged(out_stream, f"exit: {argv[1]}: numeric argument required\n".encode("utf-8"), ctx)
+            raise ShellExit(2)
+        raise ShellExit(exit_code & 0xFF)
+
     if name == "cd":
         target = argv[1] if len(argv) > 1 else ctx.state.env.get("HOME")
         print_new_cwd = argv[1:2] == ["-"]
@@ -729,6 +749,9 @@ def run_command_substitution(src: str, ctx: ExecContext) -> tuple[str, int]:
         deadline=ctx.deadline,
         stderr=ctx.stderr,
     )
-    exit_code = execute(ast, sub_ctx)
+    try:
+        exit_code = execute(ast, sub_ctx)
+    except ShellExit as exc:
+        exit_code = exc.exit_code
     text = buffer.getvalue().decode("utf-8", errors="replace")
     return text.rstrip("\n"), exit_code

package/dist/bundled-resources/runtimes/pi-shell-engine/expand.py

@@ -97,6 +97,9 @@ def _resolve_param(name: str, op: str | None, arg: Word | None, ctx: "ExecContex
     split_and_glob_eligible is False here always; callers decide splitting based on
     quoting context (Raw vs DQ), not on the parameter's own nature.
     """
+    if name == "?" and op is None:
+        return str(ctx.state.last_exit_code), False
+
     env = ctx.state.env
     if op == "#len":
         value = env.get(name, "")

package/dist/bundled-resources/runtimes/pi-shell-engine/main.py

@@ -17,7 +17,7 @@ import exec as exec_module
 import parser as parser_module
 import tokens as tokens_module
 from context import ExecContext
-from errors import UnsupportedConstruct
+from errors import ShellExit, UnsupportedConstruct
 from expand import ParamExpansionError
 from state import ShellState
 
@@ -97,6 +97,9 @@ def main() -> int:
         tokens = tokens_module.tokenize(command)
         ast = parser_module.parse(tokens)
         exit_code = exec_module.execute(ast, ctx)
+    except ShellExit as exc:
+        _write_frame(exc.exit_code, state.cwd, state.delta(original_env), None)
+        return 0
     except UnsupportedConstruct as exc:
         output.write(exc.message.encode("utf-8", errors="replace"))
         _write_frame(

package/dist/bundled-resources/runtimes/pi-shell-engine/state.py

@@ -64,6 +64,7 @@ class ShellState:
 
     cwd: str
     env: ShellEnvironment = field(default_factory=ShellEnvironment)
+    last_exit_code: int = 0
 
     def __post_init__(self) -> None:
         if not isinstance(self.env, ShellEnvironment):
@@ -71,7 +72,7 @@ class ShellState:
 
     def copy(self) -> "ShellState":
         """Return an independent copy (used for subshell isolation)."""
-        return ShellState(cwd=self.cwd, env=self.env.copy())
+        return ShellState(cwd=self.cwd, env=self.env.copy(), last_exit_code=self.last_exit_code)
 
     def chdir(self, path: str) -> None:
         """Validate `path` exists and is a directory, then update cwd + OLDPWD."""

package/dist/bundled-resources/runtimes/pi-shell-engine/tokens.py

@@ -294,6 +294,8 @@ def _scan_dollar_form(src: str, pos: int) -> tuple[Segment, int]:
             )
         close = _find_closing_paren(src, pos + 2)
         return CmdSub(src=src[pos + 2 : close]), close + 1
+    if nxt == "?":
+        return Param(name="?", op=None, arg=None), pos + 2
     if nxt and (_IDENT_START_RE.match(nxt)):
         m = _IDENT_RE.match(src, pos + 1)
         assert m is not None

package/dist/core/agent-paths.d.ts

@@ -39,6 +39,38 @@ export declare function runtimesDir(kind: string, agentDir: string): string;
 export declare function modelsDir(kind: string, agentDir: string): string;
 /** `<agentDir>/sessions` -- session transcript storage (large, established; not a "loose file"). */
 export declare function sessionsDir(agentDir: string): string;
+/**
+ * `<agentDir>/state/orchestration/sessions/<session-key>` -- the one durable control-plane
+ * bundle owned by a foreground session. Event state, worker mailboxes, mutation journals, and
+ * worker transcripts must stay beneath this boundary so explicit session deletion can remove
+ * exactly its companion artifacts without scanning global state.
+ */
+export declare function orchestrationSessionsDir(agentDir: string): string;
+/**
+ * `<agentDir>/state/orchestration/sessions/<session-key>` -- the one durable control-plane
+ * bundle owned by a foreground session.
+ */
+export declare function orchestrationSessionDir(agentDir: string, parentSessionId: string): string;
+/** `<orchestrationSessionDir>/events` -- append-only event tail, snapshot, cursor, and idempotency state. */
+export declare function orchestrationEventStoreDir(agentDir: string, parentSessionId: string): string;
+/**
+ * `<orchestrationSessionDir>/worker-conversations` -- durable Pi worker transcripts owned by one
+ * foreground session. Worker conversations remain in SessionManager's established JSONL format,
+ * but are intentionally outside the foreground session picker namespace.
+ */
+export declare function workerConversationSessionsDir(agentDir: string, parentSessionId: string): string;
+/**
+ * `<orchestrationSessionDir>/worker-mailboxes/<scope-digest>.json` -- durable bounded control
+ * messages for one logical worker. Identity stays hashed so neither agent ids nor project paths
+ * become path segments.
+ */
+export declare function workerAgentMailboxFile(agentDir: string, parentSessionId: string, scopeDigest: string): string;
+/**
+ * `<orchestrationSessionDir>/worker-actions/<scope-digest>.json` -- durable, bounded mutation
+ * intents and receipts for one fenced worker attempt. The opaque digest intentionally keeps task
+ * identifiers out of filesystem path segments and works on Windows and WSL.
+ */
+export declare function workerActionJournalFile(agentDir: string, parentSessionId: string, scopeDigest: string): string;
 /** `<agentDir>/npm` -- managed npm package installs. */
 export declare function npmDir(agentDir: string): string;
 /**

package/dist/core/agent-paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-paths.d.ts","sourceRoot":"","sources":["../../src/core/agent-paths.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Typed path SSOT for everything machine-managed under `<agentDir>` (`~/.pi/agent/` by default,\n * `getAgentDir()` in `../config.ts`). Every writer that persists machine data (stores, caches, managed\n * runtimes/models, cross-process coordination) MUST resolve its path through one of the accessors\n * below instead of hand-rolling `join(agentDir, …)` — that ad-hoc pattern is exactly how root-level\n * stragglers like `trust.json` accumulated, and nothing stopped the next writer from doing it again.\n *\n * Canonical layout:\n * ```\n * <agentDir>/\n *   auth.json settings.json models.json keybindings.json MEMORY.md USER.md SYSTEM.md …   user CONFIG/MEMORY (root, kept)\n *   okf-memory/                                                                            authored memory (root, kept)\n *   skills/ extensions/ prompts/ themes/ profiles/                                        user RESOURCES (root, kept)\n *     profiles/directories/<workspace-hash>/settings.json                                 directory overlays\n *   state/     durable machine state (model adaptation/fitness, tool performance,\n *              learning observations, trust decisions, config backups, …)                 -- stateDir/stateFile\n *   cache/     rebuildable, safe to delete (tool-path probes, jiti transform cache, uv)    -- cacheDir/cacheFile\n *   work/      transient/scratch, delegated to work-directory.ts (tenant/run/lease),\n *              including context/sessions/<session-id>/{gc,artifacts}                     -- re-exported below\n *   runtimes/<kind>  models/<kind>                                                         -- runtimesDir/modelsDir\n *   npm/ git/ sessions/                                                                    -- npmDir/gitDir/sessionsDir\n *   worktrees/<repo-slug>/<laneKey>   durable lane checkouts (core/worktree-sync)           -- worktreesDir\n * ```\n *\n * Every accessor takes `agentDir` as an explicit, required first argument -- deliberately mirroring\n * `work-directory.ts`'s existing `getWorkRoot(agentDir)` convention rather than defaulting to\n * `getAgentDir()` internally. Several real callers (stores' `forAgentDir`, test harnesses with a temp\n * agentDir) build paths for a NON-default agentDir; a hidden default would silently resolve the wrong\n * root for those callers instead of failing loudly. Callers operating on the process-wide default pass\n * `getAgentDir()` explicitly at the call site.\n *\n * These accessors are pure path builders -- no directory creation, no I/O. Every existing writer\n * already creates its parent directory at write time (see `util/atomic-file.ts`'s\n * `mkdirSync(dirname(filePath), { recursive: true })`), so duplicating that here would be redundant\n * and would blur the \"pure function\" contract readers rely on.\n */\nimport { join } from \"node:path\";\nimport {\n\tacquireWorkRun,\n\tassertPortablePathSegment,\n\tboundedWorkRetention,\n\tcreateWorkRunId,\n\tgetProcessWorkRun,\n\tgetWorkRoot,\n\tgetWorkRunDir,\n\tgetWorkTenantDir,\n\thasActiveWorkRunLease,\n\tpruneWorkTenant,\n} from \"../utils/work-directory.ts\";\nimport { getReloadCoordinationDir } from \"./reload-blockers.ts\";\n\n/** Root entries reserved for user-authored configuration and memory. */\nexport const AGENT_ROOT_FILE_NAMES = [\n\t\"auth.json\",\n\t\"settings.json\",\n\t\"models.json\",\n\t\"keybindings.json\",\n\t\"MEMORY.md\",\n\t\"USER.md\",\n\t\"SYSTEM.md\",\n\t\"APPEND_SYSTEM.md\",\n] as const;\n\n/** Root entries reserved for user resources and machine-managed storage classes. */\nexport const AGENT_ROOT_DIRECTORY_NAMES = [\n\t\"okf-memory\",\n\t\"skills\",\n\t\"extensions\",\n\t\"prompts\",\n\t\"themes\",\n\t\"profiles\",\n\t\"state\",\n\t\"cache\",\n\t\"bin\",\n\t\"work\",\n\t\"runtimes\",\n\t\"models\",\n\t\"sessions\",\n\t\"npm\",\n\t\"git\",\n\t\"worktrees\",\n] as const;\n\nconst AGENT_ROOT_ENTRY_NAMES = new Set<string>([...AGENT_ROOT_FILE_NAMES, ...AGENT_ROOT_DIRECTORY_NAMES]);\n\nexport function isCanonicalAgentRootEntry(name: string): boolean {\n\treturn AGENT_ROOT_ENTRY_NAMES.has(name);\n}\n\n/** `<agentDir>/<name>` -- a root-level user config/memory file (auth.json, settings.json, MEMORY.md, …). */\nexport function configFile(agentDir: string, name: string): string {\n\treturn join(agentDir, name);\n}\n\n/** `<agentDir>/okf-memory` -- user-authored durable OKF memory documents. */\nexport function okfMemoryDir(agentDir: string): string {\n\treturn join(agentDir, \"okf-memory\");\n}\n\n/** `<agentDir>/state` -- durable machine-managed state. Deleting it loses real history, not just cache. */\nexport function stateDir(agentDir: string): string {\n\treturn join(agentDir, \"state\");\n}\n\n/** `<agentDir>/state/<segments…>` */\nexport function stateFile(agentDir: string, ...segments: string[]): string {\n\treturn join(stateDir(agentDir), ...segments);\n}\n\n/** `<agentDir>/state/attachments` -- bounded, session-keyed clipboard image attachments. */\nexport function attachmentsDir(agentDir: string): string {\n\treturn stateFile(agentDir, \"attachments\");\n}\n\n/** `<agentDir>/state/secrets` -- encrypted credential vault and owner-approved materializations. */\nexport function secretsDir(agentDir: string): string {\n\treturn stateFile(agentDir, \"secrets\");\n}\n\n/** `<agentDir>/state/secrets/vault.json` -- encrypted, versioned generic credential vault. */\nexport function secretVaultFile(agentDir: string): string {\n\treturn join(secretsDir(agentDir), \"vault.json\");\n}\n\n/** `<agentDir>/state/secrets/materialized` -- private generated dotenv files, grouped by profile. */\nexport function managedSecretEnvDir(agentDir: string): string {\n\treturn join(secretsDir(agentDir), \"materialized\");\n}\n\n/** `<agentDir>/state/extensions/<namespace>` -- durable state owned by one extension. */\nexport function extensionStateDir(agentDir: string, namespace: string): string {\n\tassertPortablePathSegment(\"Extension namespace\", namespace);\n\treturn stateFile(agentDir, \"extensions\", namespace);\n}\n\n/** `<agentDir>/state/backups/config` -- explicit user-requested configuration snapshots. */\nexport function configBackupsDir(agentDir: string): string {\n\treturn stateFile(agentDir, \"backups\", \"config\");\n}\n\n/** `<agentDir>/cache` -- rebuildable; safe to delete (the next run just re-probes/recomputes). */\nexport function cacheDir(agentDir: string): string {\n\treturn join(agentDir, \"cache\");\n}\n\n/** `<agentDir>/cache/<segments…>` */\nexport function cacheFile(agentDir: string, ...segments: string[]): string {\n\treturn join(cacheDir(agentDir), ...segments);\n}\n\n/** `<agentDir>/cache/extensions/<namespace>` -- rebuildable cache owned by one extension. */\nexport function extensionCacheDir(agentDir: string, namespace: string): string {\n\tassertPortablePathSegment(\"Extension namespace\", namespace);\n\treturn cacheFile(agentDir, \"extensions\", namespace);\n}\n\n/** `<agentDir>/bin` -- managed executable helpers (fd, rg). */\nexport function binDir(agentDir: string): string {\n\treturn join(agentDir, \"bin\");\n}\n\n/** `<agentDir>/runtimes/<kind>` -- a managed runtime install (ollama, python, prism-llamacpp, needle, …). */\nexport function runtimesDir(kind: string, agentDir: string): string {\n\treturn join(agentDir, \"runtimes\", kind);\n}\n\n/** `<agentDir>/models/<kind>` -- downloaded model weights, grouped by provider/runtime. */\nexport function modelsDir(kind: string, agentDir: string): string {\n\treturn join(agentDir, \"models\", kind);\n}\n\n/** `<agentDir>/sessions` -- session transcript storage (large, established; not a \"loose file\"). */\nexport function sessionsDir(agentDir: string): string {\n\treturn join(agentDir, \"sessions\");\n}\n\n/** `<agentDir>/npm` -- managed npm package installs. */\nexport function npmDir(agentDir: string): string {\n\treturn join(agentDir, \"npm\");\n}\n\n/**\n * `<agentDir>/worktrees` -- lane worktree checkouts for the worktree-sync subsystem\n * (`core/worktree-sync/`), grouped as `worktrees/<repo-slug>/<laneKey>`. These hold REAL\n * uncommitted agent work, so they are durable like `state/` -- never under transient `work/`,\n * whose retention would silently eat in-progress code.\n */\nexport function worktreesDir(agentDir: string): string {\n\treturn join(agentDir, \"worktrees\");\n}\n\n/** `<agentDir>/git` -- managed git-sourced package installs. */\nexport function gitDir(agentDir: string): string {\n\treturn join(agentDir, \"git\");\n}\n\nexport type AgentResourceKind = \"skills\" | \"prompts\" | \"themes\" | \"extensions\" | \"profiles\";\n\n/** `<agentDir>/<kind>` -- a user-managed resource directory. Root, kept: moving it breaks users. */\nexport function resourceDir(kind: AgentResourceKind, agentDir: string): string {\n\treturn join(agentDir, kind);\n}\n\n/** `<agentDir>/profiles/directories` -- durable per-directory resource-profile overlays. */\nexport function directoryProfilesDir(agentDir: string): string {\n\treturn join(resourceDir(\"profiles\", agentDir), \"directories\");\n}\n\n/**\n * `work/` is a mature transient/scratch root with its own tenant/run/lease/retention machinery\n * (`utils/work-directory.ts`). The SSOT delegates to it wholesale instead of reimplementing -- these\n * are straight re-exports so every category (state/cache/work/runtimes/models/…) is reachable from one\n * module without duplicating `work-directory.ts`'s logic.\n */\nexport {\n\tgetWorkRoot,\n\tassertPortablePathSegment,\n\tboundedWorkRetention,\n\tgetWorkTenantDir,\n\tgetWorkRunDir,\n\tgetProcessWorkRun,\n\thasActiveWorkRunLease,\n\tacquireWorkRun,\n\tcreateWorkRunId,\n\tpruneWorkTenant,\n};\nexport type { AcquireWorkRunOptions, WorkRetentionOptions, WorkRunLease } from \"../utils/work-directory.ts\";\n\n/**\n * `work/reload-coordination` -- cross-process reload/live-op coordination state. Already correctly\n * work-scoped (defined in `reload-blockers.ts`, its natural home given the surrounding reload-gate\n * logic there); re-exported here under the taxonomy's canonical name for SSOT discoverability.\n */\nexport const reloadCoordinationDir = getReloadCoordinationDir;\n"]}
+{"version":3,"file":"agent-paths.d.ts","sourceRoot":"","sources":["../../src/core/agent-paths.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Typed path SSOT for everything machine-managed under `<agentDir>` (`~/.pi/agent/` by default,\n * `getAgentDir()` in `../config.ts`). Every writer that persists machine data (stores, caches, managed\n * runtimes/models, cross-process coordination) MUST resolve its path through one of the accessors\n * below instead of hand-rolling `join(agentDir, …)` — that ad-hoc pattern is exactly how root-level\n * stragglers like `trust.json` accumulated, and nothing stopped the next writer from doing it again.\n *\n * Canonical layout:\n * ```\n * <agentDir>/\n *   auth.json settings.json models.json keybindings.json MEMORY.md USER.md SYSTEM.md …   user CONFIG/MEMORY (root, kept)\n *   okf-memory/                                                                            authored memory (root, kept)\n *   skills/ extensions/ prompts/ themes/ profiles/                                        user RESOURCES (root, kept)\n *     profiles/directories/<workspace-hash>/settings.json                                 directory overlays\n *   state/     durable machine state (model adaptation/fitness, tool performance,\n *              learning observations, trust decisions, config backups, …)                 -- stateDir/stateFile\n *   cache/     rebuildable, safe to delete (tool-path probes, jiti transform cache, uv)    -- cacheDir/cacheFile\n *   work/      transient/scratch, delegated to work-directory.ts (tenant/run/lease),\n *              including context/sessions/<session-id>/{gc,artifacts}                     -- re-exported below\n *   runtimes/<kind>  models/<kind>                                                         -- runtimesDir/modelsDir\n *   npm/ git/ sessions/                                                                    -- npmDir/gitDir/sessionsDir\n *   state/orchestration/sessions/<session-key>/                                             -- one foreground-session-owned\n *                                                                                            control-plane bundle\n *   worktrees/<repo-slug>/<laneKey>   durable lane checkouts (core/worktree-sync)           -- worktreesDir\n * ```\n *\n * Every accessor takes `agentDir` as an explicit, required first argument -- deliberately mirroring\n * `work-directory.ts`'s existing `getWorkRoot(agentDir)` convention rather than defaulting to\n * `getAgentDir()` internally. Several real callers (stores' `forAgentDir`, test harnesses with a temp\n * agentDir) build paths for a NON-default agentDir; a hidden default would silently resolve the wrong\n * root for those callers instead of failing loudly. Callers operating on the process-wide default pass\n * `getAgentDir()` explicitly at the call site.\n *\n * These accessors are pure path builders -- no directory creation, no I/O. Every existing writer\n * already creates its parent directory at write time (see `util/atomic-file.ts`'s\n * `mkdirSync(dirname(filePath), { recursive: true })`), so duplicating that here would be redundant\n * and would blur the \"pure function\" contract readers rely on.\n */\nimport { createHash } from \"node:crypto\";\nimport { join } from \"node:path\";\nimport {\n\tacquireWorkRun,\n\tassertPortablePathSegment,\n\tboundedWorkRetention,\n\tcreateWorkRunId,\n\tgetProcessWorkRun,\n\tgetWorkRoot,\n\tgetWorkRunDir,\n\tgetWorkTenantDir,\n\thasActiveWorkRunLease,\n\tpruneWorkTenant,\n} from \"../utils/work-directory.ts\";\nimport { getReloadCoordinationDir } from \"./reload-blockers.ts\";\nimport { requireBoundedTrimmedText } from \"./util/bounded-value.ts\";\n\n/** Root entries reserved for user-authored configuration and memory. */\nexport const AGENT_ROOT_FILE_NAMES = [\n\t\"auth.json\",\n\t\"settings.json\",\n\t\"models.json\",\n\t\"keybindings.json\",\n\t\"MEMORY.md\",\n\t\"USER.md\",\n\t\"SYSTEM.md\",\n\t\"APPEND_SYSTEM.md\",\n] as const;\n\n/** Root entries reserved for user resources and machine-managed storage classes. */\nexport const AGENT_ROOT_DIRECTORY_NAMES = [\n\t\"okf-memory\",\n\t\"skills\",\n\t\"extensions\",\n\t\"prompts\",\n\t\"themes\",\n\t\"profiles\",\n\t\"state\",\n\t\"cache\",\n\t\"bin\",\n\t\"work\",\n\t\"runtimes\",\n\t\"models\",\n\t\"sessions\",\n\t\"npm\",\n\t\"git\",\n\t\"worktrees\",\n] as const;\n\nconst AGENT_ROOT_ENTRY_NAMES = new Set<string>([...AGENT_ROOT_FILE_NAMES, ...AGENT_ROOT_DIRECTORY_NAMES]);\n\nexport function isCanonicalAgentRootEntry(name: string): boolean {\n\treturn AGENT_ROOT_ENTRY_NAMES.has(name);\n}\n\n/** `<agentDir>/<name>` -- a root-level user config/memory file (auth.json, settings.json, MEMORY.md, …). */\nexport function configFile(agentDir: string, name: string): string {\n\treturn join(agentDir, name);\n}\n\n/** `<agentDir>/okf-memory` -- user-authored durable OKF memory documents. */\nexport function okfMemoryDir(agentDir: string): string {\n\treturn join(agentDir, \"okf-memory\");\n}\n\n/** `<agentDir>/state` -- durable machine-managed state. Deleting it loses real history, not just cache. */\nexport function stateDir(agentDir: string): string {\n\treturn join(agentDir, \"state\");\n}\n\n/** `<agentDir>/state/<segments…>` */\nexport function stateFile(agentDir: string, ...segments: string[]): string {\n\treturn join(stateDir(agentDir), ...segments);\n}\n\n/** `<agentDir>/state/attachments` -- bounded, session-keyed clipboard image attachments. */\nexport function attachmentsDir(agentDir: string): string {\n\treturn stateFile(agentDir, \"attachments\");\n}\n\n/** `<agentDir>/state/secrets` -- encrypted credential vault and owner-approved materializations. */\nexport function secretsDir(agentDir: string): string {\n\treturn stateFile(agentDir, \"secrets\");\n}\n\n/** `<agentDir>/state/secrets/vault.json` -- encrypted, versioned generic credential vault. */\nexport function secretVaultFile(agentDir: string): string {\n\treturn join(secretsDir(agentDir), \"vault.json\");\n}\n\n/** `<agentDir>/state/secrets/materialized` -- private generated dotenv files, grouped by profile. */\nexport function managedSecretEnvDir(agentDir: string): string {\n\treturn join(secretsDir(agentDir), \"materialized\");\n}\n\n/** `<agentDir>/state/extensions/<namespace>` -- durable state owned by one extension. */\nexport function extensionStateDir(agentDir: string, namespace: string): string {\n\tassertPortablePathSegment(\"Extension namespace\", namespace);\n\treturn stateFile(agentDir, \"extensions\", namespace);\n}\n\n/** `<agentDir>/state/backups/config` -- explicit user-requested configuration snapshots. */\nexport function configBackupsDir(agentDir: string): string {\n\treturn stateFile(agentDir, \"backups\", \"config\");\n}\n\n/** `<agentDir>/cache` -- rebuildable; safe to delete (the next run just re-probes/recomputes). */\nexport function cacheDir(agentDir: string): string {\n\treturn join(agentDir, \"cache\");\n}\n\n/** `<agentDir>/cache/<segments…>` */\nexport function cacheFile(agentDir: string, ...segments: string[]): string {\n\treturn join(cacheDir(agentDir), ...segments);\n}\n\n/** `<agentDir>/cache/extensions/<namespace>` -- rebuildable cache owned by one extension. */\nexport function extensionCacheDir(agentDir: string, namespace: string): string {\n\tassertPortablePathSegment(\"Extension namespace\", namespace);\n\treturn cacheFile(agentDir, \"extensions\", namespace);\n}\n\n/** `<agentDir>/bin` -- managed executable helpers (fd, rg). */\nexport function binDir(agentDir: string): string {\n\treturn join(agentDir, \"bin\");\n}\n\n/** `<agentDir>/runtimes/<kind>` -- a managed runtime install (ollama, python, prism-llamacpp, needle, …). */\nexport function runtimesDir(kind: string, agentDir: string): string {\n\treturn join(agentDir, \"runtimes\", kind);\n}\n\n/** `<agentDir>/models/<kind>` -- downloaded model weights, grouped by provider/runtime. */\nexport function modelsDir(kind: string, agentDir: string): string {\n\treturn join(agentDir, \"models\", kind);\n}\n\n/** `<agentDir>/sessions` -- session transcript storage (large, established; not a \"loose file\"). */\nexport function sessionsDir(agentDir: string): string {\n\treturn join(agentDir, \"sessions\");\n}\n\nfunction orchestrationSessionKey(parentSessionId: string): string {\n\tconst normalized = requireBoundedTrimmedText(parentSessionId, 512, \"Parent session id\");\n\tconst readable =\n\t\tencodeURIComponent(normalized)\n\t\t\t.replaceAll(\"%\", \"_\")\n\t\t\t// encodeURIComponent deliberately leaves `*` unescaped, but Windows forbids it in paths.\n\t\t\t// Restrict the readable prefix to a portable ASCII subset; the digest retains exact identity.\n\t\t\t.replaceAll(/[^a-zA-Z0-9._~-]/g, \"_\")\n\t\t\t.slice(0, 80) || \"session\";\n\tconst digest = createHash(\"sha256\").update(normalized).digest(\"hex\").slice(0, 16);\n\treturn `${readable}-${digest}`;\n}\n\n/**\n * `<agentDir>/state/orchestration/sessions/<session-key>` -- the one durable control-plane\n * bundle owned by a foreground session. Event state, worker mailboxes, mutation journals, and\n * worker transcripts must stay beneath this boundary so explicit session deletion can remove\n * exactly its companion artifacts without scanning global state.\n */\nexport function orchestrationSessionsDir(agentDir: string): string {\n\treturn stateFile(agentDir, \"orchestration\", \"sessions\");\n}\n\n/**\n * `<agentDir>/state/orchestration/sessions/<session-key>` -- the one durable control-plane\n * bundle owned by a foreground session.\n */\nexport function orchestrationSessionDir(agentDir: string, parentSessionId: string): string {\n\treturn join(orchestrationSessionsDir(agentDir), orchestrationSessionKey(parentSessionId));\n}\n\n/** `<orchestrationSessionDir>/events` -- append-only event tail, snapshot, cursor, and idempotency state. */\nexport function orchestrationEventStoreDir(agentDir: string, parentSessionId: string): string {\n\treturn join(orchestrationSessionDir(agentDir, parentSessionId), \"events\");\n}\n\n/**\n * `<orchestrationSessionDir>/worker-conversations` -- durable Pi worker transcripts owned by one\n * foreground session. Worker conversations remain in SessionManager's established JSONL format,\n * but are intentionally outside the foreground session picker namespace.\n */\nexport function workerConversationSessionsDir(agentDir: string, parentSessionId: string): string {\n\treturn join(orchestrationSessionDir(agentDir, parentSessionId), \"worker-conversations\");\n}\n\n/**\n * `<orchestrationSessionDir>/worker-mailboxes/<scope-digest>.json` -- durable bounded control\n * messages for one logical worker. Identity stays hashed so neither agent ids nor project paths\n * become path segments.\n */\nexport function workerAgentMailboxFile(agentDir: string, parentSessionId: string, scopeDigest: string): string {\n\tif (!/^[a-f0-9]{32,64}$/i.test(scopeDigest)) {\n\t\tthrow new TypeError(\"Worker agent mailbox scope digest must be a hexadecimal SHA-256 prefix.\");\n\t}\n\treturn join(\n\t\torchestrationSessionDir(agentDir, parentSessionId),\n\t\t\"worker-mailboxes\",\n\t\t`${scopeDigest.toLowerCase()}.json`,\n\t);\n}\n\n/**\n * `<orchestrationSessionDir>/worker-actions/<scope-digest>.json` -- durable, bounded mutation\n * intents and receipts for one fenced worker attempt. The opaque digest intentionally keeps task\n * identifiers out of filesystem path segments and works on Windows and WSL.\n */\nexport function workerActionJournalFile(agentDir: string, parentSessionId: string, scopeDigest: string): string {\n\tif (!/^[a-f0-9]{32,64}$/i.test(scopeDigest)) {\n\t\tthrow new TypeError(\"Worker action journal scope digest must be a hexadecimal SHA-256 prefix.\");\n\t}\n\treturn join(\n\t\torchestrationSessionDir(agentDir, parentSessionId),\n\t\t\"worker-actions\",\n\t\t`${scopeDigest.toLowerCase()}.json`,\n\t);\n}\n\n/** `<agentDir>/npm` -- managed npm package installs. */\nexport function npmDir(agentDir: string): string {\n\treturn join(agentDir, \"npm\");\n}\n\n/**\n * `<agentDir>/worktrees` -- lane worktree checkouts for the worktree-sync subsystem\n * (`core/worktree-sync/`), grouped as `worktrees/<repo-slug>/<laneKey>`. These hold REAL\n * uncommitted agent work, so they are durable like `state/` -- never under transient `work/`,\n * whose retention would silently eat in-progress code.\n */\nexport function worktreesDir(agentDir: string): string {\n\treturn join(agentDir, \"worktrees\");\n}\n\n/** `<agentDir>/git` -- managed git-sourced package installs. */\nexport function gitDir(agentDir: string): string {\n\treturn join(agentDir, \"git\");\n}\n\nexport type AgentResourceKind = \"skills\" | \"prompts\" | \"themes\" | \"extensions\" | \"profiles\";\n\n/** `<agentDir>/<kind>` -- a user-managed resource directory. Root, kept: moving it breaks users. */\nexport function resourceDir(kind: AgentResourceKind, agentDir: string): string {\n\treturn join(agentDir, kind);\n}\n\n/** `<agentDir>/profiles/directories` -- durable per-directory resource-profile overlays. */\nexport function directoryProfilesDir(agentDir: string): string {\n\treturn join(resourceDir(\"profiles\", agentDir), \"directories\");\n}\n\n/**\n * `work/` is a mature transient/scratch root with its own tenant/run/lease/retention machinery\n * (`utils/work-directory.ts`). The SSOT delegates to it wholesale instead of reimplementing -- these\n * are straight re-exports so every category (state/cache/work/runtimes/models/…) is reachable from one\n * module without duplicating `work-directory.ts`'s logic.\n */\nexport {\n\tgetWorkRoot,\n\tassertPortablePathSegment,\n\tboundedWorkRetention,\n\tgetWorkTenantDir,\n\tgetWorkRunDir,\n\tgetProcessWorkRun,\n\thasActiveWorkRunLease,\n\tacquireWorkRun,\n\tcreateWorkRunId,\n\tpruneWorkTenant,\n};\nexport type { AcquireWorkRunOptions, WorkRetentionOptions, WorkRunLease } from \"../utils/work-directory.ts\";\n\n/**\n * `work/reload-coordination` -- cross-process reload/live-op coordination state. Already correctly\n * work-scoped (defined in `reload-blockers.ts`, its natural home given the surrounding reload-gate\n * logic there); re-exported here under the taxonomy's canonical name for SSOT discoverability.\n */\nexport const reloadCoordinationDir = getReloadCoordinationDir;\n"]}

package/dist/core/agent-paths.js

@@ -19,6 +19,8 @@
  *              including context/sessions/<session-id>/{gc,artifacts}                     -- re-exported below
  *   runtimes/<kind>  models/<kind>                                                         -- runtimesDir/modelsDir
  *   npm/ git/ sessions/                                                                    -- npmDir/gitDir/sessionsDir
+ *   state/orchestration/sessions/<session-key>/                                             -- one foreground-session-owned
+ *                                                                                            control-plane bundle
  *   worktrees/<repo-slug>/<laneKey>   durable lane checkouts (core/worktree-sync)           -- worktreesDir
  * ```
  *
@@ -34,9 +36,11 @@
  * `mkdirSync(dirname(filePath), { recursive: true })`), so duplicating that here would be redundant
  * and would blur the "pure function" contract readers rely on.
  */
+import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { acquireWorkRun, assertPortablePathSegment, boundedWorkRetention, createWorkRunId, getProcessWorkRun, getWorkRoot, getWorkRunDir, getWorkTenantDir, hasActiveWorkRunLease, pruneWorkTenant, } from "../utils/work-directory.js";
 import { getReloadCoordinationDir } from "./reload-blockers.js";
+import { requireBoundedTrimmedText } from "./util/bounded-value.js";
 /** Root entries reserved for user-authored configuration and memory. */
 export const AGENT_ROOT_FILE_NAMES = [
     "auth.json",
@@ -141,6 +145,67 @@ export function modelsDir(kind, agentDir) {
 export function sessionsDir(agentDir) {
     return join(agentDir, "sessions");
 }
+function orchestrationSessionKey(parentSessionId) {
+    const normalized = requireBoundedTrimmedText(parentSessionId, 512, "Parent session id");
+    const readable = encodeURIComponent(normalized)
+        .replaceAll("%", "_")
+        // encodeURIComponent deliberately leaves `*` unescaped, but Windows forbids it in paths.
+        // Restrict the readable prefix to a portable ASCII subset; the digest retains exact identity.
+        .replaceAll(/[^a-zA-Z0-9._~-]/g, "_")
+        .slice(0, 80) || "session";
+    const digest = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+    return `${readable}-${digest}`;
+}
+/**
+ * `<agentDir>/state/orchestration/sessions/<session-key>` -- the one durable control-plane
+ * bundle owned by a foreground session. Event state, worker mailboxes, mutation journals, and
+ * worker transcripts must stay beneath this boundary so explicit session deletion can remove
+ * exactly its companion artifacts without scanning global state.
+ */
+export function orchestrationSessionsDir(agentDir) {
+    return stateFile(agentDir, "orchestration", "sessions");
+}
+/**
+ * `<agentDir>/state/orchestration/sessions/<session-key>` -- the one durable control-plane
+ * bundle owned by a foreground session.
+ */
+export function orchestrationSessionDir(agentDir, parentSessionId) {
+    return join(orchestrationSessionsDir(agentDir), orchestrationSessionKey(parentSessionId));
+}
+/** `<orchestrationSessionDir>/events` -- append-only event tail, snapshot, cursor, and idempotency state. */
+export function orchestrationEventStoreDir(agentDir, parentSessionId) {
+    return join(orchestrationSessionDir(agentDir, parentSessionId), "events");
+}
+/**
+ * `<orchestrationSessionDir>/worker-conversations` -- durable Pi worker transcripts owned by one
+ * foreground session. Worker conversations remain in SessionManager's established JSONL format,
+ * but are intentionally outside the foreground session picker namespace.
+ */
+export function workerConversationSessionsDir(agentDir, parentSessionId) {
+    return join(orchestrationSessionDir(agentDir, parentSessionId), "worker-conversations");
+}
+/**
+ * `<orchestrationSessionDir>/worker-mailboxes/<scope-digest>.json` -- durable bounded control
+ * messages for one logical worker. Identity stays hashed so neither agent ids nor project paths
+ * become path segments.
+ */
+export function workerAgentMailboxFile(agentDir, parentSessionId, scopeDigest) {
+    if (!/^[a-f0-9]{32,64}$/i.test(scopeDigest)) {
+        throw new TypeError("Worker agent mailbox scope digest must be a hexadecimal SHA-256 prefix.");
+    }
+    return join(orchestrationSessionDir(agentDir, parentSessionId), "worker-mailboxes", `${scopeDigest.toLowerCase()}.json`);
+}
+/**
+ * `<orchestrationSessionDir>/worker-actions/<scope-digest>.json` -- durable, bounded mutation
+ * intents and receipts for one fenced worker attempt. The opaque digest intentionally keeps task
+ * identifiers out of filesystem path segments and works on Windows and WSL.
+ */
+export function workerActionJournalFile(agentDir, parentSessionId, scopeDigest) {
+    if (!/^[a-f0-9]{32,64}$/i.test(scopeDigest)) {
+        throw new TypeError("Worker action journal scope digest must be a hexadecimal SHA-256 prefix.");
+    }
+    return join(orchestrationSessionDir(agentDir, parentSessionId), "worker-actions", `${scopeDigest.toLowerCase()}.json`);
+}
 /** `<agentDir>/npm` -- managed npm package installs. */
 export function npmDir(agentDir) {
     return join(agentDir, "npm");

package/dist/core/agent-paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-paths.js","sourceRoot":"","sources":["../../src/core/agent-paths.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Typed path SSOT for everything machine-managed under `<agentDir>` (`~/.pi/agent/` by default,\n * `getAgentDir()` in `../config.ts`). Every writer that persists machine data (stores, caches, managed\n * runtimes/models, cross-process coordination) MUST resolve its path through one of the accessors\n * below instead of hand-rolling `join(agentDir, …)` — that ad-hoc pattern is exactly how root-level\n * stragglers like `trust.json` accumulated, and nothing stopped the next writer from doing it again.\n *\n * Canonical layout:\n * ```\n * <agentDir>/\n *   auth.json settings.json models.json keybindings.json MEMORY.md USER.md SYSTEM.md …   user CONFIG/MEMORY (root, kept)\n *   okf-memory/                                                                            authored memory (root, kept)\n *   skills/ extensions/ prompts/ themes/ profiles/                                        user RESOURCES (root, kept)\n *     profiles/directories/<workspace-hash>/settings.json                                 directory overlays\n *   state/     durable machine state (model adaptation/fitness, tool performance,\n *              learning observations, trust decisions, config backups, …)                 -- stateDir/stateFile\n *   cache/     rebuildable, safe to delete (tool-path probes, jiti transform cache, uv)    -- cacheDir/cacheFile\n *   work/      transient/scratch, delegated to work-directory.ts (tenant/run/lease),\n *              including context/sessions/<session-id>/{gc,artifacts}                     -- re-exported below\n *   runtimes/<kind>  models/<kind>                                                         -- runtimesDir/modelsDir\n *   npm/ git/ sessions/                                                                    -- npmDir/gitDir/sessionsDir\n *   worktrees/<repo-slug>/<laneKey>   durable lane checkouts (core/worktree-sync)           -- worktreesDir\n * ```\n *\n * Every accessor takes `agentDir` as an explicit, required first argument -- deliberately mirroring\n * `work-directory.ts`'s existing `getWorkRoot(agentDir)` convention rather than defaulting to\n * `getAgentDir()` internally. Several real callers (stores' `forAgentDir`, test harnesses with a temp\n * agentDir) build paths for a NON-default agentDir; a hidden default would silently resolve the wrong\n * root for those callers instead of failing loudly. Callers operating on the process-wide default pass\n * `getAgentDir()` explicitly at the call site.\n *\n * These accessors are pure path builders -- no directory creation, no I/O. Every existing writer\n * already creates its parent directory at write time (see `util/atomic-file.ts`'s\n * `mkdirSync(dirname(filePath), { recursive: true })`), so duplicating that here would be redundant\n * and would blur the \"pure function\" contract readers rely on.\n */\nimport { join } from \"node:path\";\nimport {\n\tacquireWorkRun,\n\tassertPortablePathSegment,\n\tboundedWorkRetention,\n\tcreateWorkRunId,\n\tgetProcessWorkRun,\n\tgetWorkRoot,\n\tgetWorkRunDir,\n\tgetWorkTenantDir,\n\thasActiveWorkRunLease,\n\tpruneWorkTenant,\n} from \"../utils/work-directory.ts\";\nimport { getReloadCoordinationDir } from \"./reload-blockers.ts\";\n\n/** Root entries reserved for user-authored configuration and memory. */\nexport const AGENT_ROOT_FILE_NAMES = [\n\t\"auth.json\",\n\t\"settings.json\",\n\t\"models.json\",\n\t\"keybindings.json\",\n\t\"MEMORY.md\",\n\t\"USER.md\",\n\t\"SYSTEM.md\",\n\t\"APPEND_SYSTEM.md\",\n] as const;\n\n/** Root entries reserved for user resources and machine-managed storage classes. */\nexport const AGENT_ROOT_DIRECTORY_NAMES = [\n\t\"okf-memory\",\n\t\"skills\",\n\t\"extensions\",\n\t\"prompts\",\n\t\"themes\",\n\t\"profiles\",\n\t\"state\",\n\t\"cache\",\n\t\"bin\",\n\t\"work\",\n\t\"runtimes\",\n\t\"models\",\n\t\"sessions\",\n\t\"npm\",\n\t\"git\",\n\t\"worktrees\",\n] as const;\n\nconst AGENT_ROOT_ENTRY_NAMES = new Set<string>([...AGENT_ROOT_FILE_NAMES, ...AGENT_ROOT_DIRECTORY_NAMES]);\n\nexport function isCanonicalAgentRootEntry(name: string): boolean {\n\treturn AGENT_ROOT_ENTRY_NAMES.has(name);\n}\n\n/** `<agentDir>/<name>` -- a root-level user config/memory file (auth.json, settings.json, MEMORY.md, …). */\nexport function configFile(agentDir: string, name: string): string {\n\treturn join(agentDir, name);\n}\n\n/** `<agentDir>/okf-memory` -- user-authored durable OKF memory documents. */\nexport function okfMemoryDir(agentDir: string): string {\n\treturn join(agentDir, \"okf-memory\");\n}\n\n/** `<agentDir>/state` -- durable machine-managed state. Deleting it loses real history, not just cache. */\nexport function stateDir(agentDir: string): string {\n\treturn join(agentDir, \"state\");\n}\n\n/** `<agentDir>/state/<segments…>` */\nexport function stateFile(agentDir: string, ...segments: string[]): string {\n\treturn join(stateDir(agentDir), ...segments);\n}\n\n/** `<agentDir>/state/attachments` -- bounded, session-keyed clipboard image attachments. */\nexport function attachmentsDir(agentDir: string): string {\n\treturn stateFile(agentDir, \"attachments\");\n}\n\n/** `<agentDir>/state/secrets` -- encrypted credential vault and owner-approved materializations. */\nexport function secretsDir(agentDir: string): string {\n\treturn stateFile(agentDir, \"secrets\");\n}\n\n/** `<agentDir>/state/secrets/vault.json` -- encrypted, versioned generic credential vault. */\nexport function secretVaultFile(agentDir: string): string {\n\treturn join(secretsDir(agentDir), \"vault.json\");\n}\n\n/** `<agentDir>/state/secrets/materialized` -- private generated dotenv files, grouped by profile. */\nexport function managedSecretEnvDir(agentDir: string): string {\n\treturn join(secretsDir(agentDir), \"materialized\");\n}\n\n/** `<agentDir>/state/extensions/<namespace>` -- durable state owned by one extension. */\nexport function extensionStateDir(agentDir: string, namespace: string): string {\n\tassertPortablePathSegment(\"Extension namespace\", namespace);\n\treturn stateFile(agentDir, \"extensions\", namespace);\n}\n\n/** `<agentDir>/state/backups/config` -- explicit user-requested configuration snapshots. */\nexport function configBackupsDir(agentDir: string): string {\n\treturn stateFile(agentDir, \"backups\", \"config\");\n}\n\n/** `<agentDir>/cache` -- rebuildable; safe to delete (the next run just re-probes/recomputes). */\nexport function cacheDir(agentDir: string): string {\n\treturn join(agentDir, \"cache\");\n}\n\n/** `<agentDir>/cache/<segments…>` */\nexport function cacheFile(agentDir: string, ...segments: string[]): string {\n\treturn join(cacheDir(agentDir), ...segments);\n}\n\n/** `<agentDir>/cache/extensions/<namespace>` -- rebuildable cache owned by one extension. */\nexport function extensionCacheDir(agentDir: string, namespace: string): string {\n\tassertPortablePathSegment(\"Extension namespace\", namespace);\n\treturn cacheFile(agentDir, \"extensions\", namespace);\n}\n\n/** `<agentDir>/bin` -- managed executable helpers (fd, rg). */\nexport function binDir(agentDir: string): string {\n\treturn join(agentDir, \"bin\");\n}\n\n/** `<agentDir>/runtimes/<kind>` -- a managed runtime install (ollama, python, prism-llamacpp, needle, …). */\nexport function runtimesDir(kind: string, agentDir: string): string {\n\treturn join(agentDir, \"runtimes\", kind);\n}\n\n/** `<agentDir>/models/<kind>` -- downloaded model weights, grouped by provider/runtime. */\nexport function modelsDir(kind: string, agentDir: string): string {\n\treturn join(agentDir, \"models\", kind);\n}\n\n/** `<agentDir>/sessions` -- session transcript storage (large, established; not a \"loose file\"). */\nexport function sessionsDir(agentDir: string): string {\n\treturn join(agentDir, \"sessions\");\n}\n\n/** `<agentDir>/npm` -- managed npm package installs. */\nexport function npmDir(agentDir: string): string {\n\treturn join(agentDir, \"npm\");\n}\n\n/**\n * `<agentDir>/worktrees` -- lane worktree checkouts for the worktree-sync subsystem\n * (`core/worktree-sync/`), grouped as `worktrees/<repo-slug>/<laneKey>`. These hold REAL\n * uncommitted agent work, so they are durable like `state/` -- never under transient `work/`,\n * whose retention would silently eat in-progress code.\n */\nexport function worktreesDir(agentDir: string): string {\n\treturn join(agentDir, \"worktrees\");\n}\n\n/** `<agentDir>/git` -- managed git-sourced package installs. */\nexport function gitDir(agentDir: string): string {\n\treturn join(agentDir, \"git\");\n}\n\nexport type AgentResourceKind = \"skills\" | \"prompts\" | \"themes\" | \"extensions\" | \"profiles\";\n\n/** `<agentDir>/<kind>` -- a user-managed resource directory. Root, kept: moving it breaks users. */\nexport function resourceDir(kind: AgentResourceKind, agentDir: string): string {\n\treturn join(agentDir, kind);\n}\n\n/** `<agentDir>/profiles/directories` -- durable per-directory resource-profile overlays. */\nexport function directoryProfilesDir(agentDir: string): string {\n\treturn join(resourceDir(\"profiles\", agentDir), \"directories\");\n}\n\n/**\n * `work/` is a mature transient/scratch root with its own tenant/run/lease/retention machinery\n * (`utils/work-directory.ts`). The SSOT delegates to it wholesale instead of reimplementing -- these\n * are straight re-exports so every category (state/cache/work/runtimes/models/…) is reachable from one\n * module without duplicating `work-directory.ts`'s logic.\n */\nexport {\n\tgetWorkRoot,\n\tassertPortablePathSegment,\n\tboundedWorkRetention,\n\tgetWorkTenantDir,\n\tgetWorkRunDir,\n\tgetProcessWorkRun,\n\thasActiveWorkRunLease,\n\tacquireWorkRun,\n\tcreateWorkRunId,\n\tpruneWorkTenant,\n};\nexport type { AcquireWorkRunOptions, WorkRetentionOptions, WorkRunLease } from \"../utils/work-directory.ts\";\n\n/**\n * `work/reload-coordination` -- cross-process reload/live-op coordination state. Already correctly\n * work-scoped (defined in `reload-blockers.ts`, its natural home given the surrounding reload-gate\n * logic there); re-exported here under the taxonomy's canonical name for SSOT discoverability.\n */\nexport const reloadCoordinationDir = getReloadCoordinationDir;\n"]}
+{"version":3,"file":"agent-paths.js","sourceRoot":"","sources":["../../src/core/agent-paths.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Typed path SSOT for everything machine-managed under `<agentDir>` (`~/.pi/agent/` by default,\n * `getAgentDir()` in `../config.ts`). Every writer that persists machine data (stores, caches, managed\n * runtimes/models, cross-process coordination) MUST resolve its path through one of the accessors\n * below instead of hand-rolling `join(agentDir, …)` — that ad-hoc pattern is exactly how root-level\n * stragglers like `trust.json` accumulated, and nothing stopped the next writer from doing it again.\n *\n * Canonical layout:\n * ```\n * <agentDir>/\n *   auth.json settings.json models.json keybindings.json MEMORY.md USER.md SYSTEM.md …   user CONFIG/MEMORY (root, kept)\n *   okf-memory/                                                                            authored memory (root, kept)\n *   skills/ extensions/ prompts/ themes/ profiles/                                        user RESOURCES (root, kept)\n *     profiles/directories/<workspace-hash>/settings.json                                 directory overlays\n *   state/     durable machine state (model adaptation/fitness, tool performance,\n *              learning observations, trust decisions, config backups, …)                 -- stateDir/stateFile\n *   cache/     rebuildable, safe to delete (tool-path probes, jiti transform cache, uv)    -- cacheDir/cacheFile\n *   work/      transient/scratch, delegated to work-directory.ts (tenant/run/lease),\n *              including context/sessions/<session-id>/{gc,artifacts}                     -- re-exported below\n *   runtimes/<kind>  models/<kind>                                                         -- runtimesDir/modelsDir\n *   npm/ git/ sessions/                                                                    -- npmDir/gitDir/sessionsDir\n *   state/orchestration/sessions/<session-key>/                                             -- one foreground-session-owned\n *                                                                                            control-plane bundle\n *   worktrees/<repo-slug>/<laneKey>   durable lane checkouts (core/worktree-sync)           -- worktreesDir\n * ```\n *\n * Every accessor takes `agentDir` as an explicit, required first argument -- deliberately mirroring\n * `work-directory.ts`'s existing `getWorkRoot(agentDir)` convention rather than defaulting to\n * `getAgentDir()` internally. Several real callers (stores' `forAgentDir`, test harnesses with a temp\n * agentDir) build paths for a NON-default agentDir; a hidden default would silently resolve the wrong\n * root for those callers instead of failing loudly. Callers operating on the process-wide default pass\n * `getAgentDir()` explicitly at the call site.\n *\n * These accessors are pure path builders -- no directory creation, no I/O. Every existing writer\n * already creates its parent directory at write time (see `util/atomic-file.ts`'s\n * `mkdirSync(dirname(filePath), { recursive: true })`), so duplicating that here would be redundant\n * and would blur the \"pure function\" contract readers rely on.\n */\nimport { createHash } from \"node:crypto\";\nimport { join } from \"node:path\";\nimport {\n\tacquireWorkRun,\n\tassertPortablePathSegment,\n\tboundedWorkRetention,\n\tcreateWorkRunId,\n\tgetProcessWorkRun,\n\tgetWorkRoot,\n\tgetWorkRunDir,\n\tgetWorkTenantDir,\n\thasActiveWorkRunLease,\n\tpruneWorkTenant,\n} from \"../utils/work-directory.ts\";\nimport { getReloadCoordinationDir } from \"./reload-blockers.ts\";\nimport { requireBoundedTrimmedText } from \"./util/bounded-value.ts\";\n\n/** Root entries reserved for user-authored configuration and memory. */\nexport const AGENT_ROOT_FILE_NAMES = [\n\t\"auth.json\",\n\t\"settings.json\",\n\t\"models.json\",\n\t\"keybindings.json\",\n\t\"MEMORY.md\",\n\t\"USER.md\",\n\t\"SYSTEM.md\",\n\t\"APPEND_SYSTEM.md\",\n] as const;\n\n/** Root entries reserved for user resources and machine-managed storage classes. */\nexport const AGENT_ROOT_DIRECTORY_NAMES = [\n\t\"okf-memory\",\n\t\"skills\",\n\t\"extensions\",\n\t\"prompts\",\n\t\"themes\",\n\t\"profiles\",\n\t\"state\",\n\t\"cache\",\n\t\"bin\",\n\t\"work\",\n\t\"runtimes\",\n\t\"models\",\n\t\"sessions\",\n\t\"npm\",\n\t\"git\",\n\t\"worktrees\",\n] as const;\n\nconst AGENT_ROOT_ENTRY_NAMES = new Set<string>([...AGENT_ROOT_FILE_NAMES, ...AGENT_ROOT_DIRECTORY_NAMES]);\n\nexport function isCanonicalAgentRootEntry(name: string): boolean {\n\treturn AGENT_ROOT_ENTRY_NAMES.has(name);\n}\n\n/** `<agentDir>/<name>` -- a root-level user config/memory file (auth.json, settings.json, MEMORY.md, …). */\nexport function configFile(agentDir: string, name: string): string {\n\treturn join(agentDir, name);\n}\n\n/** `<agentDir>/okf-memory` -- user-authored durable OKF memory documents. */\nexport function okfMemoryDir(agentDir: string): string {\n\treturn join(agentDir, \"okf-memory\");\n}\n\n/** `<agentDir>/state` -- durable machine-managed state. Deleting it loses real history, not just cache. */\nexport function stateDir(agentDir: string): string {\n\treturn join(agentDir, \"state\");\n}\n\n/** `<agentDir>/state/<segments…>` */\nexport function stateFile(agentDir: string, ...segments: string[]): string {\n\treturn join(stateDir(agentDir), ...segments);\n}\n\n/** `<agentDir>/state/attachments` -- bounded, session-keyed clipboard image attachments. */\nexport function attachmentsDir(agentDir: string): string {\n\treturn stateFile(agentDir, \"attachments\");\n}\n\n/** `<agentDir>/state/secrets` -- encrypted credential vault and owner-approved materializations. */\nexport function secretsDir(agentDir: string): string {\n\treturn stateFile(agentDir, \"secrets\");\n}\n\n/** `<agentDir>/state/secrets/vault.json` -- encrypted, versioned generic credential vault. */\nexport function secretVaultFile(agentDir: string): string {\n\treturn join(secretsDir(agentDir), \"vault.json\");\n}\n\n/** `<agentDir>/state/secrets/materialized` -- private generated dotenv files, grouped by profile. */\nexport function managedSecretEnvDir(agentDir: string): string {\n\treturn join(secretsDir(agentDir), \"materialized\");\n}\n\n/** `<agentDir>/state/extensions/<namespace>` -- durable state owned by one extension. */\nexport function extensionStateDir(agentDir: string, namespace: string): string {\n\tassertPortablePathSegment(\"Extension namespace\", namespace);\n\treturn stateFile(agentDir, \"extensions\", namespace);\n}\n\n/** `<agentDir>/state/backups/config` -- explicit user-requested configuration snapshots. */\nexport function configBackupsDir(agentDir: string): string {\n\treturn stateFile(agentDir, \"backups\", \"config\");\n}\n\n/** `<agentDir>/cache` -- rebuildable; safe to delete (the next run just re-probes/recomputes). */\nexport function cacheDir(agentDir: string): string {\n\treturn join(agentDir, \"cache\");\n}\n\n/** `<agentDir>/cache/<segments…>` */\nexport function cacheFile(agentDir: string, ...segments: string[]): string {\n\treturn join(cacheDir(agentDir), ...segments);\n}\n\n/** `<agentDir>/cache/extensions/<namespace>` -- rebuildable cache owned by one extension. */\nexport function extensionCacheDir(agentDir: string, namespace: string): string {\n\tassertPortablePathSegment(\"Extension namespace\", namespace);\n\treturn cacheFile(agentDir, \"extensions\", namespace);\n}\n\n/** `<agentDir>/bin` -- managed executable helpers (fd, rg). */\nexport function binDir(agentDir: string): string {\n\treturn join(agentDir, \"bin\");\n}\n\n/** `<agentDir>/runtimes/<kind>` -- a managed runtime install (ollama, python, prism-llamacpp, needle, …). */\nexport function runtimesDir(kind: string, agentDir: string): string {\n\treturn join(agentDir, \"runtimes\", kind);\n}\n\n/** `<agentDir>/models/<kind>` -- downloaded model weights, grouped by provider/runtime. */\nexport function modelsDir(kind: string, agentDir: string): string {\n\treturn join(agentDir, \"models\", kind);\n}\n\n/** `<agentDir>/sessions` -- session transcript storage (large, established; not a \"loose file\"). */\nexport function sessionsDir(agentDir: string): string {\n\treturn join(agentDir, \"sessions\");\n}\n\nfunction orchestrationSessionKey(parentSessionId: string): string {\n\tconst normalized = requireBoundedTrimmedText(parentSessionId, 512, \"Parent session id\");\n\tconst readable =\n\t\tencodeURIComponent(normalized)\n\t\t\t.replaceAll(\"%\", \"_\")\n\t\t\t// encodeURIComponent deliberately leaves `*` unescaped, but Windows forbids it in paths.\n\t\t\t// Restrict the readable prefix to a portable ASCII subset; the digest retains exact identity.\n\t\t\t.replaceAll(/[^a-zA-Z0-9._~-]/g, \"_\")\n\t\t\t.slice(0, 80) || \"session\";\n\tconst digest = createHash(\"sha256\").update(normalized).digest(\"hex\").slice(0, 16);\n\treturn `${readable}-${digest}`;\n}\n\n/**\n * `<agentDir>/state/orchestration/sessions/<session-key>` -- the one durable control-plane\n * bundle owned by a foreground session. Event state, worker mailboxes, mutation journals, and\n * worker transcripts must stay beneath this boundary so explicit session deletion can remove\n * exactly its companion artifacts without scanning global state.\n */\nexport function orchestrationSessionsDir(agentDir: string): string {\n\treturn stateFile(agentDir, \"orchestration\", \"sessions\");\n}\n\n/**\n * `<agentDir>/state/orchestration/sessions/<session-key>` -- the one durable control-plane\n * bundle owned by a foreground session.\n */\nexport function orchestrationSessionDir(agentDir: string, parentSessionId: string): string {\n\treturn join(orchestrationSessionsDir(agentDir), orchestrationSessionKey(parentSessionId));\n}\n\n/** `<orchestrationSessionDir>/events` -- append-only event tail, snapshot, cursor, and idempotency state. */\nexport function orchestrationEventStoreDir(agentDir: string, parentSessionId: string): string {\n\treturn join(orchestrationSessionDir(agentDir, parentSessionId), \"events\");\n}\n\n/**\n * `<orchestrationSessionDir>/worker-conversations` -- durable Pi worker transcripts owned by one\n * foreground session. Worker conversations remain in SessionManager's established JSONL format,\n * but are intentionally outside the foreground session picker namespace.\n */\nexport function workerConversationSessionsDir(agentDir: string, parentSessionId: string): string {\n\treturn join(orchestrationSessionDir(agentDir, parentSessionId), \"worker-conversations\");\n}\n\n/**\n * `<orchestrationSessionDir>/worker-mailboxes/<scope-digest>.json` -- durable bounded control\n * messages for one logical worker. Identity stays hashed so neither agent ids nor project paths\n * become path segments.\n */\nexport function workerAgentMailboxFile(agentDir: string, parentSessionId: string, scopeDigest: string): string {\n\tif (!/^[a-f0-9]{32,64}$/i.test(scopeDigest)) {\n\t\tthrow new TypeError(\"Worker agent mailbox scope digest must be a hexadecimal SHA-256 prefix.\");\n\t}\n\treturn join(\n\t\torchestrationSessionDir(agentDir, parentSessionId),\n\t\t\"worker-mailboxes\",\n\t\t`${scopeDigest.toLowerCase()}.json`,\n\t);\n}\n\n/**\n * `<orchestrationSessionDir>/worker-actions/<scope-digest>.json` -- durable, bounded mutation\n * intents and receipts for one fenced worker attempt. The opaque digest intentionally keeps task\n * identifiers out of filesystem path segments and works on Windows and WSL.\n */\nexport function workerActionJournalFile(agentDir: string, parentSessionId: string, scopeDigest: string): string {\n\tif (!/^[a-f0-9]{32,64}$/i.test(scopeDigest)) {\n\t\tthrow new TypeError(\"Worker action journal scope digest must be a hexadecimal SHA-256 prefix.\");\n\t}\n\treturn join(\n\t\torchestrationSessionDir(agentDir, parentSessionId),\n\t\t\"worker-actions\",\n\t\t`${scopeDigest.toLowerCase()}.json`,\n\t);\n}\n\n/** `<agentDir>/npm` -- managed npm package installs. */\nexport function npmDir(agentDir: string): string {\n\treturn join(agentDir, \"npm\");\n}\n\n/**\n * `<agentDir>/worktrees` -- lane worktree checkouts for the worktree-sync subsystem\n * (`core/worktree-sync/`), grouped as `worktrees/<repo-slug>/<laneKey>`. These hold REAL\n * uncommitted agent work, so they are durable like `state/` -- never under transient `work/`,\n * whose retention would silently eat in-progress code.\n */\nexport function worktreesDir(agentDir: string): string {\n\treturn join(agentDir, \"worktrees\");\n}\n\n/** `<agentDir>/git` -- managed git-sourced package installs. */\nexport function gitDir(agentDir: string): string {\n\treturn join(agentDir, \"git\");\n}\n\nexport type AgentResourceKind = \"skills\" | \"prompts\" | \"themes\" | \"extensions\" | \"profiles\";\n\n/** `<agentDir>/<kind>` -- a user-managed resource directory. Root, kept: moving it breaks users. */\nexport function resourceDir(kind: AgentResourceKind, agentDir: string): string {\n\treturn join(agentDir, kind);\n}\n\n/** `<agentDir>/profiles/directories` -- durable per-directory resource-profile overlays. */\nexport function directoryProfilesDir(agentDir: string): string {\n\treturn join(resourceDir(\"profiles\", agentDir), \"directories\");\n}\n\n/**\n * `work/` is a mature transient/scratch root with its own tenant/run/lease/retention machinery\n * (`utils/work-directory.ts`). The SSOT delegates to it wholesale instead of reimplementing -- these\n * are straight re-exports so every category (state/cache/work/runtimes/models/…) is reachable from one\n * module without duplicating `work-directory.ts`'s logic.\n */\nexport {\n\tgetWorkRoot,\n\tassertPortablePathSegment,\n\tboundedWorkRetention,\n\tgetWorkTenantDir,\n\tgetWorkRunDir,\n\tgetProcessWorkRun,\n\thasActiveWorkRunLease,\n\tacquireWorkRun,\n\tcreateWorkRunId,\n\tpruneWorkTenant,\n};\nexport type { AcquireWorkRunOptions, WorkRetentionOptions, WorkRunLease } from \"../utils/work-directory.ts\";\n\n/**\n * `work/reload-coordination` -- cross-process reload/live-op coordination state. Already correctly\n * work-scoped (defined in `reload-blockers.ts`, its natural home given the surrounding reload-gate\n * logic there); re-exported here under the taxonomy's canonical name for SSOT discoverability.\n */\nexport const reloadCoordinationDir = getReloadCoordinationDir;\n"]}

package/dist/core/agent-session-contracts.d.ts

@@ -225,8 +225,10 @@ export interface SpawnedUsageTotals {
 }
 export interface IsolatedCompletionOptions {
     systemPrompt: string;
-    /** Isolated conversation; foreground session history is never inherited. */
+    /** New child-owned prompt messages for this call; foreground session history is never inherited. */
     messages: Message[];
+    /** Previously persisted child history. Omission preserves fresh one-shot behavior. */
+    history?: Message[];
     model?: Model<Api>;
     thinkingLevel?: ThinkingLevel;
     maxTokens?: number;
@@ -240,6 +242,20 @@ export interface IsolatedCompletionOptions {
     beforeToolCall?: AgentLoopConfig["beforeToolCall"];
     /** Child-only result observer. */
     afterToolCall?: AgentLoopConfig["afterToolCall"];
+    /**
+     * Durable child transcript sink. Message-end ordering means an assistant tool request is recorded
+     * before execution starts and each tool result is recorded before the next provider request.
+     * Throwing aborts the child loop; continuing without durable history would make replay unsafe.
+     */
+    onMessage?: (message: Message) => Promise<void> | void;
+    /** Durable mid-run steering inbox owned by the child conversation. */
+    getSteeringMessages?: AgentLoopConfig["getSteeringMessages"];
+    /** Durable post-turn follow-up inbox owned by the child conversation. */
+    getFollowUpMessages?: AgentLoopConfig["getFollowUpMessages"];
+    /** Child-owned provider projection, invoked before every request without mutating raw history. */
+    transformContext?: AgentLoopConfig["transformContext"];
+    /** Request-local budget/authority check, invoked immediately before every child provider transport. */
+    requestPreflight?: AgentLoopConfig["requestPreflight"];
     signal?: AbortSignal;
     /** Required cache policy; isolated calls never inherit a provider default implicitly. */
     cacheRetention: CacheRetention;
@@ -252,6 +268,8 @@ export interface IsolatedCompletionResult {
     text: string;
     usage: Usage;
     stopReason: StopReason;
+    /** Complete child-owned conversation; isolated calls never expose foreground history. */
+    messages?: Message[];
 }
 export interface ResearchLaneRunOutcome {
     started: boolean;