@stigmer/server 3.39.1-dev.20260928194002 → 3.40.1

package/src/boot/__tests__/compose.test.ts

@@ -7,7 +7,12 @@
  *   - start() flips SERVING BEFORE the port binds, so the first probe that
  *     reaches the port already sees a serving server;
  *   - shutdown flips NOT_SERVING FIRST, then drains — and the port stops
- *     answering.
+ *     answering;
+ *   - the artifact download lane binds before SERVING, so a lane that
+ *     cannot bind fails start() with the address and the setting named and
+ *     the server never reports itself serving (stigmer#1089), and a server
+ *     on an ephemeral port gets an ephemeral lane whose minted download
+ *     URLs reach it.
  */
 import { createClient } from "@connectrpc/connect";
 import { createGrpcTransport } from "@connectrpc/connect-node";
@@ -15,7 +20,13 @@ import {
   Health,
   HealthCheckResponse_ServingStatus as ServingStatus,
 } from "@stigmer/protos/grpc/health/v1/health_pb";
-import { connect as netConnect } from "node:net";
+import { ArtifactCommandController } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/command_pb";
+import { ArtifactQueryController } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/query_pb";
+import {
+  createServer as netCreateServer,
+  connect as netConnect,
+} from "node:net";
+import type { AddressInfo } from "node:net";
 import { describe, expect, it } from "vitest";
 
 import { mkdtempSync } from "node:fs";
@@ -32,11 +43,12 @@ const silentLogger = createLogger({
   write: () => {},
 });
 
-function compose() {
+function compose(env: NodeJS.ProcessEnv = {}) {
   // Each composed server gets a throwaway database — the storage stage
   // opens DB_PATH for real (never the developer's ~/.stigmer).
   const testDir = mkdtempSync(path.join(tmpdir(), "compose-test-"));
   const config = loadConfig({
+    ...env,
     STIGMER_MODEL_REGISTRY_REFRESH: "off",
     // No engine behind composed tests: 127.0.0.1:1 is deterministically
     // closed, so boots fail the non-fatal connect fast and can never touch
@@ -95,3 +107,61 @@ describe("composition-root boot ordering", () => {
     expect(refused, "the drained port must refuse new connections").toBe(true);
   });
 });
+
+describe("the artifact download lane", () => {
+  it("fails start() when the lane cannot bind, naming the address and the setting, and never serves", async () => {
+    const holder = netCreateServer();
+    await new Promise<void>((resolve) =>
+      holder.listen(0, "127.0.0.1", resolve),
+    );
+    const held = (holder.address() as AddressInfo).port;
+    try {
+      const server = await compose({ ARTIFACT_HTTP_PORT: String(held) });
+      try {
+        await expect(server.start()).rejects.toThrow(
+          `the artifact file server could not bind '127.0.0.1:${held}' (EADDRINUSE): ARTIFACT_HTTP_PORT=${held} cannot be bound; set it to a free port`,
+        );
+        // SERVING is set before the unified port binds, so a server that is
+        // still NOT_SERVING never opened it.
+        expect(server.healthState.status("")).toBe(ServingStatus.NOT_SERVING);
+      } finally {
+        await server.shutdown();
+      }
+    } finally {
+      await new Promise<void>((resolve) => holder.close(() => resolve()));
+    }
+  });
+
+  it("binds an ephemeral lane beside an ephemeral unified port, and a minted download URL reaches it", async () => {
+    const server = await compose();
+    const port = await server.start();
+    try {
+      const transport = createGrpcTransport({
+        baseUrl: `http://127.0.0.1:${port}`,
+      });
+      const command = createClient(ArtifactCommandController, transport);
+      const query = createClient(ArtifactQueryController, transport);
+      const content = new TextEncoder().encode("ephemeral lane body\n");
+      const created = await command.create({
+        spec: {
+          displayName: "ephemeral-lane.txt",
+          contentType: "text/plain",
+          source: { agentExecutionId: "aexec_01ephemerallane" },
+        },
+        content,
+      });
+      const download = await query.getDownloadUrl({
+        value: created.metadata!.id,
+      });
+
+      // An OS-assigned port, never the privileged port 1 that +1 derived
+      // from 0; the bytes coming back prove it is THIS server's lane.
+      expect(Number(new URL(download.url).port)).toBeGreaterThan(1024);
+      const served = await fetch(download.url);
+      expect(served.status).toBe(200);
+      expect(new Uint8Array(await served.arrayBuffer())).toEqual(content);
+    } finally {
+      await server.shutdown();
+    }
+  });
+});

package/src/boot/__tests__/config.test.ts

@@ -71,6 +71,25 @@ describe("loadConfig", () => {
     );
   });
 
+  // stigmer#1089: the artifact lane's port and serve URL follow the unified
+  // port the composition binds (boot/artifact-lane.ts), so the loader keeps
+  // only what the operator set and derives nothing.
+  it("leaves an unset or malformed ARTIFACT_HTTP_PORT unset, for the lane to derive", () => {
+    expect(loadConfig({}).artifactHttpPort).toBeUndefined();
+    expect(loadConfig({ GRPC_PORT: "0" }).artifactHttpPort).toBeUndefined();
+    expect(loadConfig({ ARTIFACT_HTTP_PORT: "7300x" }).artifactHttpPort).toBeUndefined();
+    expect(loadConfig({ ARTIFACT_HTTP_PORT: "7300" }).artifactHttpPort).toBe(7300);
+    expect(loadConfig({ ARTIFACT_HTTP_PORT: "0" }).artifactHttpPort).toBe(0);
+  });
+
+  it("leaves an unset ARTIFACT_LOCAL_SERVE_URL empty, for the bound lane to answer", () => {
+    expect(loadConfig({}).artifactLocalServeUrl).toBe("");
+    expect(
+      loadConfig({ ARTIFACT_LOCAL_SERVE_URL: "https://artifacts.stigmer.test" })
+        .artifactLocalServeUrl,
+    ).toBe("https://artifacts.stigmer.test");
+  });
+
   // 20260913.02 (sp.console-login, Q-CL-1): the console's public PKCE client
   // id is lenient on purpose — a CLI-only self-host that set the issuer
   // before this knob existed must keep booting on upgrade, and the served

package/src/boot/artifact-lane.ts

@@ -0,0 +1,96 @@
+/**
+ * Where the artifact file server listens, and the URL local artifact
+ * storage mints downloads under, on a server that was not told.
+ *
+ * The artifact download lane is a second loopback listener beside the
+ * unified port (domain/artifact/file-server.ts), bound only when artifact
+ * storage is local. `ARTIFACT_HTTP_PORT` and `ARTIFACT_LOCAL_SERVE_URL`
+ * place it explicitly; unset, both follow the unified port, and this module
+ * is the one place that says how.
+ *
+ * The port rules, in order: a configured port always wins (0 included — an
+ * explicit ephemeral bind); a unified port of 0 (`GRPC_PORT=0`, and the
+ * `portOverride: 0` test seam) is not known until listen, so the lane binds
+ * ephemeral too; otherwise the lane takes the unified port + 1, the default
+ * every install has always had. Deriving +1 from an ephemeral 0 gave port 1,
+ * a privileged port, and a server that reported healthy with a dead download
+ * lane (stigmer#1089). The caller passes the port the unified listener will
+ * bind (`portOverride ?? grpcPort`), the input the OAuth redirect derivation
+ * reads (boot/oauth-redirect-uri.ts).
+ *
+ * The serve URL: a configured value always wins; unset, it is the lane's own
+ * origin on localhost, read from the port the lane actually bound. The
+ * composition binds the lane before the unified port opens, so no request can
+ * mint a URL before that port exists; a read before the bind is a
+ * construction-order fault and throws rather than minting a URL for a port
+ * nothing listens on.
+ *
+ * A lane that cannot bind fails the boot, beside the storage probe it
+ * belongs with; artifactLaneBindError is the copy the operator reads, naming
+ * the address, the cause and the setting that moves the lane.
+ *
+ * Proven by __tests__/artifact-lane.test.ts and the lane cases of
+ * __tests__/compose.test.ts.
+ */
+
+export interface ArtifactLanePortInputs {
+  /** `ARTIFACT_HTTP_PORT` as loaded; undefined when unset. */
+  readonly configured: number | undefined;
+  /** The port the unified listener binds; 0 means "not known until listen". */
+  readonly unifiedPort: number;
+}
+
+/** The port the artifact file server binds; 0 asks the OS for an ephemeral one. */
+export function resolveArtifactLanePort(
+  inputs: ArtifactLanePortInputs,
+): number {
+  if (inputs.configured !== undefined) return inputs.configured;
+  if (inputs.unifiedPort === 0) return 0;
+  return inputs.unifiedPort + 1;
+}
+
+/**
+ * The serve URL local artifact storage mints download URLs under: the
+ * configured value as given, or a resolver over the lane's bound port.
+ */
+export function resolveArtifactServeUrl(
+  configured: string,
+  boundPort: () => number | undefined,
+): string | (() => string) {
+  if (configured !== "") return configured;
+  return () => {
+    const port = boundPort();
+    if (port === undefined) {
+      throw new Error(
+        "artifact download URL requested before the artifact file server bound its port",
+      );
+    }
+    return `http://localhost:${port}`;
+  };
+}
+
+/**
+ * The boot failure for a lane that could not bind: the address, the socket
+ * error's code, and the setting that moves the lane — named as the value
+ * that failed when the operator set it, as the default's escape hatch when
+ * the port was derived.
+ */
+export function artifactLaneBindError(
+  cause: unknown,
+  host: string,
+  port: number,
+  configured: boolean,
+): Error {
+  const code =
+    cause instanceof Error &&
+    typeof (cause as NodeJS.ErrnoException).code === "string"
+      ? ` (${(cause as NodeJS.ErrnoException).code})`
+      : "";
+  const remedy = configured
+    ? `ARTIFACT_HTTP_PORT=${port} cannot be bound; set it to a free port`
+    : "set ARTIFACT_HTTP_PORT to a free port (unset, the lane takes the unified port + 1)";
+  return new Error(
+    `the artifact file server could not bind '${host}:${port}'${code}: ${remedy}`,
+    { cause },
+  );
+}

package/src/boot/compose.ts

@@ -85,6 +85,7 @@ import {
 import { ensureOperatorAccount } from "../domain/identityaccount/operator.js";
 import { newDirectAccountProvisioner } from "../domain/identityaccount/provisioning.js";
 import { newResourceIdentityAccountStore } from "../domain/identityaccount/resource-store.js";
+import type { AccountsByCaller } from "../domain/identityaccount/resolve.js";
 import { registerIamPolicyServices } from "../domain/iampolicy/controller.js";
 import { newIamPolicyGrantPath } from "../domain/iampolicy/grant-path.js";
 import { asFetch, guardedFetch, nodeLookup } from "@stigmer/outbound/egress";
@@ -178,6 +179,11 @@ import { PostgresStore } from "../store/postgres/store.js";
 import { SqliteStore } from "../store/sqlite/store.js";
 import type { Store } from "../store/interface.js";
 import { resolveExtensions } from "../extensions/registry.js";
+import {
+  artifactLaneBindError,
+  resolveArtifactLanePort,
+  resolveArtifactServeUrl,
+} from "./artifact-lane.js";
 import { resolveOAuthRedirectUri } from "./oauth-redirect-uri.js";
 import { assessSkillTransferOrigin } from "./skill-transfer-origin.js";
 import type { ServerExtension } from "../extensions/registry.js";
@@ -570,6 +576,16 @@ export async function composeServer(
           logger,
         })
       : undefined);
+  // The persons callers stand for (stigmer#1387): under the
+  // require-authentication posture every caller is someone the
+  // identity-account domain can name, so memory and the person's declared
+  // preferences are that person's own; trusted-local composes none — the
+  // laptop's one operator, whose memory is the organization's switch alone
+  // (the contract's single-operator arm). The same binding both verifiers
+  // read, so a composed driver is followed here too.
+  const personAccounts: AccountsByCaller | undefined = requireAuthentication
+    ? identityAccounts
+    : undefined;
   logger.info("authorization posture resolved", {
     posture: authorizationPosture,
     authorizer:
@@ -951,11 +967,24 @@ export async function composeServer(
   // arm landed with #13; the health probe runs in start(), matching Go's
   // boot check. Since O5 the factory consults the composition's registered
   // drivers for non-built-in types (§6b).
+  //
+  // The download lane's placement (boot/artifact-lane.ts): the configured
+  // port, or the port beside the one the unified listener binds, ephemeral
+  // when that one is. Unset, the serve URL reads the port the lane actually
+  // bound in start(), before any request can mint a URL.
+  const artifactLanePort = resolveArtifactLanePort({
+    configured: config.artifactHttpPort,
+    unifiedPort: options.portOverride ?? config.grpcPort,
+  });
+  let artifactLaneBoundPort: number | undefined;
   const artifactStorage = newArtifactStorage(
     {
       type: config.artifactStorageType,
       localBasePath: config.artifactLocalBasePath,
-      localServeUrl: config.artifactLocalServeUrl,
+      localServeUrl: resolveArtifactServeUrl(
+        config.artifactLocalServeUrl,
+        () => artifactLaneBoundPort,
+      ),
       r2Bucket: config.r2Bucket,
       r2Endpoint: config.r2Endpoint,
       r2AccessKeyId: config.r2AccessKeyId,
@@ -964,10 +993,9 @@ export async function composeServer(
     },
     extensions.drivers.artifactStorageDrivers,
   );
-  // The artifact download lane: a SECOND loopback listener on
-  // ARTIFACT_HTTP_PORT, local storage only (Go server.go 849–870) —
-  // deliberately not a unified-port lane. Lifecycle rides start()/
-  // shutdown().
+  // The artifact download lane: a SECOND loopback listener, local storage
+  // only (Go server.go 849–870) — deliberately not a unified-port lane.
+  // Lifecycle rides start()/shutdown().
   const artifactFileServer =
     config.artifactStorageType === "local"
       ? createArtifactFileServer({
@@ -1439,6 +1467,7 @@ export async function composeServer(
       authorizer,
       secretService,
       authorizationLifecycle,
+      listReadScope,
     });
     // Schedule registers between channelapp and memory (Go server.go
     // 417 → 426 → 436). The clock and runner ride constant providers —
@@ -1461,6 +1490,7 @@ export async function composeServer(
       authorizer,
       authorizationLifecycle,
       listReadScope,
+      personAccounts,
       runnerCredentialProvider: runnerCredentials,
     });
     registerAgentExecutionServices(router, {
@@ -1469,6 +1499,7 @@ export async function composeServer(
       authorizer,
       authorizationLifecycle,
       listReadScope,
+      personAccounts,
       runnerCredentialProvider: runnerCredentials,
       broker: agentExecutionStreamBroker,
       engineState: executionEngineState,
@@ -1846,6 +1877,28 @@ export async function composeServer(
       // Artifact storage must be reachable and writable before the server
       // answers (Go server.go boots-fatal on the same probe).
       await artifactStorage.health();
+      // The download lane binds with the store it serves, and on the same
+      // terms: a lane that cannot bind fails the boot, where the retired Go
+      // server logged the failure and served on with every download dead
+      // (stigmer#1089). Binding here, before SERVING and the unified port,
+      // also means the derived serve URL exists before a request can mint
+      // one.
+      if (artifactFileServer !== undefined) {
+        await warnOnLegacyArtifactLayout(config.artifactLocalBasePath, logger);
+        try {
+          artifactLaneBoundPort = await artifactFileServer.listen(
+            artifactLanePort,
+            config.artifactHttpHost,
+          );
+        } catch (error) {
+          throw artifactLaneBindError(
+            error,
+            config.artifactHttpHost,
+            artifactLanePort,
+            config.artifactHttpPort !== undefined,
+          );
+        }
+      }
       // Rebuild the search index before the port binds (Go
       // server.go:617): the index is separate from the resources table,
       // and rebuilding here makes every resource — including rows an
@@ -1884,22 +1937,6 @@ export async function composeServer(
         options.host,
       );
       logger.info("stigmer-server listening", { port });
-      // The artifact file server binds AFTER the main server, exactly Go's
-      // boot order; a bind failure is logged but NOT fatal (Go's
-      // ListenAndServe goroutine logs and dies while the server runs on).
-      if (artifactFileServer !== undefined) {
-        await warnOnLegacyArtifactLayout(config.artifactLocalBasePath, logger);
-        try {
-          await artifactFileServer.listen(
-            config.artifactHttpPort,
-            config.artifactHttpHost,
-          );
-        } catch (error) {
-          logger.error("Artifact HTTP file server failed", {
-            error: error instanceof Error ? error.message : String(error),
-          });
-        }
-      }
       return port;
     },
 

package/src/boot/config.ts

@@ -95,16 +95,21 @@ export interface ServerConfig {
   /** The artifact root — shared with the runner's LOCAL_ARTIFACT_PATH (#285). */
   readonly artifactLocalBasePath: string;
   /**
-   * Base URL for local artifact download URLs — the port+1 artifact file
-   * server (#13); no trailing path segment (the storage key carries the
-   * full path).
+   * Base URL for local artifact download URLs (ARTIFACT_LOCAL_SERVE_URL;
+   * #13); no trailing path segment (the storage key carries the full path).
+   * "" = unset: the URL follows the port the artifact file server actually
+   * bound (boot/artifact-lane.ts), so an ephemeral lane mints URLs that
+   * reach it.
    */
   readonly artifactLocalServeUrl: string;
   /**
-   * The artifact file server's own port (ARTIFACT_HTTP_PORT, default
-   * grpcPort+1). Only bound when artifact storage is local.
+   * The artifact file server's own port (ARTIFACT_HTTP_PORT). Undefined =
+   * unset: the lane follows the unified port, +1, or ephemeral when that
+   * port is 0 — the rule lives in boot/artifact-lane.ts, because only the
+   * composition knows the port the unified listener binds. Only bound when
+   * artifact storage is local, and a lane that cannot bind fails the boot.
    */
-  readonly artifactHttpPort: number;
+  readonly artifactHttpPort: number | undefined;
   /**
    * The artifact file server's bind host (ARTIFACT_HTTP_HOST, DD-013;
    * shipped with the Docker image, Phase-2 P4). Defaults to 127.0.0.1 —
@@ -294,8 +299,9 @@ export const DEFAULT_SANDBOX_RUNNER_IMAGE = "ghcr.io/stigmer/runner:latest";
 export function loadConfig(env: NodeJS.ProcessEnv = process.env): ServerConfig {
   const { operatorEmail, operatorName } = loadOperatorIdentity(env);
   const grpcPort = envInt(env, "GRPC_PORT", DEFAULT_GRPC_PORT);
-  // Go: ARTIFACT_HTTP_PORT defaults to the gRPC port + 1.
-  const artifactHttpPort = envInt(env, "ARTIFACT_HTTP_PORT", grpcPort + 1);
+  // Unset (or malformed, the loader's leniency) leaves the lane to follow
+  // the unified port; boot/artifact-lane.ts derives it at composition.
+  const artifactHttpPort = envOptionalInt(env, "ARTIFACT_HTTP_PORT");
   const artifactHttpHost = envString(env, "ARTIFACT_HTTP_HOST", "127.0.0.1");
   const artifactStorageType = envString(env, "ARTIFACT_STORAGE_TYPE", "local");
   const r2 = {
@@ -337,11 +343,7 @@ export function loadConfig(env: NodeJS.ProcessEnv = process.env): ServerConfig {
       "ARTIFACT_LOCAL_BASE_PATH",
       defaultArtifactPath(),
     ),
-    artifactLocalServeUrl: envString(
-      env,
-      "ARTIFACT_LOCAL_SERVE_URL",
-      `http://localhost:${artifactHttpPort}`,
-    ),
+    artifactLocalServeUrl: envString(env, "ARTIFACT_LOCAL_SERVE_URL", ""),
     logLevel: envString(env, "LOG_LEVEL", "info"),
     env: envString(env, "ENV", "local"),
     modelRegistryUpstream: envString(
@@ -531,14 +533,22 @@ function envString(
 }
 
 function envInt(env: NodeJS.ProcessEnv, key: string, fallback: number): number {
+  return envOptionalInt(env, key) ?? fallback;
+}
+
+/** An integer setting, or undefined when it is unset or malformed. */
+function envOptionalInt(
+  env: NodeJS.ProcessEnv,
+  key: string,
+): number | undefined {
   const value = env[key];
   if (value === undefined || value === "") {
-    return fallback;
+    return undefined;
   }
   const parsed = Number.parseInt(value, 10);
   // Go's strconv.Atoi rejects trailing garbage ("7234x"); Number.parseInt
   // would accept it, so the round-trip check keeps the two loaders aligned.
   return Number.isSafeInteger(parsed) && String(parsed) === value.trim()
     ? parsed
-    : fallback;
+    : undefined;
 }

package/src/domain/agent/controller.ts

@@ -11,8 +11,11 @@
  * Proven by agent.conformance.test.ts (CONFORMANCE_TARGET=local),
  * __tests__/agent.test.ts and __tests__/store-faults.test.ts.
  *
- * Versus Stigmer Cloud, OSS excludes the Authorize, CreateIamPolicies, and
- * Publish steps (no multi-tenant auth, IAM/FGA, or event publishing here).
+ * Every chain opens with Authorize; create, delete and updateVisibility run
+ * the shared tuple-lifecycle steps against the composed lifecycle;
+ * getByReference loads, then authorizes the loaded agent exactly as `get`
+ * would (AuthorizeResolvedTarget). The kind has no list RPC. Per-RPC
+ * posture: docs/authorization-coverage.md §6.
  */
 import type { ConnectRouter, HandlerContext } from "@connectrpc/connect";