omp-conductor 0.17.1 → 0.18.1

package/src/lifecycle.ts

@@ -53,7 +53,7 @@ const READY_TIMEOUT_MS = 15_000;
 const READY_POLL_MS = 250;
 
 /** `/healthz` is a local, in-memory answer; a slow one means something is wrong. */
-const HEALTH_TIMEOUT_MS = 1_500;
+export const HEALTH_TIMEOUT_MS = 1_500;
 
 /** Default grace period between `SIGTERM` and `SIGKILL`. */
 const STOP_TIMEOUT_MS = 10_000;
@@ -340,21 +340,52 @@ export function acquireOnceLease(
   throw new Error("could not acquire the daemon lease — a stale holder kept reappearing");
 }
 
+/**
+ * Why a health probe came back negative. A timeout means the process is up
+ * but not answering (wedged or overloaded); a refusal means nothing is
+ * listening on the port at all. Everything else — a 500, a torn response —
+ * is `other`, a health answer rather than a probe verdict.
+ */
+export type HealthCheckFailure = "timeout" | "refused" | "other";
+
+export type HealthCheckResult =
+  | { ok: true; body?: string }
+  | { ok: false; failure: HealthCheckFailure; body?: string };
+
 /**
  * Probes the daemon's own health endpoint. Never throws: a refused connection,
  * a DNS-less host, a hung socket and a 500 are all just "not healthy", and the
- * callers of this are the ones responsible for saying so nicely.
+ * callers of this are the ones responsible for saying so nicely. The `failure`
+ * kind lets a caller tell "up but slow" (timeout) from "nothing listening"
+ * (refused) instead of collapsing both into `{ ok: false }` (#716).
  */
-export async function healthCheck(port: number): Promise<{ ok: boolean; body?: string }> {
+export async function healthCheck(port: number): Promise<HealthCheckResult> {
   try {
     const res = await fetch(`http://127.0.0.1:${port}/healthz`, {
       signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS),
     });
     const body = (await res.text()).trim();
-    return { ok: res.ok, ...(body.length > 0 ? { body } : {}) };
-  } catch {
-    return { ok: false };
+    if (!res.ok) {
+      return { ok: false, failure: "other", ...(body.length > 0 ? { body } : {}) };
+    }
+    return { ok: true, ...(body.length > 0 ? { body } : {}) };
+  } catch (err) {
+    return { ok: false, failure: healthFailureKind(err) };
+  }
+}
+
+/**
+ * Classify a fetch rejection: the timeout signal raises `TimeoutError`; a
+ * refused connection is `ConnectionRefused` under Bun and `ECONNREFUSED`
+ * under undici. Anything else is an unclassified probe failure.
+ */
+function healthFailureKind(err: unknown): HealthCheckFailure {
+  if (err instanceof Error && err.name === "TimeoutError") return "timeout";
+  const code = (err as { code?: unknown } | null)?.code;
+  if (code === "ConnectionRefused" || code === "ECONNREFUSED" || code === "ECONNRESET") {
+    return "refused";
   }
+  return "other";
 }
 
 /** Whether a `/healthz` body names `project` as served: the daemon's health
@@ -932,6 +963,127 @@ export function systemdMainPid(unit = SYSTEMD_UNIT): number | undefined {
   return ownership.kind === "active" ? ownership.pid : undefined;
 }
 
+/**
+ * The run-control endpoint the `worker` verbs may address.
+ *
+ * `record` is the pidfile's own answer: the record port is authoritative
+ * because the daemon itself wrote it, and the record's `project` (when set)
+ * rides along so callers keep refusing a record pinned to another project
+ * exactly as before. `unit` is the systemd answer for a missing or stale
+ * record: the unit is active, its MainPID is alive, and `/healthz` on the
+ * probe port proved a conductor daemon serving `expectedProject` — the port
+ * was located, not assumed. `unserved` is that same live unit when no port
+ * proved itself: the daemon is running but its control address cannot be
+ * located, so callers must refuse rather than guess. `unknown` is the
+ * manager-failure answer: the unit's ownership could not be read (bus,
+ * permission, timeout), so neither running nor stopped is provable and the
+ * callers must refuse — collapsing that into `none` is how a control verb
+ * lies "daemon is not running" while the unit is up. `none` is the confirmed
+ * negative: no record, and no unit with a live MainPID.
+ */
+export type DaemonControlTarget =
+  | { kind: "record"; pid: number; port: number; project?: string }
+  | { kind: "unit"; pid: number; port: number }
+  | { kind: "unserved"; pid: number; port: number }
+  | { kind: "unknown"; reason: string }
+  | { kind: "none" };
+
+/**
+ * The port a unit-run daemon is probed on when the pidfile is absent: the
+ * generated unit always pins `--port` 8787 (`DEFAULT_PORT`), so that is the
+ * default candidate. The port is verified by `/healthz` before it is used —
+ * a listener is never trusted for being on the default port alone (#811).
+ *
+ * A test process redirects the probe with `OMP_CONDUCTOR_TEST_DAEMON_PORT`,
+ * the same seam discipline as `OMP_CONDUCTOR_TEST_SYSTEMCTL_STATE`: a CLI
+ * test cannot bind the real 8787 (the host's actual daemon may answer, the
+ * #399 failure mode), so its fake unit daemon serves on an ephemeral port
+ * that the state names.
+ */
+function controlProbePort(): number {
+  if (process.env["NODE_ENV"] === "test") {
+    const override = process.env["OMP_CONDUCTOR_TEST_DAEMON_PORT"];
+    if (override !== undefined && override.trim() !== "") {
+      const port = Number.parseInt(override.trim(), 10);
+      if (Number.isInteger(port) && port > 0 && port <= 65535) return port;
+    }
+  }
+  return DEFAULT_PORT;
+}
+
+/**
+ * Resolve the running daemon's pid + port for the run-control verbs, or prove
+ * the daemon is not running. The pidfile is authoritative while the process
+ * it names is alive; when it is missing or stale, the systemd unit is the
+ * liveness witness — the same consultation `status` performs (#716): an
+ * active unit whose MainPID is alive proves the daemon runs even though no
+ * record pins its port. The port is never assumed: `/healthz` on the probe
+ * port must prove a conductor daemon answering for `expectedProject` before
+ * that address is offered as something to operate (#811).
+ *
+ * Never throws — the caller decides whether `unserved` (a live unit with no
+ * proved endpoint) or `none` (nothing running) is the answer to give.
+ */
+export async function daemonControlTarget(
+  expectedProject?: string,
+): Promise<DaemonControlTarget> {
+  const record = livingDaemon();
+  if (record !== undefined) {
+    return {
+      kind: "record",
+      pid: record.pid,
+      port: record.port,
+      ...(record.project === undefined ? {} : { project: record.project }),
+    };
+  }
+  const ownership = probeUnit();
+  // A manager query the manager could not answer is not "no unit": collapsing
+  // it into `none` is exactly how a control verb reports a live unit-owned
+  // daemon stopped. The caller must refuse on the honest indeterminacy.
+  if (ownership.kind === "unknown") return { kind: "unknown", reason: ownership.reason };
+  if (ownership.kind !== "active" || !isAlive(ownership.pid)) return { kind: "none" };
+  const port = controlProbePort();
+  const health = await healthCheck(port);
+  if (!health.ok || !healthServesProject(health.body, expectedProject)) {
+    return { kind: "unserved", pid: ownership.pid, port };
+  }
+  return { kind: "unit", pid: ownership.pid, port };
+}
+
+/**
+ * The reachable { pid, port } a run-control verb may operate, or the refusal
+ * that names why it cannot. The refusal language is one shared place so
+ * `worker` and `extend` cannot drift apart on the same endpoint questions:
+ * `none` is the plain "not running"; a record pinned to another project is
+ * the same refusal the verbs always gave; an unprovable live unit and an
+ * unknown manager state both fail closed instead of contacting anything or
+ * claiming the daemon stopped.
+ */
+export async function requireDaemonControl(
+  expectedProject: string,
+): Promise<{ pid: number; port: number }> {
+  const target = await daemonControlTarget(expectedProject);
+  if (target.kind === "none") throw new Error("daemon is not running");
+  if (target.kind === "unknown") {
+    throw new Error(
+      `cannot determine whether ${SYSTEMD_UNIT} is running (${target.reason}) — ` +
+        `refusing to send run control while liveness is unknown; ` +
+        `retry when systemctl answers, or check \`systemctl status ${SYSTEMD_UNIT}\``,
+    );
+  }
+  if (target.kind === "record" && target.project !== undefined && target.project !== expectedProject) {
+    throw new Error(
+      `daemon serves project "${target.project}", not requested project "${expectedProject}"`,
+    );
+  }
+  if (target.kind === "unserved") {
+    throw new Error(
+      `daemon is running (${SYSTEMD_UNIT} pid ${target.pid}) but not serving /healthz for project "${expectedProject}" on port ${target.port} — no run-control endpoint could be located, so nothing was changed`,
+    );
+  }
+  return { pid: target.pid, port: target.port };
+}
+
 // ---------------------------------------------------------------------------
 // internals
 // ---------------------------------------------------------------------------

package/src/omp.ts

@@ -8,17 +8,23 @@
  * `createAgentSession`, `subscribe` or `abort`, exactly one file breaks.
  */
 
-/**
- * Harness package name. Held in a variable and cast to `string` at the call
- * site on purpose: a non-literal specifier stops `tsc` from trying to resolve
- * the module, which is the whole reason this shim exists.
- */
-import { chmodSync, chownSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { chmodSync, chownSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { createServer, type Server, type Socket } from "node:net";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
+import {
+  OMP_HARNESS_PACKAGE,
+  packageNodeModulesRoot,
+  workerHarnessPath,
+  workerLaunchArgv,
+  workerSessionEnv,
+  type WorkerIdentity,
+} from "./host.ts";
+import { harnessVersion, resolveHarnessEntry } from "./harness-loader.ts";
 import { readOnlySession, worktreeConfinement } from "./confinement.ts";
+import { observeGraphTools } from "./graph.ts";
 import { releasePolicyTripwire, type GateShape, type ReleaseBlockContext } from "./release-policy.ts";
 import type {
   HostToParent,
@@ -26,11 +32,53 @@ import type {
   SessionHostSpec,
 } from "./session-host.ts";
 import { decodeFrames, encodeFrame } from "./session-host.ts";
-import type { ResolvedGrants, SessionRole } from "./types.ts";
+import type { GraphToolsObservation, ResolvedGrants, SessionRole } from "./types.ts";
 import { SESSION_ROLE_ENV } from "./types.ts";
 import { conductorVerbs } from "./verbs/client.ts";
 
-const OMP_PACKAGE = "@oh-my-pi/pi-coding-agent";
+/**
+ * Harness package name. Held in a variable and cast to `string` at the call
+ * site on purpose: a non-literal specifier stops `tsc` from trying to resolve
+ * the module, which is the whole reason this shim exists.
+ */
+const OMP_PACKAGE = OMP_HARNESS_PACKAGE;
+
+/**
+ * Why the explicitly anchored harness entry is not the one installed beside
+ * omp-conductor, or `undefined` when it is — or when there is nothing to
+ * compare, because this package is running from a source checkout with no
+ * install root of its own.
+ *
+ * The failure it names is silent otherwise (#828): Bun's ambient bare-package
+ * resolution can choose its install cache even when the worker binding is
+ * mounted and inode-current. The production resolver is therefore
+ * {@link resolveHarnessEntry}, rooted at this module's directory; this check
+ * remains the fail-closed attestation that the resolved absolute path stayed
+ * inside the same install.
+ */
+export function harnessOutsideInstall(
+  moduleDir: string = import.meta.dir,
+  resolveSpecifier: (specifier: string) => string = () => resolveHarnessEntry(moduleDir),
+): string | undefined {
+  const root = packageNodeModulesRoot(moduleDir);
+  if (root === undefined) return undefined;
+  let resolved: string;
+  try {
+    const result = resolveSpecifier(OMP_PACKAGE);
+    resolved = result.startsWith("file:") ? fileURLToPath(result) : result;
+  } catch {
+    // Nothing resolved at all. The import below reports that far better than a
+    // guess here could, and reporting it twice in two spellings is worse.
+    return undefined;
+  }
+  if (resolved.startsWith(`${root}/`)) return undefined;
+  return (
+    `omp-conductor could not load its peer dependency ${OMP_PACKAGE} from its own installation: it resolves to ` +
+    `${resolved}, outside ${root}. Refusing Bun's ambient auto-install cache prevents a different harness build ` +
+    "and native addon from standing in for the operator's install. Run `omp-conductor setup host` to verify the " +
+    "worker binding, or install the harness alongside omp-conductor."
+  );
+}
 
 /**
  * The only session surface the dispatcher is allowed to know about: send one
@@ -73,6 +121,39 @@ export interface AgentSessionLike {
    * downgrade, instead of it vanishing and a run just reading dumber.
    */
   modelFallbackMessage?: string;
+  /**
+   * The code-graph session observation (#726): whether the graph MCP tools
+   * were in this session's registry, as a one-shot async fact. The harness
+   * tool registry settles late in a session's life (MCP wiring finalises
+   * after creation), so the in-process session under {@link createLocalSession}
+   * exposes this promise; the session-host child relays the resolved value
+   * over the wire, and the proxy session {@link createSession} exposes the
+   * settled observation as {@link graphTools}. Resolving `undefined` means no
+   * observation could be recorded (surface absent or never readable) — never
+   * "graph tools absent", which is the `present: false` truth value.
+   */
+  graphToolsReady?: Promise<GraphToolsObservation | undefined>;
+  /**
+   * The code-graph session observation (#726): whether the graph MCP tools
+   * were in this session's registry. Set on the proxy session once the child's
+   * relayed observation lands. Absent means no observation was recorded — never
+   * "graph tools absent", which is the `present: false` truth value.
+   */
+  graphTools?: GraphToolsObservation;
+  /**
+   * The version of the omp-conductor module this session process actually
+   * LOADED, attested by the live process at session start (#832): the module
+   * tree this session's tools execute out of, read from the package this
+   * process resolved — never from the package files on disk after the fact.
+   * Absent only when the version cannot be read (a hand-built fake, a
+   * packaging oddity) — absence is not "the newest", and an upgrade that
+   * cannot see the loaded version must not claim the session reloaded.
+   */
+  extensionVersion?: string;
+  /** Absolute entry path of the harness module this session process loaded. */
+  harnessPath?: string;
+  /** Version read from the package owning {@link harnessPath}. */
+  harnessVersion?: string;
 }
 
 /**
@@ -197,16 +278,47 @@ export async function createLocalSession(opts: {
    * session has no route to a mutation to scope in the first place.
    */
   readOnly?: boolean;
+  /**
+   * The structured-settlement contract (#540): a JSON Schema the session's
+   * `yield` tool validates its `data` payload against. The worker yields its
+   * settlement as structured output instead of writing prose for the caller to
+   * regex. A subagent-oriented harness option, forwarded as-is.
+   */
+  outputSchema?: unknown;
+  /**
+   * Enforcement policy for {@link outputSchema}. The worker contract is
+   * `"permissive"`: a schema violation must still settle with whatever the
+   * worker produced, never discard the report.
+   */
+  outputSchemaMode?: "permissive" | "strict";
+  /**
+   * Force the hidden `yield` tool into this session's toolset (#540). Without
+   * it the model has no sanctioned way to submit structured output.
+   */
+  requireYieldTool?: boolean;
 }): Promise<AgentSessionLike> {
+  let harnessPath: string;
+  try {
+    // An explicit Bun-supported root is the resolver contract. A bare import
+    // from this same bound module was observed selecting the worker's ambient
+    // auto-install cache even while the peer beside it was readable (#828).
+    harnessPath = resolveHarnessEntry(import.meta.dir);
+  } catch (cause) {
+    throw new Error(
+      `omp-conductor could not resolve its peer dependency ${OMP_PACKAGE} from ${import.meta.dir}. Install it alongside omp-conductor (it is deliberately not bundled, so the dispatcher runs the same harness build as the operator).`,
+      { cause },
+    );
+  }
+  const stray = harnessOutsideInstall(import.meta.dir, () => harnessPath);
+  if (stray !== undefined) throw new Error(stray);
   let loaded: unknown;
   try {
-    // Dynamic import is load-bearing, not laziness: the harness is an optional
-    // peer dependency that is absent when this package is type-checked or
-    // published, so a static import would fail the build it must survive.
-    loaded = await import(OMP_PACKAGE as string);
+    // Dynamic import is load-bearing: the runtime-selected absolute path pins
+    // the operator's peer without making it a build-time dependency.
+    loaded = await import(harnessPath);
   } catch (cause) {
     throw new Error(
-      `omp-conductor could not load its peer dependency ${OMP_PACKAGE}. Install it alongside omp-conductor (it is deliberately not bundled, so the dispatcher runs the same harness build as the operator).`,
+      `omp-conductor could not load its peer dependency ${OMP_PACKAGE} from ${harnessPath}. Install it alongside omp-conductor (it is deliberately not bundled, so the dispatcher runs the same harness build as the operator).`,
       { cause },
     );
   }
@@ -290,6 +402,13 @@ export async function createLocalSession(opts: {
     // agentDir (~/.omp/agent/mcp.json) — without this, workers grep-only and
     // burn the turns cap on discovery (#29).
     enableMCP: true,
+    // The structured-settlement contract (#540): subagent-oriented options
+    // threaded to the harness so the worker can yield its report as a schema-
+    // validated object instead of prose. Absent for every other session kind —
+    // probes and orchestrator sessions never yield.
+    ...(opts.outputSchema === undefined ? {} : { outputSchema: opts.outputSchema }),
+    ...(opts.outputSchemaMode === undefined ? {} : { outputSchemaMode: opts.outputSchemaMode }),
+    ...(opts.requireYieldTool === undefined ? {} : { requireYieldTool: opts.requireYieldTool }),
     // Mechanical tool gates: confinement prevents structured worktree I/O from
     // escaping cwd; release policy blocks release/deploy calls when configured.
     ...(extensions.length === 0 ? {} : { extensions }),
@@ -304,6 +423,19 @@ export async function createLocalSession(opts: {
   const modelFallbackMessage =
     typeof fallback === "string" && fallback !== "" ? fallback : undefined;
 
+  // The code-graph session observation (#726): whether the graph MCP tools are
+  // in this session's registry. The harness tool registry is structural and
+  // settles late — MCP wiring finalises through a deferred discovery pass after
+  // `createAgentSession` resolves, so the read can throw in the creation
+  // window, and the graph tools surface under the *enabled* names, never the
+  // active ones. `observeGraphTools` polls that surface until it stops
+  // throwing, bounded; an absent surface (older harness build) or an
+  // unreadable one records no observation — a registry answer is never
+  // guessed. The observation resolves asynchronously so the session handshake
+  // never waits for it.
+  const sessionTools = raw as { getEnabledToolNames?: () => string[] };
+  const graphToolsReady = observeGraphTools(sessionTools.getEnabledToolNames?.bind(sessionTools));
+
   // One real subscription fanned out per event type, so N `on()` calls cost one
   // listener on the harness stream and unknown event types cost nothing.
   const handlers = new Map<string, ((e: unknown) => void)[]>();
@@ -314,6 +446,7 @@ export async function createLocalSession(opts: {
     for (const cb of handlers.get("*") ?? []) cb(event);
   });
 
+  const loadedHarnessVersion = harnessVersion(harnessPath);
   const session: AgentSessionLike = {
     prompt: (text, promptOpts) => raw.prompt(text, promptOpts),
     on(event, cb) {
@@ -329,6 +462,12 @@ export async function createLocalSession(opts: {
         raw.abort({ goalReason: "interrupted", reason: "operator pause" }),
       ).then(() => undefined);
     },
+    // The loaded-module attestation (#832): this session process executes the
+    // conductor module it resolved at start; the version is a property of this
+    // process's loaded tree, deliberately not of what is on disk now.
+    ...(conductorModuleVersion() === undefined ? {} : { extensionVersion: conductorModuleVersion() }),
+    harnessPath,
+    ...(loadedHarnessVersion === undefined ? {} : { harnessVersion: loadedHarnessVersion }),
     // The path the session actually opened, never one we asked for: the
     // arm/monitor tooling reads this file as proof of activity, so a path
     // nothing ever writes to is worse than no path at all.
@@ -336,6 +475,7 @@ export async function createLocalSession(opts: {
       return raw.sessionFile;
     },
     ...(modelFallbackMessage === undefined ? {} : { modelFallbackMessage }),
+    graphToolsReady,
   };
 
   disposers.set(session, async () => {
@@ -414,6 +554,28 @@ function asRawSession(created: unknown): RawSession {
 /** Absolute path of the child entrypoint, resolved against this package. */
 export const SESSION_HOST = join(import.meta.dir, "session-host.ts");
 
+/**
+ * The version of the omp-conductor package this *process* loaded — the module
+ * tree this process's session machinery actually executes, read from the
+ * package.json next to `import.meta.dir` (#832). Read once per process and
+ * cached: the upgrade's session-reload proof compares this against the target
+ * release to tell a genuinely reloaded OMP process from a package install the
+ * live session never picked up. `undefined` when the file cannot be read —
+ * absence is a missing attestation, never "the newest".
+ */
+let loadedConductorVersion: string | undefined;
+export function conductorModuleVersion(): string | undefined {
+  if (loadedConductorVersion !== undefined) return loadedConductorVersion;
+  try {
+    const raw = readFileSync(join(import.meta.dir, "..", "package.json"), "utf8");
+    const parsed = JSON.parse(raw) as { version?: unknown };
+    loadedConductorVersion = typeof parsed.version === "string" ? parsed.version : undefined;
+  } catch {
+    loadedConductorVersion = undefined;
+  }
+  return loadedConductorVersion;
+}
+
 /**
  * How long the parent waits for a child to connect and report `ready`.
  *
@@ -453,6 +615,18 @@ export interface CreateSessionOptions {
   model?: string;
   resume?: boolean;
   role: SessionRole;
+  /**
+   * The worker identity this session must run under (#798): when set, the
+   * child is launched through {@link workerLaunchArgv}'s identity transition
+   * (setpriv) before any of its code runs, its environment is re-pointed at
+   * the worker's own home/agent path, the control socket is granted to that
+   * uid, and the child refuses to build a session unless its kernel uid/gid
+   * match. The daemon resolves this identity once and threads it through every
+   * worker launch; a worker session is never launched without it. Absent, the
+   * session runs as this process's own identity — the orchestrator and every
+   * test surface.
+   */
+  identity?: WorkerIdentity;
   releaseGrants?: ResolvedGrants;
   onReleaseBlocked?: (shape: GateShape, context: ReleaseBlockContext) => void;
   /**
@@ -508,6 +682,12 @@ export interface CreateSessionOptions {
    * without a live harness or a model bill.
    */
   hostModule?: string;
+  /**
+   * Test-only worker binding root. Production always uses
+   * `WORKER_HARNESS_NODE_MODULES`; the Linux privilege regression supplies an
+   * inode-identical temporary binding so it never mutates the live host mount.
+   */
+  harnessNodeModules?: string;
   /**
    * Deny every tool but reading and searching (#307).
    *
@@ -515,6 +695,20 @@ export interface CreateSessionOptions {
    * gate — actually lives.
    */
   readOnly?: boolean;
+  /**
+   * The structured-settlement contract (#540): a JSON Schema the session's
+   * `yield` tool validates its `data` payload against. Forwarded to the child
+   * through the host spec, exactly like {@link ompSettingsFile}.
+   */
+  outputSchema?: unknown;
+  /**
+   * Enforcement policy for {@link outputSchema} — the worker contract is
+   * `"permissive"`, so a schema violation settles with whatever the worker
+   * produced instead of losing the report.
+   */
+  outputSchemaMode?: "permissive" | "strict";
+  /** Force the hidden `yield` tool into this session's toolset (#540). */
+  requireYieldTool?: boolean;
 }
 
 /**
@@ -587,13 +781,22 @@ export async function createSession(opts: CreateSessionOptions): Promise<AgentSe
     );
   }
   // The socket is the run's own channel, and the daemon's own uid is the only
-  // one that speaks on it.
+  // one that speaks on it — unless this session runs under the worker
+  // identity, in which case the child (and only the child) is the worker uid,
+  // and the socket must be granted to it or the very first connect fails
+  // before the identity could matter.
   chmodSync(socketPath, 0o600);
+  if (opts.identity !== undefined) {
+    chownSync(socketPath, opts.identity.uid, opts.identity.gid);
+  }
 
   const spec: SessionHostSpec = {
     socket: socketPath,
     cwd: opts.cwd,
     role: opts.role,
+    ...(opts.identity === undefined
+      ? {}
+      : { identity: { uid: opts.identity.uid, gid: opts.identity.gid } }),
     ...(opts.sessionDir === undefined ? {} : { sessionDir: opts.sessionDir }),
     ...(opts.model === undefined ? {} : { model: opts.model }),
     ...(opts.resume === undefined ? {} : { resume: opts.resume }),
@@ -601,17 +804,41 @@ export async function createSession(opts: CreateSessionOptions): Promise<AgentSe
     ...(opts.verbSocketPath === undefined ? {} : { verbSocketPath: opts.verbSocketPath }),
     ...(opts.readOnly === undefined ? {} : { readOnly: opts.readOnly }),
     ...(opts.ompSettingsFile === undefined ? {} : { ompSettingsFile: opts.ompSettingsFile }),
+    ...(opts.outputSchema === undefined ? {} : { outputSchema: opts.outputSchema }),
+    ...(opts.outputSchemaMode === undefined ? {} : { outputSchemaMode: opts.outputSchemaMode }),
+    ...(opts.requireYieldTool === undefined ? {} : { requireYieldTool: opts.requireYieldTool }),
   };
 
   const log = opts.onChildLog ?? ((line: string) => process.stderr.write(`${line}\n`));
-  const argv = [process.execPath, opts.hostModule ?? SESSION_HOST, JSON.stringify(spec)];
+  const hostModule = opts.hostModule ?? SESSION_HOST;
+  // Under the worker identity the child launches from the read-only binding of
+  // the operator's install (#828). The child then resolves the harness from an
+  // explicit root and runs with `--no-install`; the entry remap and resolver
+  // anchor therefore name the same tree, while Bun has no ambient-cache
+  // fallback for either the peer or its transitive/native imports.
+  const packageRoot = packageNodeModulesRoot(hostModule);
+  const boundEntry =
+    opts.harnessNodeModules === undefined
+      ? workerHarnessPath(hostModule, packageRoot)
+      : workerHarnessPath(hostModule, packageRoot, opts.harnessNodeModules);
+  const entryModule = opts.identity === undefined ? hostModule : boundEntry ?? hostModule;
+  const payloadArgv = [process.execPath, "--no-install", entryModule, JSON.stringify(spec)];
+  const argv = workerLaunchArgv(payloadArgv, opts.identity);
+  // The session's own role is stamped on the child, so a process the agent
+  // runs — `omp-conductor report` from its sandbox — can tell a worker session
+  // from the operator's shell. Direct CLI runs outside a spawned session
+  // inherit nothing and stay the orchestrator surface. Under the worker
+  // identity, the child's HOME and agent/state roots are re-pointed at the
+  // worker account's own, so the harness it boots writes worker state, never
+  // the daemon's.
+  let env: Record<string, string | undefined> | undefined;
+  if (opts.role !== undefined) {
+    env = { ...process.env, [SESSION_ROLE_ENV]: opts.role };
+    if (opts.identity !== undefined) env = workerSessionEnv(env, opts.identity);
+  }
   const child = Bun.spawn(argv, {
     cwd: opts.cwd,
-    // Stamp the session's own role on the child, so a process the agent runs —
-    // `omp-conductor report` from its sandbox — can tell a worker session from
-    // the operator's shell. Direct CLI runs outside a spawned session inherit
-    // nothing and stay the orchestrator surface.
-    env: opts.role === undefined ? undefined : { ...process.env, [SESSION_ROLE_ENV]: opts.role },
+    env,
     stdin: "ignore",
     // The harness writes progress to stdout; both streams are the daemon's log,
     // never the protocol. The protocol has its own socket precisely so a chatty
@@ -741,6 +968,10 @@ export async function createSession(opts: CreateSessionOptions): Promise<AgentSe
   const pending = new Map<number, { resolve: () => void; reject: (err: Error) => void }>();
   let sessionFile: string | undefined;
   let modelFallbackMessage: string | undefined;
+  let graphTools: GraphToolsObservation | undefined;
+  let extensionVersion: string | undefined;
+  let loadedHarnessPath: string | undefined;
+  let loadedHarnessVersion: string | undefined;
   let promptSeq = 0;
 
   const { promise: ready, resolve: onReady, reject: onReadyFail } = Promise.withResolvers<void>();
@@ -844,8 +1075,14 @@ export async function createSession(opts: CreateSessionOptions): Promise<AgentSe
         case "ready":
           sessionFile = message.sessionFile;
           modelFallbackMessage = message.modelFallbackMessage;
+          extensionVersion = message.extensionVersion;
+          loadedHarnessPath = message.harnessPath;
+          loadedHarnessVersion = message.harnessVersion;
           onReady();
           break;
+        case "graph-tools":
+          graphTools = message.graphTools;
+          break;
         case "start-error":
           fail(message.message);
           break;
@@ -939,6 +1176,18 @@ export async function createSession(opts: CreateSessionOptions): Promise<AgentSe
     get modelFallbackMessage() {
       return modelFallbackMessage;
     },
+    get graphTools() {
+      return graphTools;
+    },
+    get extensionVersion() {
+      return extensionVersion;
+    },
+    get harnessPath() {
+      return loadedHarnessPath;
+    },
+    get harnessVersion() {
+      return loadedHarnessVersion;
+    },
   };
 
   disposers.set(session, async () => {