@gavana.ai/cli 0.3.0 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog — @gavana.ai/cli
 
+## 0.3.3
+
+### Fixed
+
+- **`auth login` stops handing out an instruction it already carried out.** It
+  opened the browser and then printed a line that read as a request to open the
+  URL, so a coding agent running the command opened it a second time and the
+  user was left on two tabs of one authorization request — same `client_id`,
+  same `state`, same `code_challenge`. The browser path now says the URL is
+  already open and prints it only to be shown. The one case that still asks is a
+  machine where the open actually failed.
+- **The login wait is announced, and settable.** It blocked for an unannounced
+  180 seconds, longer than the command timeout a caller is likely to assume, so
+  an agent-run login was killed mid-sign-in and took the local callback server —
+  and the user's open tab — with it. The wait is now printed, `--timeout
+  SECONDS` sets it, and the timeout error says the open page is dead and that
+  re-running prints a new URL.
+- **`canvas_validate` no longer excuses a run that referenced nothing.** The
+  product-fidelity review began by filtering to outputs that already carried
+  reference evidence, so a prompt-only run emptied that filter and was graded
+  `not-applicable` — the worst case was the one case it excused. An imported
+  product reference that no generated output uses now raises
+  `unused_product_reference` and reports `needs-review`, naming both the ignored
+  product and the outputs that ignored it. A canvas holding an imported product
+  and no generated output stays `not-applicable`.
+
+## 0.3.2
+
+### Changed
+
+- **`mcp install` says what is left to do.** It answered `installed: true` and
+  stopped, so agents reported the tools as ready while the server sat
+  unauthenticated. The result now carries `authenticated: false` and the
+  remaining steps: restart the client, sign that server in (its login is its
+  own, separate from the CLI's), and confirm with a real read rather than a
+  status line.
+
+### Fixed
+
+- **`bin/gavana.mjs` ships executable.** It was published as `0644` while its
+  `craftboard` twin was `0755`, so the `gavana` command depended on npm
+  repairing the mode while linking. Where it did not, the first command a new
+  user ran answered `permission denied` (exit 126).
+
+## 0.3.1
+
+### Fixed
+
+- **`auth login` no longer stacks a new delegation on every login.** The CLI
+  registered a fresh OAuth client each time — a new client id against a new
+  loopback port — so Gavana could not tell one login from the next, and the
+  delegations it minted never expire. They accumulated until the account hit
+  its token cap, at which point the exchange failed and the CLI answered with
+  another login that failed the same way. The CLI now registers under a stable
+  per-installation id (`installId` in the agent config), so Gavana returns the
+  client id this machine already had and replaces the delegation it holds.
+  Other machines are untouched: each install keeps its own id.
+
 ## 0.3.0
 
 ### Added

package/guides/generated-assets.md

@@ -33,6 +33,14 @@ order: 6
   proves more than one variant, pass the one the user named rather than letting
   the import pick. If no durable references can be imported, say exact product
   fidelity is unverified.
+- When the user supplied the product image themselves and there is no product
+  page, call `product_photoshoot_generate` with `references` set to the durable
+  `node:` handles already on the canvas, one direction object per requested
+  output. It verifies those nodes before any paid work and stops when one is
+  not a durable image. Save an asset to the canvas first: a workflow input
+  binds to a node, not to an `asset:` handle. This is the route for several
+  distinct directions from one uploaded photo; one image call with `count > 1`
+  is not.
 {{/hosted}}{{#local}}- This surface has no product-page importer. Ask the user for the images
   themselves, bring them in through the supported asset flow, and pass the
   resulting handles as references. Do not fetch the page and describe it in a

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gavana.ai/cli",
-    "version": "0.3.0",
+    "version": "0.3.3",
     "description": "JSON-first command-line client for the Gavana Canvas API",
     "type": "module",
     "bin": {

package/src/canvas-agent-guide.mjs

@@ -8,7 +8,7 @@ import { renderForSurface } from "./tools/surface-names.mjs";
 export const GAVANA_CANVAS_GUIDE_VERSION = "1.6.1";
 export const GAVANA_CANVAS_GUIDE_INDEX_URI = `gavana://guides/canvas/v${GAVANA_CANVAS_GUIDE_VERSION.split(".")[0]}/index`;
 export const GAVANA_CANVAS_GUIDE_WORKFLOW_INSTRUCTION =
-    "For the first canvas task in a session, and before any unfamiliar canvas operation, inspect the relevant guide through MCP resources or call guide_search then guide_get. Before changing an existing canvas, call canvas_get. For spatial, multi-node, or destructive work, call canvas_validate with the proposed operations, apply one revision-safe atomic batch, then call canvas_validate again. Campaign work must read creative-canvas and use a reference-led concept before image output. {{#local}}Before image or video generation, call model_list for the required capability and use its exact model: handle; a bare model name does not select a saved connection. If no matching model is returned, report that the agent account cannot access the connection instead of asking the user to add a key again.{{/local}}{{#hosted}}Before video generation, call video_model_find for the required capability and use its exact model: handle; a bare model name does not select a saved connection. If no matching model is returned, report that the agent account cannot access the connection instead of asking the user to add a key again. Image generation has no model-discovery tool here: omit model unless the user named an exact handle.{{/hosted}} A product page URL is source input, never prompt prose. {{#hosted}}When asked to generate one or more exact-product directions from a product page, call product_photoshoot_generate once with one explicit direction object per requested output; it imports verified references before any paid generation and stops if none are available. Use product_reference_pack_import only for a standalone import with no generation. When the page proves more than one variant, pass the variantSelector the user named.{{/hosted}}{{#local}}This surface has no product-page importer: ask for the images themselves and bring them in through the supported asset flow rather than describing the page in a prompt.{{/local}} When a standalone image fallback uses visual references, forward every exact node:/asset: handle (and each known role) in the image request; never reduce that work to a prompt-only generation. Image tools return durable queued progress by default; report it immediately and {{#local}}call run_wait{{/local}}{{#hosted}}set wait true{{/hosted}} only when the current user explicitly needs the completed asset in the same interaction. Otherwise run_get is authoritative; use the exact Canvas URL for navigation, but remember Canvas activity may lag. After an image or workflow finishes, read completionReview. Never claim Done while completionReview.doneClaimAllowed is false, delivery is pending, failed, or non-durable, or blocking findings remain. Render campaign compositions for visual inspection. Treat legacy warnings as review items, not permission to rewrite unrelated work. For N separate images, set count on one image call and never ask one prompt for N panels, frames, or a collage.";
+    "For the first canvas task in a session, and before any unfamiliar canvas operation, inspect the relevant guide through MCP resources or call guide_search then guide_get. Before changing an existing canvas, call canvas_get. For spatial, multi-node, or destructive work, call canvas_validate with the proposed operations, apply one revision-safe atomic batch, then call canvas_validate again. Campaign work must read creative-canvas and use a reference-led concept before image output. {{#local}}Before image or video generation, call model_list for the required capability and use its exact model: handle; a bare model name does not select a saved connection. If no matching model is returned, report that the agent account cannot access the connection instead of asking the user to add a key again.{{/local}}{{#hosted}}Before video generation, call video_model_find for the required capability and use its exact model: handle; a bare model name does not select a saved connection. If no matching model is returned, report that the agent account cannot access the connection instead of asking the user to add a key again. Image generation has no model-discovery tool here: omit model unless the user named an exact handle.{{/hosted}} A product page URL is source input, never prompt prose. {{#hosted}}When asked to generate one or more exact-product directions from a product page, call product_photoshoot_generate once with one explicit direction object per requested output; it imports verified references before any paid generation and stops if none are available. Use product_reference_pack_import only for a standalone import with no generation. When the page proves more than one variant, pass the variantSelector the user named. When the product image is already on the canvas and there is no product page, call the same tool with references set to its durable node: handles and one direction object per requested output; it verifies those nodes before any paid generation. Several distinct directions are never one image call with count > 1.{{/hosted}}{{#local}}This surface has no product-page importer: ask for the images themselves and bring them in through the supported asset flow rather than describing the page in a prompt.{{/local}} When a standalone image fallback uses visual references, forward every exact node:/asset: handle (and each known role) in the image request; never reduce that work to a prompt-only generation. Image tools return durable queued progress by default; report it immediately and {{#local}}call run_wait{{/local}}{{#hosted}}set wait true{{/hosted}} only when the current user explicitly needs the completed asset in the same interaction. Otherwise run_get is authoritative; use the exact Canvas URL for navigation, but remember Canvas activity may lag. After an image or workflow finishes, read completionReview. Never claim Done while completionReview.doneClaimAllowed is false, delivery is pending, failed, or non-durable, or blocking findings remain. Render campaign compositions for visual inspection. Treat legacy warnings as review items, not permission to rewrite unrelated work. For N separate images, set count on one image call and never ask one prompt for N panels, frames, or a collage.";
 export const GAVANA_CANVAS_GUIDE_READ_ONLY_INSTRUCTION =
     "For the first canvas task in a session, and before any unfamiliar canvas review, inspect the relevant guide through MCP resources or call guide_search then guide_get. Call canvas_get before reasoning about an existing canvas, and use canvas_validate to audit its current graph. Treat validation warnings as review items and never claim to mutate the canvas.";
 

package/src/canvas-agent-validation.mjs

@@ -324,9 +324,65 @@ function graphFindings(canvas, validationOptions = {}) {
             }
         }
     }
+
+    // Canvas-level, because the failure is an absence: no single output is
+    // malformed, they simply all ignored the product the person imported.
+    // Reported against the outputs so the standard scoping decides whether it
+    // blocks — this task's work is pinned, somebody else's older run is not.
+    const unusedProducts = unusedProductReferenceNodes(canvas);
+    if (unusedProducts.length) {
+        const outputs = canvas.nodes.filter(isGeneratedOutput);
+        if (outputs.length) {
+            findings.push(
+                finding(
+                    "unused_product_reference",
+                    "warning",
+                    `${unusedProducts.map((node) => nodeHandle(node.id)).join(", ")} was imported as an exact product reference, but no generated output on this canvas references it. Prompt-only output is not the exact product.`,
+                    { nodeIds: [...outputs.map((node) => cleanId(node.id)), ...unusedProducts.map((node) => cleanId(node.id))], guideId: "generated-assets" },
+                ),
+            );
+        }
+    }
     return { findings, truncatedCodes: Array.from(truncatedCodes) };
 }
 
+/**
+ * Imported product references that nothing generated on this canvas used.
+ *
+ * `productFidelityReview` cannot see this on its own: it starts by filtering to
+ * outputs that already carry reference evidence, so the run that used no
+ * reference at all empties its input and grades itself not-applicable. The
+ * worst case was the one case it excused.
+ */
+function unusedProductReferenceNodes(canvas) {
+    const products = canvas.nodes.filter((node) => isRecord(node.metadata) && node.metadata.productReference === true);
+    if (!products.length) return [];
+    const outputs = canvas.nodes.filter(isGeneratedOutput);
+    if (!outputs.length) return [];
+    const usedNodeIds = new Set();
+    const usedStorageKeys = new Set();
+    for (const output of outputs) {
+        const metadata = isRecord(output.metadata) ? output.metadata : {};
+        for (const value of Array.isArray(metadata.referenceNodeIds) ? metadata.referenceNodeIds : []) usedNodeIds.add(cleanId(value));
+        for (const value of Array.isArray(metadata.referenceHandles) ? metadata.referenceHandles : []) {
+            const handle = String(value || "");
+            if (handle.startsWith("node:")) usedNodeIds.add(cleanId(handle.slice("node:".length)));
+        }
+        for (const value of Array.isArray(metadata.references) ? metadata.references : []) usedStorageKeys.add(String(value || ""));
+        for (const connection of canvas.connections) {
+            if (connection.mode !== "reference") continue;
+            if (cleanId(connection.toNodeId || connection.to) !== cleanId(output.id)) continue;
+            usedNodeIds.add(cleanId(connection.fromNodeId || connection.from));
+        }
+    }
+    return products.filter((node) => {
+        if (usedNodeIds.has(cleanId(node.id))) return false;
+        const storageKey = isRecord(node.metadata) ? node.metadata.storageKey : undefined;
+        const content = isRecord(node.metadata) ? node.metadata.content : undefined;
+        return !(storageKey && usedStorageKeys.has(String(storageKey))) && !(content && usedStorageKeys.has(String(content)));
+    });
+}
+
 /**
  * Detect the most specific candidate Section by center point so validation can
  * diagnose a frame that visibly escapes it. Persisted section membership uses
@@ -482,11 +538,29 @@ function reviewArea(findings, ...codes) {
 }
 
 function productFidelityReview(canvas, generatedOutputs) {
+    const unusedProductHandles = unusedProductReferenceNodes(canvas)
+        .map((node) => nodeHandle(node.id))
+        .sort();
     const referenceTargets = generatedOutputs.filter((node) => outputHasReferenceEvidence(node, canvas.connections));
     if (!referenceTargets.length) {
+        // An unused imported product is the whole reason this review exists.
+        // Standing down here graded the one run that ignored every reference as
+        // if fidelity were never in question.
+        if (unusedProductHandles.length && generatedOutputs.length) {
+            const outputHandles = generatedOutputs.map((node) => nodeHandle(node.id)).sort();
+            return {
+                status: "needs-review",
+                reviewedOutputCount: generatedOutputs.length,
+                unusedProductReferenceHandles: unusedProductHandles,
+                needsReviewOutputHandles: outputHandles,
+                evidenceMissingOutputHandles: [],
+                reasons: outputHandles.map((handle) => ({ nodeHandle: handle, reason: `Generated without referencing the imported product ${unusedProductHandles.join(", ")}; exact product fidelity is unverified.` })),
+            };
+        }
         return {
             status: "not-applicable",
             reviewedOutputCount: 0,
+            unusedProductReferenceHandles: unusedProductHandles,
             needsReviewOutputHandles: [],
             evidenceMissingOutputHandles: [],
         };
@@ -501,9 +575,10 @@ function productFidelityReview(canvas, generatedOutputs) {
         // References preserve origin and intent. They never turn a retained
         // creative output into a completion gate. Exact composition is the
         // exception: it must carry a verified finalized-image hash.
-        status: evidenceMissing.length ? "needs-review" : "passed",
+        status: evidenceMissing.length || unusedProductHandles.length ? "needs-review" : "passed",
         reviewedOutputCount: referenceTargets.length,
-        needsReviewOutputHandles: evidenceMissingOutputHandles,
+        unusedProductReferenceHandles: unusedProductHandles,
+        needsReviewOutputHandles: uniqueSorted([...evidenceMissingOutputHandles, ...(unusedProductHandles.length ? generatedOutputs.filter((node) => !outputHasReferenceEvidence(node, canvas.connections)).map((node) => nodeHandle(node.id)) : [])]),
         evidenceMissingOutputHandles,
         reasons: evidenceMissing.map((node) => ({ nodeHandle: nodeHandle(node.id), reason: "Exact composition is missing its verified output hash." })),
     };

package/src/commands.mjs

@@ -41,8 +41,8 @@ export const GAVANA_CLI_COMMANDS = Object.freeze([
     {
         group: "auth",
         action: "login",
-        usage: ["gavana auth login [--profile NAME] [--read-only]", "gavana auth login --base-url URL --token-stdin"],
-        groupUsage: ["gavana auth login [--profile NAME] [--read-only] [--no-browser]", "gavana auth login --token-stdin [--profile NAME]"],
+        usage: ["gavana auth login [--profile NAME] [--read-only] [--timeout SECONDS]", "gavana auth login --base-url URL --token-stdin"],
+        groupUsage: ["gavana auth login [--profile NAME] [--read-only] [--no-browser] [--timeout SECONDS]", "gavana auth login --token-stdin [--profile NAME]"],
     },
     { group: "auth", action: "status", usage: ["gavana auth status"], groupUsage: ["gavana auth status [--profile NAME]"] },
     { group: "config", action: "list", usage: ["gavana config list | get [PROFILE] | use PROFILE"], groupUsage: ["gavana config list"] },

package/src/config.mjs

@@ -2,10 +2,12 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { execFile as execFileCallback } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import { promisify } from "node:util";
 
 const execFile = promisify(execFileCallback);
 const KEYCHAIN_SERVICE = "ai.gavana.cli";
+const INSTALL_ID_PATTERN = /^[A-Za-z0-9_-]{16,64}$/;
 
 export async function readAgentConfig(env = process.env, dependencies = {}) {
     const store = await readAgentConfigStore(env);
@@ -68,6 +70,7 @@ export async function writeAgentConfig(config, env = process.env) {
     if (credentialStore === "macos-keychain") delete profileConfig.token;
     const next = {
         version: 1,
+        ...(current.installId ? { installId: current.installId } : {}),
         activeProfile: profile,
         profiles: { ...(current.profiles || {}), [profile]: profileConfig },
     };
@@ -90,6 +93,20 @@ export async function writeAgentConfigStore(config, env = process.env) {
     return filePath;
 }
 
+/**
+ * The id this installation registers its OAuth client under. It is not a
+ * credential: it exists so a repeat `auth login` is recognised as the same
+ * install and replaces the delegation it already holds, instead of leaving a
+ * new one behind on every login.
+ */
+export async function readOAuthInstallId(env = process.env) {
+    const store = await readAgentConfigStore(env);
+    if (store.installId) return store.installId;
+    const installId = randomBytes(24).toString("base64url");
+    await writeAgentConfigStore({ ...store, installId }, env);
+    return installId;
+}
+
 export async function removeAgentConfig(env = process.env) {
     const filePaths = agentConfigFileCandidates(env);
     await Promise.all(filePaths.map((filePath) => fs.rm(filePath, { force: true })));
@@ -164,14 +181,15 @@ function agentConfigFileCandidates(env) {
 
 function normalizeConfigStore(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) return { version: 1, activeProfile: "default", profiles: {} };
+    const install = typeof value.installId === "string" && INSTALL_ID_PATTERN.test(value.installId) ? { installId: value.installId } : {};
     if (value.profiles && typeof value.profiles === "object" && !Array.isArray(value.profiles)) {
-        return { version: 1, activeProfile: cleanProfileName(value.activeProfile || "default"), profiles: value.profiles };
+        return { version: 1, ...install, activeProfile: cleanProfileName(value.activeProfile || "default"), profiles: value.profiles };
     }
     const legacy = {
         ...(typeof value.baseUrl === "string" && value.baseUrl ? { baseUrl: value.baseUrl } : {}),
         ...(typeof value.token === "string" && value.token ? { token: value.token } : {}),
     };
-    return { version: 1, activeProfile: "default", profiles: Object.keys(legacy).length ? { default: legacy } : {} };
+    return { version: 1, ...install, activeProfile: "default", profiles: Object.keys(legacy).length ? { default: legacy } : {} };
 }
 
 function selectedProfileName(store, env) {

package/src/guide-sources.mjs

@@ -49,7 +49,7 @@ export const GAVANA_CANVAS_GUIDE_SOURCES = Object.freeze([
         description: "Prepare media nodes, start only explicit generation, and preserve output lineage.",
         keywords: Object.freeze(["generated","generation","image","video","output","asset","durable","lineage","placeholder","job"]),
         order: 6,
-        markdown: "\n## Before generation\n\n- Read the destination canvas and relevant source nodes.\n- Use exact source `node:` or `asset:` handles.\n{{#local}}- Before image or video generation, call `model_list` for the required capability and pass its exact `model:` handle. A bare model name does not select a saved connection. If no matching model is returned, report that the agent account cannot access that connection; do not ask the user to add a key again.\n{{/local}}{{#hosted}}- Before video generation, call `video_model_find` for the required capability and pass its exact `model:` handle. A bare model name does not select a saved connection. If no matching model is returned, report that the agent account cannot access that connection; do not ask the user to add a key again.\n- Image generation has no model-discovery tool on this surface. Omit `model` and Gavana uses the account's configured default; pass `model` only when the user named an exact handle. Do not go looking for a tool that lists image models here.\n{{/hosted}}- For a standalone image request, pass every visual source in `references`.\n  Use `{ \"handle\": \"node:...\", \"role\": \"identity\" }` when its\n  responsibility is known; valid roles are `identity`, `construction`,\n  `texture`, `fit`, and `style`. Do not flatten multi-reference work\n  into prompt prose or omit a source during fallback.\n- Reuse existing Canvas `node:` or `asset:` handles directly. Do not download\n  and re-upload a generated Canvas image merely to use it as the next\n  generation's reference. State whether a style reference establishes the\n  brand-world or typography/layout direction in the prompt.\n- A product page URL is source input, not prompt prose. Never paste it into a\n  generation prompt, and never describe prompt-only output as the exact product.\n{{#hosted}}- When asked to generate one or more exact-product directions from a product\n  page, call `product_photoshoot_generate` once. Supply one explicit direction\n  object per requested output; the tool imports durable gallery references\n  first and runs each direction as its own reference-guided image job. Use\n  `product_reference_pack_import` only when the user wants a standalone import\n  with no generation. Both take an optional `variantSelector`; when the page\n  proves more than one variant, pass the one the user named rather than letting\n  the import pick. If no durable references can be imported, say exact product\n  fidelity is unverified.\n{{/hosted}}{{#local}}- This surface has no product-page importer. Ask the user for the images\n  themselves, bring them in through the supported asset flow, and pass the\n  resulting handles as references. Do not fetch the page and describe it in a\n  prompt: that produces a generic product, not theirs.\n{{/local}}- Create an empty image or video target only through supported operations. Do not write media bytes, storage keys, or arbitrary output URLs into metadata.\n- Connect prompts, products, references, Lists, and frame inputs to their target with the correct direction and mode.\n\n## Paid execution\n\nGeneration is allowed only after explicit current-turn user intent. Start one run with one caller-stable idempotency key. When the user asks for N separate images, pass `count: N` (1-4) on one image call: Gavana reserves one image node per output and writes one image into each. Never encode N as a prompt describing N panels, frames, or a collage — that returns one composite image in one node. When you pass `targetNodeIds`, pass exactly one target node per output; a mismatch is rejected. For a multi-direction product photoshoot, never encode the directions as one shared prompt with `count > 1`; the product photoshoot tool owns one `count: 1` child per direction under one durable Recipe Run. Image tools return durable queued progress by default; report that progress immediately. {{#local}}Do not automatically call `run_wait`; call it only when the current user explicitly needs the completed asset in this same interaction.{{/local}}{{#hosted}}Do not block on the result: leave `wait` false and let the call return its queued run. Set `wait` true only when the current user explicitly needs the completed asset in this same interaction.{{/hosted}} Otherwise, use the returned exact Canvas URL for navigation, but treat `run_get` as the authoritative status; Canvas activity is a presentation surface and may lag. Do not start another run while one is pending. A terminal failure must be reported without automatic retry.\n\n## Sizes, formats, and limits\n\nThere is no size discovery tool. What holds today:\n\n- `size` accepts an exact `WIDTHxHEIGHT` or an aspect shorthand like `4:5`.\n  gpt-image models render `1024x1024`, `1024x1536`, and `1536x1024`; anything\n  else resolves to the closest of those. The run's `settings` reports both\n  `requestedSize` and `effectiveSize`, and a resolved request also returns a\n  `parameterAdjustments` entry — read them before telling the person what they\n  got, and never assume the size you asked for is the size that was made.\n- Imports accept PNG, JPEG, WebP, and GIF up to 50 MB. A larger or undecodable\n  source is refused without writing anything; that refusal will not succeed on\n  retry, so shrink the image or link a smaller rendition instead.\n\n## Completion\n\n`run_get` is what you call while a run is going, and it answers about state, not pixels. Its response always links the finished image; {{#hosted}}pass `includeImage: true` {{/hosted}}{{#local}}read the linked asset {{/local}}only when a person is about to look at the picture, because inlining one costs a couple of megabytes on every read. A run that is still going also dates its own answer: `timing.observedAt` is when the record was read, `timing.elapsedMs` runs off the wall clock, and `timing.stale` with `timing.staleNote` means nothing has written to the run in a long while — the work may already be finished, so read the destination canvas before starting anything new.\n\nDo not claim a generated image is durable until the result returns a target `node:`, durable `asset:`, and the final canvas read shows server-owned media fields. `run_get` is the authoritative status when a user asks whether a run is done; a queued Canvas activity row is not evidence that the provider never started. A video Job may return a protected download without materializing a native video node; report exactly what the server returned and do not invent durability.\n\nKeep generated output spatially near its input stage and connected to its source, prompt, List, or workflow. After finalization, run `canvas_validate` and read `completionReview`: it reports overlap, full-frame Section containment, reference lineage, and delivery state. Do not claim Done while it says `doneClaimAllowed: false`, including when delivery is pending, failed, or non-durable. Render the Canvas for visual inspection when the request includes a campaign, poster, banner, or multi-direction composition. Reference provenance is not a user workflow state and never requires a Keep action. Never create another paid provider call automatically.\n",
+        markdown: "\n## Before generation\n\n- Read the destination canvas and relevant source nodes.\n- Use exact source `node:` or `asset:` handles.\n{{#local}}- Before image or video generation, call `model_list` for the required capability and pass its exact `model:` handle. A bare model name does not select a saved connection. If no matching model is returned, report that the agent account cannot access that connection; do not ask the user to add a key again.\n{{/local}}{{#hosted}}- Before video generation, call `video_model_find` for the required capability and pass its exact `model:` handle. A bare model name does not select a saved connection. If no matching model is returned, report that the agent account cannot access that connection; do not ask the user to add a key again.\n- Image generation has no model-discovery tool on this surface. Omit `model` and Gavana uses the account's configured default; pass `model` only when the user named an exact handle. Do not go looking for a tool that lists image models here.\n{{/hosted}}- For a standalone image request, pass every visual source in `references`.\n  Use `{ \"handle\": \"node:...\", \"role\": \"identity\" }` when its\n  responsibility is known; valid roles are `identity`, `construction`,\n  `texture`, `fit`, and `style`. Do not flatten multi-reference work\n  into prompt prose or omit a source during fallback.\n- Reuse existing Canvas `node:` or `asset:` handles directly. Do not download\n  and re-upload a generated Canvas image merely to use it as the next\n  generation's reference. State whether a style reference establishes the\n  brand-world or typography/layout direction in the prompt.\n- A product page URL is source input, not prompt prose. Never paste it into a\n  generation prompt, and never describe prompt-only output as the exact product.\n{{#hosted}}- When asked to generate one or more exact-product directions from a product\n  page, call `product_photoshoot_generate` once. Supply one explicit direction\n  object per requested output; the tool imports durable gallery references\n  first and runs each direction as its own reference-guided image job. Use\n  `product_reference_pack_import` only when the user wants a standalone import\n  with no generation. Both take an optional `variantSelector`; when the page\n  proves more than one variant, pass the one the user named rather than letting\n  the import pick. If no durable references can be imported, say exact product\n  fidelity is unverified.\n- When the user supplied the product image themselves and there is no product\n  page, call `product_photoshoot_generate` with `references` set to the durable\n  `node:` handles already on the canvas, one direction object per requested\n  output. It verifies those nodes before any paid work and stops when one is\n  not a durable image. Save an asset to the canvas first: a workflow input\n  binds to a node, not to an `asset:` handle. This is the route for several\n  distinct directions from one uploaded photo; one image call with `count > 1`\n  is not.\n{{/hosted}}{{#local}}- This surface has no product-page importer. Ask the user for the images\n  themselves, bring them in through the supported asset flow, and pass the\n  resulting handles as references. Do not fetch the page and describe it in a\n  prompt: that produces a generic product, not theirs.\n{{/local}}- Create an empty image or video target only through supported operations. Do not write media bytes, storage keys, or arbitrary output URLs into metadata.\n- Connect prompts, products, references, Lists, and frame inputs to their target with the correct direction and mode.\n\n## Paid execution\n\nGeneration is allowed only after explicit current-turn user intent. Start one run with one caller-stable idempotency key. When the user asks for N separate images, pass `count: N` (1-4) on one image call: Gavana reserves one image node per output and writes one image into each. Never encode N as a prompt describing N panels, frames, or a collage — that returns one composite image in one node. When you pass `targetNodeIds`, pass exactly one target node per output; a mismatch is rejected. For a multi-direction product photoshoot, never encode the directions as one shared prompt with `count > 1`; the product photoshoot tool owns one `count: 1` child per direction under one durable Recipe Run. Image tools return durable queued progress by default; report that progress immediately. {{#local}}Do not automatically call `run_wait`; call it only when the current user explicitly needs the completed asset in this same interaction.{{/local}}{{#hosted}}Do not block on the result: leave `wait` false and let the call return its queued run. Set `wait` true only when the current user explicitly needs the completed asset in this same interaction.{{/hosted}} Otherwise, use the returned exact Canvas URL for navigation, but treat `run_get` as the authoritative status; Canvas activity is a presentation surface and may lag. Do not start another run while one is pending. A terminal failure must be reported without automatic retry.\n\n## Sizes, formats, and limits\n\nThere is no size discovery tool. What holds today:\n\n- `size` accepts an exact `WIDTHxHEIGHT` or an aspect shorthand like `4:5`.\n  gpt-image models render `1024x1024`, `1024x1536`, and `1536x1024`; anything\n  else resolves to the closest of those. The run's `settings` reports both\n  `requestedSize` and `effectiveSize`, and a resolved request also returns a\n  `parameterAdjustments` entry — read them before telling the person what they\n  got, and never assume the size you asked for is the size that was made.\n- Imports accept PNG, JPEG, WebP, and GIF up to 50 MB. A larger or undecodable\n  source is refused without writing anything; that refusal will not succeed on\n  retry, so shrink the image or link a smaller rendition instead.\n\n## Completion\n\n`run_get` is what you call while a run is going, and it answers about state, not pixels. Its response always links the finished image; {{#hosted}}pass `includeImage: true` {{/hosted}}{{#local}}read the linked asset {{/local}}only when a person is about to look at the picture, because inlining one costs a couple of megabytes on every read. A run that is still going also dates its own answer: `timing.observedAt` is when the record was read, `timing.elapsedMs` runs off the wall clock, and `timing.stale` with `timing.staleNote` means nothing has written to the run in a long while — the work may already be finished, so read the destination canvas before starting anything new.\n\nDo not claim a generated image is durable until the result returns a target `node:`, durable `asset:`, and the final canvas read shows server-owned media fields. `run_get` is the authoritative status when a user asks whether a run is done; a queued Canvas activity row is not evidence that the provider never started. A video Job may return a protected download without materializing a native video node; report exactly what the server returned and do not invent durability.\n\nKeep generated output spatially near its input stage and connected to its source, prompt, List, or workflow. After finalization, run `canvas_validate` and read `completionReview`: it reports overlap, full-frame Section containment, reference lineage, and delivery state. Do not claim Done while it says `doneClaimAllowed: false`, including when delivery is pending, failed, or non-durable. Render the Canvas for visual inspection when the request includes a campaign, poster, banner, or multi-direction composition. Reference provenance is not a user workflow state and never requires a Keep action. Never create another paid provider call automatically.\n",
     }),
     Object.freeze({
         id: "existing-canvases",

package/src/runner.mjs

@@ -9,7 +9,7 @@ import { promisify } from "node:util";
 import { CanvasAgentApiError, createCanvasAgentClient, markdownForResult, parseElementHandle } from "./client.mjs";
 import { GAVANA_CLI_VERSION, gavanaCapabilitySummary } from "./capabilities.mjs";
 import { GAVANA_CLI_GROUP_HELP, gavanaCommandActions, gavanaCommandGroupUsageLines, gavanaCommandGroups, gavanaCommandIsKnown, gavanaCommandUsageLines } from "./commands.mjs";
-import { agentConfigFilePath, listAgentProfiles, readAgentConfig, readAgentConfigMetadata, removeAgentProfile, setActiveAgentProfile, writeAgentConfig } from "./config.mjs";
+import { agentConfigFilePath, listAgentProfiles, readAgentConfig, readAgentConfigMetadata, readOAuthInstallId, removeAgentProfile, setActiveAgentProfile, writeAgentConfig } from "./config.mjs";
 import { gavanaMcpClientDefinition } from "./mcp-targets.mjs";
 
 const BOOLEAN_OPTIONS = new Set(["help", "version", "pretty", "raw", "yes", "confirm", "rebase", "wait", "no-wait", "progress", "preflight", "token-stdin", "no-verify", "no-browser", "audio", "no-audio", "read-only"]);
@@ -643,7 +643,7 @@ async function runAuthCommand(action, _args, options, env, runtime) {
         if (!token) {
             const login = runtime.oauthLogin
                 ? await runtime.oauthLogin({ baseUrl, readOnly: options["read-only"] === true, profile: profile || current.profile })
-                : await performBrowserOAuthLogin({ baseUrl, readOnly: options["read-only"] === true, noBrowser: options["no-browser"] === true, runtime });
+                : await performBrowserOAuthLogin({ baseUrl, readOnly: options["read-only"] === true, noBrowser: options["no-browser"] === true, timeoutMs: secondsOption(options.timeout, OAUTH_LOGIN_DEFAULT_TIMEOUT_MS / 1000) * 1000, env, runtime });
             token = login.accessToken;
             loginMethod = "browser";
         }
@@ -738,7 +738,10 @@ async function revokeBrowserOAuthToken(baseUrl, token, fetchImpl) {
     }
 }
 
-export async function performBrowserOAuthLogin({ baseUrl, readOnly = false, noBrowser = false, runtime = {} }) {
+export const OAUTH_LOGIN_DEFAULT_TIMEOUT_MS = 180_000;
+
+export async function performBrowserOAuthLogin({ baseUrl, readOnly = false, noBrowser = false, timeoutMs, env = process.env, runtime = {} }) {
+    const waitMs = timeoutMs || runtime.oauthTimeoutMs || OAUTH_LOGIN_DEFAULT_TIMEOUT_MS;
     const fetchImpl = runtime.fetchImpl || globalThis.fetch;
     if (typeof fetchImpl !== "function") throw usageError("This runtime does not provide fetch for browser login.");
     const origin = new URL(createCanvasAgentClient({ token: "configuration-validation", baseUrl, fetchImpl }).baseUrl).origin;
@@ -748,11 +751,17 @@ export async function performBrowserOAuthLogin({ baseUrl, readOnly = false, noBr
     const callback = runtime.createOAuthCallbackServer ? await runtime.createOAuthCallbackServer(state) : await createOAuthCallbackServer(state);
     try {
         const scopes = readOnly ? "canvas:read asset:read element:read" : "canvas:read canvas:write asset:read element:read element:write image:generate video:generate job:manage";
+        // Registering under a stable install id is what makes this login a
+        // reconnect: Gavana returns the client id this machine already had and
+        // replaces the delegation it issued last time, instead of stacking a
+        // new one behind a client it has never seen.
+        const softwareId = runtime.installId || (await readOAuthInstallId(env));
         const registrationResponse = await fetchImpl(`${origin}/oauth/register`, {
             method: "POST",
             headers: { "Content-Type": "application/json", Accept: "application/json" },
             body: JSON.stringify({
                 client_name: "Gavana CLI",
+                software_id: softwareId,
                 redirect_uris: [callback.redirectUri],
                 token_endpoint_auth_method: "none",
                 grant_types: ["authorization_code"],
@@ -774,9 +783,37 @@ export async function performBrowserOAuthLogin({ baseUrl, readOnly = false, noBr
             scope: scopes,
             state,
         }).toString();
-        (runtime.stderr || process.stderr).write(`Open this URL to connect Gavana:\n${authorize}\n`);
-        if (!noBrowser) await (runtime.openBrowser ? runtime.openBrowser(authorize.toString()) : openBrowser(authorize.toString()));
-        const { code } = await callback.wait(runtime.oauthTimeoutMs || 180_000);
+        // Whoever reads this line acts on it, and under a coding agent that
+        // reader is the agent. Reporting instead of ordering was not enough:
+        // "if no window opens, this is the URL" states a condition the reader
+        // cannot evaluate — it never sees the window — so it assumes the worst
+        // and opens the URL that is already open, and one login costs the user
+        // two tabs on the same authorization request. The prohibition has to be
+        // said outright, and only the branch where nothing opened may ask for
+        // the URL to be opened.
+        //
+        // The wait is announced because the caller has to survive it. An agent
+        // running this as a command sizes its own timeout, and every default
+        // worth guessing at is shorter than this one.
+        const stderrStream = runtime.stderr || process.stderr;
+        const askToOpen = () => stderrStream.write(`Open this URL to connect Gavana:\n${authorize}\n`);
+        const announceWait = () => stderrStream.write(`This waits up to ${Math.round(waitMs / 1000)} seconds for the sign-in to finish.\n`);
+        if (noBrowser) askToOpen();
+        else {
+            let opened = true;
+            try {
+                await (runtime.openBrowser ? runtime.openBrowser(authorize.toString()) : openBrowser(authorize.toString()));
+            } catch {
+                // No window came up, so a prohibition would strand the user on a
+                // page nobody opened. A machine with no browser is the one case
+                // where asking is the right instruction.
+                opened = false;
+            }
+            if (opened) stderrStream.write(`Your browser is opening the Gavana sign-in page. Do not open it again — this URL is already open, and is printed only so you can show it to me:\n${authorize}\n`);
+            else askToOpen();
+        }
+        announceWait();
+        const { code } = await callback.wait(waitMs);
         const tokenResponse = await fetchImpl(`${origin}/oauth/token`, {
             method: "POST",
             headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
@@ -837,7 +874,7 @@ async function createOAuthCallbackServer(expectedState) {
             Promise.race([
                 result,
                 new Promise((_, rejectTimeout) => {
-                    const timer = setTimeout(() => rejectTimeout(usageError("Gavana browser login timed out. Run auth login again.")), timeoutMs);
+                    const timer = setTimeout(() => rejectTimeout(usageError("Gavana browser login timed out. The page that was open is now dead. Run auth login again, use the new URL it prints, and pass --timeout SECONDS if you need longer than this.")), timeoutMs);
                     timer.unref?.();
                 }),
             ]),
@@ -944,7 +981,20 @@ async function runMcpCommand(action, args, options, baseUrl, runtime) {
     if (action === "config" || !definition.command) return definition;
     const execute = runtime.execFile || execFile;
     await execute(definition.command, definition.args);
-    return { ...definition, installed: true };
+    // Registering is not signing in, and `installed: true` was the last thing
+    // this command said. Agents read that as the end of the job and told people
+    // their tools were ready while the server sat unauthenticated. The steps
+    // that remain are known here, so they ship with the result.
+    return {
+        ...definition,
+        installed: true,
+        authenticated: false,
+        nextSteps: [
+            `Restart your client so it loads the ${definition.serverName} server.`,
+            `Sign this server in from inside your client — it has its own login, separate from the CLI's. In Claude Code: /mcp, choose ${definition.serverName}.`,
+            "Confirm with a read-only call, such as listing canvases. A status line saying connected is not proof.",
+        ],
+    };
 }
 
 function completionScript(shell) {

package/src/version.mjs

@@ -7,4 +7,4 @@
 //
 // scripts/gavana-mcp-tool-contract.test.mjs asserts this equals
 // packages/cli/package.json, so the two cannot drift.
-export const GAVANA_CLI_VERSION = "0.3.0";
+export const GAVANA_CLI_VERSION = "0.3.3";