@orchestraworks/cli 0.5.1 → 0.5.3

package/node_modules/@orchestraworks/client/dist/models/EnvironmentSnapshot.js

@@ -20,6 +20,7 @@ exports.EnvironmentSnapshotFromJSONTyped = EnvironmentSnapshotFromJSONTyped;
 exports.EnvironmentSnapshotToJSON = EnvironmentSnapshotToJSON;
 exports.EnvironmentSnapshotToJSONTyped = EnvironmentSnapshotToJSONTyped;
 const EnvironmentIngressPolicy_1 = require("./EnvironmentIngressPolicy");
+const EnvironmentHooks_1 = require("./EnvironmentHooks");
 const EnvironmentVolumeMount_1 = require("./EnvironmentVolumeMount");
 const EnvironmentEgressPolicy_1 = require("./EnvironmentEgressPolicy");
 const EnvironmentDisk_1 = require("./EnvironmentDisk");
@@ -90,6 +91,9 @@ function EnvironmentSnapshotFromJSONTyped(json, ignoreDiscriminator) {
         'keepAliveWhenIdle': json['keepAliveWhenIdle'],
         'ttl': json['ttl'] == null ? undefined : json['ttl'],
         'shutdownGracePeriodSeconds': json['shutdownGracePeriodSeconds'] == null ? undefined : json['shutdownGracePeriodSeconds'],
+        'workingDirectory': json['workingDirectory'] == null ? undefined : json['workingDirectory'],
+        'hooks': json['hooks'] == null ? undefined : (0, EnvironmentHooks_1.EnvironmentHooksFromJSON)(json['hooks']),
+        'setupTimeoutSeconds': json['setupTimeoutSeconds'] == null ? undefined : json['setupTimeoutSeconds'],
     };
 }
 function EnvironmentSnapshotToJSON(json) {
@@ -119,5 +123,8 @@ function EnvironmentSnapshotToJSONTyped(value, ignoreDiscriminator = false) {
         'keepAliveWhenIdle': value['keepAliveWhenIdle'],
         'ttl': value['ttl'],
         'shutdownGracePeriodSeconds': value['shutdownGracePeriodSeconds'],
+        'workingDirectory': value['workingDirectory'],
+        'hooks': (0, EnvironmentHooks_1.EnvironmentHooksToJSON)(value['hooks']),
+        'setupTimeoutSeconds': value['setupTimeoutSeconds'],
     };
 }

package/node_modules/@orchestraworks/client/dist/models/Machine.d.ts

@@ -43,11 +43,17 @@ export interface Machine {
      */
     environmentId: string;
     /**
-     * Compute registration key this machine launched on
+     * The internal registration key this machine launched on, for operators; computeProviderId names the compute provider
      * @type {string}
      * @memberof Machine
      */
     computeProviderKey: string;
+    /**
+     * The compute provider this machine runs on: cprov_orchestra on hosted compute, or the self-hosted record whose Launcher runs it. Absent on a customer's own enrolled machine
+     * @type {string}
+     * @memberof Machine
+     */
+    computeProviderId?: string;
     /**
      * Compute-provider instance id
      * @type {string}

package/node_modules/@orchestraworks/client/dist/models/Machine.js

@@ -105,6 +105,7 @@ function MachineFromJSONTyped(json, ignoreDiscriminator) {
         'organizationId': json['organizationId'],
         'environmentId': json['environmentId'],
         'computeProviderKey': json['computeProviderKey'],
+        'computeProviderId': json['computeProviderId'] == null ? undefined : json['computeProviderId'],
         'computeProviderInstanceId': json['computeProviderInstanceId'] == null ? undefined : json['computeProviderInstanceId'],
         'status': json['status'],
         'reason': json['reason'] == null ? undefined : json['reason'],
@@ -141,6 +142,7 @@ function MachineToJSONTyped(value, ignoreDiscriminator = false) {
         'organizationId': value['organizationId'],
         'environmentId': value['environmentId'],
         'computeProviderKey': value['computeProviderKey'],
+        'computeProviderId': value['computeProviderId'],
         'computeProviderInstanceId': value['computeProviderInstanceId'],
         'status': value['status'],
         'reason': value['reason'],

package/node_modules/@orchestraworks/client/dist/models/UpdateEnvironmentRequest.d.ts

@@ -13,6 +13,7 @@ import type { EnvironmentIngressPolicy } from './EnvironmentIngressPolicy';
 import type { EnvironmentPlatformRequest } from './EnvironmentPlatformRequest';
 import type { EnvironmentEgressPolicy } from './EnvironmentEgressPolicy';
 import type { EnvironmentProvisionSpecRequest } from './EnvironmentProvisionSpecRequest';
+import type { EnvironmentHooksRequest } from './EnvironmentHooksRequest';
 /**
  *
  * @export
@@ -49,6 +50,18 @@ export interface UpdateEnvironmentRequest {
      * @memberof UpdateEnvironmentRequest
      */
     provisionSpec?: EnvironmentProvisionSpecRequest;
+    /**
+     * The absolute folder every conversation's agent starts in, on every kind: a path starting with / on linux and macos, and a drive or UNC path on windows, at most 1024 characters. A machine keeps the value it was created with. The worker creates the folder when it is missing, owned by the account the agent runs as, and an agent placement whose folder cannot be created or entered fails. Absent, the agent starts in the worker's own folder for its harness. On an update, absent leaves the stored value and an empty one clears it.
+     * @type {string}
+     * @memberof UpdateEnvironmentRequest
+     */
+    workingDirectory?: string;
+    /**
+     * Scripts the worker runs at points of a machine's and an agent's life. onStartMachine and onStartAgent are built; onStartSession, onStopSession, onStopAgent and onStopMachine are reserved. On an update, an absent object or member leaves the stored hook.
+     * @type {EnvironmentHooksRequest}
+     * @memberof UpdateEnvironmentRequest
+     */
+    hooks?: EnvironmentHooksRequest;
     /**
      * Labels: the customer's key-to-value tags; the platform reads no key. Merged into the stored labels as a JSON Merge Patch: absent leaves them, a key with a string sets it, a key with null removes it, and null removes them all
      * @type {{ [key: string]: string | null; }}

package/node_modules/@orchestraworks/client/dist/models/UpdateEnvironmentRequest.js

@@ -22,6 +22,7 @@ const EnvironmentIngressPolicy_1 = require("./EnvironmentIngressPolicy");
 const EnvironmentPlatformRequest_1 = require("./EnvironmentPlatformRequest");
 const EnvironmentEgressPolicy_1 = require("./EnvironmentEgressPolicy");
 const EnvironmentProvisionSpecRequest_1 = require("./EnvironmentProvisionSpecRequest");
+const EnvironmentHooksRequest_1 = require("./EnvironmentHooksRequest");
 /**
  * Check if a given object implements the UpdateEnvironmentRequest interface.
  */
@@ -41,6 +42,8 @@ function UpdateEnvironmentRequestFromJSONTyped(json, ignoreDiscriminator) {
         'egressPolicy': json['egressPolicy'] == null ? undefined : (0, EnvironmentEgressPolicy_1.EnvironmentEgressPolicyFromJSON)(json['egressPolicy']),
         'ingressPolicy': json['ingressPolicy'] == null ? undefined : (0, EnvironmentIngressPolicy_1.EnvironmentIngressPolicyFromJSON)(json['ingressPolicy']),
         'provisionSpec': json['provisionSpec'] == null ? undefined : (0, EnvironmentProvisionSpecRequest_1.EnvironmentProvisionSpecRequestFromJSON)(json['provisionSpec']),
+        'workingDirectory': json['workingDirectory'] == null ? undefined : json['workingDirectory'],
+        'hooks': json['hooks'] == null ? undefined : (0, EnvironmentHooksRequest_1.EnvironmentHooksRequestFromJSON)(json['hooks']),
         'labels': json['labels'] == null ? undefined : json['labels'],
     };
 }
@@ -57,6 +60,8 @@ function UpdateEnvironmentRequestToJSONTyped(value, ignoreDiscriminator = false)
         'egressPolicy': (0, EnvironmentEgressPolicy_1.EnvironmentEgressPolicyToJSON)(value['egressPolicy']),
         'ingressPolicy': (0, EnvironmentIngressPolicy_1.EnvironmentIngressPolicyToJSON)(value['ingressPolicy']),
         'provisionSpec': (0, EnvironmentProvisionSpecRequest_1.EnvironmentProvisionSpecRequestToJSON)(value['provisionSpec']),
+        'workingDirectory': value['workingDirectory'],
+        'hooks': (0, EnvironmentHooksRequest_1.EnvironmentHooksRequestToJSON)(value['hooks']),
         'labels': value['labels'],
     };
 }

package/node_modules/@orchestraworks/client/dist/models/index.d.ts

@@ -124,6 +124,9 @@ export * from './Environment';
 export * from './EnvironmentDisk';
 export * from './EnvironmentDiskMount';
 export * from './EnvironmentEgressPolicy';
+export * from './EnvironmentHook';
+export * from './EnvironmentHooks';
+export * from './EnvironmentHooksRequest';
 export * from './EnvironmentIngressPolicy';
 export * from './EnvironmentMount';
 export * from './EnvironmentPlatform';

package/node_modules/@orchestraworks/client/dist/models/index.js

@@ -142,6 +142,9 @@ __exportStar(require("./Environment"), exports);
 __exportStar(require("./EnvironmentDisk"), exports);
 __exportStar(require("./EnvironmentDiskMount"), exports);
 __exportStar(require("./EnvironmentEgressPolicy"), exports);
+__exportStar(require("./EnvironmentHook"), exports);
+__exportStar(require("./EnvironmentHooks"), exports);
+__exportStar(require("./EnvironmentHooksRequest"), exports);
 __exportStar(require("./EnvironmentIngressPolicy"), exports);
 __exportStar(require("./EnvironmentMount"), exports);
 __exportStar(require("./EnvironmentPlatform"), exports);

package/node_modules/@orchestraworks/client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchestraworks/client",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Orchestra public API TypeScript client",
   "author": "Living Computers",
   "repository": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchestraworks/cli",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "type": "module",
   "description": "The Orchestra command line.",
   "license": "Apache-2.0",
@@ -109,13 +109,13 @@
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "1.3.0",
-    "@orchestraworks/client": "0.5.1",
-    "@orchestraworks/worker": "0.0.136",
+    "@orchestraworks/client": "0.5.3",
+    "@orchestraworks/worker": "0.0.138",
     "commander": "^14.0.0",
     "liquidjs": "^10.28.0"
   },
   "optionalDependencies": {
-    "@orchestraworks/local": "0.0.136"
+    "@orchestraworks/local": "0.0.138"
   },
   "bundleDependencies": [
     "@orchestraworks/client"

package/skills/orchestra/SKILL.md

@@ -63,7 +63,7 @@ in a project may point at its own project or the shared space; a row in the shar
 shared space. So a shared agent takes items from every project, and an agent in a project takes items only
 from that project.
 
-**In the starter.** The organization has no project. Each of the five agents starts with `agent-worker`. The
+**In the starter.** The organization has no project. Each of the four agents starts with `agent-worker`. The
 Manager Agent is then given `agent-manager`, because it works in every pipeline and changes the Engineer
 Agents.
 
@@ -78,7 +78,11 @@ Agents.
 claude, codex, pi, script, custom; fixed at create); docs/architecture/agent-skills-and-runtime-manifest.md:250-302
 (modelSettings; a running turn keeps its model, the next turn takes the new one);
 docs/architecture/agent-runtime-images.md:3 (one image carries the four harnesses). Starter: the kit branch's
-cli/templates/engineering-team/main.ts. -->
+cli/templates/engineering-team/main.ts. Script agents: docs/architecture/api.md:1362-1368 (the five harness
+values), :1398 (no model settings on script or custom); docs/architecture/agent-skills-and-runtime-manifest.md
+§ SCRIPT command and input (program from instructions, input on stdin, no skills); agent-runtime-images.md:862-872
+(bash on Linux, PowerShell on Windows); docs/architecture/events-and-triggers.md:146-154 (a schedule trigger
+targets a pipeline); factory/main.ts, the archivist (schedule, pipeline, assign rule, script agent). -->
 
 **What it is.** An *agent* is a worker with a name, standing *instructions*, one environment, a harness, a
 model, and the skills and files it uses. The *harness* is the coding program that runs the agent on a machine:
@@ -89,9 +93,34 @@ model the harness calls, set in the agent's model settings.
 the model gateway when its model settings turn the gateway on (section 7). Work reaches it as sessions (section
 8), most often started by assigning it a work item (section 10).
 
-**In the starter.** The Manager Agent, Engineer Agent lg and Engineer Agent bare run `claude` on
-`claude-opus-5-5`. Engineer Agent md runs `codex` on `gpt-6.1-sol`, and Engineer Agent sm runs `codex` on
-`gpt-6-luna`. Engineer Agent bare takes only the Bootstrap's baseline replays.
+**In the starter.** The Manager Agent and Engineer Agent lg run `claude` on `claude-opus-5-5`. Engineer
+Agent md runs `codex` on `gpt-6.1-sol`, and Engineer Agent sm runs `codex` on `gpt-6-luna`. Work goes to
+Engineer Agent lg first. Engineer Agent sm and md get work only once a person says a kind of work may go
+to them.
+
+**The harnesses.** `harness` is set once, when the agent is created.
+
+| Harness | Runs | Model |
+|---|---|---|
+| `claude` | Claude Code | Yes, from the agent's model settings |
+| `codex` | Codex | Yes, from the agent's model settings |
+| `pi` | The pi coding agent | Yes, from the agent's model settings |
+| `script` | The agent's instructions, as a shell program: Bash on Linux, PowerShell on Windows | No |
+| `custom` | Nothing: the machine runs the customer's own image, and the platform starts no harness | No |
+
+**A `script` agent** is for deterministic work that needs no model judgment: pulling data from Pendo or
+another analytics source into the platform's custom metrics (`orchestra metrics write-value`), joining data
+across systems, a scheduled sync, or a docs archive run. Its instructions are the program. Each turn's text
+reaches the program on its standard input. It starts like any agent:
+
+- a work item assigned to it, by a person or by a workflow rule;
+- a trigger on a connection's events, with the agent as the target;
+- a schedule: a trigger on a 5-field UTC cron makes a work item in a pipeline, and a rule assigns the item
+  to the agent. A schedule trigger targets a pipeline, never an agent directly.
+
+A `script` agent cannot use skills or model settings (the platform refuses both with a 400), and it cannot
+judge, read or write prose the way a model does. A turn runs its whole program again, so the program must be
+safe to run twice. It is billed as an agent: **Settings › Plan & usage** shows the plan.
 
 **Cannot yet.**
 - Change an agent's harness after it is created. Make a new agent instead.
@@ -137,12 +166,24 @@ disks on Windows). -->
 ports, settings and network rules. A *machine* is one live computer made from it, where an agent works. A
 machine carries one agent.
 
-- *Size.* CPU and memory, from a fixed ladder: 0.5, 1, 2, 4, 8, 16 or 32 CPU, with 2 GB of memory per CPU.
-- *Image.* The disk the machine starts from. The stock image is Debian with Node 22, Java 21 and 25, git,
-  Docker with Compose, `gh` and `acli`, and all four harnesses.
+- *Runtime* (`platform.runtime`). `microvm` (the default) or `vm`, with the operating system and the
+  architecture. It is fixed when the environment is created. To change it, make a new environment.
+- *Size.* CPU and memory, with 2 GB of memory per CPU. A `microvm` takes 0.5, 1, 2, 4, 8, 16 or 32 CPU. A
+  Linux `vm` takes 2, 4 or 8 CPU. A Windows `vm` takes 4 or 8 CPU.
+- *Image.* The disk the machine starts from. The stock `microvm` image is Debian with Node 24, Java 21 and
+  25, Python 3, a C and C++ build toolchain, git, `jq`, Docker with Compose and Buildx, the worker and all
+  four harnesses. The agent installs any other tool it needs. The orchestra-fdk skill's
+  `references/environment.md`, section 5, has each operating system's image.
 - *Setup script.* A script that runs once, as root, on each new machine, before the agent arrives and before
-  any code is cloned. Bash on Linux, PowerShell on Windows. At most 64 KiB, stopped after 10 minutes. A failed
-  script fails the machine. Its output is kept as is, so it must never print a secret.
+  any code is cloned. Bash on Linux, PowerShell on Windows. At most 64 KiB. After 10 minutes the worker
+  kills it with every process it started, and the machine fails. A failed script fails the machine. Its
+  output is kept as is, so it must never print a secret. A process the script starts in the background keeps
+  running after the script ends, until the machine stops. Write the script so that it can run again on a
+  new machine, over a `/home` that already has files.
+- *Network edge certificate.* The edge re-signs each HTTPS answer with its own certificate authority. The
+  worker adds it to the machine's trust store, and points `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`,
+  `REQUESTS_CA_BUNDLE` and `GIT_SSL_CAINFO` at its file for the setup script and the harness. A tool with a
+  certificate list of its own, such as Git for Windows, needs that file added.
 - *Settings* (`env`). Plain values set on every machine. They are stored and shown in plain text, so a key
   never goes here (section 6).
 - *Ports.* Each declared port gets a *machine endpoint*, a web address that only signed-in members of the
@@ -151,16 +192,31 @@ machine carries one agent.
 - *Working folder* (`workingDirectory`). Not released yet: a folder where the harness starts every
   conversation. Today the agent clones or uses its code under `/work` in its own first turn, as the
   starter's agents do.
-- *Lifetime.* A conversation lets go of its machine 5 minutes after its last turn, and a machine lives at
-  most 2 hours, unless the environment sets other values.
+- *Lifetime.* Three values in the environment's `provisionSpec`, in seconds:
+  - `ttlAfterIdle`, 300 by default. A conversation lets go of its machine this long after its last turn.
+    The machine then stops within about one more minute. Work the harness itself runs in the background,
+    such as a background shell, holds the machine until it ends.
+  - `keepAliveWhenIdle`, false by default. `true` turns the idle stop off.
+  - `ttl`, 7200 (2 hours) by default. The most a machine lives, counted from its creation, idle, running or
+    stopped. The plan can make it shorter. A turn still running at that time is stopped.
+- *What a stop does.* It depends on where the machine runs:
+  - Hosted Linux, `microvm` and `vm`: the machine is deleted. A `/home` volume stays. The next turn gets a
+    new machine, which runs the setup script again.
+  - Hosted Windows `vm`, and a VM that a Launcher runs: the machine is *parked*. The VM stops and keeps its
+    disk. The next turn, or a new conversation of the same agent, starts the same VM. The setup script does
+    not run again. After `ttl` the machine is deleted, and the next turn gets a new one.
+  - A stop ends every process on the machine. An install the agent left running outside the harness, or one
+    the setup script started, is killed. Run a long install in the turn itself.
+  - The kit cannot declare the three values yet. Set them with `orchestra environments update <slug> --body
+    @timers.json`, where the file holds `{"provisionSpec":{"ttl":<seconds>}}` and the others you change. An
+    apply sends none of the three, so it keeps the values you set.
 
 **How it relates.** An agent names one environment. A change to the image, size, setup script, settings or
 disks reaches only machines made after the change. A change to the network rules is different: it reaches
 running machines too (section 5).
 
 **In the starter.** Four environments: `manager-work-lg` and `engineer-work-lg` at 32 CPU, `engineer-work-md`
-at 16, `engineer-work-sm` at 2. Engineer Agent bare uses `engineer-work-lg` with Engineer Agent lg; each agent
-still gets its own machines. Each uses the stock image, starts Docker in `lib/setup.sh`, and keeps Docker's
+at 16, `engineer-work-sm` at 2. Each uses the stock image, starts Docker in `lib/setup.sh`, and keeps Docker's
 data on its own disk.
 
 **Can.**
@@ -173,6 +229,13 @@ data on its own disk.
   team owns and the Orchestra runtime image as its base, which is handed over by hand.
 - macOS machines that Orchestra launches. A Mac works only as the team's own enrolled machine (section 18).
 - Extra disks on Windows or on an enrolled machine.
+- A launched Windows machine on Windows 11, or on any version other than Windows Server 2025. A customer's
+  Windows image must carry our
+  worker, installed as our Windows runtime assembly installs it (`install-vm-runtime.ps1`, which ends with
+  `orchestra install --role image --yes`). A plain captured Windows VM does not register.
+- Not released yet: a one-command installer that turns a customer's own Windows image into one Orchestra can
+  run. What such an image carries today: the orchestra-fdk skill's `references/environment.md`, "Windows in
+  three stages", stage 2.
 - Not proven yet: the 32 CPU size on production capacity. If an lg machine waits a long time for room, tell the
   Orchestra team.
 
@@ -186,8 +249,8 @@ rules); docs/architecture/egress.md:59 (the machine's shim holds no policy cache
 cli/src/constructs/environment.ts:231 (deny rules default to priority 900), allowAll, denyAll, allow, deny,
 routeModelsViaGateway, bearer, basic, header, inject; cli/templates/bug-fix/image/setup.sh (the Docker start);
 support.atlassian.com/bitbucket-cloud/docs/using-api-tokens (Bearer for the API, Basic with
-x-bitbucket-api-token-auth for git). Starter: the kit branch's cli/templates/engineering-team/README.md
-"Commissioning". -->
+x-bitbucket-api-token-auth for git). Starter: cli/templates/engineering-team/README.md, "Every
+machine". -->
 
 **What it's for.** The agent works as if it had full access. Control lives outside the machine, at the network
 edge: which sites a machine may reach, and which keys are added on the way. The agent never holds those keys.
@@ -204,13 +267,12 @@ unless you set one, so it wins over the open default and over the usual allow ru
 reaches every machine at once, machines already running included, from their next request.
 
 **How it relates.** An allow rule can add a secret to matching requests (section 6). Calls to the Orchestra
-platform itself skip these rules: the agent's role decides them (section 1). So a machine blocked from Bitbucket
-still downloads a file through `orchestra files get-content`.
+platform itself skip these rules: the agent's role decides them (section 1). So a machine blocked from the
+code host still downloads a file through `orchestra files get-content`.
 
-**In the starter.** Every machine is open, and adds the gateway key on the model gateway's host. The Manager
-Agent's machine adds the Bitbucket and Jira tokens. The Engineer Agents' machines deny Bitbucket and the Jira
-site until *commissioning*, when they start real work: then `access: "tokens"` in `main.ts` swaps the deny rules
-for the token rules. Apply that change only when no replay is running, because it reaches running machines.
+**In the starter.** Every machine is open to every host, and adds the gateway key on the model gateway's
+host. The starter connects no code host or tracker. A rule added for one later still adds its key: the open
+default allows a host only when no rule matches it.
 
 **Can.** Deny rules by host, path and method; keys added as `Bearer <secret>`, `Basic <secret>`, the bare
 secret in any header, or a full header recipe; Basic auth formed from a user name and a secret
@@ -235,8 +297,7 @@ edge*.
 **How it relates.** A secret works only through a network rule (section 5). Never put a key in an
 environment's settings or in instructions: the machine's processes read every setting.
 
-**In the starter.** The gateway key's secret, and once connected, the Bitbucket token (twice: once for the API,
-once for git) and the Jira token.
+**In the starter.** The gateway key's secret only.
 
 **Can.** A secret's value comes from a shell variable at apply (`fromEnv`), from a hidden prompt at apply on a
 terminal (`fromCommandLine`), or from a gateway key the platform mints (`fromGatewayKey`).
@@ -265,7 +326,10 @@ network rules carry the option (sections 2 and 5).
   are plain text.
 - *Codex.* A personal access token, made by a ChatGPT Business or Enterprise member, or a separate ChatGPT
   sign-in kept on a `/home` volume that every machine using it shares. A Codex sign-in stays off the model
-  gateway, which refuses its requests with `model_not_found`.
+  gateway, which refuses its requests with `model_not_found`. The Codex sign-in goes in the
+  `ORCHESTRA_WORKER_CODEX_` variables in the environment's `env`, in plain text. The worker writes them into
+  Codex's own sign-in file and passes none of them on (the orchestra-fdk skill's `references/authoring.md`,
+  "The subscription variables").
 
 **An Orchestra account, through the model gateway.** The model gateway is a hosted service at
 `models.orchestraworks.ai`. One endpoint reaches OpenAI, Anthropic and open models. A *gateway key* is a key
@@ -288,13 +352,11 @@ subscription or its own key turns it off. For plan questions, send the person to
 in the console.
 
 **In the starter.** The code as written uses the model gateway: one key, `model-gateway`, and the gateway rule
-on every environment. A subscription or an own key needs an edit, as the orchestra-fdk skill's step 6 says.
+on every environment. A subscription or an own key needs an edit, as the orchestra-fdk skill's phase 2 says.
 
 **Cannot yet.**
 - A gateway route without the rule on the environment. An environment declared in code keeps only what it
   declares, so the rule must be on every environment.
-- Not released yet: the worker settings that put a Codex sign-in on a machine. Until they are, a `codex`
-  agent uses the model gateway or an OpenAI API key.
 
 ## 8. Session and turn
 
@@ -315,7 +377,7 @@ message. Interrupt stops the running turn, not the conversation.
 **How it relates.** Assigning an agent a work item starts its session on the item, or wakes its open one
 (section 10). A trigger can also start one (section 12). Each turn runs on a machine (section 4).
 
-**In the starter.** Assigning "Set up" to the Manager Agent starts its session. `orchestra sessions wait <session id>` waits
+**In the starter.** Assigning an item to the Manager Agent starts its session. `orchestra sessions wait <session id>` waits
 for the turn to end. The console shows the same session.
 
 ## 9. Pipeline and stage
@@ -335,8 +397,9 @@ conditions an item must meet to enter it (`requires`), such as a passed check.
 **How it relates.** Work items live in pipelines (section 10). Workflow rules act on one pipeline's items
 (section 11). A trigger can create items in a pipeline (section 12).
 
-**In the starter.** Four pipelines: Onboarding (`onbd`), Bugs (`bug`), Features (`feat`) and Support (`supp`).
-An item may move from any stage to any other, for now.
+**In the starter.** Three pipelines: Bugs (`bug`), Features (`feat`) and Support (`supp`). An item may move
+from any stage to any other, for now. An agent moves an item to its review stage when it needs a person: In
+review in Bugs and Features, Waiting on requester in Support.
 
 **Rule.** The platform refuses to delete a pipeline that still has open items, or that a trigger or workflow
 names. Close or move the items and remove those first.
@@ -361,8 +424,8 @@ and a stage's conditions can read them.
 **How it relates.** An item's sessions are listed on it (section 8). An agent can be asked about an item without
 taking it over (`work-items message`). Rules and judges act on items (section 11).
 
-**In the starter.** The Set up and Bootstrap items in Onboarding. In the Bootstrap, the Manager Agent creates
-Replay items and assigns them to Engineer Agent lg and Engineer Agent bare.
+**In the starter.** A person creates an item and assigns it to the Manager Agent. The Manager Agent triages
+it, puts the code bundle's file id in it, and assigns it to an Engineer Agent.
 
 **Cannot yet.** Declare items in the factory code. Create them with `orchestra work-items create`.
 
@@ -404,7 +467,7 @@ conversation.
 **How it relates.** It listens through a connection (section 17), and makes items (section 10) or sessions
 (section 8).
 
-**In the starter.** None yet. A tracker listener comes after commissioning.
+**In the starter.** None yet. A tracker listener, which turns each new issue into an item, comes later.
 
 **Cannot yet.** A tracker board that sends no events makes no items. Confirm events reach the platform before
 switching a listener on.
@@ -431,8 +494,9 @@ Not released yet: managed skills that a new agent's list carries by default (`in
 carry work between agents.
 
 **In the starter.** The Manager Agent uploads each git
-bundle as a file, and the Engineer Agent answers with a patch file. The Bootstrap writes a codebase skill, and
-commissioning adds it to the Engineer Agents.
+bundle as a file, and the Engineer Agent answers with a patch file. The Manager Agent makes a codebase skill
+and names its slug. The team names that skill in `main.ts` for the Engineer Agents, or the next apply takes
+it away.
 
 ## 14. Plan
 
@@ -497,6 +561,8 @@ each part at length. What follows is only what a reader needs to run a command s
 - **Nouns and verbs.** `orchestra <noun> <verb>`. Nouns match the API's paths, such as `agents`, `work-items`
   and `sessions`. The usual verbs are `list`, `get`, `create`, `update` and `delete`; a command keeps its own
   verb, such as `work-items assign`. `orchestra sessions wait <session id>` waits for a turn to end.
+  `orchestra sessions tail <session id>` prints each item of the session as it is saved, and
+  `--until-settled` stops it when the turn ends.
 - **Output.** `--output json` prints the API's answer as it is on stdout, with key values masked. Read the field
   you need from its place:
   - A list answers a page: `{"data":[…],"page":1,"limit":20,"total":42}`. The rows are in `data`.
@@ -554,18 +620,27 @@ the kit's reference, `docs/REFERENCE.md`, section 7, "Connections, triggers, and
 
 - Cannot yet: Bitbucket OAuth without an OAuth consumer the organization registers first.
 - Cannot yet: git over `bitbucket.org` through the Bitbucket connection. It adds its credential only on
-  `api.bitbucket.org`, so git still needs the token rule.
-- In the starter: none. For the first run, personal tokens are enough. Connections and listeners come later.
+  `api.bitbucket.org`, so git needs a Secret and its own rule on `bitbucket.org`.
+- In the starter: none. The first run needs no integration. The orchestra-fdk skill's
+  `references/integrations/` files say how to add each one.
 
 ## 18. The team's own machines and network
 
 <!-- Sources, on develop at 19459f9ebb: docs/architecture/compute-plane.md:134-166 (an enrolled machine: no
 network rules; which environments go there is the operator's choice); docs/architecture/api.md:1191 (enrolled
 kind); cli/src/constructs/environment.ts (the kit always sends provisionSpec, so it cannot declare an enrolled
-environment); no Launcher code or document on develop; docs/architecture/local-agent-runtime.md (the local
+environment); on this branch: cli/src/constructs/compute-provider.ts and environment.ts (`computeProvider`),
+docs/architecture/compute-plane.md:529-600 (three Launcher targets, all amd64; allow-only network rules; no
+edge proxy in front of a Launcher machine; the gallery and runtime images), launcher/README.md and
+launcher/deploy/azure/main.bicep (the Azure template, the public Launcher image); docs/architecture/local-agent-runtime.md (the local
 environment, its outpost kinds; no privileged machine launch); on develop at 09a3758669,
 local/launch/modelkey.go (model key carriers per harness, the gateway address variable) and
-worker/facts/families.json (how each harness takes the gateway address). -->
+worker/facts/families.json (how each harness takes the gateway address); on develop at f62fad1481,
+agents/runtime/assembly/common/placeholder-env (the images' placeholder ANTHROPIC_API_KEY),
+LauncherProperties.kt (the gallery images at Versions/latest), launcher/config/config.go (Dsv5 default);
+worker/facts/families.json (the ORCHESTRA_WORKER_ names), worker/service/manager_windows.go (SfdkWorker),
+infra/packer/azure-windows-runtime.pkr.hcl (the startup task), launcher/cloud/cloud.go (the VM tags);
+the proven list is the test run of 2026-10-05. -->
 
 - Can: enroll the team's own Mac, Linux or Windows machine with the worker (`orchestra outpost`, `orchestra worker
   enroll`). It runs agents, and its ports can still be shown as machine endpoints.
@@ -573,8 +648,58 @@ worker/facts/families.json (how each harness takes the gateway address). -->
   token rules do not work there, and the agent needs its own model sign-in and tokens on that machine. Which
   environments go to enrolled machines is set by the Orchestra team, not in code, and the kit cannot declare an
   enrolled environment.
-- Cannot yet: reach a private network (a VPN or the team's own cloud) from Orchestra's machines.
-- Cannot yet: the *Launcher*, which would run machines inside the team's own cloud, and Azure.
+- Cannot yet: reach a private network (a VPN or the team's own cloud) from Orchestra's hosted machines. A
+  Launcher (below) runs the machines inside the team's own Azure network instead.
+- Can: the *Launcher* on Azure. It is a program the team runs in their own Azure subscription, from our
+  public image `orchestraworks.azurecr.io/launcher:0.1.0` and the template in `launcher/deploy/azure`. It
+  starts the machines of every environment that names its record. Declare the record with `ComputeProvider`
+  (its `azure` block names the subscriptions and, for pods, the AKS cluster's OIDC issuer), and name it in
+  the environment's `computeProvider`. It runs three kinds of machine, all amd64:
+  - `linux-vm`, for an environment with `{ os: "linux", runtime: "vm" }`: an Azure VM, parked when idle;
+  - `windows-vm`, for `{ os: "windows", runtime: "vm" }`: an Azure Windows VM, parked when idle;
+  - `kata-pod`, for `{ os: "linux", runtime: "microvm" }`: a Kata pod on the team's AKS cluster, deleted
+    when idle.
+- Cannot yet, on a Launcher machine: a key added at the edge. No network edge of ours stands in front of
+  it, so its network rules may only allow. Not released yet: our network edge for machines in the team's
+  own network.
+- Credentials on a Launcher machine are the team's to manage on the machine. The platform delivers none.
+  - The model sign-in goes in the worker service's own environment: `ORCHESTRA_WORKER_CLAUDE_OAUTH_TOKEN`
+    for a Claude subscription token; `ANTHROPIC_API_KEY` for an Anthropic API key or an Orchestra gateway
+    key, which replaces our image's placeholder; `ORCHESTRA_WORKER_OPENAI_API_KEY` or
+    `ORCHESTRA_WORKER_CODEX_PERSONAL_ACCESS_TOKEN` for `codex`. On Windows, that is the `SfdkWorker`
+    service's `Environment` registry value.
+  - With a gateway key, keep the agent's model gateway on. The platform sets the gateway address.
+  - Other tokens, such as git, a package feed or an Azure DevOps personal access token: the team's own boot
+    step sets them, for example from their Key Vault with a managed identity on the VM.
+  - The worker reads its environment when its service starts. The boot step runs before the worker starts,
+    or restarts the worker service after. On our Windows image, the startup task `orchestra-azure-userdata`
+    starts `SfdkWorker`.
+  - Never put a token in `provisionSpec.env` (`env` in the kit). The platform stores it, an environment
+    read returns it, and it travels in plain text in the VM's startup data.
+  - The Launcher attaches no managed identity to the VMs it creates. The tags `orchestra-launcher` (the
+    record's id) and `orchestra-machine` (the machine's id) let the team's automation find them. Not
+    released yet: a managed identity attached when the Launcher creates a VM.
+- Proven on Orchestra's test environment with a new Launcher 0.1.0, a team's own Windows image and the
+  `Dsv6` size family:
+  - A `claude` turn ran. It reached the model through an Orchestra gateway key, with no network edge.
+  - The worker registered about 1 minute 46 seconds after the VM was created.
+  - The first turn included a harness install of about 60 seconds, on an image without the harness.
+  - A parked VM resumed, the same VM, in about 2 minutes.
+  - With `ttlAfterIdle` at 300 seconds, the VM parked about 8 minutes after the last turn, not the 6 that
+    section 4 gives.
+  - Standby capacity gave a new conversation a ready machine, and its turn started in 3.5 seconds.
+- Can: our public Azure community gallery images, version 0.0.136, both Gen2, on SCSI or NVMe sizes:
+  - `/CommunityGalleries/orchestraworks-881a796f-0a84-4be1-af80-0a38564a406a/Images/runtime-win/Versions/0.0.136`
+  - `/CommunityGalleries/orchestraworks-881a796f-0a84-4be1-af80-0a38564a406a/Images/runtime-linux/Versions/0.0.136`
+
+  A Launcher VM environment that names no image boots the matching one at `Versions/latest`. Name the
+  `0.0.136` id as the environment's image to pin it.
+- The Launcher's VM targets use the `Dsv5` size family by default. A subscription with no `Dsv5` capacity
+  names a family it has, such as `Dsv4` or `Dsv6`, as `vmSizeFamily` on each VM target in the Launcher's
+  settings (`targets` in the deploy template). The Launcher README lists the families it accepts.
+- Not released yet: the Launcher on AWS.
+- Can: when a Launcher does not work, run `orchestra compute-providers check <id-or-slug>` first. It shows
+  whether the Launcher polls, its protocol, its health and why each target failed, and exits 1 on a failure.
 - Can: the local environment (`orchestra local`), a local copy of the platform on the developer's own
   computer, stands up an environment and proves it in three milestones: the whole stack up, validation the
   way a person uses it, then the tests; one agent turn runs after validation. It starts machines whatever network