@everfir/az8-cli 0.2.0-preview.4 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,39 @@
 All notable AZ8 CLI changes are recorded here. The CLI package has its own linear version sequence;
 it does not inherit the Web application or monorepo root version.
 
+## 0.2.0 - 2026-07-22
+
+First stable semantic Project Canvas client for agents.
+
+### Added
+
+- Project management, persistent NDJSON Canvas collaboration, one-shot compatibility wrappers,
+  semantic note and hierarchy authoring, Core Node generation, Workflow observation, and safe local
+  media upload/download.
+- A runtime-discoverable built-in agent Skill covering platform concepts, capability discovery,
+  persistent request/process lifecycle, generation sequencing, recovery, and prohibited bypasses.
+
+### Stability contract
+
+- Public Canvas writes remain available only through semantic Operations and internal Commands;
+  callers cannot write raw backend, Yjs, Core Node, or Project Content data.
+- Protocol `1.0`, ordered request/Receipt behavior, authenticated presence, no automatic write retry,
+  and explicit deferred scopes form the initial stable compatibility boundary.
+- 3D World, Asset aggregate management, automatic layout, media replacement, and batch upload remain
+  intentionally deferred rather than partially exposed.
+
+## 0.2.0-preview.5 - 2026-07-22
+
+### Changed
+
+- Canvas awareness names now preserve the authenticated user's Web-equivalent display name first
+  and append a CLI-owned parenthesized client suffix, defaulting to `(cli)`.
+- `--client-name <suffix>` may override the client suffix for persistent and one-shot lifecycles,
+  but caller-provided parentheses are rejected so presence cannot obscure the name boundary.
+- CLI attention awareness now publishes only the semantic cursor and omits selection bounds.
+- `startGeneration` now carries valid Workflow execution-time estimates into the View Node's
+  generation history as Web-compatible median and maximum completion timestamps.
+
 ## 0.2.0-preview.4 - 2026-07-22
 
 ### Changed

package/README.md

@@ -3,12 +3,12 @@
 AZ8 CLI is a semantic Project Canvas client for agents. It does not import Web implementation code
 and does not expose raw backend, Yjs, or document mutation commands.
 
-## Install the internal preview
+## Install
 
-AZ8 CLI requires Node.js 20 or newer. Install the preview channel from the configured npm registry:
+AZ8 CLI requires Node.js 20 or newer. Install the stable channel from the configured npm registry:
 
 ```bash
-npm install --global @everfir/az8-cli@preview
+npm install --global @everfir/az8-cli
 az8 --version
 az8 help
 az8 guide
@@ -17,12 +17,12 @@ az8 guide
 For a supplied release artifact, install the exact immutable tarball instead:
 
 ```bash
-npm install --global ./everfir-az8-cli-0.2.0-preview.4.tgz
+npm install --global ./everfir-az8-cli-0.2.0.tgz
 az8 --version
 ```
 
-`az8 --version` must report the version selected for the agent environment. Preview releases do not
-replace npm's `latest` channel. Pin an exact version or tarball for reproducible agent runs.
+`az8 --version` must report the version selected for the agent environment. Pin an exact version or
+tarball for reproducible agent runs.
 
 ## Built-in agent Skill
 
@@ -124,7 +124,10 @@ az8 canvas operation <project-id> startGeneration \
 Operation input is one JSON object supplied by exactly one of `--input-stdin`, `--input-file`, or
 `--input-json`; omitted input defaults to `{}`. Input is limited to one MiB. `--timeout-ms` controls
 the same Operation acknowledgement or domain observation window as persistent stdio, and
-`--client-name` changes only the ephemeral awareness display name.
+`--client-name` changes only the parenthesized client suffix of the ephemeral awareness name. The
+authenticated display name always remains first: the default is `<current user> (cli)`, while
+`--client-name codex` produces `<current user> (codex)`. Parentheses are owned by the CLI and are
+rejected in caller-provided suffixes.
 
 Success writes one `az8.canvas.one-shot.v1` JSON document to stdout and exits `0`. A definitive
 input, validation, permission, or business failure writes structured JSON to stderr and exits `1`.
@@ -216,7 +219,7 @@ Canvas query, keep capability discovery and all ordered Operations in the same l
 it down only after the authoring task is complete.
 
 ```bash
-az8 canvas open <project-id> --write --format ndjson
+az8 canvas open <project-id> --write --format ndjson [--client-name codex]
 ```
 
 The process writes one `hello` frame, then waits for an `initialize` request on stdin:
@@ -226,9 +229,12 @@ The process writes one `hello` frame, then waits for an `initialize` request on
 ```
 
 Before readiness the client hydrates the current authenticated account profile. Canvas Operations use
-that immutable account id and display name for persisted creator data. The `client.name` supplied by
-`initialize` is awareness-only and cannot impersonate or rename the persisted author. Project owner
-metadata is likewise never treated as the current actor on shared Projects.
+that immutable account id and display name for persisted creator data. Awareness always displays the
+authenticated name first and a CLI-owned parenthesized client suffix second. The default suffix is
+`cli`; startup `--client-name` overrides it, otherwise `initialize.client.name` may provide it.
+Caller suffixes cannot contain parentheses. This name is awareness-only and cannot impersonate or
+rename the persisted author. The CLI publishes its Attention Cursor but deliberately omits selection
+bounds. Project owner metadata is likewise never treated as the current actor on shared Projects.
 
 After `ready`, requests use `query`, `configureObservations`, `operation`, `reconnect`, or `shutdown`.
 The public authoring surface includes the note lifecycle, non-World View Node hierarchy operations,
@@ -311,6 +317,9 @@ explicitly submitting the same input. An uncertain backend or collaboration outc
 are acknowledged. It first estimates the exact current Draft inputs, then materializes literal Core
 Nodes and starts with the estimate's cost and Definition version. This estimate is internal: there is
 no public estimate Operation, balance query, caller-supplied expected cost, or second confirmation.
+When the estimate includes execution-time ranges, the generation history records Web-compatible
+median and maximum completion timestamps from the pre-submit time so Web can render the same expected
+generation duration for a CLI-started Run.
 Waiting for a terminal result is deliberately a separate operation. Generation is a non-undoable
 Canvas History barrier. The CLI does not expose Assets, arbitrary Core Node creation, or 3D World
 operations.
@@ -340,9 +349,9 @@ Every output frame has `protocolVersion`, monotonic `streamSeq`, `type`, `payloa
 after collaboration-server acknowledgement. A timeout or lost acknowledgement is indeterminate,
 moves the Canvas context offline, and requires explicit reconnect and inspection before any retry.
 
-## Preview acceptance checklist
+## Release acceptance checklist
 
-Before distributing a preview tarball, verify all of the following from its clean installation, not
+Before distributing a release tarball, verify all of the following from its clean installation, not
 from TypeScript source:
 
 1. `az8 --version` matches the immutable package version; `az8 help` lists the built-in guide,

package/RELEASE.md

@@ -1,7 +1,7 @@
-# AZ8 CLI preview release
+# AZ8 CLI release
 
-This package is an internal preview. `preview` is the release channel; it must not replace npm's
-`latest` tag until a separate stability decision is made.
+`latest` is the stable release channel. Preview versions remain immutable historical artifacts and
+must not be republished or renamed into a stable version.
 
 ## Release gate
 
@@ -12,9 +12,11 @@ pnpm release:az8-cli
 pnpm release:pack:az8-cli
 ```
 
-The first command runs CLI tests, type checking, builds a real npm tarball, installs that tarball in
-a clean temporary directory, and verifies the installed `az8` executable. The second preserves the
-verified tarball and clean installation under `tmp/az8-cli-release/` for live acceptance.
+The first command rebuilds the CLI's classified workspace dependencies, runs CLI tests and type
+checking, builds a real npm tarball, installs that tarball in a clean temporary directory, and
+verifies the installed `az8` executable. The second repeats the dependency-aware prepack and
+preserves the verified tarball and clean installation under `tmp/az8-cli-release/` for live
+acceptance. Never bundle against pre-existing workspace `dist/` output.
 
 Run the live smoke only against the test environment. It creates one Project unless `--project-id`
 reuses an explicit test Project, starts one image generation, and uploads one tiny PNG:
@@ -28,28 +30,45 @@ node apps/az8-cli/scripts/smoke-test.js \
 The smoke report must show authenticated persistent stdio, ordered shutdown, a completed Workflow
 Run whose target resolves its output Core Node, upload replay without another transfer, and matching
 download SHA-256. `--skip-generation` is only for diagnosing unrelated media or transport checks;
-it cannot satisfy full release acceptance.
+it cannot satisfy full release acceptance. When the release changes generation-time projection,
+select a timing-enabled test Definition and require its persisted Web estimate:
+
+```bash
+node apps/az8-cli/scripts/smoke-test.js \
+  --bin ./tmp/az8-cli-release/install/node_modules/.bin/az8 \
+  --env-file ./.env.local \
+  --generation-definition-id <timing-enabled-test-definition-id> \
+  --require-generation-estimate
+```
 
 Before publishing, also run the test-environment acceptance checklist in the packaged README and the
 repository-wide `pnpm verify`. Publishing is an external action and requires explicit operator
 authorization:
 
 ```bash
-npm publish ./tmp/az8-cli-release/everfir-az8-cli-0.2.0-preview.4.tgz --tag preview
+npm publish ./tmp/az8-cli-release/everfir-az8-cli-0.2.0.tgz --tag latest
 npm view @everfir/az8-cli dist-tags versions --json
 ```
 
-Do not pass `--tag latest`. Do not publish from an unverified source directory.
+Publish only the exact retained tarball whose SHA-512 appears in the stable release verification
+record. Do not publish from an unverified source directory. If the obsolete misspelled `prewview`
+tag still exists after stable publication, remove that tag without unpublishing its immutable
+version:
+
+```bash
+npm dist-tag rm @everfir/az8-cli prewview
+npm view @everfir/az8-cli dist-tags --json
+```
 
 ## Rollback
 
-Published versions are immutable. Rollback moves the `preview` tag to a previously verified version
+Published versions are immutable. Rollback moves `latest` to a previously verified stable version
 instead of unpublishing or overwriting a package:
 
 ```bash
-npm dist-tag add @everfir/az8-cli@<previous-version> preview
+npm dist-tag add @everfir/az8-cli@<previous-stable-version> latest
 npm view @everfir/az8-cli dist-tags --json
-npm install --global @everfir/az8-cli@preview
+npm install --global @everfir/az8-cli
 az8 --version
 ```
 

package/dist/main.js

@@ -4527,6 +4527,27 @@ var require_src2 = __commonJS({
   }
 });
 
+// src/canvas-awareness.ts
+var DEFAULT_CANVAS_CLIENT_NAME = "cli";
+function normalizeCanvasClientName(value) {
+  const name = (value ?? DEFAULT_CANVAS_CLIENT_NAME).trim();
+  if (!name) {
+    throw invalidClientName("Canvas client name must not be empty.");
+  }
+  if (/[()]/.test(name)) {
+    throw invalidClientName(
+      "Canvas client name must not contain parentheses; AZ8 adds the required (name) suffix."
+    );
+  }
+  return name;
+}
+function formatCanvasAwarenessName(actorDisplayName, clientName) {
+  return `${actorDisplayName} (${normalizeCanvasClientName(clientName)})`;
+}
+function invalidClientName(message) {
+  return Object.assign(new Error(message), { code: "invalid-client-name" });
+}
+
 // ../../node_modules/.pnpm/lib0@0.2.117/node_modules/lib0/math.js
 var floor = Math.floor;
 var abs = Math.abs;
@@ -13579,10 +13600,7 @@ var HocuspocusProjectCanvasDocumentImplementation = class {
     this.setAwarenessFields({
       cursor: input.cursor,
       updatedAt: Date.now(),
-      view: {
-        kind: "canvas",
-        ...input.selection ? { selection: input.selection } : {}
-      }
+      view: { kind: "canvas" }
     });
   }
   getAwareness() {
@@ -15916,6 +15934,7 @@ var CoreNodeCreativeLoop = class {
         prepared,
         timeoutMs
       });
+      const submittedAt = this.context.now();
       const run = await this.systems.workflowRuntime.startRun({
         definitionId: definition.id,
         expectedCost: estimate.estimatedCost,
@@ -15933,11 +15952,13 @@ var CoreNodeCreativeLoop = class {
         runtime: {
           expectedCost: estimate.estimatedCost,
           expectedDefinitionVersion: estimate.definitionVersion,
+          ...createEstimatedCompletionTimes(estimate, submittedAt),
           instanceIds: [run.id],
           materializedInputs: materialized.materializedInputs,
           originClientId: this.context.clientInstanceId,
-          submittedAt: timestamp
-        }
+          submittedAt
+        },
+        updatedAt: timestamp
       };
       const { creationIntent: _creationIntent, ...data } = asRecord3(target.data);
       const after = {
@@ -16224,6 +16245,28 @@ var CoreNodeCreativeLoop = class {
     };
   }
 };
+function createEstimatedCompletionTimes(estimate, submittedAt) {
+  const ranges = estimate.executionTimeRanges;
+  if (!ranges?.length)
+    return {};
+  let medianSeconds = 0;
+  let maxSeconds = 0;
+  let validRangeCount = 0;
+  for (const range of ranges) {
+    if (!Number.isFinite(range.medianSeconds) || range.medianSeconds < 0 || !Number.isFinite(range.maxSeconds) || range.maxSeconds < 0) {
+      continue;
+    }
+    medianSeconds += range.medianSeconds;
+    maxSeconds += range.maxSeconds;
+    validRangeCount += 1;
+  }
+  if (validRangeCount === 0)
+    return {};
+  return {
+    estimatedMaxCompletionAt: submittedAt + maxSeconds * 1e3,
+    estimatedMedianCompletionAt: submittedAt + medianSeconds * 1e3
+  };
+}
 function attention(viewNodeId, result3) {
   return { attention: { kind: "view-nodes", viewNodeIds: [viewNodeId] }, result: result3 };
 }
@@ -22727,9 +22770,26 @@ function mapWorkflowRunEstimate(value, definitionId) {
     canAfford: value.can_afford,
     definitionId: value.definition_id,
     definitionVersion: value.definition_version,
-    estimatedCost: value.estimated_cost
+    estimatedCost: value.estimated_cost,
+    executionTimeRanges: (value.execution_time_ranges ?? []).flatMap((item) => {
+      const range = item.range;
+      if (!range || !isNonNegativeFinite(range.minSeconds) || !isNonNegativeFinite(range.maxSeconds) || !isNonNegativeFinite(range.medianSeconds) || !isNonNegativeFinite(range.sampleCount)) {
+        return [];
+      }
+      return [
+        {
+          maxSeconds: range.maxSeconds,
+          medianSeconds: range.medianSeconds,
+          minSeconds: range.minSeconds,
+          sampleCount: range.sampleCount
+        }
+      ];
+    })
   };
 }
+function isNonNegativeFinite(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
 function mapWorkflowDefinition(value) {
   if (!value.id || !value.name || typeof value.version !== "number") {
     throw new Error("Workflow Runtime returned an invalid Definition.");
@@ -22903,7 +22963,8 @@ var CanvasSession = class {
   projectionRevision = 0;
   actorId = null;
   health;
-  async connect(displayName, onState) {
+  async connect(clientName, onState) {
+    const normalizedClientName = normalizeCanvasClientName(clientName);
     this.closeContext();
     this.transition("authenticating", onState);
     this.health.connectionAttempts += 1;
@@ -22927,7 +22988,10 @@ var CanvasSession = class {
     });
     this.document = document2;
     try {
-      document2.setIdentity({ accountId: actor.accountId, displayName });
+      document2.setIdentity({
+        accountId: actor.accountId,
+        displayName: formatCanvasAwarenessName(actor.displayName, normalizedClientName)
+      });
       this.transition("hydrating", onState);
       const foundationData = this.dependencies.foundationData ?? createAz8FoundationDataSystem(this.config);
       const projectContent = this.dependencies.projectContent ?? createAz8ProjectContentSystem(this.config);
@@ -23037,8 +23101,7 @@ var CanvasSession = class {
   }
   publishAttentionBounds(bounds) {
     this.requireDocument().setAttention({
-      cursor: { x: bounds.x + bounds.width + 24, y: bounds.y + bounds.height / 2 },
-      selection: bounds
+      cursor: { x: bounds.x + bounds.width + 24, y: bounds.y + bounds.height / 2 }
     });
   }
   closeContext() {
@@ -23379,18 +23442,20 @@ function requirePositiveInteger(value, field) {
 
 // src/canvas-protocol-server.ts
 var CanvasProtocolServer = class {
-  constructor(config, projectId, output, session) {
+  constructor(config, projectId, output, session, options = {}) {
     this.projectId = projectId;
     this.output = output;
+    this.options = options;
     this.client = new CanvasClient(config, projectId, session);
   }
   projectId;
   output;
+  options;
   client;
   initialized = false;
   shuttingDown = false;
   shutdownFinalized = false;
-  displayName = "AZ8 CLI";
+  clientName = "cli";
   observationPreset = "compact";
   observationInclude = /* @__PURE__ */ new Set();
   recordedRequests = /* @__PURE__ */ new Map();
@@ -23533,8 +23598,11 @@ var CanvasProtocolServer = class {
         "initialize projectId does not match canvas open."
       );
     }
+    const clientName = normalizeCanvasClientName(
+      this.options.clientName ?? request.payload.client?.name
+    );
     this.initialized = true;
-    this.displayName = request.payload.client?.name ?? "AZ8 CLI";
+    this.clientName = clientName;
     this.observationPreset = request.payload.observationPreset ?? "compact";
     this.unsubscribeObservation = this.session.subscribe((observation) => {
       const category = observation.kind === "workflow" ? "workflow" : "canvas";
@@ -23558,7 +23626,7 @@ var CanvasProtocolServer = class {
   }
   async connect(requestId) {
     try {
-      await this.client.connect(this.displayName, (state) => {
+      await this.client.connect(this.clientName, (state) => {
         void this.output.emitMandatory({ payload: { state }, requestId, type: "lifecycle" });
       });
     } catch (error) {
@@ -23936,7 +24004,7 @@ async function runCanvasOneShot(config, command, dependencies = {}) {
   try {
     assertProcessIndependent(command);
     client = dependencies.clientFactory?.(config, command.projectId) ?? new CanvasClient(config, command.projectId);
-    await client.connect(command.clientName ?? "AZ8 CLI one-shot");
+    await client.connect(normalizeCanvasClientName(command.clientName));
     if (command.kind === "query") {
       return {
         exitCode: 0,
@@ -24159,7 +24227,7 @@ async function runCanvasMediaDownload(config, command, dependencies = {}) {
   try {
     client = dependencies.mediaDownloadClientFactory?.(config, command.projectId) ?? new CanvasClient(config, command.projectId);
     try {
-      await client.connect(command.clientName ?? "AZ8 CLI media download");
+      await client.connect(normalizeCanvasClientName(command.clientName));
     } catch {
       throw new MediaDownloadError(
         "canvas-connection-failed",
@@ -25029,7 +25097,7 @@ function projectHelpOutput() {
 function canvasHelpOutput() {
   return [
     "Canvas:",
-    "  az8 canvas open <project-id> --write --format ndjson",
+    "  az8 canvas open <project-id> --write --format ndjson [--client-name <suffix>]",
     "  az8 canvas inspect <project-id>    Print the latest persisted snapshot as JSON",
     "  az8 canvas upload <project-id> --file <path> --idempotency-key <key>",
     "  az8 canvas download <project-id> (--view-node-id <id> | --core-node-id <id>) --output <path>",
@@ -25042,7 +25110,7 @@ function canvasHelpOutput() {
     "  --input-json <json>              Read one inline JSON object",
     "  --request-id <id>                Set the Operation Receipt request ID",
     "  --timeout-ms <ms>                Set the operation acknowledgement timeout",
-    "  --client-name <name>             Set the ephemeral awareness display name",
+    "  --client-name <suffix>           Set the parenthesized awareness client suffix",
     "",
     "One-shot query options:",
     "  --view-node-id <id>              Select one View Node for canvas.detail",
@@ -25235,7 +25303,15 @@ async function runPersistentCanvas(args2) {
   });
   try {
     const config = await resolveCliConfig(args2, {});
-    server = new CanvasProtocolServer(config, projectId, output);
+    const requestedClientName = readOption3(args2, "--client-name");
+    const clientName = requestedClientName ? normalizeCanvasClientName(requestedClientName) : void 0;
+    server = new CanvasProtocolServer(
+      config,
+      projectId,
+      output,
+      void 0,
+      clientName ? { clientName } : {}
+    );
     const shutdownOnSignal = (signal) => {
       void server?.shutdownFromControl(signal.toLowerCase()).finally(() => process.stdin.destroy());
     };
@@ -25252,7 +25328,10 @@ async function runPersistentCanvas(args2) {
 }
 function readOption3(args2, name) {
   const index = args2.indexOf(name);
-  return index >= 0 ? args2[index + 1] : void 0;
+  if (index < 0) return void 0;
+  const value = args2[index + 1];
+  if (!value || value.startsWith("--")) throw new Error(`${name} requires a value.`);
+  return value;
 }
 function safeDiagnostic(error) {
   const message = error instanceof Error ? error.message : "Persistent Canvas client failed.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everfir/az8-cli",
-  "version": "0.2.0-preview.4",
+  "version": "0.2.0",
   "description": "Semantic Project Canvas client for AZ8 Studio agents.",
   "license": "UNLICENSED",
   "type": "module",
@@ -16,20 +16,21 @@
   "main": "./dist/main.js",
   "publishConfig": {
     "access": "public",
-    "tag": "preview"
+    "tag": "latest"
   },
   "scripts": {
-    "build": "rm -rf dist && esbuild src/main.ts --bundle --platform=node --format=esm --target=node20 --banner:js='import { createRequire } from \"node:module\"; const require = createRequire(import.meta.url);' --outfile=dist/main.js",
+    "build": "pnpm build:dependencies && rm -rf dist && esbuild src/main.ts --bundle --platform=node --format=esm --target=node20 --banner:js='import { createRequire } from \"node:module\"; const require = createRequire(import.meta.url);' --outfile=dist/main.js",
+    "build:dependencies": "pnpm --filter @everfir/az8-cli^... build",
     "dev": "tsx src/main.ts",
     "start": "node dist/main.js",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "biome check .",
     "prepack": "pnpm build",
     "prepublishOnly": "pnpm release:check",
-    "release:check": "pnpm test && pnpm typecheck && node scripts/verify-package.js",
+    "release:check": "pnpm build:dependencies && pnpm test && pnpm typecheck && node scripts/verify-package.js",
     "release:pack": "node scripts/verify-package.js --output-dir ../../tmp/az8-cli-release --keep-install",
     "release:smoke": "node scripts/smoke-test.js",
-    "test": "tsx --tsconfig tsconfig.test.json --test src/**/*.test.ts"
+    "test": "tsx --tsconfig tsconfig.test.json --test src/**/*.test.ts && node --test scripts/*.test.js"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",

package/skills/az8-cli/SKILL.md

@@ -46,8 +46,10 @@ capabilities instead of guessing operation names or input shapes.
   outcome, revisions, and optional usage. It is not Canvas History.
 - **History** contains reversible local interactions. Only Operations advertised as `undoable`
   participate. A generation start is a History barrier and is not undone by `undo`.
-- **Awareness** is ephemeral presence, client name, and Attention Cursor information. It never
-  grants authority, changes persisted authorship, or proves a business result.
+- **Awareness** is ephemeral presence, client suffix, and Attention Cursor information. The visible
+  name is always `<authenticated display name> (<client suffix>)`; the default suffix is `cli`.
+  CLI awareness does not publish selection bounds. Awareness never grants authority, changes
+  persisted authorship, or proves a business result.
 - **Actor** is the authenticated account from `AZ8_TOKEN`. A client or awareness name cannot
   impersonate another author.
 
@@ -131,6 +133,10 @@ and Operations, observe concurrent changes, and shut it down only after the Canv
 az8 canvas open <project-id> --write --format ndjson
 ```
 
+Use `--client-name <suffix>` only when a more specific CLI presence label helps collaborators. The
+CLI owns the surrounding parentheses, rejects parentheses in the supplied suffix, and always keeps
+the authenticated user display name first.
+
 1. Continuously drain stdout; it is an ordered NDJSON protocol stream and may apply backpressure.
 2. Read `hello`, select protocol `1.0`, then send `initialize` for the same Project ID.
 3. Wait for `ready` before any query or Operation.
@@ -144,6 +150,24 @@ az8 canvas open <project-id> --write --format ndjson
 Protocol truth is written to stdout. stderr contains diagnostics only. Unknown optional fields are
 additive; ignore them. Do not treat a process exit code as the result of the last persistent request.
 
+Treat the persistent process lifetime and each request lifetime separately:
+
+- Keep the process running between requests. Decide request completion only from the matching
+  `requestId` and its `requestCompleted` or `requestFailed` frame; never wait for process exit.
+- Treat `requestAccepted` as admission only. For a write, wait for its terminal Receipt before
+  issuing the next query or Operation.
+- Continuously drain and parse stdout, but do not repeatedly poll an idle process merely to make it
+  produce output. No new frame is a normal healthy state when no lifecycle, request, Canvas, or
+  Workflow fact changed.
+- Do not interpret a shell/agent-host read window ending with no output (for example, a 30-second
+  terminal yield) as CLI latency, request timeout, or connection failure. Check request terminal
+  frames and lifecycle/health facts instead.
+- Keep one connected client for related work. Reopening one-shot clients repeatedly pays connection,
+  synchronization, and hydration cost each time and loses local History, Receipts, and presence.
+- Remember that the current persistent protocol processes requests serially. A long
+  `waitWorkflowRun` occupies the request lane until the Run becomes terminal or its observation
+  window ends; submit it only when no other request needs that lane.
+
 Use one-shot only for:
 
 - an isolated read when no Canvas write is planned;
@@ -195,10 +219,15 @@ Generation is an explicit sequence, never one transaction:
    current facts. Stop after the first non-success.
 5. `startGeneration` succeeds when the Workflow Run is accepted and immediate Canvas effects are
    acknowledged. This completes the start interaction; it does not mean generation finished.
-6. Retain the Workflow Run ID. Use `waitWorkflowRun` when waiting is useful, or `getWorkflowRun`
-   later. An observation-window timeout while the authoritative Run remains pending/running is an
-   ordinary read outcome and does not cancel the Run or take a healthy context offline.
-7. On terminal success, query the target detail and resolve its current output Core Node through
+6. Retain the Workflow Run ID. After the successful start Receipt, continue any work that does not
+   require the generated output. Prefer `workflowChanged` observations while the persistent client
+   is active, and use `getWorkflowRun` at a meaningful later checkpoint.
+7. Use `waitWorkflowRun` only when the next step actually requires terminal output and the current
+   request lane can remain dedicated to waiting. Choose one intentional observation window; do not
+   emulate polling with repeated short waits. An observation-window timeout while the authoritative
+   Run remains pending/running is an ordinary read outcome and does not cancel the Run or take a
+   healthy context offline.
+8. On terminal success, query the target detail and resolve its current output Core Node through
    Project Content before downloading or placing it elsewhere.
 
 Workflow Definitions change over time. Query `workflowDefinitions.summary`, then
@@ -207,7 +236,9 @@ configuration option, modality, cost, or media compatibility from its display na
 
 The start Receipt may report `usage.credits.status` as `estimated`, `not-consumed`, or `unknown`.
 Estimated cost is informational, not final charged usage. There is no second confirmation. Never
-claim actual credit consumption from an estimate.
+claim actual credit consumption from an estimate. When timing data is available, `startGeneration`
+also records the same median and maximum completion timestamps Web uses to display expected duration;
+these timestamps remain estimates and do not change the Run's completion boundary.
 
 ## Media
 
@@ -285,8 +316,8 @@ Never:
   or protocol payloads;
 - inspect, print, or edit an operator-provisioned credential source merely to check whether it
   exists; authenticate with a bounded read instead;
-- use awareness client names to impersonate persisted authors or treat Attention Cursor position as
-  authority;
+- use awareness client suffixes to impersonate persisted authors, supply parentheses to obscure the
+  authenticated-name boundary, or treat Attention Cursor position as authority;
 - use one-shot as if it retained History, Receipts, replay state, observations, or presence;
 - attempt Asset membership, arbitrary Core Node creation, 3D World editing, unsupported
   Decoration, alignment, or automatic layout through lower-level access;