@gajae-code/coding-agent 0.16.4 → 0.16.6

package/CHANGELOG.md

@@ -2,6 +2,60 @@
 
 ## [Unreleased]
 
+## [0.16.6] - 2026-09-07
+### Fixed
+
+- `gjc --smoke-test` no longer fails on a cold or loaded host. The isolated-shell smoke wrote its descendant marker empty while the in-shell wait loop tested for a non-empty file, so the probe command could never reach its parked `sleep` and always burned the full 5s budget, leaving the 5s readiness poll no slack; the 1s descendant-reap window was equally tight. The marker now carries content, readiness and reaping use explicit 30s/15s deadlines, and the probe gets a 60s budget it still never needs. This failed the darwin-x64 release binary check on v0.16.5, which published nothing.
+- SDK lifecycle replay no longer rejects a live endpoint as replaced because of sub-millisecond filesystem metadata drift. The ready authority re-derived the endpoint mtime from a fresh `stat` while every other field came from the indexed record, so the two floats could differ in their last digits and replay hashing reported `endpoint_stale` for the endpoint it had just validated. Replacement fencing is unchanged: the on-disk file must still match the indexed record before that authority exists.
+
+## [0.16.5] - 2026-09-07
+### Added
+
+- `gjc ultragoal succession offer|adopt|status` gives an approved Ultragoal an explicit, audited path from the repository it was planned in to the repository its implementation belongs to (#5353). Previously the repository-binding guard correctly refused to execute the plan from the second repository and the only ways forward — editing `repositoryBinding` or copying the runtime directory — both defeated that boundary and laundered verification provenance. `offer` records the source repository/session, the selected unfinished goal ids, verified source artifact digests, and the complete carryover (the source brief and each objective verbatim, plus the unresolved obligations recorded against those goals), then installs a durable outgoing ownership fence: the source run immediately refuses to schedule or checkpoint the handed-off goals, while goals outside the selection stay schedulable. The source `brief.md`, `goals.json` and `ledger.jsonl` are never written — not even appended to — so their recorded digests stay verifiable, and adoption performs no write to the source repository at all. `adopt` starts a fresh run under the target repository's own binding with new pending goals and no inherited receipts, quality gates, validation batches, steering, owner identity or activated objective; historical statuses, reviews and approvals travel as provenance only. Digests are integrity evidence, never authorization: adoption additionally requires the source fence, a bounded `--authorize`/`--authorized-by` statement, and an explicit goal selection. Because the fence deliberately leaves unselected goals schedulable, admission compares a snapshot of the offered work — the brief plus each selected goal's record and unresolved obligations — rather than whole-file digests, so ordinary source progress cannot permanently strand the handed-off work; whole-file digests remain recorded as provenance and observed drift is written into the adoption record. A selection that takes only part of a validation batch, or splits a review blocker from the goal it still blocks, is rejected rather than silently dropping that obligation, and dependency groups travel as explicit obligations with source-to-target id mapping while the source's batch metadata and receipts stay behind. Terminal-critic blockers are carried as unmet requirements even though the verdict itself is not inherited. Exclusion is a single repository-wide `O_EXCL` claim per operation rather than a directory scan, so two simultaneous sessions cannot both become owners, and adoption is pinned to the exact worktree the offer named because linked worktrees keep separate `.gjc` state. Until publication completes the target refuses to execute — a visible `goals.json` is not admission evidence, the adoption record is. Adoption fails closed on changed offered work, an altered or unfenced offer, an offer path that escapes the source worktree, a target the offer does not name, an occupied target session, and any duplicate or simultaneous adoption in the target repository. A retry reconciles only this operation's own partial bytes: a matching operation id is never authority to overwrite target work it did not write, and a published plan whose files have disappeared is refused rather than reconstructed. There is deliberately no `revoke` verb, because any read-then-delete of the fence races a concurrent adoption and could revive the source while the target is starting.
+
+### Fixed
+
+- Concurrent print-mode resumes rejected by the managed transcript append fence now exit with one retry diagnostic instead of crashing during disposal, including failures while persisting startup model overrides before print mode begins. A pre-write identity mismatch disowns the stale transcript without rewriting another process's successor; genuinely uncertain I/O closure still fails closed.
+- Disk artifact GC and `gjc gc --empty-delete-receipts` now reclaim empty artifact `.removing` directories left by interrupted session deletion, including projects with no remaining transcripts. Only the two generated quarantine-name shapes qualify; no-follow directory snapshots prove emptiness, and non-recursive removal retains non-empty, symlinked, or raced entries with explicit reasons.
+- SDK `session.spawn` now publishes the child PID/incarnation-bound lifecycle marker before waiting for host registration, so headless and managed-tmux children can become ready. Incomplete substrate proofs are rejected and released before seed handoff; registration failures include validated startup phase/reason diagnostics without task text.
+- File-lock acquisition and GC now reclaim orphaned `.lock.pending.<pid>.<uuid>` directories after their owner dies, with a bounded acquisition sweep and exact-identity deletion. Live, unknown, in-process, malformed, symlinked, and host-qualified owners remain protected; cleanup failures cannot block acquisition (related #5198).
+- File-lock acquisition timeouts now expose a typed error with the lock path, retry count, and holder description. Lease mutation and SDK shutdown classify contention without depending on operator-facing wording, and unrelated shutdown failures still propagate.
+- Broker `session.list` pagination cursors now evict the oldest entry when the 32-cursor budget is full instead of failing new paginations with `cursor capacity is exhausted` (#5370). Abandoned or partial paginations degrade gracefully (the evicted cursor reports `cursor is expired or invalid` on next use) so unrelated session ops never fail once the index exceeds one page; the obsolete capacity-exhausted path is removed.
+- `session.delete` uncertain-cleanup fences are now identity-scoped: an unbound `terminal_uncertain` ledger entry no longer blanket-fences deletes for every other session id, and a delete refusal records its own target session so the fence it leaves is scoped to that session. Existing poisoned ledgers need no migration — unbound rows are ignored in place on the next read and stop amplifying (#5364).
+- Runtime state persistence now identifies contradictory `ready_for_input`/`live` fields with their lifecycle state and expected value instead of reporting only a generic invalid/unreadable marker error. Invalid markers remain untouched; this does not migrate or repair old session state.
+- LSP auto-discovery now launches trusted executable symlinks through their discovered paths instead of canonicalizing them to their targets, preserving proxy invocation names such as `rust-analyzer` when installed through rustup. The LSP status action now labels these entries as configured rather than active, since a client has not necessarily started (#5354).
+- SDK snapshot pages now read and integrity-check one contiguous span instead of rereading chunks per row. Reverse-provider disconnects discard connection-scoped registration receipts; relay shutdown releases backpressure listeners without destroying caller-owned sinks, and fragmented request frames are assembled once per newline.
+
+- The TUI working spinner and tool intent remain visible when a run continues after automatic context compaction, a compaction-hook veto, or a successful managed model retry. Temporary status replacement no longer marks the foreground run as finished; actual completion and cancellation still clear it.
+- Coordinator delegates recover a creation-WAL crash before the initial prompt claim without recreating the session or replaying compacted requests. Recurring pin cleanup bounds each readiness pass to 32 session WALs and 32 pinned receipts, skips live caller-key locks, and revisits the namespace after clean scans so surviving coordinators discover later peer crashes as well as previously skipped pins.
+- Session import no longer stalls on large credential-free content. The import redactor's URL-credential rule accepted an unbounded scheme before the literal `://`, so a long alphabetic run re-tried every prefix and scanning cost grew quadratically with the input (50k/100k/200k characters took 0.7s/2.7s/10.6s on text containing no credential at all). Every imported string crosses this fail-closed redactor, so one large transcript message was enough to stall an import of Claude Code or Codex history. The scheme is now length-bounded, which restores linear scanning while `https://`, `postgres://`, and `git+ssh://` credentials are still redacted.
+- SDK saved-session resume now enforces a supplied transcript `sessionIdentity` for both live reattach and cold launch instead of silently replacing it with the broker's current snapshot. Lifecycle create/resume results also expose the opaque `endpointIncarnation`, and same-key replay refuses an endpoint replacement rather than refreshing success by session ID when a numeric generation is reused.
+- An ACP client that declares no MCP servers no longer loses `session/new`, `session/load`, and `session/fork` to the broker's bare readiness default. Only the MCP branch asked for a readiness budget, so an MCP-less launch kept the 10s default while a host cold start measurably crosses it whenever a second host starts alongside the first: the broker then returned `terminal_uncertain` ("Lifecycle startup could not be proven"), which Paseo recorded as a failed provider snapshot and left the GJC provider reading `error` instead of `available`, so imported terminal sessions attached to nothing and showed no transcript. Every ACP launch now requests the same budget the MCP path already used, independent of whether the client declared servers.
+- `subagent await` now accepts integer heartbeat intervals up to 60,000 ms, including 10,000 ms, instead of rejecting them at an undocumented 5,000 ms schema limit. Zero still disables heartbeat updates and the default cadence is unchanged.
+- Coordinator delegates recover a creation-WAL crash before the initial prompt claim without recreating the session or replaying compacted requests. Startup pin cleanup skips live observations without waiting on their caller-key locks, and revisits skipped pins so a surviving coordinator can clean up after a peer commits its response and crashes.
+- Interrupted standalone-binary installs now reclaim an installer lock only when its recorded process ID is no longer running. Live or malformed locks remain protected and fail closed, so a cancelled `gjc update` no longer permanently blocks the next update while concurrent installers remain serialized.
+- Disconnecting an MCP server during its initial connection now returns after cancelling the acquisition instead of waiting forever when an uncooperative transport ignores abort. The pool still owns and closes any late connection, retains cleanup failures for retry, and releases the manager's pending-cleanup fence after successful settlement (#5329).
+- SDK session routing now uses the Broker's endpoint timestamp comparison, accepting sub-millisecond representation differences while retaining device/inode and exact file-replacement checks. Valid live sessions no longer become unavailable solely because timestamp conversions round differently.
+- Paseo announcement now honors `PASEO_LISTEN` ahead of daemon pid metadata, uses `$PASEO_HOME` consistently in default path construction, and removes redundant target-selection and SDK frame-delivery indirection.
+- When every auto-compaction candidate fails, the reported error now leads with the first candidate's failure and lists each candidate that was tried with its own error. The chain starts at the session model and ends on a same-provider largest-context fallback, so surfacing only the final error named a model the user never chose (e.g. `openai-codex/gpt-5.4` on an `astra` preset session) and hid that their own model had already failed the same way.
+- Registry fingerprints now enforce the existing regular-file and 32 MiB admission limits with bounded reads. Model activation, thinking overlay lookup, transcript navigation, slash autocomplete, and observer digest updates avoid repeated allocations; status lines without a git segment no longer request git status.
+- Telegram `/session_recent` now distinguishes sessions currently connected to the notification daemon from saved history and prints a ready-to-copy resume command. Inside a session's existing topic, `/session_resume` and `/session_close` can omit the session ID, including after that topic became inactive.
+- POSIX bash tool sessions now run the embedded persistent brush shell behind a guardian, supervisor, and runtime boundary. Shell self-signals such as `kill -TRAP $$`, external self-signals, process-group signals, and runtime/supervisor death terminate only the owned boundary, reap ordinary and new-session descendants, authenticate control records, return and persist signal-derived status metadata, retire the affected session, and leave the GJC host available for subsequent commands.
+- Memory-guard samples finishing after disable/re-enable or session re-registration no longer restore stale GC latches or restart-advisory windows that suppress the next lifecycle's pressure response.
+- Added ordered, capability-scoped Function Hooks middleware to the canonical extension event runner, with monotonic grant attenuation, target-aware transforms and denials, bounded timeout/abort behavior, redacted provenance-aware audit evidence, and activation-generation fencing. Plugin-bundle Function Hook declarations are validated and hashed but fail closed before host-realm import until a genuine capability-enforcing isolate is available; legacy constrained plugin hooks remain compatible.
+- Coordinator MCP delegation now releases the session transition lock after durable admission so force/queue prompts can dispatch during bounded completion observation. New and reused delegates persist and replay the complete bounded response, including timeout and waiting snapshots, while receipt-first crash recovery preserves accepted prompt identity and successor terminal fences without redispatch. Pending delegate responses pin their source prompt/turn through age and size compaction until final response commit; resumed keys with missing live authority remain unsealed and fail closed instead of redispatching or sealing a busy error.
+- Concurrent SDK CLI cold starts now single-flight broker spawning through an atomically published, process-incarnation-bound lock. Coordination owners use a machine identity keyed from the shared agent root, so separate config profiles recover one another's dead claims without allowing another machine to reclaim a live generation. Every discovery probe is bounded by the startup deadline, and a dedicated bootstrap watchdog terminates a child that outlives its startup fence. A crashed spawner is reclaimed without letting simultaneous healers delete a successor claim; retained legacy broker-lock quarantines no longer collide with takeover; incomplete owner records fail closed; and PID reuse no longer wedges broker startup. (#5198)
+- Skill discovery now reports project `.claude/skills` / `.codex/skills` import candidates before user-home ones, so a populated operator home (hundreds of convention skills is ordinary) can no longer spend the bounded diagnostic budget before the project's own convention skill is named.
+
+### Fixed
+
+- SDK submissions that reject during post-turn cleanup no longer publish a contradictory second terminal after their correlation has already settled.
+- Paseo session imports discard unused CLI stdout instead of leaving an unread pipe.
+- SDK live-attach streams preserve producer order across text deltas, final messages, and tool events even when asynchronous extension handlers are slow, without replaying or broadcasting turn content. Content observed while the correlated `agent_start` is still being durably recorded is held and released after the start frame, so no consumer sees turn content before the turn it belongs to; held content is delivered only to the owners that held the run when it was produced, and the hold is bounded (256 events, oldest dropped with one warning) so a wedged start write can neither invert the start/content boundary nor accumulate a whole response in memory.
+- SDK prompts consumed together after queued steering is interrupted now each receive correlated starts, streamed content, and one terminal, without adopting unrelated pending submissions.
+
+- Tool hot paths avoid overlap-table allocations for equal/append-only ACP output, redundant UTF-8 tail previews, repeated diagnostics suffix scans, and duplicate background GitHub-cache refreshes. Job polling now releases watches and timers when a progress callback throws.
+
 ## [0.16.4] - 2026-09-05
 ### Added
 

package/dist/types/capability/types.d.ts

@@ -28,6 +28,8 @@ export interface LoadContext {
      * produced. This includes MCP registrations and user-installed skills.
      */
     userAgentDir?: string;
+    /** Resolver-owned classification for the selected user agent directory. */
+    profileAuthority?: "default" | "custom";
     /** Git repository root (directory containing .git), or null if not in a repo */
     repoRoot: string | null;
     /** Owning session settings for provider policy decisions. */
@@ -81,6 +83,8 @@ export interface LoadOptions {
      * process-wide one (`createAgentSession({ agentDir })`).
      */
     agentDir?: string;
+    /** Resolver-owned classification for `agentDir`; preserve it across HOME/config refreshes. */
+    profileAuthority?: "default" | "custom";
     /** Include items even if they fail validation. Default: false */
     includeInvalid?: boolean;
     /** Include items disabled via settings. Default: false */

package/dist/types/cli/customize-doctor.d.ts

@@ -89,6 +89,28 @@ export interface CustomizeDoctorItem {
     mcp?: McpSafeSummary;
     /** Present only for quarantined plugin-bundle surfaces. */
     quarantineCode?: string;
+    /** Metadata-only Function Hook policy projection; hook code is never executed. */
+    functionHooks?: CustomizeFunctionHookSummary[];
+}
+export interface CustomizeFunctionHookSummary {
+    extensionId: string;
+    order: number;
+    event: string;
+    target?: string;
+    phase?: "before" | "after";
+    scope: "user" | "project";
+    plugin: string;
+    relativePath: string;
+    status: "disabled" | "quarantined" | "blocked-isolate" | "legacy-active";
+    requestedCapabilities: string[];
+    effectiveCapabilities: string[];
+    attenuateDownstream: string[];
+    networkDestinations: string[];
+    filesystemRoots: string[];
+    capabilityHash?: string;
+    implementationHash?: string;
+    quarantineCode?: string;
+    remediation: string;
 }
 export interface CustomizeDoctorSurface {
     kind: CustomizeSurfaceKind;

package/dist/types/config/file-lock.d.ts

@@ -11,9 +11,17 @@ export interface FileLockOptions {
     /** Previous local host identities accepted only when deciding stale-owner reclamation. */
     previousOwnerHostIds?: readonly string[];
 }
-/** Release retries cover transient Windows/Dropbox handle denial without extending the lock indefinitely. */
-export declare const FILE_LOCK_RELEASE_RETRY_ATTEMPTS = 5;
-export declare const FILE_LOCK_RELEASE_RETRY_DELAY_MS = 10;
+export declare class FileLockAcquireError extends Error {
+    readonly filePath: string;
+    readonly lockPath: string;
+    readonly attempts: number;
+    readonly holder: string;
+    readonly code = "acquire_timeout";
+    constructor(filePath: string, lockPath: string, attempts: number, holder: string);
+}
+/** Release retries cover transient handle denial and a competing exact-removal quarantine cleanup. */
+export declare const FILE_LOCK_RELEASE_RETRY_ATTEMPTS = 20;
+export declare const FILE_LOCK_RELEASE_RETRY_DELAY_MS = 25;
 export declare const FileLockTestHooks: {
     afterParentMkdir?: (lockPath: string) => void | Promise<void>;
     nativePublicationBindings?: () => {
@@ -47,6 +55,8 @@ export declare function readFileLockInfoForGc(lockDir: string): Promise<FileLock
 /** Owner identity stamped into a `<file>.lock/info` record. */
 export interface FileLockOwnerToken {
     pid: number;
+    /** Kernel-derived identity for the exact process generation owning `pid`. */
+    process_incarnation?: string;
     start_time?: string;
     /** Encoding marker for the canonical UTC process-start identity. */
     start_time_format?: string;
@@ -93,6 +103,7 @@ export type GenericFileLockDirStaleVerdict = {
  * but the reclaim-after-stale scenario the issue describes is now guarded.
  */
 export declare function removeFileLockDirForGc(lockDir: string, expected: FileLockOwnerToken, preVerdictIdentity?: GenericFileLockDirIdentity): Promise<FileLockGcRemoval>;
+type OwnerLiveness = "alive" | "dead" | "unknown";
 /**
  * @internal
  * READ-ONLY verdict on an EXISTING generic `<file>.lock/` directory that another lock
@@ -122,6 +133,7 @@ type NativeFileLockBindings = {
     snapshotDirectoryTree(lockPath: string): NativeDirectoryTreeResult;
     exactRemoveDirectoryTree(lockPath: string, snapshot: NonNullable<NativeDirectoryTreeResult["snapshot"]>): NativeExactUnlinkResult;
 };
+export declare function acquireFileLock(filePath: string, options?: FileLockOptions): Promise<() => Promise<void>>;
 /**
  * Serializes all contenders, including callers in the same process. Because this
  * API exposes no ownership token, recursive acquisition is indistinguishable
@@ -129,4 +141,20 @@ type NativeFileLockBindings = {
  * that fact through its own `lockHeld` path instead of acquiring it again.
  */
 export declare function withFileLock<T>(filePath: string, fn: () => Promise<T>, options?: FileLockOptions): Promise<T>;
+/** Strictly recognize the staging names emitted by tryAcquireLock. */
+export declare function fileLockStagingOwnerPid(name: string): number | null;
+export interface FileLockStagingResult {
+    path: string;
+    pid?: number;
+    status: OwnerLiveness;
+    removed: boolean;
+    reason: string;
+}
+/** Observe identity before probing; neither a replacement nor a symlink inherits the verdict. */
+export declare function inspectFileLockStagingDir(stagingPath: string, probe?: (pid: number) => OwnerLiveness, remove?: boolean): Promise<FileLockStagingResult>;
+/** Bounded opportunistic cleanup; the acquisition caller treats failures as diagnostic only. */
+export declare function reapOrphanedLockStagingDirs(lockPath: string): Promise<{
+    removed: string[];
+    retained: FileLockStagingResult[];
+}>;
 export {};

package/dist/types/coordinator-mcp/question-state.d.ts

@@ -187,6 +187,8 @@ export interface PromptRequestV1 {
         turn_id: string;
     };
     coordinator_turn_id?: string;
+    /** Retain prompt and source turn until the delegate's outer response is durable. */
+    delegate_response_pending?: boolean;
     safe_response?: Record<string, unknown>;
     error_code?: PublicReason | "idempotency_conflict";
     created_at: string;
@@ -275,6 +277,11 @@ export interface CoordinatorSessionTransactionV1 {
     recovery: {
         prompt_watermark_at: string | null;
         last_repaired_at: string | null;
+        /** One-shot authority for the initial delegate prompt, consumed atomically with its claim. */
+        initial_delegate_request?: {
+            key_digest: string;
+            request_digest: string;
+        };
     };
 }
 export type CanonicalCreateIntentV1 = {

package/dist/types/coordinator-mcp/server.d.ts

@@ -72,6 +72,13 @@ interface CoordinatorServices {
     afterCanonicalReportCommit?: (sessionId: string) => void | Promise<void>;
     /** Test barrier invoked after a canonical report safe response is durable and before outer idempotency completion. */
     afterCanonicalReportSafeResponse?: (sessionId: string, response: Record<string, unknown>) => void | Promise<void>;
+    /** Test barriers around delegate admission and outer response durability. */
+    afterDelegateAdmission?: (sessionId: string) => void | Promise<void>;
+    afterDelegateCreationWalCommitted?: (sessionId: string) => void | Promise<void>;
+    afterDelegateCreationCompleted?: () => void | Promise<void>;
+    beforeDelegateResponseCommit?: () => void | Promise<void>;
+    afterDelegateResponseCommit?: () => void | Promise<void>;
+    readCoordinatorSessionEntries?: (directory: string) => Promise<string[]>;
 }
 type CoordinatorModelResolution = {
     ok: true;

package/dist/types/discovery/helpers.d.ts

@@ -59,11 +59,34 @@ export declare const SOURCE_PATHS: {
         readonly projectDir: ".vscode";
     };
 };
+/** Ancestors from `cwd` through `stopAt`, excluding one normalized authority boundary. */
+export declare function getAncestorDirs(cwd: string, stopAt?: string | null, excludeDir?: string): Array<{
+    dir: string;
+    depth: number;
+}>;
 export type SourceId = keyof typeof SOURCE_PATHS;
+export type ProfileAuthority = "default" | "custom";
 /**
  * Get user-level path for a source.
  */
 export declare function getUserPath(ctx: LoadContext, source: SourceId, subpath: string): string | null;
+/**
+ * Deterministic user-scope skill scan directories, highest precedence first.
+ *
+ * The canonical root is the agent directory (`getAgentDir()`, moved by
+ * `--agent-dir` / `GJC_CODING_AGENT_DIR` / `setAgentDir()`) — the target of
+ * every user-scope skill writer (`gjc migrate`, `gjc skill`). An agent-directory
+ * profile is a *separate* user scope, the same contract as MCP user config
+ * (#4768): its legacy home-relative roots are not scanned, so a profile cannot
+ * pick up the default profile's skills (and vice versa). The resolver-owned
+ * `profileAuthority` classification is authoritative when supplied, so a
+ * custom profile remains isolated even if a later HOME/config-root refresh
+ * makes its path look like the current default. In the default profile the
+ * agent directory is `<home>/<configDir>/agent` and the configured legacy roots
+ * below it are still honored, exactly as before.
+ */
+export declare function resolveUserAgentDir(home: string, userAgentDir?: string): string;
+export declare function getUserSkillScanDirs(home: string, userAgentDir?: string, profileAuthority?: ProfileAuthority): string[];
 /**
  * Get project-level path for a source (cwd only).
  */
@@ -115,6 +138,8 @@ export interface ParsedAgentFields {
 export declare function parseAgentFields(frontmatter: Record<string, unknown>): ParsedAgentFields | null;
 export interface ScanSkillsFromDirOptions {
     dir: string;
+    /** Selected authority root whose own identity must not be a symlink. */
+    authorityRoot?: string;
     providerId: string;
     level: "user" | "project";
     requireDescription?: boolean;
@@ -124,7 +149,15 @@ export declare function compareSkillOrder(aName: string, aPath: string, bName: s
 export declare const SKILL_FRONTMATTER_SCAN_BYTES: number;
 /** Maximum total bytes read while seeking the frontmatter closing delimiter. */
 export declare const SKILL_FRONTMATTER_SCAN_TOTAL_BYTES: number;
+export declare const SkillDiscoveryTestHooks: {
+    afterCandidateValidated?: (candidatePath: string) => void | Promise<void>;
+    afterAuthorityRootValidated?: (root: string) => void | Promise<void>;
+    afterAuthorityRootMissing?: (root: string) => void | Promise<void>;
+    afterContainedRootValidated?: (root: string) => void | Promise<void>;
+};
 export declare function scanSkillsFromDir(_ctx: LoadContext, options: ScanSkillsFromDirOptions): Promise<LoadResult<Skill>>;
+/** Read a regular single-link file that remains contained by its configured root. */
+export declare function readContainedFile(root: string, filePath: string): Promise<string | null>;
 /**
  * Recursively expand environment variables in an object.
  */

package/dist/types/exec/bash-executor.d.ts

@@ -1,6 +1,19 @@
-import type { MinimizerOptions } from "@gajae-code/natives";
+import type { MinimizerOptions, ShellOptions, ShellRunOptions, ShellRunResult } from "@gajae-code/natives";
 import { Settings, type ShellMinimizerSettings } from "../config/settings";
 import { type TerminalArtifactPublisher } from "../session/streaming-output";
+type BashShellRunResult = ShellRunResult & {
+    signal?: string;
+};
+type Shell = {
+    run(options: ShellRunOptions, onChunk?: (error: Error | null, chunk: string) => void): Promise<BashShellRunResult>;
+    abort(): Promise<void>;
+    close(): Promise<void>;
+    isTerminal?(): boolean;
+    ready?(): Promise<void>;
+    isRunSignalActive?(signal: AbortSignal): boolean;
+};
+type ShellFactory = (options?: ShellOptions) => Shell | Promise<Shell>;
+export declare function setShellFactoryForTests(factory: ShellFactory | undefined): void;
 export interface BashArtifactSaveSummary {
     artifactId: string;
     complete: boolean;
@@ -74,6 +87,8 @@ export interface BashExecutorOptions {
 export interface BashResult {
     output: string;
     exitCode: number | undefined;
+    /** POSIX signal that terminated the isolated shell execution boundary. */
+    signal?: string;
     cancelled: boolean;
     truncated: boolean;
     totalLines: number;
@@ -97,3 +112,4 @@ export declare function disposeAllShellSessions(): Promise<void>;
 /** Translate `ShellMinimizerSettings` into native `MinimizerOptions`, or `undefined` when disabled. */
 export declare function buildMinimizerOptions(group: ShellMinimizerSettings): MinimizerOptions | undefined;
 export declare function executeBash(command: string, options?: BashExecutorOptions): Promise<BashResult>;
+export {};

package/dist/types/exec/bash-shell-guardian.d.ts

@@ -0,0 +1,15 @@
+import type { Process as NativeProcess } from "@gajae-code/natives";
+type OwnershipRecord = {
+    pid: number;
+    incarnation: string;
+    darwinUniqueId?: string | null;
+    signature: string;
+};
+export declare function parseOwnershipRecord(line: string): OwnershipRecord | undefined;
+export declare function retainOwnedProcess<T extends Pick<NativeProcess, "pid" | "incarnation">>(owned: Map<string, T>, processRef: T, guardianPid?: number): boolean;
+export declare function extendOwnedDarwinAncestry<T extends {
+    uniqueId: bigint;
+    parentUniqueId: bigint;
+}>(knownUniqueIds: Set<bigint>, candidates: ReadonlyMap<number, T>): number[];
+export declare function runBashShellGuardian(): Promise<void>;
+export {};

package/dist/types/exec/bash-shell-runtime-entry.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/types/exec/bash-shell-signals.d.ts

@@ -0,0 +1,2 @@
+export declare function fatalCatchableSignals(): NodeJS.Signals[];
+export declare function signalExitCode(signal: NodeJS.Signals): number | undefined;

package/dist/types/exec/bash-shell-supervisor-entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/exec/bash-shell-supervisor.d.ts

@@ -0,0 +1,10 @@
+import { type BashShellWorkerResponse } from "./bash-shell-worker-protocol";
+export declare function createUtf8LineDecoder(onLine: (line: string) => void, options?: {
+    maxBufferedBytes?: number;
+    onOverflow?: () => void;
+}): {
+    push(chunk: Uint8Array): void;
+    end(): void;
+};
+export declare function parseAuthenticatedWorkerResponse(line: string, protocolToken: string | undefined): BashShellWorkerResponse | undefined;
+export declare function runBashShellSupervisor(): Promise<void>;

package/dist/types/exec/bash-shell-worker-entry.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/types/exec/bash-shell-worker-protocol.d.ts

@@ -0,0 +1,63 @@
+import type { MinimizerOptions, ShellOptions, ShellRunOptions, ShellRunResult } from "@gajae-code/natives";
+export declare const BASH_SHELL_WORKER_ARG = "--internal-bash-shell-worker";
+export declare const BASH_SHELL_SUPERVISOR_ARG = "--internal-bash-shell-supervisor";
+export declare const BASH_SHELL_RUNTIME_ARG = "--internal-bash-shell-runtime";
+export type IsolatedShellOptions = Pick<ShellOptions, "sessionEnv" | "snapshotPath"> & {
+    minimizer?: MinimizerOptions;
+    containedProcessGroup?: boolean;
+};
+export type IsolatedShellRunOptions = Omit<ShellRunOptions, "signal">;
+export type IsolatedShellRunResult = ShellRunResult & {
+    /** POSIX signal that terminated the isolated shell worker, when applicable. */
+    signal?: string;
+};
+export type BashShellWorkerRequest = {
+    type: "init";
+    token: string;
+    options?: IsolatedShellOptions;
+    ownershipLedger?: {
+        path: string;
+        token: string;
+    };
+} | {
+    type: "run";
+    token: string;
+    id: number;
+    options: IsolatedShellRunOptions;
+} | {
+    type: "abort";
+    token: string;
+    id: number;
+} | {
+    type: "close";
+    token: string;
+    id: number;
+};
+export type BashShellWorkerResponse = {
+    type: "ready";
+    token: string;
+    supervisorPid?: number;
+} | {
+    type: "chunk";
+    token: string;
+    id: number;
+    chunk: string;
+} | {
+    type: "result";
+    token: string;
+    id: number;
+    result: IsolatedShellRunResult;
+} | {
+    type: "void";
+    token: string;
+    id: number;
+} | {
+    type: "retiring";
+    token: string;
+    message: string;
+} | {
+    type: "error";
+    token: string;
+    id?: number;
+    message: string;
+};

package/dist/types/exec/bash-shell-worker.d.ts

@@ -0,0 +1 @@
+export declare function runBashShellWorker(): Promise<void>;

package/dist/types/exec/isolated-shell.d.ts

@@ -0,0 +1,19 @@
+import type { ShellRunOptions } from "@gajae-code/natives";
+import { type IsolatedShellOptions, type IsolatedShellRunResult } from "./bash-shell-worker-protocol";
+export interface IsolatedShellLifecycle {
+    onTerminal?: (shell: IsolatedShell) => void;
+    workerArgv?: string[];
+}
+export declare class IsolatedShell {
+    #private;
+    constructor(options?: IsolatedShellOptions, lifecycle?: IsolatedShellLifecycle);
+    isTerminal(): boolean;
+    ready(): Promise<void>;
+    supervisorPid(): number | undefined;
+    isRunSignalActive(signal: AbortSignal): boolean;
+    wasRunSignalDispatched(signal: AbortSignal): boolean;
+    run(options: ShellRunOptions, onChunk?: (error: Error | null, chunk: string) => void): Promise<IsolatedShellRunResult>;
+    abort(): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function smokeTestIsolatedShell(): Promise<void>;

package/dist/types/extensibility/extensions/function-hooks-internal.d.ts

@@ -0,0 +1,9 @@
+import { type FunctionHookRegistration } from "./function-hooks";
+export type TaggedFunctionHookHandler = (...args: unknown[]) => Promise<unknown>;
+export declare function tagExtensionHandlerRegistrationOrder<T extends (...args: never[]) => unknown>(handler: T, registrationOrder: number): T;
+export declare function wrapExtensionHandlerRegistration<T extends (...args: never[]) => unknown>(handler: T, registrationOrder: number): T;
+export declare function getExtensionHandlerRegistrationOrder(value: unknown): number | undefined;
+export declare function tagFunctionHookHandler(registration: FunctionHookRegistration): TaggedFunctionHookHandler;
+export declare function getFunctionHookRegistration(value: unknown): FunctionHookRegistration | undefined;
+/** Host-only root-confined read used by the mediated filesystem capability. */
+export declare function readConstrainedFunctionHookFile(filePath: string, cwd: string, roots: readonly string[]): Promise<string>;

package/dist/types/extensibility/extensions/function-hooks.d.ts

@@ -0,0 +1,169 @@
+import type { ImageContent, TextContent } from "@gajae-code/ai/core";
+import type { CustomMessage } from "../../session/messages";
+import type { ExtensionEvent, ExtensionSessionMetadata, ExtensionUIContext } from "./types";
+/** Function hooks use the existing extension event stream; `*` is observation middleware. */
+export type FunctionHookEventType = ExtensionEvent["type"] | "*";
+export type FunctionHookPayloadFor<T extends FunctionHookEventType> = T extends "*" ? ExtensionEvent : Extract<ExtensionEvent, {
+    type: T;
+}>;
+/** Narrow capability vocabulary. Parent names expand only to their children. */
+export type FunctionHookCapability = "tool" | "tool.inspect" | "tool.transform" | "tool.deny" | "ui" | "ui.status" | "ui.widget" | "ui.notify" | "ui.transform" | "session" | "session.read" | "session.message" | "session.deny" | "audit" | "audit.append" | "network" | "network.fetch" | "filesystem" | "filesystem.read";
+export declare const FUNCTION_HOOK_CAPABILITIES: readonly FunctionHookCapability[];
+export type FunctionHookOperation = Exclude<FunctionHookCapability, "tool" | "ui" | "session" | "audit" | "network" | "filesystem">;
+export interface FunctionHookGrantInput {
+    capabilities?: readonly FunctionHookCapability[];
+    networkDestinations?: readonly string[];
+    filesystemRoots?: readonly string[];
+    /** An attenuation boundary can only remove downstream operations. */
+    attenuateDownstream?: readonly FunctionHookCapability[];
+}
+export interface FunctionHookGrant {
+    readonly capabilities: readonly FunctionHookCapability[];
+    readonly networkDestinations: readonly string[];
+    readonly filesystemRoots: readonly string[];
+    readonly attenuateDownstream?: readonly FunctionHookCapability[];
+}
+export interface FunctionHookRegistrationOptions extends FunctionHookGrantInput {
+    target?: string;
+    registrationId?: string;
+}
+export interface FunctionHookProvenance {
+    readonly source: "builtin" | "user" | "project" | "extension" | "plugin-bundle";
+    readonly scope?: "user" | "project" | "native";
+    readonly plugin?: string;
+    readonly extensionId?: string;
+    readonly path: string;
+    readonly activationGeneration?: number;
+}
+export interface FunctionHookInvocation<TEvent extends ExtensionEvent = ExtensionEvent> {
+    readonly eventId: string;
+    readonly correlationId: string;
+    readonly eventType: TEvent["type"];
+    readonly provenance: FunctionHookProvenance;
+    readonly registrationOrder: number;
+    readonly payload: Readonly<TEvent>;
+    readonly signal: AbortSignal;
+}
+export interface FunctionHookMessage {
+    customType: string;
+    content: string | (TextContent | ImageContent)[];
+    display?: boolean;
+    details?: unknown;
+    attribution?: CustomMessage["attribution"];
+    triggerTurn?: boolean;
+    deliverAs?: "steer" | "followUp";
+}
+export interface FunctionHookAuditRecord {
+    readonly sequence: number;
+    readonly eventId: string;
+    readonly correlationId: string;
+    readonly eventType: string;
+    readonly action: "continue" | "deny" | "return" | "error" | "timeout";
+    readonly registrationOrder: number;
+    readonly provenance: {
+        source: FunctionHookProvenance["source"];
+        scope?: FunctionHookProvenance["scope"];
+        plugin?: string;
+        extensionId?: string;
+        path: string;
+    };
+    readonly reason?: string;
+    readonly payloadHash?: string;
+    readonly evidence?: unknown;
+    readonly requestedCapabilities?: readonly FunctionHookCapability[];
+    readonly effectiveCapabilities?: readonly FunctionHookCapability[];
+    readonly capabilityHash?: string;
+    readonly activationGeneration?: number;
+}
+export interface FunctionHookCapabilities {
+    readonly tool?: {
+        readonly canInspect: boolean;
+        readonly canTransform: boolean;
+        readonly canDeny: boolean;
+    };
+    readonly ui?: {
+        readonly canTransform: boolean;
+        readonly setStatus: (key: string, text: string | undefined) => void;
+        readonly setWidget: (key: string, content: string[] | undefined) => void;
+        readonly notify: (message: string, type?: "info" | "warning" | "error") => void;
+    };
+    readonly session?: {
+        readonly canRead: boolean;
+        readonly canDeny: boolean;
+        readonly metadata: Readonly<ExtensionSessionMetadata> | undefined;
+        readonly emitMessage: (message: FunctionHookMessage, options?: {
+            triggerTurn?: boolean;
+            deliverAs?: "steer" | "followUp";
+        }) => void;
+    };
+    readonly audit?: {
+        readonly append: (evidence: Record<string, unknown>) => void;
+    };
+    readonly network?: {
+        readonly fetch: (input: string | URL, init?: RequestInit) => Promise<Response>;
+    };
+    readonly filesystem?: {
+        readonly readFile: (filePath: string) => Promise<string>;
+    };
+}
+export type FunctionHookResult<TEvent extends ExtensionEvent = ExtensionEvent> = {
+    action: "continue";
+    event?: TEvent;
+} | {
+    action: "deny";
+    reason: string;
+} | {
+    action: "return";
+    value: unknown;
+};
+export type FunctionHookNext<TEvent extends ExtensionEvent = ExtensionEvent> = (event?: TEvent) => Promise<FunctionHookResult<TEvent>>;
+export type FunctionHook<TEvent extends ExtensionEvent = ExtensionEvent> = (invocation: FunctionHookInvocation<TEvent>, capabilities: FunctionHookCapabilities, next: FunctionHookNext<TEvent>) => FunctionHookResult<TEvent> | undefined | Promise<FunctionHookResult<TEvent> | undefined>;
+export interface FunctionHookRegistration {
+    readonly event: FunctionHookEventType;
+    readonly target?: string;
+    readonly registrationId?: string;
+    readonly handler: FunctionHook;
+    readonly grant: FunctionHookGrant;
+    readonly provenance: FunctionHookProvenance;
+    readonly registrationOrder?: number;
+}
+export declare function validateFunctionHookTarget(target: string): string;
+export declare function normalizeFunctionHookGrant(input?: FunctionHookGrantInput): FunctionHookGrant;
+export declare function compatibilityFunctionHookGrant(event: string): FunctionHookGrant;
+export declare function functionHookGrantOperations(grant: FunctionHookGrant): ReadonlySet<FunctionHookOperation>;
+export declare function intersectFunctionHookGrants(grant: FunctionHookGrant, allowed: FunctionHookGrant | undefined): FunctionHookGrant;
+/** Host-owned ceiling for caller-registered in-process extension and hook middleware. */
+export declare const DEFAULT_EXTENSION_FUNCTION_HOOK_GRANT: FunctionHookGrant;
+export declare function attenuateFunctionHookGrant(grant: FunctionHookGrant, removed: readonly FunctionHookCapability[] | undefined): FunctionHookGrant;
+export declare function functionHookGrantHash(grant: FunctionHookGrant): string;
+/** Bounded JSON-shaped redaction for diagnostics and audit sinks. Accessors are never invoked. */
+export declare function redactFunctionHookValue(value: unknown, depth?: number, seen?: WeakSet<object>): unknown;
+export declare function functionHookPayloadHash(value: unknown): string;
+export declare function isPlainFunctionHookData(value: unknown, seen?: WeakSet<object>): boolean;
+export declare function isSafeFunctionHookValue(value: unknown, seen?: WeakSet<object>): boolean;
+export declare function isValidFunctionHookEventValue(event: ExtensionEvent): boolean;
+export declare function functionHookEventIdentityMatches(original: ExtensionEvent, candidate: ExtensionEvent): boolean;
+export declare function cloneFunctionHookData<T>(value: T): T;
+/** Security-boundary clone for transformed events; never aliases caller-owned data. */
+export declare function cloneFunctionHookDataStrict<T>(value: T): T;
+export interface FunctionHookCapabilityBindings {
+    readonly cwd: string;
+    readonly ui: ExtensionUIContext;
+    readonly sessionMetadata?: ExtensionSessionMetadata;
+    readonly isActive?: () => boolean;
+    readonly emitMessage: (message: FunctionHookMessage, options?: {
+        triggerTurn?: boolean;
+        deliverAs?: "steer" | "followUp";
+    }) => void;
+    readonly appendAudit: (evidence: Record<string, unknown>) => void;
+    readonly fetch: (input: string | URL, init?: RequestInit) => Promise<Response>;
+    readonly readFile: (filePath: string, roots: readonly string[]) => Promise<string>;
+}
+export declare function createFunctionHookCapabilities(grant: FunctionHookGrant, bindings: FunctionHookCapabilityBindings): FunctionHookCapabilities;
+export declare function compatibilityPayloadForFunctionHook(event: ExtensionEvent, grant: FunctionHookGrant, wildcard: boolean): ExtensionEvent;
+export declare function functionHookInspectAllowed(event: ExtensionEvent, grant: FunctionHookGrant, wildcard: boolean): boolean;
+export declare function functionHookTransformAllowed(event: ExtensionEvent, grant: FunctionHookGrant): boolean;
+export declare function functionHookDenyAllowed(event: ExtensionEvent, grant: FunctionHookGrant): boolean;
+export declare function sanitizeFunctionHookReason(reason: unknown, fallback: string): string;
+/** Validate terminal short-circuit values before they enter event-specific host control flow. */
+export declare function isValidFunctionHookReturnValue(event: ExtensionEvent, value: unknown): boolean;