@orchestraworks/cli 0.5.7 → 0.6.0

package/README.md

@@ -20,7 +20,7 @@ The full guide to every construct, secrets, connections and troubleshooting is [
 ```bash
 npm install -g @orchestraworks/cli         # the CLI, on your path as `orchestra`
 npm install @orchestraworks/cli            # the current release
-npm install @orchestraworks/cli@0.5.7      # this exact release
+npm install @orchestraworks/cli@0.6.0      # this exact release
 ```
 
 Then `import { Factory, Agent, … } from "@orchestraworks/cli"` normally — the package `exports` entry resolves

package/dist/cli/api/approval.js

@@ -6,7 +6,7 @@
 // policy is resolved once per invocation at command-handler entry and handed in — this module reads no
 // environment variable and holds no default, so a gate can never disagree with the banner that described it.
 // An unattended invocation that WOULD prompt is a named refusal, never a silent proceed.
-import { MANAGED_BY_LABEL_KEY } from "../../core/labels.js";
+import { MANAGED_BY_LABEL_KEY, managedByOf } from "../../core/labels.js";
 import { describeSource, preApprovalLevers, } from "../core/approval-policy.js";
 import { isAffirmative, NOTHING_WAS_WRITTEN, readConfirmLine } from "../core/prompts.js";
 /**
@@ -139,8 +139,8 @@ export function readManagedByMarker(body) {
     if (typeof labels !== "object" || labels === null || Array.isArray(labels)) {
         return undefined;
     }
-    const marker = labels[MANAGED_BY_LABEL_KEY];
-    return typeof marker === "string" && marker !== "" ? marker : undefined;
+    const marker = managedByOf(labels);
+    return marker !== "" ? marker : undefined;
 }
 /**
  * It states the CONSEQUENCE — the next `apply` reverts this — because that, not the marker, is what the

package/dist/cli/commands/outpost/local.js

@@ -15,14 +15,13 @@ import { spawnSync } from "node:child_process";
 import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { StackUnreachableError, authorityBytes, readCurrentRun, readProbe, readRun, ensureDir, localDir, readRunFacts, removeIfPresent, sameAddress, stackConfigDir, addressKey, } from "../local/launcher.js";
+import { EGRESS_CA_URL, machineValue } from "./machine-names.js";
 /**
  * Where a container fetches this run's certificate authority when nothing names another path. It is the
  * agent account's own home in our runtime image, which the image contract fixes at `/home`; any other
  * image names its own with `--trust-file`.
  */
 export const DEFAULT_TRUST_FILE = "/home/.orchestra/local-authority.pem";
-/** The name the container's own set carries the plain authority endpoint on (`local/launch/bootstrap.go`). */
-const AUTHORITY_URL_NAME = "SFDK_EGRESS_CA_URL";
 export async function requireLocalEnvironment(call) {
     try {
         await trustThisRunsAuthority(call);
@@ -116,7 +115,8 @@ function authorityEndpoint(call, env) {
             // The folder is gone or unreadable, so the exported endpoint below is all there is.
         }
     }
-    const exported = (env[AUTHORITY_URL_NAME] ?? "").trim();
+    // The container's own set carries the plain authority endpoint on this name (`local/launch/bootstrap.go`).
+    const exported = machineValue(env, EGRESS_CA_URL);
     return exported === "" ? undefined : { url: exported, trustFile: DEFAULT_TRUST_FILE };
 }
 /**

package/dist/cli/commands/outpost/machine-names.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A machine name under the spelling a worker reads first and the former one that a worker built before the
+ * rename reads alone. Both are written, and the new one is read first, until the compatibility rules of
+ * the rename end. Each pair is the one `fwp/schema/environment-v1.json` declares.
+ */
+export interface MachineName {
+    readonly name: string;
+    readonly former: string;
+}
+export declare const EGRESS_CA_URL: MachineName;
+export declare const ENROLLMENT_TOKEN: MachineName;
+export declare const TRANSPORT_TRUST_ROOTS: MachineName;
+export declare const TRANSPORT_TRUST_ROOTS_FILE: MachineName;
+/** The trimmed value under the new name, or under the former one where the new one is unset or blank. */
+export declare function machineValue(env: NodeJS.ProcessEnv, machineName: MachineName): string;
+/** The value under both spellings. */
+export declare function bothSpellings(machineName: MachineName, value: string): Record<string, string>;

package/dist/cli/commands/outpost/machine-names.js

@@ -0,0 +1,22 @@
+export const EGRESS_CA_URL = { name: "ORCHESTRA_EGRESS_CA_URL", former: "SFDK_EGRESS_CA_URL" };
+export const ENROLLMENT_TOKEN = {
+    name: "ORCHESTRA_WORKER_ENROLLMENT_TOKEN",
+    former: "SFDK_ENROLLMENT_TOKEN",
+};
+export const TRANSPORT_TRUST_ROOTS = {
+    name: "ORCHESTRA_WORKER_TRANSPORT_TRUST_ROOTS",
+    former: "SFDK_TRANSPORT_TRUST_ROOTS",
+};
+export const TRANSPORT_TRUST_ROOTS_FILE = {
+    name: "ORCHESTRA_WORKER_TRANSPORT_TRUST_ROOTS_FILE",
+    former: "SFDK_TRANSPORT_TRUST_ROOTS_FILE",
+};
+/** The trimmed value under the new name, or under the former one where the new one is unset or blank. */
+export function machineValue(env, machineName) {
+    const value = (env[machineName.name] ?? "").trim();
+    return value !== "" ? value : (env[machineName.former] ?? "").trim();
+}
+/** The value under both spellings. */
+export function bothSpellings(machineName, value) {
+    return { [machineName.name]: value, [machineName.former]: value };
+}

package/dist/cli/commands/outpost/up.js

@@ -25,6 +25,7 @@ import { runWorkerBinary } from "../worker/launcher.js";
 import { bootCheckOfEnrollment, evaluateChecks, latestSession, listEnrollments, parseBudgets, readAgent, readEnrollment, readEnvironment, renderChecks, } from "../local/checks.js";
 import { ensureDir, readRun, runLocal, stackConfigDir, } from "../local/launcher.js";
 import { DEFAULT_TRUST_FILE, composeBootstrap, mintEnrollment, placeAuthority, requireAgentId, requireEnrolledEnvironment, requireHarness, readOutpostRecord, requireLocalEnvironment, resolveRunFolder, writeOutpostRecord, } from "./local.js";
+import { bothSpellings, EGRESS_CA_URL, ENROLLMENT_TOKEN, machineValue, TRANSPORT_TRUST_ROOTS, TRANSPORT_TRUST_ROOTS_FILE, } from "./machine-names.js";
 /**
  * The port every worker's token feed listens on (`worker/shim/feed.go`). One worker runs on a machine and
  * one shim reads from it, so the two agree on a number rather than on a variable; a second outpost here
@@ -262,14 +263,14 @@ function accountNumber(args) {
  * composed from is this container's own, which is where `docker run -e OPENAI_API_KEY` put it.
  */
 async function prepareInContainer(deps, apis, env, agent, harness, trustFile, namedRoot) {
-    const offer = (env.SFDK_ENROLLMENT_TOKEN ?? "").trim();
+    const offer = machineValue(env, ENROLLMENT_TOKEN);
     if (offer === "") {
         throw new Error("this container carries no enrollment offer: run `orchestra outpost token --agent " +
             `${agent.id}\` on the machine serving the stack and export what it prints here.`);
     }
-    const authority = (env.SFDK_EGRESS_CA_URL ?? "").trim();
+    const authority = machineValue(env, EGRESS_CA_URL);
     if (authority === "") {
-        throw new Error("this container's environment names no certificate authority in SFDK_EGRESS_CA_URL, and it verifies " +
+        throw new Error(`this container's environment names no certificate authority in ${EGRESS_CA_URL.name}, and it verifies ` +
             "this run's certificate against one. Export what `orchestra outpost token` printed.");
     }
     await placeAuthority(authority, trustFile, deps.fetchApi);
@@ -278,10 +279,11 @@ async function prepareInContainer(deps, apis, env, agent, harness, trustFile, na
         throw new Error("no enrollment of this run matches the offer this container carries; mint another one.");
     }
     const composed = workerEnvironment(env, {
-        SFDK_TRANSPORT_TRUST_ROOTS_FILE: trustFile,
+        ...bothSpellings(TRANSPORT_TRUST_ROOTS_FILE, trustFile),
         ...emptiedCarriers(harness, env),
     });
-    delete composed.SFDK_TRANSPORT_TRUST_ROOTS;
+    delete composed[TRANSPORT_TRUST_ROOTS.name];
+    delete composed[TRANSPORT_TRUST_ROOTS.former];
     const home = (composed.HOME ?? "").trim();
     const credentials = composeCredentialFiles(agent, harness, env);
     if (credentials.length > 0 && home === "") {

package/dist/cli/commands/worker/enroll.d.ts

@@ -3,8 +3,9 @@ export interface WorkerEnrollOptions {
     root?: string;
 }
 /**
- * There is deliberately no token flag. The worker reads the enrollment token from `SFDK_ENROLLMENT_TOKEN` or
- * the file `SFDK_ENROLLMENT_TOKEN_FILE` names, because a token on a command line is readable by every process
- * listing on the machine for as long as the process runs, and it lands in shell history on the way in.
+ * There is deliberately no token flag. The worker reads the enrollment token from
+ * `ORCHESTRA_WORKER_ENROLLMENT_TOKEN` or the file `ORCHESTRA_WORKER_ENROLLMENT_TOKEN_FILE` names, because a token
+ * on a command line is readable by every process listing on the machine for as long as the process runs, and it
+ * lands in shell history on the way in.
  */
 export declare function workerEnrollCommand(options?: WorkerEnrollOptions, deps?: WorkerCommandDeps): Promise<void>;

package/dist/cli/commands/worker/enroll.js

@@ -1,8 +1,9 @@
 import { handOffToWorker, optionalFlag } from "./launcher.js";
 /**
- * There is deliberately no token flag. The worker reads the enrollment token from `SFDK_ENROLLMENT_TOKEN` or
- * the file `SFDK_ENROLLMENT_TOKEN_FILE` names, because a token on a command line is readable by every process
- * listing on the machine for as long as the process runs, and it lands in shell history on the way in.
+ * There is deliberately no token flag. The worker reads the enrollment token from
+ * `ORCHESTRA_WORKER_ENROLLMENT_TOKEN` or the file `ORCHESTRA_WORKER_ENROLLMENT_TOKEN_FILE` names, because a token
+ * on a command line is readable by every process listing on the machine for as long as the process runs, and it
+ * lands in shell history on the way in.
  */
 export async function workerEnrollCommand(options = {}, deps = {}) {
     await handOffToWorker(["enroll", ...optionalFlag("--root", options.root)], deps);

package/dist/cli/core/auth.d.ts

@@ -14,19 +14,31 @@ export declare const AUTH_ENV: {
     /** Read after `baseUrl`: the platform writes this name into every machine. */
     readonly machineBaseUrl: "PLATFORM_BASE_URL";
     readonly token: "ORCHESTRA_API_TOKEN";
+    /** Set by the worker on each harness and hook process; the file holds a token it renews. */
+    readonly tokenFile: "ORCHESTRA_API_TOKEN_FILE";
     readonly organizationId: "ORCHESTRA_ORGANIZATION_ID";
     /** Presence is the declaration. */
-    readonly edgeInjected: "SFDK_AUTH_EDGE_INJECTED";
+    readonly edgeInjected: "ORCHESTRA_AUTH_EDGE_INJECTED";
     /** Set by the worker on each harness process it starts. */
+    readonly sessionId: "ORCHESTRA_SESSION_ID";
+};
+/**
+ * The spellings a machine set before the rename, read when the name above is absent: a running worker and a
+ * pinned runtime image still set only these.
+ */
+export declare const FORMER_MACHINE_ENV: {
+    readonly edgeInjected: "SFDK_AUTH_EDGE_INJECTED";
     readonly sessionId: "SFDK_SESSION_ID";
 };
+/** Whether this machine declares edge authentication, under either spelling. */
+export declare function edgeInjectedFrom(env: NodeJS.ProcessEnv): boolean;
 /** The base URL the environment names, and which of the two variables named it. */
 export declare function baseUrlFromEnv(env: NodeJS.ProcessEnv): {
     readonly value: string;
     readonly variable: string;
 } | undefined;
 /** Which tier of the chain supplied the authorization. */
-export type AuthProvider = "env" | "profile" | "edge";
+export type AuthProvider = "env" | "file" | "profile" | "edge";
 /**
  * The conversation the command runs in, or undefined when the variable is absent, empty or whitespace only.
  * The only reader of the variable: auth resolution and `login` both call it.
@@ -36,6 +48,9 @@ export declare function sessionIdFrom(env: NodeJS.ProcessEnv): string | undefine
  * `session` rides along under the PROFILE provider only: `token` is the bearer as of this resolution, and
  * the session is what keeps a bearer valid over time. The env provider's token has nothing to refresh it
  * with and the edge provider holds no credential at all, so for both the field's absence is structural.
+ *
+ * Under the FILE provider the worker renews the token in place, so `token` reads the file again before each
+ * request, and the token names its own organization, so no organization is resolved.
  */
 export type AuthResolution = {
     readonly provider: "env" | "profile";
@@ -44,6 +59,11 @@ export type AuthResolution = {
     readonly organizationId?: string;
     readonly session?: CredentialSession;
     readonly sessionId?: string;
+} | {
+    readonly provider: "file";
+    readonly token: () => string;
+    readonly baseUrl: string;
+    readonly sessionId?: string;
 } | {
     readonly provider: "edge";
     readonly baseUrl: string;

package/dist/cli/core/auth.js

@@ -1,8 +1,9 @@
 // Every command resolves credentials through ONE ordered chain, with strict presence-is-selection
 // precedence: `ORCHESTRA_API_TOKEN` (one opaque slot holding ANY principal's bearer — the CLI never looks inside,
-// IAM judges server-side), then the `orchestra auth login` profile, then the sandbox flag the platform DECLARES and
-// never infers (the request goes out BARE and the egress stamps the per-request agent authorization, so no
-// credential material ever enters the sandbox), then a refusal.
+// IAM judges server-side), then the agent token file the worker names in `ORCHESTRA_API_TOKEN_FILE` and renews
+// while the agent is placed, then the `orchestra auth login` profile, then the sandbox flag the platform
+// DECLARES and never infers (the request goes out BARE and the egress stamps the per-request agent
+// authorization), then a refusal.
 //
 // The precedence is purely CLIENT-side. Inside a sandbox the egress stamp REPLACES whatever the request
 // carried, so an exported token is sent, then overwritten, and the call executes as the agent.
@@ -13,6 +14,7 @@
 // Resolution is ASYNC because the profile tier renews itself. The renewal lives in
 // `core/credentialSession.ts`: this module decides WHICH credential a command uses, and the session owns
 // what happens to it over time.
+import { readFileSync } from "node:fs";
 import { CredentialSession } from "./credentialSession.js";
 import { DEFAULT_PROFILE_NAME, loadProfile as loadProfileFromDisk, } from "./profile.js";
 /**
@@ -28,12 +30,26 @@ export const AUTH_ENV = {
     /** Read after `baseUrl`: the platform writes this name into every machine. */
     machineBaseUrl: "PLATFORM_BASE_URL",
     token: "ORCHESTRA_API_TOKEN",
+    /** Set by the worker on each harness and hook process; the file holds a token it renews. */
+    tokenFile: "ORCHESTRA_API_TOKEN_FILE",
     organizationId: "ORCHESTRA_ORGANIZATION_ID",
     /** Presence is the declaration. */
-    edgeInjected: "SFDK_AUTH_EDGE_INJECTED",
+    edgeInjected: "ORCHESTRA_AUTH_EDGE_INJECTED",
     /** Set by the worker on each harness process it starts. */
+    sessionId: "ORCHESTRA_SESSION_ID",
+};
+/**
+ * The spellings a machine set before the rename, read when the name above is absent: a running worker and a
+ * pinned runtime image still set only these.
+ */
+export const FORMER_MACHINE_ENV = {
+    edgeInjected: "SFDK_AUTH_EDGE_INJECTED",
     sessionId: "SFDK_SESSION_ID",
 };
+/** Whether this machine declares edge authentication, under either spelling. */
+export function edgeInjectedFrom(env) {
+    return firstPresent(env[AUTH_ENV.edgeInjected], env[FORMER_MACHINE_ENV.edgeInjected]) !== undefined;
+}
 /** The base URL the environment names, and which of the two variables named it. */
 export function baseUrlFromEnv(env) {
     for (const variable of [AUTH_ENV.baseUrl, AUTH_ENV.machineBaseUrl]) {
@@ -49,8 +65,13 @@ export function baseUrlFromEnv(env) {
  * The only reader of the variable: auth resolution and `login` both call it.
  */
 export function sessionIdFrom(env) {
-    const value = env[AUTH_ENV.sessionId]?.trim();
-    return value === undefined || value === "" ? undefined : value;
+    for (const variable of [AUTH_ENV.sessionId, FORMER_MACHINE_ENV.sessionId]) {
+        const value = env[variable]?.trim();
+        if (value !== undefined && value !== "") {
+            return value;
+        }
+    }
+    return undefined;
 }
 /**
  * The chain distinguishes "absent" from "empty", so the fields are copied conditionally: an unconditional
@@ -80,6 +101,26 @@ export class MissingBaseUrlError extends Error {
         this.name = "MissingBaseUrlError";
     }
 }
+/** The trimmed content, or undefined when the file is missing, unreadable, empty or whitespace only. */
+function tokenFromFile(path) {
+    let content;
+    try {
+        content = readFileSync(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const token = content.trim();
+    return token === "" ? undefined : token;
+}
+/** A failed read mid-command keeps the last token read rather than sending the request bare. */
+function fileTokenReader(path, first) {
+    let last = first;
+    return () => {
+        last = tokenFromFile(path) ?? last;
+        return last;
+    };
+}
 /** Loopback hosts reachable over plain HTTP — the local dev-stack contract. */
 const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
 /**
@@ -132,12 +173,18 @@ export async function resolveAuthWithWarnings(env, flags, deps = {}) {
     const profile = (deps.loadProfile ?? loadProfileFromDisk)(flags.profile);
     const baseUrl = firstPresent(flags.baseUrl, baseUrlFromEnv(env)?.value, profile?.baseUrl);
     const envToken = firstPresent(env[AUTH_ENV.token]);
+    const tokenFilePath = firstPresent(env[AUTH_ENV.tokenFile]);
+    const fileToken = envToken === undefined && tokenFilePath !== undefined ? tokenFromFile(tokenFilePath) : undefined;
     const profileToken = firstPresent(profile?.token);
-    const edgeDeclared = firstPresent(env[AUTH_ENV.edgeInjected]) !== undefined;
+    const edgeDeclared = edgeInjectedFrom(env);
     // Read before the provider split: a person may export it by hand under any provider.
     const sessionId = sessionIdFrom(env);
     const withSessionId = sessionId !== undefined ? { sessionId } : {};
-    if (envToken === undefined && profileToken === undefined && !edgeDeclared) {
+    if (envToken === undefined && fileToken === undefined && profileToken === undefined && !edgeDeclared) {
+        if (tokenFilePath !== undefined) {
+            throw new MissingCredentialsError(`no auth provider resolved: ${AUTH_ENV.tokenFile} names ${tokenFilePath}, which the worker has not ` +
+                `written yet. The worker writes it once the agent is placed on this machine; try again shortly.`);
+        }
         throw new MissingCredentialsError(`no auth provider resolved: export ${AUTH_ENV.token}, run \`orchestra auth login\`, or run inside a host ` +
             `where the platform declares ${AUTH_ENV.edgeInjected}.`);
     }
@@ -146,6 +193,17 @@ export async function resolveAuthWithWarnings(env, flags, deps = {}) {
     }
     // Refuse before ANY network access, for every provider — the bare edge send included.
     assertSecretTransport(baseUrl);
+    if (fileToken !== undefined && tokenFilePath !== undefined) {
+        return {
+            auth: {
+                provider: "file",
+                token: fileTokenReader(tokenFilePath, fileToken),
+                baseUrl,
+                ...withSessionId,
+            },
+            warnings: [],
+        };
+    }
     if (envToken === undefined && profileToken === undefined) {
         // The egress stamps the authorization and the stamped identity carries the org.
         return { auth: { provider: "edge", baseUrl, ...withSessionId }, warnings: [] };
@@ -223,6 +281,9 @@ export function platformTargetFrom(auth) {
     if (auth.provider === "edge") {
         return { baseUrl: auth.baseUrl, ...sessionId };
     }
+    if (auth.provider === "file") {
+        return { baseUrl: auth.baseUrl, token: auth.token, ...sessionId };
+    }
     return {
         baseUrl: auth.baseUrl,
         token: auth.token,

package/dist/cli/core/errors.js

@@ -182,6 +182,10 @@ function guidance(status, api, ctx) {
             case "env":
                 return (`The token in ${AUTH_ENV.token} is not accepted. Renew that token and re-export ` +
                     `${AUTH_ENV.token}; a stored login profile is not what this command used.`);
+            case "file":
+                return (`The agent token in the file ${AUTH_ENV.tokenFile} names is not accepted. The worker renews that ` +
+                    `file, so there is nothing to renew here: the token expired before the worker renewed it, or the ` +
+                    `agent's placement on this machine, the machine's state or the agent's status refused it.`);
             case "edge":
                 return (`Authorization is stamped at the egress edge (${AUTH_ENV.edgeInjected} is declared), so there is ` +
                     `no credential here to renew — the stamping path itself failed. Check the egress/identity plane.`);

package/dist/cli/core/platform-client.d.ts

@@ -50,7 +50,8 @@ export declare function withRefreshRetry(fetchApi: FetchAPI, session: Credential
  */
 export interface PlatformTarget {
     readonly baseUrl: string;
-    readonly token?: string;
+    /** The bearer, or under the file provider a reader of the worker's renewed token, called before each request. */
+    readonly token?: string | (() => string);
     readonly organizationId?: string;
     /**
      * `token` above is the bearer as of auth resolution; the session is what keeps a bearer valid, and every
@@ -73,7 +74,7 @@ export declare function createPlatformApis(target: PlatformTarget, fetchApi: Fet
 export interface RawPlatformRequest {
     baseUrl: string;
     /** Absent for the bare edge send, exactly as for a typed command. */
-    token?: string;
+    token?: string | (() => string);
     organizationId?: string;
     /** The live credentials behind `token`, when the resolution carried one. */
     session?: CredentialSession;

package/dist/cli/core/session-body.d.ts

@@ -1,5 +1,5 @@
 /**
- * The one body rule behind `SFDK_SESSION_ID`: a JSON object body that names no `sessionId` gains the
+ * The one body rule behind `ORCHESTRA_SESSION_ID`: a JSON object body that names no `sessionId` gains the
  * conversation id. Anything else goes out exactly as it came in: no id, a body that is not a string, a
  * content type other than `application/json`, a body that does not parse as a JSON object, and one that
  * already names a `sessionId`, which is how an explicit `--session-id` wins.

package/dist/cli/core/session-body.js

@@ -1,5 +1,5 @@
 /**
- * The one body rule behind `SFDK_SESSION_ID`: a JSON object body that names no `sessionId` gains the
+ * The one body rule behind `ORCHESTRA_SESSION_ID`: a JSON object body that names no `sessionId` gains the
  * conversation id. Anything else goes out exactly as it came in: no id, a body that is not a string, a
  * content type other than `application/json`, a body that does not parse as a JSON object, and one that
  * already names a `sessionId`, which is how an explicit `--session-id` wins.

package/dist/cli/firstRun.d.ts

@@ -56,9 +56,9 @@ export interface FirstRunGateDeps extends InterviewDeps {
 }
 /**
  * The pre-command gate: the interview runs on a machine where a person is present and nothing is
- * configured. A credential supplied by the environment — an exported token, or the marker the platform sets
- * on a machine where the egress stamps the authorization — skips the interview and nothing else, so a
- * command's own rules are untouched either way.
+ * configured. A credential supplied by the environment — an exported token, the token file the worker
+ * names, written yet or not, or the marker the platform sets on a machine where the egress stamps the
+ * authorization — skips the interview and nothing else, so a command's own rules are untouched either way.
  *
  * The terminal is checked first, so a run with no person to ask touches neither the disk nor the network.
  */

package/dist/cli/firstRun.js

@@ -7,7 +7,7 @@
 // EVERYTHING THIS FILE PRINTS GOES TO STDERR, including the sign-in it runs. The interview can precede any
 // command, and stdout is that command's result channel — under `--output json` a question printed there
 // would land inside the document a caller is parsing.
-import { AUTH_ENV, authFlagsFrom, firstPresent, } from "./core/auth.js";
+import { AUTH_ENV, authFlagsFrom, edgeInjectedFrom, firstPresent, } from "./core/auth.js";
 import { loginCommand } from "./core/login.js";
 import { defaultIo } from "./core/output.js";
 import { DEFAULT_PROFILE_NAME, loadProfile as loadProfileFromDisk, saveProfile as saveProfileToDisk, } from "./core/profile.js";
@@ -168,9 +168,9 @@ async function resolveHarnesses(flags, context) {
 }
 /**
  * The pre-command gate: the interview runs on a machine where a person is present and nothing is
- * configured. A credential supplied by the environment — an exported token, or the marker the platform sets
- * on a machine where the egress stamps the authorization — skips the interview and nothing else, so a
- * command's own rules are untouched either way.
+ * configured. A credential supplied by the environment — an exported token, the token file the worker
+ * names, written yet or not, or the marker the platform sets on a machine where the egress stamps the
+ * authorization — skips the interview and nothing else, so a command's own rules are untouched either way.
  *
  * The terminal is checked first, so a run with no person to ask touches neither the disk nor the network.
  */
@@ -179,7 +179,9 @@ export async function runFirstRunIfNeeded(flags, deps = {}) {
     if ((deps.isTTY ?? process.stdin.isTTY === true) !== true) {
         return;
     }
-    if (firstPresent(env[AUTH_ENV.token]) !== undefined || firstPresent(env[AUTH_ENV.edgeInjected]) !== undefined) {
+    if (firstPresent(env[AUTH_ENV.token]) !== undefined ||
+        firstPresent(env[AUTH_ENV.tokenFile]) !== undefined ||
+        edgeInjectedFrom(env)) {
         return;
     }
     const loadProfile = deps.loadProfile ?? loadProfileFromDisk;

package/dist/cli/main.js

@@ -406,9 +406,10 @@ export function buildProgram(handlers = defaultHandlers, pointer = bundledSkillP
         .command("enroll")
         .option("--root <dir>", "directory this worker installed its pinned runtime and harness families into")
         .description("redeem this machine's enrollment token, then serve it")
-        .addHelpText("after", "\nThe enrollment token is read from SFDK_ENROLLMENT_TOKEN, or from the file SFDK_ENROLLMENT_TOKEN_FILE\n" +
-        "names. There is no flag for it: a token on the command line is readable by every process listing on\n" +
-        "the machine, and it lands in shell history on the way in.\n")
+        .addHelpText("after", "\nThe enrollment token is read from ORCHESTRA_WORKER_ENROLLMENT_TOKEN, or from the file\n" +
+        "ORCHESTRA_WORKER_ENROLLMENT_TOKEN_FILE names; the former names SFDK_ENROLLMENT_TOKEN and\n" +
+        "SFDK_ENROLLMENT_TOKEN_FILE still work. There is no flag for it: a token on the command line is readable\n" +
+        "by every process listing on the machine, and it lands in shell history on the way in.\n")
         .action((options) => handlers.workerEnroll(options));
     // The local environment, and the machines it runs. `up` deliberately takes NO auth flags: it starts a
     // stack rather than reaching one, and the address and the token it prints are the stack's own answer. The

package/dist/constructs/environment.d.ts

@@ -93,6 +93,7 @@ export interface RouteModelsViaGatewayOptions {
 export declare class EgressPolicy {
     private readonly defaultAction;
     private readonly rules;
+    private gatewayKey;
     private constructor();
     static denyAll(): EgressPolicy;
     /**
@@ -140,6 +141,8 @@ export declare class EgressPolicy {
      * as well.
      */
     routeModelsViaGateway(opts: RouteModelsViaGatewayOptions): EgressPolicy;
+    /** @internal The variables this policy names a credential in, each set to its reference. */
+    _declaredEnv(): Record<string, string>;
     /**
      * Each entry lands as an ordinary allow rule — the same wire shape, in the same `rules` array, in the same
      * declaration order — so the emitted plan is byte-identical to one where the author typed every rule out by
@@ -270,18 +273,24 @@ export interface EnvironmentProps {
     /** At most four, and never at `/home`. */
     disks?: DiskMount[];
     /**
-     * Set on every machine built from this environment and forwarded into the agent process itself. There is
-     * deliberately no "looks like a secret" detector on them: a checker that caught most API-key shapes would
-     * teach authors that the ones it missed were safe. Names beginning `SFDK_` are platform-owned, written last
-     * and rejected with a 400, except the four `SFDK_WORKER_*` release settings, which reach the worker alone. `HOME` is not a platform
-     * variable at all — the account inside the runtime image decides where the home directory is — so declaring
-     * it points the harness elsewhere, and a home off the mounted volume does not survive a machine recycle.
-     * `ANTHROPIC_BASE_URL` is not reserved; the way to point a harness at the model gateway is the agent's
-     * `modelSettings.enableModelGateway`. Whether two names are the same name is keyed on the TARGET OS, which makes two rejections real on
-     * Windows that cannot happen on POSIX: a case-variant of the reserved prefix is reserved, and two keys
-     * differing only in case are one variable, so the API keeps neither.
+     * Set on every machine built from this environment and forwarded into the agent process. There is no "looks
+     * like a secret" detector: one that caught most key shapes would teach authors the rest were safe. Names
+     * beginning `ORCHESTRA_` or `SFDK_` are platform-owned and refused, except ordinary `ORCHESTRA_FDK_` names and
+     * the `ORCHESTRA_WORKER_*` release settings, which reach the worker alone. `HOME` is the image's to decide;
+     * declaring it moves the harness off the mounted home. Names are compared under the target OS, so on Windows a
+     * case-variant of a reserved prefix is reserved and two keys differing only in case are one variable.
+     *
+     * A Secret or a Connection in place of text sets the reference `orchestra:secret/<id>` or
+     * `orchestra:connection/<id>`, resolved at apply, which a tool sends as its token and the egress edge
+     * replaces with that credential (`GH_TOKEN`, `GITLAB_TOKEN`, `ORCHESTRA_GIT_CREDENTIAL` for git).
+     */
+    env?: Record<string, string | ISecret | IConnection>;
+    /**
+     * The credentials a request from this environment's machines gets when it names none, the first whose hosts
+     * cover the request's host serving. `replace` defaults to true; false leaves a request that carries its own
+     * value in the credential's header as it was sent. Omitted, apply leaves the live list alone; `[]` clears it.
      */
-    env?: Record<string, string>;
+    credentials?: EnvironmentCredential[];
     /** The reference rides the environment; the value is resolved platform-side at each machine create and never
      *  leaves the control plane. */
     imagePullCredential?: ISecret;
@@ -304,6 +313,10 @@ export interface EnvironmentProps {
     /** Fixed at create; undeclared, the environment is created in Shared. */
     team?: ITeam;
 }
+export interface EnvironmentCredential {
+    credential: ISecret | IConnection;
+    replace?: boolean;
+}
 export declare class Environment extends Construct implements IEnvironment {
     /** Accepts a platform id or a slug interchangeably — one rule, stated on `IResource`. */
     readonly environmentId: string;