@stackbone/cli 0.3.0 → 0.3.2

package/main.js

@@ -501,6 +501,25 @@ var init_approvals = __esmMin((() => {
 //#endregion
 //#region ../../libs/shared/validators/src/lib/agents/contract.ts
 /**
+* Whether a box speaking protocol `version` can be registered as a deployment.
+* Pure and total: the caller passes the number the handshake reported.
+*/
+function supportsDeploymentRegistration(version) {
+	return version >= 15;
+}
+/**
+* The one sentence both doors print when a box is below the floor.
+*
+* Shared, not copied, because the wizard and `stackbone link` refuse by the same
+* rule and an operator who tries the other door must not read a different story.
+* For the same reason it names no door: there is no "register it from the
+* terminal instead" any more, and the only way out it can honestly offer is the
+* one that works everywhere — run a current image.
+*/
+function deploymentRegistrationRefusal(version) {
+	return `This box speaks protocol version ${version}. Registering a deployment needs version 15 or later, because an older box refuses the signed call that proves its secret. Update the image the box runs to a current one and try again.`;
+}
+/**
 * Validates that the negotiated `contract.version` is at or above the
 * version the SDK still executes against. Pure, table-driven, never throws.
 *
@@ -604,7 +623,7 @@ var init_deployments = __esmMin((() => {
 		agentSlug: agentSlugSchema,
 		url: z.url(),
 		hmacSecret: z.string().min(1),
-		imageTag: z.string().min(1).max(200)
+		imageTag: z.string().min(1).max(200).optional()
 	});
 	z.object({ url: z.url() });
 	deploymentResponseSchema = z.object({
@@ -3461,7 +3480,7 @@ function createContractStore(resolved = resolveConfig({})) {
 	};
 }
 async function performHandshake(baseUrl, fetchImpl) {
-	const url = `${baseUrl}${CONTRACT_PATH}`;
+	const url = `${baseUrl}${CONTRACT_PATH$1}`;
 	let response;
 	try {
 		response = await fetchImpl(url, { method: "GET" });
@@ -3547,12 +3566,12 @@ function maybeLogDebug(debugLogged, key, contract) {
 	debugLogged.add(key);
 	console.warn(`[stackbone] contract handshake ok: baseUrl=${key} version=${contract.version} capabilities=${contract.capabilities.length}`);
 }
-var CONTRACT_PATH;
+var CONTRACT_PATH$1;
 var init_contract_handshake = __esmMin((() => {
 	init_src$13();
 	init_config$1();
 	init_result$1();
-	CONTRACT_PATH = "/api/contract";
+	CONTRACT_PATH$1 = "/api/contract";
 }));
 //#endregion
 //#region ../../libs/sdk/src/contract/capability-registry.ts
@@ -10576,7 +10595,7 @@ var createBoxAuthGate = (options) => {
 //#endregion
 //#region ../../libs/runtime/workspace-runtime/src/lib/server/contract.ts
 init_src$13();
-var STACKBONE_CLI_BUILD_VERSION = "0.3.0";
+var STACKBONE_CLI_BUILD_VERSION = "0.3.2";
 /**
 * Capabilities the local emulator advertises on `GET /api/contract`, derived
 * from the route registry above so the advertised set and the mounted routes
@@ -10597,7 +10616,7 @@ var EMULATOR_CAPABILITIES = Object.keys({
 	"browser.provider": "/api/browser-provider"
 });
 var buildContractResponse = () => contractResponseSchema.parse({
-	version: 14,
+	version: 15,
 	minSupported: 1,
 	capabilities: [...EMULATOR_CAPABILITIES],
 	build: {
@@ -40738,8 +40757,7 @@ var redisConnection = (redisUrl) => {
 	const db = path === "" ? void 0 : Number(path);
 	if (db !== void 0 && !Number.isInteger(db)) throw new Error(`Invalid Redis database in URL path: '${url.pathname}' (expected an integer)`);
 	return {
-		host: url.hostname,
-		port: url.port ? Number(url.port) : 6379,
+		url: redisUrl,
 		...db === void 0 ? {} : { db },
 		maxRetriesPerRequest: null
 	};
@@ -41160,7 +41178,7 @@ var init_connections = __esmMin((() => {
 	buildAgentEnv = (base, injection, options) => {
 		const env = {
 			...base,
-			[STACKBONE_ENV_KEYS.contractVersion]: String(14),
+			[STACKBONE_ENV_KEYS.contractVersion]: String(15),
 			[STACKBONE_ENV_KEYS.agentId]: injection.agentId,
 			[STACKBONE_ENV_KEYS.postgresUrl]: injection.services.postgresUrl,
 			[STACKBONE_ENV_KEYS.s3Endpoint]: injection.services.s3Endpoint,
@@ -45043,7 +45061,8 @@ var buildEmulatorApp = (opts, hooks = {}) => {
 			"x-stackbone-session",
 			"x-stackbone-conversation",
 			"x-api-key",
-			"anthropic-version"
+			"anthropic-version",
+			STACKBONE_SIGNATURE_HEADER
 		],
 		exposeHeaders: ["X-Stackbone-Run-Id"]
 	}));
@@ -49159,7 +49178,9 @@ STACKBONE_SECRET_KEY=${secretKey}
 # agent creates its own schema on first boot. It must have the pgvector extension
 # available — see the README.
 # DATABASE_URL=postgres://user:password@host:5432/dbname?sslmode=require
-# WORKFLOW_REDIS_URL=redis://host:6379
+# WORKFLOW_REDIS_URL=redis://default:password@host:6379
+# Managed Redis always wants a password, and some require TLS — use rediss:// for
+# those. Percent-encode a password containing / + = or @, or the URL will not parse.
 
 # ---- Optional ----------------------------------------------------------------
 # Set if your database role is not allowed to create schemas; you then apply the
@@ -49244,6 +49265,14 @@ and apply these by hand first, in filename order:
 
 Both live inside the image; \`docker run --rm ${input.imageTag} ls <path>\` lists them.
 
+Redis needs no preparation, only a reachable URL. Managed instances hand out a
+password, so the URL carries one — \`redis://default:password@host:6379\`. Use
+\`rediss://\` where the provider requires TLS (Upstash, ElastiCache with encryption
+in transit), and percent-encode a password containing \`/\`, \`+\`, \`=\` or \`@\`. The
+agent PINGs Redis before it starts and stops with the reason if it cannot: a
+rejected password fails right away, and a Redis still starting up is retried for
+30 seconds first.
+
 ## Running it somewhere other than Compose
 
 The agent serves on port **${RUNTIME_PORT}** by default, and binds whatever
@@ -53652,6 +53681,175 @@ var assertSdkCompatible = async (ctx, opts) => {
 	return result;
 };
 //#endregion
+//#region src/services/project.service.ts
+var GITIGNORE_MARKER_BEGIN$1 = "# >>> stackbone >>>";
+var GITIGNORE_BLOCK = [
+	GITIGNORE_MARKER_BEGIN$1,
+	".stackbone/",
+	"node_modules/",
+	"dist/",
+	"# <<< stackbone <<<",
+	""
+].join("\n");
+var exists = async (path) => {
+	try {
+		await stat(path);
+		return true;
+	} catch (err) {
+		if (isENOENT(err)) return false;
+		throw err;
+	}
+};
+var writeProjectConfig = async (ctx, agent, input, extras = {}) => {
+	const config = {
+		schemaVersion: 1,
+		organizationId: agent.organizationId,
+		agentId: agent.id,
+		controlPlaneUrl: ctx.apiUrl,
+		...extras.localDevInstallationId !== void 0 ? { localDevInstallationId: extras.localDevInstallationId } : {},
+		...extras.organizationSlug !== void 0 ? { organizationSlug: extras.organizationSlug } : {},
+		...extras.agentSlug !== void 0 ? { agentSlug: extras.agentSlug } : {},
+		...extras.starter !== void 0 ? { starter: extras.starter } : {}
+	};
+	await mkdir(join(input.root, ".stackbone"), { recursive: true });
+	await writeFile(join(input.root, ".stackbone", "project.json"), JSON.stringify(config, null, 2));
+	return config;
+};
+var ensureGitignore = async (root) => {
+	const path = join(root, ".gitignore");
+	let current = "";
+	try {
+		current = await readFile(path, "utf8");
+	} catch (err) {
+		if (!isENOENT(err)) throw err;
+	}
+	if (current.includes(GITIGNORE_MARKER_BEGIN$1)) return;
+	await writeFile(path, current.length > 0 && !current.endsWith("\n") ? `${current}\n${GITIGNORE_BLOCK}` : `${current}${GITIGNORE_BLOCK}`);
+};
+var detectExistingProjectFiles = async (root, paths) => {
+	const checks = await Promise.all(paths.map((p) => exists(join(root, p))));
+	return paths.filter((_, i) => checks[i]);
+};
+//#endregion
+//#region src/services/register-agent.ts
+var registerAgentEager = async (ctx, input) => {
+	const slug = input.slug ?? input.name;
+	let agent;
+	let created = false;
+	try {
+		agent = await getAgentByOwnerAndSlug(ctx, input.organizationSlug, slug);
+	} catch (err) {
+		if (!(isStackboneCliError(err) && err.code === "not_found")) throw err;
+		agent = await createAgent(ctx, {
+			organizationSlug: input.organizationSlug,
+			name: input.name,
+			slug,
+			...input.description !== void 0 ? { description: input.description } : {}
+		});
+		created = true;
+	}
+	const localDev = await upsertLocalDevInstallation(ctx, {
+		creatorOrganizationSlug: input.organizationSlug,
+		agentTemplateSlug: agent.slug
+	});
+	return {
+		agent,
+		localDev,
+		created
+	};
+};
+//#endregion
+//#region src/commands/dev/link-on-demand.ts
+/** Sentinel for the "none of these" row in the agent picker. */
+var CREATE_NEW = "\0create-new";
+/**
+* A control-plane slug from a folder name: lowercase, non-alphanumerics folded
+* to single dashes, no leading or trailing dash. A folder called `Astex Email
+* Agent` should not fail the create call for a reason nobody typed.
+*/
+var slugifyProjectName = (name) => name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+var promptForAgentInteractively = async (agents) => {
+	if (agents.length === 0) return null;
+	const value = await select({
+		message: "This project is not linked to an agent yet. Which one is it?",
+		options: [...agents.map((a) => ({
+			value: a.slug,
+			label: a.name,
+			hint: a.slug
+		})), {
+			value: CREATE_NEW,
+			label: "Create a new agent",
+			hint: "registers one for this project"
+		}]
+	});
+	if (isCancel(value)) throw new StackboneCliError({
+		code: "no_project",
+		message: "No agent selected, so this directory is still unlinked.",
+		suggestion: "Run `stackbone dev` again and pick an agent, or create one in Studio."
+	});
+	return value === CREATE_NEW ? null : String(value);
+};
+var promptForNewNameInteractively = async (suggested) => {
+	const value = await text$1({
+		message: "Name for the new agent",
+		initialValue: suggested,
+		validate: (v) => slugifyProjectName(v ?? "").length === 0 ? "Pick a name with letters or numbers in it." : void 0
+	});
+	if (isCancel(value)) throw new StackboneCliError({
+		code: "no_project",
+		message: "No name given, so no agent was created.",
+		suggestion: "Run `stackbone dev` again to pick or create one."
+	});
+	return String(value);
+};
+/**
+* The message a non-interactive run gets. Kept apart from the interactive path
+* because it is the one a CI log will carry, and the old text sent the reader to
+* two commands that both do the wrong thing here.
+*/
+var unlinkedProjectError = () => new StackboneCliError({
+	code: "no_project",
+	message: "No project linked in this directory, and nothing here can ask which agent it is.",
+	suggestion: "Run `stackbone dev` in a terminal to pick an agent, or write .stackbone/project.json yourself (`stackbone agents get <slug>` prints the id). `stackbone init` scaffolds a NEW project over this one — not what you want for a project you were handed."
+});
+/**
+* Link this directory to an agent, asking which one, and return the config the
+* boot needs. Throws {@link unlinkedProjectError} when nobody can be asked.
+*/
+var linkProjectOnDemand = async (ctx, projectRoot, deps = {}) => {
+	if (!canPromptInteractively(ctx)) throw unlinkedProjectError();
+	const list = deps.listAgents ?? listAgents;
+	const activeOrg = deps.getActiveOrganization ?? getActiveOrganization;
+	const register = deps.registerAgentEager ?? registerAgentEager;
+	const askAgent = deps.promptForAgent ?? promptForAgentInteractively;
+	const askName = deps.promptForNewName ?? promptForNewNameInteractively;
+	const org = await activeOrg(ctx);
+	const name = await askAgent((await list(ctx)).map((a) => ({
+		slug: a.slug,
+		name: a.name ?? a.slug
+	}))) ?? slugifyProjectName(await askName(basename(projectRoot)));
+	if (name.length === 0) throw new StackboneCliError({
+		code: "generic",
+		message: "That name has no letters or numbers in it, so it cannot become an agent slug.",
+		suggestion: "Run `stackbone dev` again and give the agent a name."
+	});
+	const registration = await register(ctx, {
+		organizationSlug: org.slug,
+		name
+	});
+	const config = await writeProjectConfig(ctx, registration.agent, {
+		root: projectRoot,
+		force: false
+	}, {
+		localDevInstallationId: registration.localDev.id,
+		organizationSlug: registration.localDev.organizationSlug,
+		agentSlug: registration.localDev.agentSlug
+	});
+	await ensureGitignore(projectRoot);
+	log.success(registration.created ? `Registered agent "${registration.agent.slug}" and linked this directory to it.` : `Linked this directory to agent "${registration.agent.slug}".`);
+	return config;
+};
+//#endregion
 //#region src/commands/dev/print-contract.ts
 var defaultWriteStdout = (chunk) => {
 	process.stdout.write(chunk);
@@ -53766,12 +53964,7 @@ var createReloadRenderer = () => {
 	};
 };
 var buildHandler$2 = (ctx, flags) => protectedCommand(async (innerCtx) => {
-	const config = await innerCtx.projectConfig.read();
-	if (!config) throw new StackboneCliError({
-		code: "no_project",
-		message: "No project linked in this directory",
-		suggestion: "Run `stackbone init` or `stackbone link` first"
-	});
+	const config = await innerCtx.projectConfig.read() ?? await linkProjectOnDemand(innerCtx, resolve(innerCtx.cwd));
 	if (!innerCtx.flags.json) intro(formatBrandHeader({
 		version: STACKBONE_CLI_BUILD_VERSION,
 		command: "dev",
@@ -53896,7 +54089,7 @@ var buildHandler$2 = (ctx, flags) => protectedCommand(async (innerCtx) => {
 			tunnelUrl: session.publicUrl,
 			localUrl: session.emulatorUrl,
 			deeplink,
-			contractVersion: 14,
+			contractVersion: 15,
 			capabilityCount: EMULATOR_CAPABILITIES.length,
 			agentName: agent.name,
 			colors: process.stdout.isTTY === true
@@ -54785,6 +54978,18 @@ it. The emulator API listens on \`http://127.0.0.1:4242\` by default. The tunnel
 mandatory: it fills the \`local_tunnel_url\` field on the \`installation\` row and
 yields the Studio deeplink.
 
+**A project that was handed to you links itself here.** \`.stackbone/\` is
+gitignored, so a project cloned from someone else's repository arrives with no
+link. \`dev\` lists the agents your organization owns, lets you pick one or create
+a new one named after the folder, writes \`.stackbone/project.json\` and carries on
+booting. Neither of the alternatives fits this case: \`stackbone init\` registers a
+_new_ agent and scaffolds its own \`package.json\` over the project you just
+received, and \`stackbone link\` is for registering a box you already deployed, so
+it requires its URL, HMAC secret and image tag.
+
+Non-interactive runs (\`--json\`, \`--yes\`, CI, no terminal) still fail rather than
+guessing, and say what to do instead.
+
 The project is a **workspace**: every \`deep-agents/<name>/index.ts\`, plus
 every \`workflows/<name>.workflow.ts\`, discovered by convention (with an
 explicit \`stackbone.config.ts\` override for workflows). Boot:
@@ -56446,10 +56651,12 @@ them.
   the CLI must run from WSL2, Docker Desktop with WSL2 integration enabled
   (or Docker Engine inside the Ubuntu distro) covers it.
 - **A project:** run \`stackbone init\` to scaffold a workspace shell (a
-  \`deep-agents/\` folder, a \`workflows/\` folder and supporting files), or
-  \`stackbone link\` to connect an existing directory. Add pieces over time with
-  \`stackbone add agent <name>\`, \`stackbone add workflow <name>\` or
-  \`stackbone add workflow-agent <name>\`.
+  \`deep-agents/\` folder, a \`workflows/\` folder and supporting files). Add
+  pieces over time with \`stackbone add agent <name>\`,
+  \`stackbone add workflow <name>\` or \`stackbone add workflow-agent <name>\`.
+  A project someone handed you needs none of that: it arrives unlinked, and
+  \`dev\` asks which agent it is. See
+  [A project that arrived without a link](#a-project-that-arrived-without-a-link).
 - **At least one agent or workflow:** \`stackbone dev\` discovers your workspace
   by convention, any \`deep-agents/<name>/index.ts\` (or a
   \`workflows/<name>.workflow.ts\`) is enough to activate the runtime. A
@@ -56461,6 +56668,27 @@ them.
   \`STACKBONE_FRPC_BIN\` to point at a system install when your environment
   forbids untrusted binaries.
 
+## A project that arrived without a link
+
+A project you cloned from someone else's repository has no link to an agent.
+\`.stackbone/\` is gitignored, so the link never travels with the code.
+
+\`stackbone dev\` does not stop for that. It lists the agents your organization
+owns, lets you pick one or create a new one named after the folder, writes
+\`.stackbone/project.json\`, adds it to \`.gitignore\` and carries on booting.
+
+Neither of the other commands fits this case:
+
+- \`stackbone init\` registers a **new** agent and writes its own \`package.json\`,
+  \`tsconfig.json\` and scaffold over the project you were just handed.
+- \`stackbone link\` registers a box you have already deployed, so it requires
+  that box's URL, HMAC secret and image tag.
+
+A run that cannot ask fails instead of guessing, and says what to do instead.
+That covers any run without a terminal, a \`CI\` environment variable, \`--yes\` or
+\`--json\`. See
+[This directory is not linked to an agent](/docs/cli/troubleshooting#this-directory-is-not-linked-to-an-agent).
+
 ## Synopsis
 
 \`\`\`sh
@@ -57118,6 +57346,26 @@ Stages you do not use are skipped: no workflows means no \`workflows\` or
 
 ## \`stackbone dev\` failures
 
+### This directory is not linked to an agent
+
+**Symptom:** \`stackbone dev\` exits before any stage runs with \`no_project\` and
+"No project linked in this directory, and nothing here can ask which agent it
+is."
+
+**Cause:** the project has no \`.stackbone/project.json\` and this run cannot
+prompt for one. \`.stackbone/\` is gitignored, so a project cloned from someone
+else's repository always arrives unlinked, and a run without a terminal (or one
+with a \`CI\` environment variable, \`--yes\` or \`--json\`) has nobody to ask.
+
+**Fix:** run \`stackbone dev\` once from a terminal and pick the agent. It writes
+the link, and every later run reuses it, scripted or not. To link without a
+prompt, write \`.stackbone/project.json\` yourself; \`stackbone agents get <slug>\`
+prints the agent id it needs.
+
+Reaching for \`stackbone init\` here is the common mistake: it registers a new
+agent and scaffolds over the project you were handed. Full contract:
+[A project that arrived without a link](/docs/cli/local-development#a-project-that-arrived-without-a-link).
+
 ### Docker not running, or the datastore is unhealthy
 
 **Symptom:** the \`docker\` stage fails, or \`platform-migrations\` /
@@ -62648,84 +62896,6 @@ var createHitlCommand = defineGroup({
 	}
 });
 //#endregion
-//#region src/services/register-agent.ts
-var registerAgentEager = async (ctx, input) => {
-	const slug = input.slug ?? input.name;
-	let agent;
-	let created = false;
-	try {
-		agent = await getAgentByOwnerAndSlug(ctx, input.organizationSlug, slug);
-	} catch (err) {
-		if (!(isStackboneCliError(err) && err.code === "not_found")) throw err;
-		agent = await createAgent(ctx, {
-			organizationSlug: input.organizationSlug,
-			name: input.name,
-			slug,
-			...input.description !== void 0 ? { description: input.description } : {}
-		});
-		created = true;
-	}
-	const localDev = await upsertLocalDevInstallation(ctx, {
-		creatorOrganizationSlug: input.organizationSlug,
-		agentTemplateSlug: agent.slug
-	});
-	return {
-		agent,
-		localDev,
-		created
-	};
-};
-//#endregion
-//#region src/services/project.service.ts
-var GITIGNORE_MARKER_BEGIN$1 = "# >>> stackbone >>>";
-var GITIGNORE_BLOCK = [
-	GITIGNORE_MARKER_BEGIN$1,
-	".stackbone/",
-	"node_modules/",
-	"dist/",
-	"# <<< stackbone <<<",
-	""
-].join("\n");
-var exists = async (path) => {
-	try {
-		await stat(path);
-		return true;
-	} catch (err) {
-		if (isENOENT(err)) return false;
-		throw err;
-	}
-};
-var writeProjectConfig = async (ctx, agent, input, extras = {}) => {
-	const config = {
-		schemaVersion: 1,
-		organizationId: agent.organizationId,
-		agentId: agent.id,
-		controlPlaneUrl: ctx.apiUrl,
-		...extras.localDevInstallationId !== void 0 ? { localDevInstallationId: extras.localDevInstallationId } : {},
-		...extras.organizationSlug !== void 0 ? { organizationSlug: extras.organizationSlug } : {},
-		...extras.agentSlug !== void 0 ? { agentSlug: extras.agentSlug } : {},
-		...extras.starter !== void 0 ? { starter: extras.starter } : {}
-	};
-	await mkdir(join(input.root, ".stackbone"), { recursive: true });
-	await writeFile(join(input.root, ".stackbone", "project.json"), JSON.stringify(config, null, 2));
-	return config;
-};
-var ensureGitignore = async (root) => {
-	const path = join(root, ".gitignore");
-	let current = "";
-	try {
-		current = await readFile(path, "utf8");
-	} catch (err) {
-		if (!isENOENT(err)) throw err;
-	}
-	if (current.includes(GITIGNORE_MARKER_BEGIN$1)) return;
-	await writeFile(path, current.length > 0 && !current.endsWith("\n") ? `${current}\n${GITIGNORE_BLOCK}` : `${current}${GITIGNORE_BLOCK}`);
-};
-var detectExistingProjectFiles = async (root, paths) => {
-	const checks = await Promise.all(paths.map((p) => exists(join(root, p))));
-	return paths.filter((_, i) => checks[i]);
-};
-//#endregion
 //#region src/services/skills.service.ts
 var execFileAsync = promisify(execFile);
 /**
@@ -63221,6 +63391,84 @@ var verifyDeploymentSecret = async (args) => {
 	return readIdentityVerification(response);
 };
 //#endregion
+//#region src/services/handshake.service.ts
+init_src$13();
+/** Public, credential-free handshake every deployed box serves. */
+var CONTRACT_PATH = "/api/contract";
+/**
+* Something is at that address, but it is not a Stackbone box: a gateway's error
+* page, a company site, a load balancer in front of the wrong service. Kept
+* distinct from "nothing answered" because the remedy is different — one is an
+* address to correct, the other a machine to go and look at.
+*/
+var notAHandshake = (url, status, cause) => new StackboneCliError({
+	code: "generic",
+	message: `${url} answered with HTTP ${status}, but not with a Stackbone box handshake`,
+	suggestion: "Check --url points at the box itself: a company site, or a load balancer in front of the wrong service, answers just like this.",
+	cause
+});
+/**
+* Asks a box which protocol version it speaks, before it is registered.
+*
+* Uses a DIRECT `fetch` — `ctx.http` refuses absolute URLs on purpose (it only
+* ever talks to the control plane), and this is a cross-host call to the
+* customer's own box. The handshake is public and takes no credential, which is
+* what makes it usable here: at this point in `link` nothing has been registered,
+* so there is no identity to present anyway.
+*/
+var readBoxContract = async (args) => {
+	const fetchImpl = args.fetchImpl ?? fetch;
+	let contractUrl;
+	try {
+		contractUrl = new URL(CONTRACT_PATH, args.url).toString();
+	} catch (cause) {
+		throw new StackboneCliError({
+			code: "generic",
+			message: `--url is not a valid URL: ${args.url}`,
+			suggestion: "Pass the full public URL of the deployed agent, e.g. https://agent.example.com",
+			cause
+		});
+	}
+	let response;
+	try {
+		response = await fetchImpl(contractUrl, { method: "GET" });
+	} catch (cause) {
+		throw new StackboneCliError({
+			code: "generic",
+			message: `Nothing answered at ${args.url}, so there is no way to read which protocol version that box speaks`,
+			suggestion: "Check --url is the public address of the running container and that this machine can reach it.",
+			cause
+		});
+	}
+	let body;
+	try {
+		body = await response.json();
+	} catch (cause) {
+		throw notAHandshake(args.url, response.status, cause);
+	}
+	const parsed = contractResponseSchema.safeParse(body);
+	if (!response.ok || !parsed.success) throw notAHandshake(args.url, response.status, parsed.success ? body : parsed.error);
+	return parsed.data;
+};
+/**
+* Refuses a box this product cannot register, whatever door it came through.
+*
+* Pure and total: it reads the version the handshake reported and nothing else.
+* The floor is `MIN_SUPPORTED_DEPLOYMENT_REGISTRATION_CONTRACT_VERSION`, NOT the
+* SDK-wide `MIN_SUPPORTED_CONTRACT_VERSION` — that one is 1, the handshake schema
+* already refuses anything below 1, and a guard built on it could never fire.
+* The sentence comes from the shared source the browser wizard prints too, so an
+* operator who tries the other door reads the same story about the same box.
+*/
+var assertBoxCanBeRegistered = (contract) => {
+	if (supportsDeploymentRegistration(contract.version)) return;
+	throw new StackboneCliError({
+		code: "generic",
+		message: deploymentRegistrationRefusal(contract.version),
+		suggestion: "Re-run `stackbone link` once the box is running a current image."
+	});
+};
+//#endregion
 //#region src/commands/link/link.command.ts
 var requireLinkField = (value, flag, description) => {
 	const trimmed = (value ?? "").trim();
@@ -63307,6 +63555,8 @@ var runLink = async (ctx, args) => {
 	const activeOrg = await getActiveOrganization(ctx);
 	const agent = await getAgentByOwnerAndSlug(ctx, activeOrg.slug, chosenSlug);
 	if (!ctx.flags.json) log.step(`Linking ${targetDir} to ${agent.slug}`);
+	if (!ctx.flags.json) log.step("Reading the box protocol version");
+	assertBoxCanBeRegistered(await readBoxContract({ url }));
 	if (!ctx.flags.json) log.step("Verifying the --secret against the deployed container");
 	const identityVerification = await verifyDeploymentSecret({
 		url,
@@ -65605,7 +65855,7 @@ if (shouldReexecUnderWinpty({
 if (isVersionFlag(rawArgs)) {
 	process.stdout.write(`${formatVersionOutput({
 		cliVersion: STACKBONE_CLI_BUILD_VERSION,
-		contractVersion: 14
+		contractVersion: 15
 	})}\n`);
 	process.exit(0);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackbone/cli",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "license": "UNLICENSED",
   "type": "module",
   "bin": {