insta 0.0.77 → 0.0.79

package/dist/api.js

@@ -67,11 +67,9 @@ export class ApiClient {
     }
     // Returns parsed body for status < 400 (incl. 202); throws ApiError otherwise.
     async request(method, path, body, opts = {}) {
-        const res = await this.raw(method, path, body, opts.auth ?? true, opts);
+        const res = await this.rawRequest(method, path, body, opts);
         if (agentMode() && res.status === 202 && res.body?.status === 'approval_required')
             throw new AgentApprovalRequired(res.body);
-        if (res.status >= 400)
-            throw new ApiError(res.status, res.body?.error ?? `HTTP ${res.status}`, res.body);
         return res.body;
     }
     // Like request but returns {status, body} so callers can branch on 202 (approval_required).
@@ -93,12 +91,13 @@ export class ApiClient {
         const headers = { 'Content-Type': 'application/json', 'Insta-Hints': '1', 'User-Agent': USER_AGENT };
         if (auth && this.cfg.accessToken)
             headers.Authorization = `Bearer ${this.cfg.accessToken}`;
+        const payload = body === undefined ? undefined : JSON.stringify(body);
         if (auth && scope.evidence !== false)
-            Object.assign(headers, await agentHeaders(this, method, path, body === undefined ? '' : JSON.stringify(body), scope));
+            Object.assign(headers, await agentHeaders(this, method, path, payload ?? '', scope));
         const res = await this.fetchImpl(this.apiUrl + path, {
             method,
             headers,
-            body: body === undefined ? undefined : JSON.stringify(body),
+            body: payload,
             signal: scope.signal,
         });
         const text = await res.text();

package/dist/commands/auth.js

@@ -193,7 +193,7 @@ export async function deviceGrant(post, wait = sleepSeconds, open) {
                 continue;
             } // RFC 8628 §3.5: back off by 5s
             // The platform's per-IP limiter answers a bare HTTP 429 (no OAuth error code) when a poll
-            // trips it — seen on prod 2026-09-10 after ~8 min of steady 5s polling. That is the same
+            // trips it. That is the same
             // instruction as slow_down: the code is still pending, so back off and keep waiting rather
             // than abort a login the human may be one click away from approving.
             if (e.status === 429) {

package/dist/commands/billing.js

@@ -85,10 +85,8 @@ export async function billing(opts) {
 }
 // insta billing upgrade <tier> — start a Stripe Checkout to subscribe the org to a paid tier.
 export async function billingUpgrade(tier, opts) {
-    // pro|team, matching what POST /orgs/:orgId/billing/checkout actually accepts. This said
-    // pro|enterprise, which was wrong both ways: `team` is a real self-serve tier and was refused
-    // here, and `enterprise` is per-deal and 400s at the server. The suspension hint above now names
-    // the org's own tier, so a Team org was being sent to a command that rejected it.
+    // pro|team, matching what POST /orgs/:orgId/billing/checkout accepts: `team` is a real
+    // self-serve tier, and `enterprise` is per-deal and 400s at the server.
     if (tier !== 'pro' && tier !== 'team')
         die('tier must be pro|team');
     const api = await ApiClient.load();

package/dist/commands/compute.js

@@ -64,8 +64,7 @@ export function domainGuidanceLines(r, ctx = {}) {
 // Whether this provider reports an edge routing target AT ALL. The compute plane's domain view
 // always carries an `ssl` status, so a plane answer without `origin` is a daemon too old to report
 // where the hostname resolves — we cannot confirm routing, and must not call it serving. A Fly
-// answer carries no `ssl` and has no per-hostname origin concept, so its own verdict stands
-// (r2d2 round 1 Critical: "no target reported" was previously treated as ready for both).
+// answer carries no `ssl` and has no per-hostname origin concept, so its own verdict stands.
 const reportsOrigin = (r) => r.ssl !== undefined;
 // Where the hostname actually resolves — the region-specific origin the plane requested vs what
 // Cloudflare holds. Each shape carries its action; absent fields are reported as absent.
@@ -116,9 +115,8 @@ export function domainStatusLines(r, ctx = {}) {
     // A record is settled only when the platform says `ok` — or, for a provider that reports no
     // per-record status at all (Fly), when it vouched for the whole set with `configured`. missing,
     // mismatch and never-checked are each outstanding and each add a blocker. Applying this to only
-    // the ownership TXT and the FIRST routing record was the bug (r2d2 round 3): every other record
-    // rendered from `configured` alone and blocked nothing, so an apex whose AAAA was missing, or a
-    // still-pending validation record, could ride under a `serving https://…` line.
+    // some records lets an apex whose AAAA is missing, or a still-pending validation record, ride
+    // under a `serving https://…` line.
     const verdictOf = (d) => d.status ?? (r.configured ? 'ok' : 'unchecked');
     if (txt) {
         const st = verdictOf(txt);
@@ -139,7 +137,7 @@ export function domainStatusLines(r, ctx = {}) {
     }
     else if (reportsOrigin(r)) {
         // The stage is drawn even with no record to draw it from: an omitted stage reads as "not
-        // required", when in fact the platform told us nothing to publish (cubic P2). Only the plane
+        // required", when in fact the platform told us nothing to publish. Only the plane
         // proves ownership by TXT, so only a plane answer missing one is a problem.
         stage('ownership', 'unknown', 'the platform returned no ownership TXT for this domain — nothing to publish yet; ask an operator');
         blockers.push('no ownership TXT from the platform');
@@ -148,10 +146,10 @@ export function domainStatusLines(r, ctx = {}) {
         stage('ownership', 'n/a', '(this provider does not use an ownership TXT)');
     }
     if (routing.length === 0) {
-        // No routing record for the hostname — whatever ELSE came back. Keying this on an entirely
-        // empty record set was the bug (r2d2 round 2): a payload carrying only the ownership TXT
-        // skipped the stage and added no blocker, so a `configured: true` answer with a live cert and
-        // a confirmed origin printed `serving` for a hostname with nothing pointing at us.
+        // No routing record for the hostname — whatever ELSE came back. Keyed on an entirely empty
+        // record set, a payload carrying only the ownership TXT skips the stage and adds no blocker,
+        // so a `configured: true` answer with a live cert and a confirmed origin prints `serving`
+        // for a hostname with nothing pointing at us.
         stage('cname', 'unknown', 'the platform returned no routing record for this domain — nothing to publish yet; ask an operator');
         blockers.push('no routing record from the platform');
     }
@@ -213,7 +211,7 @@ export function domainStatusLines(r, ctx = {}) {
     }
     const resolve = domainResolveLine(r);
     out.push(resolve.line);
-    // An error STATE is a blocker whether or not the plane sent a reason with it (cubic P2): a row
+    // An error STATE is a blocker whether or not the plane sent a reason with it: a row
     // that says `error` has not been observed serving, and saying otherwise is the blackhole lie.
     if (r.status === 'error') {
         stage('error', r.status, r.errorReason || '(the plane reported an error state with no reason)');
@@ -230,7 +228,7 @@ export function domainStatusLines(r, ctx = {}) {
     // `serving` is claimed only when every stage above agreed: the provider says configured, the
     // routing target is confirmed, and NOTHING is outstanding. A blocker beside a `configured: true`
     // answer means the record set and the verdict disagree — report the disagreement, never paper
-    // over it with a URL the user would then trust (cubic P1).
+    // over it with a URL the user would then trust.
     if (r.configured && blockers.length === 0)
         stage('serving', `https://${r.hostname}`, '');
     else
@@ -249,7 +247,7 @@ export function domainConflictMessage(host, e, services, ctx = {}) {
     const owner = m?.[1] && m[1] !== 'another' ? m[1] : undefined;
     const region = m?.[2];
     // The release command must name the OWNER's group, and the branch the user is working on — a
-    // command that defaults back to the linked branch would release nothing (cubic P2).
+    // command that defaults back to the linked branch would release nothing.
     const release = (group) => `insta compute remove-domain ${host}${flags({ group, branch: ctx.branch })}`;
     if (owner) {
         const here = services.find((s) => s.type === 'compute' && s.name === owner);
@@ -379,14 +377,6 @@ export async function computeStatus(serviceName, opts) {
     info(`compute ${serviceName ?? id}: desired=${r.desiredState}  live=${r.state}`);
 }
 // ---- exec (one-shot command; no interactive shell/PTY) ----
-// `insta compute exec [service] -- <command> [args…]`: the command must reach the platform
-// byte-for-byte and can itself contain dashes or another `--`, so it can't be a normal commander
-// positional — with `service` optional, commander flattens everything past the literal `--` into
-// one operand list and has no way to tell "no service, command starts here" apart from "service IS
-// the first command token". Splitting argv on the first literal `--` after `compute exec`
-// ourselves, before commander ever parses it, removes the ambiguity; this is the only place in the
-// whole CLI a bare `--` has this meaning, so nothing else is affected. Exported for a direct,
-// network-free unit test — this split is the seam most likely to regress.
 /** The options `insta compute exec` declares — the one source of truth. index.ts builds the
  *  commander command from this list, and the payload scan below uses it to know where the CLI's
  *  own arguments stop. Adding an option here reaches both. */
@@ -650,9 +640,9 @@ export function volumeWriteLine(name, body) {
 export function volumeDeleteLine(name) {
     return `compute ${name}: volume deleted — the disk and its data are gone; suspend fast-wake and scale-out are back`;
 }
-// Map a DELETE .../volume failure. Pure, exported for tests (r2d2 review rounds 1+2: this is the
-// close-call branch worth pinning). An older backend has no DELETE route, and what its 404 looks
-// like depends on who answered: the real platform (Fastify, no custom notFound handler) sends its
+// Map a DELETE .../volume failure. Pure, exported for tests. An older backend has no DELETE
+// route, and what its 404 looks like depends on who answered: the real platform (Fastify, no
+// custom notFound handler) sends its
 // default body {"message":"Route DELETE:/… not found","error":"Not Found"} → ApiError message
 // "Not Found"; a proxy or bodyless 404 leaves ApiError's own "HTTP 404" fallback. BOTH are the
 // generic route-miss shape and mean version skew, not a bug — parroting them would send the user
@@ -750,7 +740,7 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
-import { aliasFor, certifiesPublicKey, hasOwnedBlock, isSafeAlias, isSafeConfigValue, isSafeSSHHost, isSafeSSHUsername, isSafeTimestamp, isSSHCertificateRecord, mayWidenCAHost, parseCAPublicKey, planCertAuthority, renderConfigBlock, revertCertAuthority, upsertConfigBlock, } from './ssh-config.js';
+import { aliasFor, certifiesPublicKey, hasOwnedBlock, isSafeAlias, isSafeConfigValue, isSafeSSHHost, isSafeSSHUsername, isSafeTimestamp, isSSHCertificateRecord, mayWidenCAHost, parseCAPublicKey, planCertAuthority, renderConfigBlock, revertCertAuthority, upsertConfigBlock, ownedBlock, ownedBlockIsFirst } from './ssh-config.js';
 /** Where this CLI keeps its own SSH material. Deliberately NOT ~/.ssh: we never
  *  touch a key the user already had, and a dedicated key pairs with
  *  IdentitiesOnly to avoid being identified by the wrong one. */
@@ -769,6 +759,15 @@ export const instaAliasStorePath = () => join(instaSSHDir(), 'aliases.json');
 export const userKnownHostsPath = () => join(homedir(), '.ssh', 'known_hosts');
 /** The renewal-hook command prefix. ssh-config.ts appends the validated alias. */
 export const ENSURE_CERT_COMMAND = 'insta __ssh-ensure-cert';
+/** The gateway's public port when the plane does not say: :2222, the port the
+ *  lane shipped on (:22 waits for a compliance exception). The plane's answer
+ *  in a mint response ALWAYS wins over this; it exists for stores and planes
+ *  that predate the `port` field, so a working alias does not stop working. */
+export const DEFAULT_SSH_PORT = 2222;
+/** A TCP port as the plane returns it: an integer, 1..65535. */
+export function isValidPort(v) {
+    return typeof v === 'number' && Number.isInteger(v) && v >= 1 && v <= 65535;
+}
 /** Never throws: a missing or hand-mangled store must degrade to "nothing is
  *  set up", not break `ssh` for every alias. */
 export function readAliasStore(path = instaAliasStorePath()) {
@@ -800,6 +799,7 @@ export function isValidAliasRecord(r) {
     return typeof v.projectId === 'string' && v.projectId !== ''
         && typeof v.serviceId === 'string' && v.serviceId !== ''
         && (v.branch === undefined || typeof v.branch === 'string')
+        && (v.port === undefined || isValidPort(v.port))
         && isSafeConfigValue(v.host) && isSafeConfigValue(v.username);
 }
 /** Refuse to point an existing alias at a different service.
@@ -839,7 +839,7 @@ export function hostEntries(store) {
         // sit where the rendering does.
         .filter(([alias, r]) => isSafeAlias(alias) && isValidAliasRecord(r))
         .sort(([a], [b]) => a.localeCompare(b))
-        .map(([alias, r]) => ({ alias, hostName: r.host, user: r.username, certificateFile: instaCertPath(alias) }));
+        .map(([alias, r]) => ({ alias, hostName: r.host, user: r.username, port: r.port ?? DEFAULT_SSH_PORT, certificateFile: instaCertPath(alias) }));
 }
 /**
  * When `ssh-keygen -L` output says the certificate stops being valid, or
@@ -969,6 +969,11 @@ export function validateCertResponse(body) {
     // are refused rather than rendered.
     if (!isSafeTimestamp(b.expiresAt))
         throw new Error('the platform returned an unusable certificate expiry');
+    // Optional only because planes predating the field exist; PRESENT and wrong
+    // is refused, never coerced -- a port we made up is a connection that hangs.
+    if (b.port !== undefined && !isValidPort(b.port)) {
+        throw new Error(`the platform returned an unusable ssh port: ${JSON.stringify(String(b.port).slice(0, 16))}`);
+    }
     // Parsed here rather than at install time so a malformed key fails before
     // anything is written, instead of after the alias is already recorded.
     if (b.caPublicKey !== undefined)
@@ -992,9 +997,7 @@ const sshKeygenVerifyCert = (certPath) => {
  * So the authority is `ssh-keygen -L`, run against a temporary file, and the
  * real file is only replaced once it passes. Spawning it here costs nothing
  * new: certNeedsRenewal already runs the same binary on this same path, every
- * time a certificate exists. (An earlier round declined this on the grounds
- * that a subprocess did not belong on the renewal path -- that reasoning was
- * simply wrong about what the path already does.)
+ * time a certificate exists.
  *
  * A missing ssh-keygen is a REFUSAL, not a pass: it means we cannot confirm,
  * and an unconfirmable certificate must not displace one that works. Nothing
@@ -1235,6 +1238,40 @@ function withLockedFile(name, fn, { waitMs, staleMs, sleep, busy }) {
         sleep(LOCK_POLL_MS);
     }
 }
+/** The block ssh_config SHOULD carry for this store, rendered the one way. */
+function renderInstalledBlock(store) {
+    return renderConfigBlock({
+        entries: hostEntries(store),
+        identityFile: instaKeyPath(),
+        knownHostsFile: userKnownHostsPath(),
+        ensureCertCommand: ENSURE_CERT_COMMAND,
+    });
+}
+/** Whether the installed block differs from what the store renders -- the ONE
+ *  predicate for "rewrite ssh_config". A host move, a port the plane changed,
+ *  and a stanza written before the Port line existed all show up here; a
+ *  renewal whose response changed nothing does not, which matters because
+ *  OpenSSH is reading the file while the hook runs and a rename over an open
+ *  file fails on Windows. No installed block = nothing to repair (setup owns
+ *  the first write). */
+function configBlockStale(store) {
+    let existing;
+    try {
+        existing = readFileSync(join(homedir(), '.ssh', 'config'), 'utf8');
+    }
+    catch {
+        return false;
+    }
+    const installed = ownedBlock(existing);
+    if (installed === undefined)
+        return false;
+    // Position is content too: a block that has slid below other configuration
+    // is shadowed keyword by keyword (first obtained value wins), whatever its
+    // text says. The rewrite puts it back where setup wrote it, at the top.
+    if (!ownedBlockIsFirst(existing))
+        return true;
+    return installed.replace(/\n+$/, '') !== renderInstalledBlock(store).replace(/\n+$/, '');
+}
 function installConfigBlock(store) {
     const cfg = join(homedir(), '.ssh', 'config');
     mkdirSync(dirname(cfg), { recursive: true, mode: 0o700 });
@@ -1246,12 +1283,7 @@ function installConfigBlock(store) {
     // target says.
     const existedBefore = pathExists(cfg);
     const existing = readUserText(cfg);
-    const block = renderConfigBlock({
-        entries: hostEntries(store),
-        identityFile: instaKeyPath(),
-        knownHostsFile: userKnownHostsPath(),
-        ensureCertCommand: ENSURE_CERT_COMMAND,
-    });
+    const block = renderInstalledBlock(store);
     // Backed up: this is the file that decides whether the user can ssh anywhere
     // at all, and our block goes at the TOP of it.
     writeFileAtomicSync(cfg, upsertConfigBlock(existing, block), { mode: 0o600, backup: true });
@@ -1370,6 +1402,20 @@ export async function ensureCertForAlias(alias, timeoutMs = RENEWAL_REQUEST_TIME
     try {
         if (!isSafeAlias(alias))
             return;
+        // Repair BEFORE the renewal gate, because the stanza can lag the store
+        // with no certificate due: an alias set up before the Port line existed
+        // dials :22 on every connection, and waiting for its certificate to age
+        // would leave it failing for up to the certificate's lifetime. The
+        // predicate is content drift, so the common case -- an up-to-date stanza --
+        // is one file read and a string compare, with no lock taken; only a stale
+        // stanza takes the alias-store lock, re-checks under it and rewrites.
+        if (configBlockStale(readAliasStore())) {
+            withAliasStoreLock(() => {
+                const store = readAliasStore();
+                if (store[alias] && configBlockStale(store))
+                    installConfigBlock(store);
+            }, { waitMs: KNOWN_HOSTS_LOCK_WAIT_MS });
+        }
         if (!certNeedsRenewal(instaCertPath(alias)))
             return;
         // An IDE opens several connections at once and `scp` adds more, so the
@@ -1433,9 +1479,16 @@ export async function ensureCertForAlias(alias, timeoutMs = RENEWAL_REQUEST_TIME
                     return;
                 if (!certNeedsRenewal(instaCertPath(alias)))
                     return;
+                // The plane's answer wins, on every field it answers. `moved` is the
+                // host/user half and keeps its CA requirement below (a new host needs
+                // an anchor); the port has no such requirement but is part of the
+                // record all the same, and a legacy record without one gains it here
+                // so the stanza can carry the line.
+                const port = out.port ?? held.port ?? DEFAULT_SSH_PORT;
                 const moved = held.host !== out.host || held.username !== out.username;
-                const store = moved
-                    ? { ...before, [alias]: { ...held, host: out.host, username: out.username } }
+                const recordChanged = moved || held.port !== port;
+                const store = recordChanged
+                    ? { ...before, [alias]: { ...held, host: out.host, username: out.username, port } }
                     : before;
                 const installed = configBlockInstalled();
                 const ca = out.caPublicKey;
@@ -1463,11 +1516,13 @@ export async function ensureCertForAlias(alias, timeoutMs = RENEWAL_REQUEST_TIME
                 // host into a renewal that gives up -- one failed renewal and a
                 // `--setup` to repair it, never a half-moved alias.
                 const steps = [];
-                if (moved)
+                if (recordChanged)
                     steps.push(() => { const back = snapshotForUndo(instaAliasStorePath()); writeAliasStore(store); return back; });
                 if (ca !== undefined)
                     steps.push(() => installCertAuthority(hostPatternFor(out.host), ca));
-                if (moved && installed)
+                // Drift, not "moved": a changed port rewrites the stanza; an unchanged
+                // response leaves the file alone (see configBlockStale).
+                if (installed && configBlockStale(store))
                     steps.push(() => installConfigBlock(store));
                 steps.push(() => out.staged.commit());
                 // ONE section from reading the anchor to committing the certificate
@@ -1653,11 +1708,10 @@ function processAlive(pid) {
  *  move or remove the lock, so there is no window in which the file is
  *  missing for something to slip in through.
  *
- *  And the takeover NEVER UNLINKS THE PATH. The first version verified the
- *  token, unlinked the lock and created its own, and nothing tied that unlink
- *  to the inode it had verified: a holder releasing in between let a third
- *  process create a fresh lock at the path, which the breaker then deleted.
- *  Here the breaker writes its token INTO the inode the two names share.
+ *  And the takeover NEVER UNLINKS THE PATH: an unlink-then-create is not tied
+ *  to the inode that was verified, so a holder releasing in between lets a
+ *  third process create a fresh lock at the path, which the breaker then
+ *  deletes. Here the breaker writes its token INTO the inode the two names share.
  *  `path` keeps its inode throughout, so there is no moment at which the lock
  *  at `path` can have become somebody else's between the check and the act:
  *  the holder judged dead cannot release, every other breaker is behind the
@@ -1752,7 +1806,7 @@ export async function computeSSH(serviceName, opts, deps = {}) {
             assertAliasFree(before, alias, { projectId: p.projectId, serviceId: svc.id, branch });
             const store = {
                 ...before,
-                [alias]: { projectId: p.projectId, ...(branch ? { branch } : {}), serviceId: svc.id, host: out.host, username: out.username },
+                [alias]: { projectId: p.projectId, ...(branch ? { branch } : {}), serviceId: svc.id, host: out.host, username: out.username, port: out.port ?? DEFAULT_SSH_PORT },
             };
             // Whether ~/.ssh is BACKING this store, not merely whether --setup was
             // passed. The store and the certificate are rewritten by every issuance,
@@ -1811,9 +1865,9 @@ export async function computeSSH(serviceName, opts, deps = {}) {
         out.staged.discard();
     }
     if (opts.json)
-        return printJson({ alias, host: out.host, username: out.username, expiresAt: out.expiresAt, configured: installed });
+        return printJson({ alias, host: out.host, username: out.username, port: out.port ?? DEFAULT_SSH_PORT, expiresAt: out.expiresAt, configured: installed });
     for (const line of sshAdvice({
-        alias, host: out.host, username: out.username, expiresAt: out.expiresAt, serviceName: svc.name,
+        alias, host: out.host, username: out.username, port: out.port ?? DEFAULT_SSH_PORT, expiresAt: out.expiresAt, serviceName: svc.name,
         configured: installed, identityFile: instaKeyPath(), certificateFile: instaCertPath(alias),
     }))
         emit(line);
@@ -1830,7 +1884,7 @@ export async function computeSSH(serviceName, opts, deps = {}) {
  */
 export function sshAdvice(r) {
     const head = r.configured
-        ? [`ssh ${r.alias}  →  ${r.username}@${r.host}`]
+        ? [`ssh ${r.alias}  →  ${r.username}@${r.host} (port ${r.port})`]
         : [
             // Every option here is load-bearing. The key lives at
             // ~/.insta/ssh/id_ed25519 and the certificate at <alias>-cert.pub;
@@ -1839,7 +1893,9 @@ export function sshAdvice(r) {
             // this command just issued -- it fails, having printed success.
             // IdentitiesOnly stops a loaded agent from spending the server's
             // MaxAuthTries on unrelated keys before ours is ever tried.
-            `ssh -i ${shQuote(r.identityFile)} -o CertificateFile=${shQuote(r.certificateFile)} -o IdentitiesOnly=yes ${shQuote(`${r.username}@${r.host}`)}`,
+            // -p is not optional: the gateway is on :2222 and :22 is closed, so a
+            // pasted command without it fails before the credential is ever tried.
+            `ssh -p ${r.port} -i ${shQuote(r.identityFile)} -o CertificateFile=${shQuote(r.certificateFile)} -o IdentitiesOnly=yes ${shQuote(`${r.username}@${r.host}`)}`,
             `  run \`insta compute ssh ${r.serviceName} --setup\` once for the shorter \`ssh ${r.alias}\`, automatic renewal, and scp/-L support`,
         ];
     return [...head, `  certificate valid until ${r.expiresAt}`];

package/dist/commands/db.js

@@ -6,9 +6,7 @@ import { parseVolumeGib, q, resolveSoleService } from './services.js';
 // Toggle a postgres service between scale-to-zero (the default: instance suspends when idle,
 // cold-starts on the next connection) and always-on (instance stays warm; idle RAM bills at
 // actual usage). Thin wrapper over PATCH /database/settings {scaleToZero} — insta-db-backed
-// postgres only. Legacy Neon path: Neon is no longer used by any environment (postgres is 100%
-// insta-db) and this code is retained, not live — Neon-backed services managed their own
-// autosuspend and the platform returned an error for them.
+// postgres only.
 export async function dbAlwaysOn(mode, opts) {
     if (mode !== 'on' && mode !== 'off')
         throw new Error('mode must be on|off');
@@ -55,9 +53,8 @@ export async function fetchDbInstance(api, projectId, suffix) {
         return { kind: 'ok', body: res.body };
     }
     catch (e) {
-        // The platform answers a provider-shaped 502 for services with no manageable instance
-        // (the legacy Neon path — Neon is no longer used by any environment; this branch is retained,
-        // not live): a soft case, not a failure. Everything else stays an error — an expired
+        // The platform answers a provider-shaped 502 for services with no manageable instance:
+        // a soft case, not a failure. Everything else stays an error — an expired
         // token must not render as "no ceiling set" — but wrapped so the user sees what failed.
         if (e instanceof ApiError && e.status === 502)
             return { kind: 'no-instance' };
@@ -121,9 +118,6 @@ export async function dbLimits(opts) {
     const mem = typeof res.body?.memoryMib === 'number' ? fmtMib(res.body.memoryMib) : (opts.memory ?? 'unchanged');
     info(`postgres ${opts.group ?? 'default'}: ceiling set to ${cpu} / ${mem}`);
 }
-// Render the instance's volume from a database/instance read. Pure, exported for tests. Reads the
-// CANONICAL volume* names only — storageSize/storageGiB are deprecated aliases the platform drops
-// next release, so depending on them here would be a scheduled breakage.
 // Bytes → human units, one decimal above KiB. Local because the metrics payload is the only
 // bytes-denominated read in this file (fmtMib serves the MiB-denominated resize path).
 export function fmtBytes(n) {
@@ -185,6 +179,9 @@ export async function dbStats(opts) {
     for (const line of dbStatsLines(opts.group ?? 'default', res.body))
         info(line);
 }
+// Render the instance's volume from a database/instance read. Pure, exported for tests. Reads the
+// CANONICAL volume* names only — storageSize/storageGiB are deprecated aliases the platform drops
+// next release, so depending on them here would be a scheduled breakage.
 export function dbVolumeLines(group, body) {
     const gib = typeof body?.volumeGib === 'number' ? `${body.volumeGib}Gi` : (typeof body?.volumeSize === 'string' ? body.volumeSize : undefined);
     if (gib === undefined)

package/dist/commands/deploy.js

@@ -38,9 +38,9 @@ async function discoverLane(api, projectId, branch, opts) {
         if (!known.includes(tag)) {
             die(`this platform answered with a source-build lane this CLI does not know (${JSON.stringify(tag)}) — upgrade with \`insta upgrade\``);
         }
-        // The tag alone is not the contract: each branch carries a payload this code then trusts.
-        // An `archive` with malformed limits fell back to local defaults, so the CLI would enforce
-        // caps the SERVER does not have, and a `none` with no reason died with `undefined`.
+        // The tag alone is not the contract: each branch carries a payload this code then trusts, so
+        // it is validated too — an `archive` with malformed limits must not fall back to local
+        // defaults the SERVER does not enforce, and a `none` must carry its reason.
         if (tag === 'archive') {
             const l = lane.limits;
             const positive = (v) => typeof v === 'number' && Number.isSafeInteger(v) && v > 0;
@@ -112,7 +112,7 @@ export function dockerfileExposedPort(dockerfile) {
 // This message is for the target that still REQUIRES a Dockerfile: a Fly-backed service, where a
 // directory deploy builds the Dockerfile in the directory and dies without one. On insta-compute
 // the archive lane carries the directory to the gateway and nixpacks builds it, so this dead end is
-// no longer universal. It names every way forward instead of the bare "add one".
+// not universal. It names every way forward instead of the bare "add one".
 //
 // It deliberately does NOT say "save the Dockerfile `insta build --explain` prints": that file is
 // not standalone — it COPYs `.nixpacks/nixpkgs-<hash>.nix` support files nixpacks writes beside it,

package/dist/commands/feedback.js

@@ -39,7 +39,7 @@ const FEEDBACK_ENDPOINT = process.env.INSTA_FEEDBACK_URL ||
     'https://feedback.instacloud.com/v1/feedback';
 const FEEDBACK_INGEST_TOKEN = process.env.INSTA_FEEDBACK_TOKEN || 'insta-feedback-public-v1';
 // 15s gives the backend's scale-to-zero cold start room to answer (the ingest service waits out
-// the DB wake and persists, so a report can land after the old 10s deadline gave up on it).
+// the DB wake and persists, so a report can land after a shorter deadline gave up on it).
 // An expired deadline is reported as UNCONFIRMED, not failed — the report may well be stored.
 const FEEDBACK_TIMEOUT_MS = 15_000;
 const MAX_FILE_BYTES = 256 * 1024;
@@ -153,7 +153,7 @@ export async function buildPayload(opts, ctx) {
         branch: project?.branch,
     };
 }
-/** One POST, 10s timeout, zero retries — feedback is a side quest and must never hang the CLI.
+/** One POST, one bounded attempt (FEEDBACK_TIMEOUT_MS), zero retries — feedback is a side quest and must never hang the CLI.
  *  Transport and server failures come back as a result, not an exception: the caller downgrades
  *  them to a warning so a broken feedback backend can't fail the user's actual task. */
 export async function submit(payload, fetchImpl) {

package/dist/commands/manifest.js

@@ -6,8 +6,7 @@ import { info, printJson } from '../util.js';
  *
  * `kind` is the platform's internal resource kind, and for compute it is always 'fly' — 'fly' is
  * the compute SEAT, occupied by the microvm plane on any environment that has cut over. Printing
- * it is how `insta manifest` came to tell users and agents that a microvm-backed service ran on
- * Fly (staging, 2026-08-25: `fly(api)` for a row serving from warm pod insta-warm-00178a-16).
+ * it tells users and agents that a microvm-backed service runs on Fly.
  *
  * So for compute rows the label is the platform's explicit `provider`, and when that is absent --
  * an older platform, or a row whose provider the platform itself could not determine -- we fall

package/dist/commands/metrics.js

@@ -98,8 +98,7 @@ function printDimensions(dims) {
 // insta usage — usage across the 5 billing dimensions (cpu/memory/volume/egress/storage) for the
 // current billing cycle. Shows the whole ORG by default (with a per-project breakdown); pass --proj
 // [id] for a single project (the linked one, or a given id). Billed dimensions, not raw provider
-// meters. (Historical: those were fly/neon meters — Neon is no longer used by any environment,
-// though the adapter code is retained, not live.)
+// meters.
 export async function usage(opts) {
     const api = await ApiClient.load();
     const p = await requireProject();

package/dist/commands/secrets.js

@@ -162,27 +162,66 @@ async function readStdin() {
         data += chunk;
     return data.trim();
 }
+// Every platform SkipReason (applyTargets.ts) except 'unknown-service', which means the plan
+// could not resolve the service, not that it correctly chose to skip it.
+const BENIGN_SKIP_REASONS = new Set(['no-image', 'other-branch', 'caller-deploying', 'skip-deploy']);
+// Three outcomes: an unwritten entry is a hard failure; a written entry with a
+// failed or unexplained-skip service is durable but not fully live; anything else is success.
+export function applyVerdict(entries, services) {
+    if (entries.some((e) => !e.written))
+        return 'not-written';
+    const degraded = services.some((s) => s.result === 'failed' || (s.result === 'skipped' && !BENIGN_SKIP_REASONS.has(s.reason ?? '')));
+    return degraded ? 'degraded' : 'ok';
+}
+// util.ts already claims 1 (plain failure) and 2 (nothing ran, re-run is safe); this state fits
+// neither, so it takes the next code rather than overload one of theirs.
+export function applyExitCode(verdict) {
+    return verdict === 'ok' ? 0 : verdict === 'not-written' ? 1 : 3;
+}
+// Pure — one line per service, extending `branch.ts`'s create/skip convention; `started` matters most, it means new billing.
+export function applyServiceLines(services) {
+    return services.map((s) => {
+        if (s.result === 'started')
+            return `  + ${s.serviceId} started (was stopped — this now bills)`;
+        if (s.result === 'deployed')
+            return `  ~ ${s.serviceId} redeployed`;
+        if (s.result === 'failed')
+            return `  ! ${s.serviceId} failed${s.reason ? `: ${s.reason}` : ''}`;
+        return `  = ${s.serviceId}${s.reason ? ` (${s.reason})` : ''}`;
+    });
+}
 // Set a user secret. Project-wide by default; --branch scopes it to one branch. --service binds
 // it to a branch service instead, which implies the current branch (binding requires one). Value
 // comes from the argument, or stdin when omitted (keeps secret values out of shell history).
-export async function secretsSet(name, value, opts) {
+export async function secretsSet(name, value, opts, deps) {
     // An empty --service must not fall through to a project-wide WRITE. The scoping test below is a
     // truthiness check, so `--service ''` (a client interpolating an absent variable) would have put
     // the secret at a WIDER scope than the caller asked for, visible to every service on the branch.
     assertServiceRef(opts.service);
-    const api = await ApiClient.load();
-    const p = await requireProject();
+    const d = deps ?? (await loadDeps());
     const v = value ?? (await readStdin());
     if (!v)
         die('value is required (pass as an argument or on stdin)');
-    const branch = opts.service ? (opts.branch ?? p.branch) : opts.branch;
-    const payload = { value: v, ...(branch ? { branch } : {}), ...(opts.service ? { service: opts.service } : {}) };
-    const res = await api.rawRequest('PUT', `/projects/${p.projectId}/secrets/${encodeURIComponent(name)}`, payload);
+    const branch = opts.service ? (opts.branch ?? d.linkedBranch) : opts.branch;
+    // The batch always deploys on ONE branch, so the top level falls back to the linked one even when the entry itself is project-wide.
+    const entry = { kind: 'set', name, value: v, ...(branch ? { branch } : {}), ...(opts.service ? { service: opts.service } : {}) };
+    const res = await d.api.rawRequest('POST', `/projects/${d.projectId}/apply`, { branch: branch ?? d.linkedBranch, entries: [entry] });
     if (handleApproval(res, opts.json))
         return;
+    const entries = res.body.entries ?? [];
+    const services = res.body.services ?? [];
+    const verdict = applyVerdict(entries, services);
+    process.exitCode = applyExitCode(verdict);
     if (opts.json)
-        return printJson({ ok: true, name, branch: branch ?? null, service: opts.service ?? null });
+        return printJson({ ok: verdict === 'ok', verdict, name, branch: branch ?? null, service: opts.service ?? null, entries, services });
     info(`set ${name}${opts.service ? ` → ${opts.service}` : ''} (${branch ? `branch ${branch}` : 'project-wide'})`);
+    for (const line of applyServiceLines(services))
+        info(line);
+    // Verdict note on stderr, after the per-service lines: not success, and not the same failure either.
+    if (verdict === 'not-written')
+        process.stderr.write(`error: ${name} was not written\n`);
+    else if (verdict === 'degraded')
+        process.stderr.write(`warning: ${name} is saved but not applied everywhere — retry the deploy for the services marked failed above, do not resend this value\n`);
 }
 // Remove a user secret. --service removes only THAT service's copy (the platform has always
 // honoured ?service= here; without the flag a name several services define stays defined).
@@ -192,21 +231,26 @@ export async function secretsUnset(name, opts, deps) {
     // Service scoping REQUIRES a branch (a service exists on a branch, so the platform rejects the
     // pair without one) — so --service defaults to the linked branch, exactly as `secrets set` does.
     const branch = opts.service ? (opts.branch ?? d.linkedBranch) : opts.branch;
-    const parts = [];
-    if (branch)
-        parts.push(`branch=${encodeURIComponent(branch)}`);
-    if (opts.service)
-        parts.push(`service=${encodeURIComponent(opts.service)}`);
-    const qs = parts.length ? `?${parts.join('&')}` : '';
-    const res = await d.api.rawRequest('DELETE', `/projects/${d.projectId}/secrets/${encodeURIComponent(name)}${qs}`);
+    const entry = { kind: 'delete', name, ...(branch ? { branch } : {}), ...(opts.service ? { service: opts.service } : {}) };
+    const res = await d.api.rawRequest('POST', `/projects/${d.projectId}/apply`, { branch: branch ?? d.linkedBranch, entries: [entry] });
     if (handleApproval(res, opts.json))
         return;
+    const entries = res.body.entries ?? [];
+    const services = res.body.services ?? [];
+    const verdict = applyVerdict(entries, services);
+    process.exitCode = applyExitCode(verdict);
     // The EFFECTIVE branch, not the flag: with --service and no --branch the scope that was deleted
     // is the linked branch's, and the output has to say which scope it actually touched.
     if (opts.json)
-        return printJson({ ok: true, name, branch: branch ?? null, service: opts.service ?? null });
+        return printJson({ ok: verdict === 'ok', verdict, name, branch: branch ?? null, service: opts.service ?? null, entries, services });
     const scope = opts.service ? `${opts.service}, branch ${branch}` : branch ? `branch ${branch}` : 'project-wide';
     info(`unset ${name} (${scope})`);
+    for (const line of applyServiceLines(services))
+        info(line);
+    if (verdict === 'not-written')
+        process.stderr.write(`error: ${name} was not removed\n`);
+    else if (verdict === 'degraded')
+        process.stderr.write(`warning: ${name} is removed but not applied everywhere — retry the deploy for the services marked failed above\n`);
 }
 export async function secretsBind(envName, source, opts) {
     if (!opts.to)

package/dist/commands/services.js

@@ -85,9 +85,8 @@ export function servicesAddRequestBody(type, name, branch, opts) {
         type, name, ...(branch ? { branch } : {}), public: !!opts.public,
         ...(opts.image ? { image: opts.image } : {}), ...(opts.port ? { port: parsePort(opts.port) } : {}),
         ...(opts.region ? { region: opts.region } : {}),
-        // Sent whenever the flag was given, false included: compute is born always-on by default
-        // (insta-platform #385, 2026-09-07), so `--no-always-on` must reach the API as an explicit
-        // false. Omitted means the platform default.
+        // Sent whenever the flag was given, false included: compute is born always-on by default,
+        // so `--no-always-on` must reach the API as an explicit false. Omitted means the platform default.
         ...(opts.alwaysOn !== undefined ? { alwaysOn: opts.alwaysOn } : {}),
         ...(opts.volume !== undefined ? { volumeGib: parseVolumeGib(opts.volume) } : {}),
         ...(opts.mountPath !== undefined ? { volumeMountPath: opts.mountPath } : {}),

package/dist/commands/setup.js

@@ -21,7 +21,7 @@ import { projectCreate, projectLink, slugifyName } from './project.js';
 import { envUse } from './env.js';
 import { installAgentConfigs } from './mcp.js';
 import { detectChannel } from './upgrade.js';
-export { resolveSpawnable, whichOnPath } from '../spawn.js';
+export { resolveSpawnable } from '../spawn.js';
 // The `skills` tool we shell out to prints a clack UI: a frame-by-frame clone spinner, an
 // "Installing to all N agents" banner, a full N-line install-path box, and a third-party
 // "Security Risk Assessment" that flags our OWN first-party skill as "Critical Risk". Streamed
@@ -65,7 +65,7 @@ export function parseInstalledAgents(output) {
         // The tool boxes each line ("│    → ~/.claude/skills/insta   │"), so don't anchor to EOL.
         // Separator-agnostic: on Windows the tool prints C:\Users\…\.claude\skills\insta — a
         // forward-slash-only match found nothing there, collapsing the summary to a nameless
-        // "Agents set up" (user report).
+        // "Agents set up".
         const m = plain.match(/→\s*(\S+)[\\/]skills[\\/][A-Za-z0-9_-]+/);
         if (m && m[1])
             paths.add(m[1]);
@@ -256,7 +256,7 @@ export function requireMcpRegistration(status) {
 /** The environment `setup agent` should target, and whether the machine must be switched to it
  *  first. Pure — decides only; the caller performs the switch.
  *
- *  The contract (CLI ≥ 0.0.38): the public one-liner `npx -y insta setup agent` means PRODUCTION,
+ *  The contract: the public one-liner `npx -y insta setup agent` means PRODUCTION,
  *  full stop — a leftover `insta env use staging` from last month must not silently give a new
  *  onboarding run staging skills. Staging is an explicit ask: `--env staging` (or $INSTA_ENV).
  *  Two deliberate exceptions leave the machine alone:
@@ -442,7 +442,7 @@ export async function setupAgent(opts, run = defaultRunner, mint, installConfigs
     // --project / --create: bind this directory to a project inside the SAME process. Never split
     // this back into `setup agent && insta project <cmd>` as one paste: no shell joiner survives
     // every Windows shell, and in shells without bracketed paste the queued second line is eaten
-    // as the answer to the login prompt above (console PR #290). Both need the session: without
+    // as the answer to the login prompt above. Both need the session: without
     // one the manual command is the hint, never a hang; a failure (bad id, no access, name taken)
     // is a REAL error — binding a project is the entire point of the flag — so it sets the exit
     // code instead of pretending setup succeeded.

package/dist/commands/ssh-config.js

@@ -115,10 +115,12 @@ export function renderConfigBlock(o) {
             throw new Error(`refusing to write an unsafe ssh HostName into ssh_config: ${JSON.stringify(e.hostName)}`);
         if (!isSafeConfigValue(e.user))
             throw new Error(`refusing to write an unsafe ssh User into ssh_config: ${JSON.stringify(e.user)}`);
+        if (!Number.isInteger(e.port) || e.port < 1 || e.port > 65535)
+            throw new Error(`refusing to write an unusable ssh Port into ssh_config: ${JSON.stringify(e.port)}`);
         lines.push(`Host ${e.alias}`, 
         // Without HostName and User the alias is not routing at all: ssh resolves
         // `api.insta` in DNS and logs in as the local OS username.
-        `  HostName ${e.hostName}`, `  User ${e.user}`, `  IdentityFile ${quoteConfigPath(o.identityFile)}`, `  CertificateFile ${quoteConfigPath(e.certificateFile)}`, 
+        `  HostName ${e.hostName}`, `  User ${e.user}`, `  Port ${e.port}`, `  IdentityFile ${quoteConfigPath(o.identityFile)}`, `  CertificateFile ${quoteConfigPath(e.certificateFile)}`, 
         // WRITTEN, not left to the default, and this is the one keyword where
         // being first in the file does not save us. First-wins settles a keyword
         // two blocks both set; a keyword we never set at all goes on being filled
@@ -137,24 +139,29 @@ export function renderConfigBlock(o) {
         // IdentitiesOnly is not tidiness. SSH offers public keys ONE AT A TIME,
         // so a user with several keys is identified non-deterministically -- the
         // server sees whichever key happened to be offered first, which may not be
-        // the one carrying our certificate. exe.dev calls this heisen-connect.
-        // Without this line a developer with a full ssh-agent gets intermittent,
-        // unexplainable auth failures.
+        // the one carrying our certificate. Without this line a developer with a
+        // full ssh-agent gets intermittent, unexplainable auth failures.
         '  IdentitiesOnly yes');
         // Connection multiplexing collapses scp, an IDE's several connections and a
         // second terminal onto ONE connection; without it a single developer can
         // reach the per-service session cap in an afternoon.
         //
-        // OMITTED ON WINDOWS, where it is not an optimisation but a broken config.
+        // The socket is keyed on %C -- a hash of (local host, remote host, port,
+        // user) -- not %r@%h:%p. A ControlPath is a Unix-domain socket, whose path
+        // is capped at 104 bytes on macOS (108 on Linux), and the route-key user
+        // plus the regional gateway hostname sailed past that: a real prod alias
+        // rendered a 109-byte path and every `ssh` died on `ControlPath too long`.
+        // %C is a fixed 40 hex chars however long the host and user grow, so the
+        // path can no longer overflow; it also drops the `:` the old token carried.
+        //
+        // OMITTED ON WINDOWS, where it is not an optimisation but a broken config:
         // Win32-OpenSSH does not implement ControlMaster (PowerShell/Win32-OpenSSH
-        // #1328, #405) and fails the connection rather than ignoring the directive,
-        // and the ControlPath itself contains a `:` before %p, which is not a legal
-        // character in a Windows filename. Every alias would be unusable on a
-        // platform this repo runs CI for. The effective-config tests need a real
-        // `ssh` and skip on Windows, so this branch is asserted on the rendered
-        // text instead.
+        // #1328, #405) and FAILS the connection rather than ignoring the directive,
+        // so every alias would be unusable on a platform this repo runs CI for. The
+        // effective-config tests need a real `ssh` and skip on Windows, so this
+        // branch is asserted on the rendered text instead.
         if ((o.platform ?? process.platform) !== 'win32') {
-            lines.push('  ControlMaster auto', '  ControlPath ~/.insta/ssh/cm-%r@%h:%p', '  ControlPersist 10m');
+            lines.push('  ControlMaster auto', '  ControlPath ~/.insta/ssh/cm-%C', '  ControlPersist 10m');
         }
         if (o.ensureCertCommand) {
             // Renewal happens while OpenSSH PARSES the config, before it connects, so
@@ -210,6 +217,35 @@ export function upsertConfigBlock(existing, block) {
 export function hasOwnedBlock(existing) {
     return existing.split('\n').some(isMarkerLine(BLOCK_BEGIN));
 }
+/** Whether nothing that OpenSSH would read precedes the owned block. OpenSSH
+ *  takes the FIRST obtained value for each keyword, so a `Host *` stanza -- or a
+ *  bare global `Port 22` -- above our block silently overrides the block's
+ *  Port, HostName, User and credential; that is why upsertConfigBlock writes
+ *  the block at the top. Comments and blank lines above it are harmless and do
+ *  not count. false when there is no owned block at all. */
+export function ownedBlockIsFirst(existing) {
+    const lines = existing.split('\n');
+    const begin = lines.findIndex(isMarkerLine(BLOCK_BEGIN));
+    if (begin === -1)
+        return false;
+    return lines.slice(0, begin).every((l) => /^\s*(#.*)?$/.test(l));
+}
+/** The installed owned block, BEGIN through END marker inclusive, exactly as it
+ *  sits in the file; undefined when there is none (or an unterminated one). It
+ *  exists so a writer can compare what IS installed with what it WOULD render
+ *  and touch the file only when the two differ -- a stanza written before a
+ *  keyword existed (the Port line) is the case, and "nothing changed in the
+ *  response" is not the same question as "nothing would change in the file". */
+export function ownedBlock(existing) {
+    const lines = existing.split('\n');
+    const begin = lines.findIndex(isMarkerLine(BLOCK_BEGIN));
+    if (begin === -1)
+        return undefined;
+    const end = lines.findIndex((l, n) => n > begin && isMarkerLine(BLOCK_END)(l));
+    if (end === -1)
+        return undefined;
+    return lines.slice(begin, end + 1).join('\n');
+}
 /** A marker is a WHOLE LINE, never a substring of one.
  *
  *  Matching the marker text wherever it occurred made a user's comment that
@@ -297,11 +333,10 @@ function isEcdsaBody(curve, point, wantCurve, pointLen) {
 /** Exactly ONE OpenSSH public-key record: `<type> <base64>` with an optional
  *  comment, and nothing else -- no second line, no leading directive.
  *
- *  `renderCertAuthority` only trimmed, so an embedded newline in the CA value
- *  smuggled additional known_hosts lines past it. Parsing to the three fields
- *  we will actually write, and rebuilding the line from THOSE, means a value
- *  either is one key record or is refused; there is no third outcome where
- *  part of it is honoured. */
+ *  Parsing to the three fields we will actually write, and rebuilding the line
+ *  from THOSE, means a value either is one key record or is refused; there is
+ *  no third outcome where part of it is honoured (an embedded newline would
+ *  otherwise smuggle additional known_hosts lines through). */
 export function parseCAPublicKey(value) {
     if (typeof value !== 'string')
         throw new Error('the platform returned no ssh certificate authority key');
@@ -318,22 +353,18 @@ export function parseCAPublicKey(value) {
     if (!/^[A-Za-z0-9+/]+={0,3}$/.test(blob) || blob.length < 32) {
         throw new Error('refusing a certificate authority key whose body is not base64');
     }
-    // The blob's OWN type must agree with the text field. Base64-shaped is not
-    // the same as "is a key": an anchor built from a mislabelled or arbitrary
-    // blob installs silently and then fails at connect time, where the message
-    // points at known_hosts rather than at the response that produced it.
-    // The WHOLE blob, not just its first field. A first-field check rejects
-    // arbitrary base64 and still accepts a correct type name followed by noise --
-    // and an anchor built from that installs silently, then fails at connect
-    // time, where the message points at known_hosts rather than at the response
-    // that produced it.
+    // The blob's OWN type must agree with the text field, and the WHOLE blob is
+    // checked, not just its first field: a first-field check rejects arbitrary
+    // base64 and still accepts a correct type name followed by noise -- and an
+    // anchor built from that installs silently, then fails at connect time,
+    // where the message points at known_hosts rather than at the response that
+    // produced it.
     const fields = sshBlobFields(blob);
     if (!fields || fields.length < 2 || fields[0].toString('utf8') !== type) {
         throw new Error(`refusing a certificate authority key whose body does not match its type ${JSON.stringify(type.slice(0, 32))}`);
     }
-    // And the fields must be the ones THIS type has. ed25519 was the only type
-    // held to its shape at first, so a correct RSA or ECDSA type name followed by
-    // any well-formed fields passed -- see CA_KEY_SHAPES.
+    // And the fields must be the ones THIS type has (see CA_KEY_SHAPES): a
+    // correct RSA or ECDSA type name followed by any well-formed fields must not pass.
     if (!shape(fields)) {
         throw new Error(`refusing a certificate authority key whose body is not the shape of ${JSON.stringify(type.slice(0, 32))}`);
     }
@@ -631,8 +662,7 @@ export function planCertAuthority(existing, hostPattern, caKey) {
 export function revertCertAuthority(current, plan) {
     const kept = current.split('\n').filter((l) => l.trimEnd() !== plan.line);
     // Only the ONE trailing blank the split leaves behind a final newline. A
-    // blank line before that is the user's -- trailing blanks included, which a
-    // loop popping every empty tail line was deleting on the failure path.
+    // blank line before that is the user's -- trailing blanks included.
     if (kept.length > 0 && kept[kept.length - 1] === '')
         kept.pop();
     // Only the anchors that are genuinely gone: a concurrent install may already

package/dist/commands/template.js

@@ -329,7 +329,7 @@ export async function templateDeploy(target, opts = {}, deps = {}) {
         manifest = fetched.manifest;
         source = fetched.source;
         vars = collectManifestVariables(manifest);
-        // Spec 4.4: exactly ONE line in front of today's output. A second "deploying template …" line
+        // Exactly ONE line in front of today's output. A second "deploying template …" line
         // would read as a duplicate of the "deploying template <code> to branch <branch>" line below,
         // so the manifest's code@version rides on this one instead.
         if (!quiet) {

package/dist/commands/upgrade.js

@@ -9,9 +9,8 @@
 // `resolveLatest()`, reading npm's `latest` dist-tag, the same thing `npx insta@latest` and
 // `npm i -g insta` resolve. Both the background check and `insta upgrade` go through it, and the
 // binary channel then installs THAT version by tag (INSTA_VERSION=v<latest>) rather than asking
-// GitHub independently for /releases/latest. Two independent resolvers is how the two paths came
-// to disagree; they have drifted before (v0.0.46 was merged but never tagged, so it exists on
-// neither npm nor GitHub).
+// GitHub independently for /releases/latest. Two independent resolvers is how the two paths
+// drift apart: a version can be merged but never tagged, so it exists on neither npm nor GitHub.
 //
 // A CACHE MUST NOT LIE. ~/.insta/update-check.json is a cache of that one answer, never a second
 // source. Every path that learns the real latest rewrites it (including a successful upgrade),
@@ -348,7 +347,7 @@ export async function autoupdate(mode) {
  *  `upgrade`/`autoupdate` are the update machinery itself. Every `__` command
  *  is internal machinery rather than a user at a prompt, and the rule is
  *  written as a PREFIX so the next such command inherits it instead of
- *  rediscovering it -- which is exactly how this was missed:
+ *  rediscovering it:
  *  `__ssh-ensure-cert` is run by OpenSSH while it PARSES ssh_config, on every
  *  ssh, scp, `ssh -G` and IDE connection, so a nudge here is written straight
  *  into the ssh session's stderr and an auto-upgrade spawns a detached process

package/dist/config.js

@@ -16,9 +16,8 @@ const PROJECT_FILE = 'project.json';
 // CLI treat the shared link as foreign. It records the project id too, because project.json is
 // committed and this file is not: a pull or checkout can replace the project underneath it.
 const LINK_PLANE_FILE = 'link-plane.json';
-// The cloud API default. Uses the instacloud.com brand domain (matches the agents.instacloud.com
-// onboarding), NOT the legacy beta-api.insta.insforge.dev host — same backend, branded domain.
-// Only affects fresh installs: a persisted apiUrl (from a prior login) or INSTA_API_URL wins below.
+// The cloud API default. Only affects fresh installs: a persisted apiUrl (from a prior login) or
+// INSTA_API_URL wins below.
 const DEFAULT_API = ENVS[DEFAULT_ENV].api;
 export async function readGlobal() {
     // Precedence, most explicit first:
@@ -147,7 +146,7 @@ export async function findProjectRoot(cwd = process.cwd()) {
 }
 /** The link that applies to `cwd`, and whether it was made against a DIFFERENT control plane. A
  *  project id means nothing on another control plane (cloud, staging and every insta-oss box each
- *  have their own), and the CLI used to reuse a link against whatever API it was pointed at. */
+ *  have their own). */
 export async function resolveProjectLink(cwd = process.cwd()) {
     // Linkless targeting (CI / one-offs / agents): INSTA_PROJECT_ID resolves the project with no
     // link file, and beats one when both exist — an explicit parameter outranks ambient state.
@@ -170,8 +169,8 @@ export async function resolveProjectLink(cwd = process.cwd()) {
     catch {
         return null;
     }
-    // No sidecar — a link from before this existed, or a teammate who just cloned — resolves as it
-    // always did: there is nothing to say which control plane it belongs to.
+    // No sidecar (a teammate who just cloned): nothing says which control plane the link belongs
+    // to, so it resolves unchecked.
     const record = await readLinkPlane(root);
     if (record) {
         const current = safeUrl((await readGlobal()).apiUrl);

package/dist/flyctl-build.js

@@ -1,6 +1,6 @@
 // Build a source directory into an image and push it to Fly's registry, using a short-lived,
 // app-scoped deploy token minted by the platform (the CLI never holds a standing Fly credential).
-// Shells out to `flyctl deploy --build-only --push` (remote builder). Ported from firth.
+// Shells out to `flyctl deploy --build-only --push` (remote builder).
 import { spawn } from 'node:child_process';
 import { existsSync, writeFileSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
@@ -80,7 +80,7 @@ export async function ensureFlyctl() {
             return;
         }
         if (process.platform === 'linux') {
-            // A fresh Linux machine (CI containers included — insta-e2e run 31284364163) has no flyctl
+            // A fresh Linux machine (CI containers included) has no flyctl
             // and no brew; without this branch `insta deploy <dir>` dead-ends on a hand-install of a
             // third-party CLI. Official installer, pinned into ~/.fly; the current process extends its
             // own PATH because the installer's shell-profile edit can't reach an already-running process.

package/dist/github-source.js

@@ -7,7 +7,6 @@ import { tmpdir } from 'node:os';
 import { join, sep } from 'node:path';
 import { parseManifestYaml, MANIFEST_FILE } from './template-manifest.js';
 const GITHUB_HOST = /^(?:https?:\/\/)?(?:www\.)?github\.com\//i;
-// An explicit address: a scheme, or an scp-style user@host:path. Never a local path.
 // A scheme (with or without its slashes) or an scp-style user@host:path. The slashes are optional
 // because `https:/github.com/o/r`, a URL that lost one, must be named as a bad address rather than
 // resolved as a directory called `https:`. Two or more scheme characters are required so a Windows
@@ -49,7 +48,7 @@ function decodedSegments(parts, target) {
 }
 /** Parse a github.com URL into owner, repo and the still-unsplit ref+path tail.
  *  null = not URL-shaped, so the caller's local-directory and registry modes still get a look.
- *  A URL-shaped target that is not a github.com repository URL throws (spec 4.1). */
+ *  A URL-shaped target that is not a github.com repository URL throws. */
 export function parseGitHubTemplateUrl(target) {
     if (!GITHUB_HOST.test(target)) {
         // Name a non-GitHub address for what it is; let everything else reach local/registry mode.
@@ -140,7 +139,7 @@ function releaseChild(child) {
     }
     catch { /* already gone */ }
 }
-/** spawnFn is injected so the timeout path is testable without a network (spec FAQ 7.15). */
+/** spawnFn is injected so the timeout path is testable without a network. */
 export function makeGitRunner(spawnFn = nodeSpawn) {
     return (args, opts) => new Promise((resolve) => {
         // Spawned directly, NOT through resolveSpawnable: that wrapper exists for npm-installed
@@ -232,7 +231,7 @@ export function splitRefAndPath(refAndPath, refs) {
 }
 /** One round trip answers two questions: the default branch, and where the ref ends. The commit
  *  is NOT taken from here — an annotated tag lists its tag object, and a branch can move before
- *  the clone. fetchGitHubTemplate reads it from the checkout instead (spec FAQ 7.10). */
+ *  the clone. fetchGitHubTemplate reads it from the checkout instead. */
 export async function resolveGitHubRef(t, run) {
     // HEAD is listed EXPLICITLY: adding refspecs otherwise drops the symref line that names the
     // default branch (measured on this repo: 375 refs unfiltered, 188 with the filter, and no
@@ -285,7 +284,7 @@ export async function fetchGitHubTemplate(target, run = defaultGitRunner, parse
     const dir = mkdtempSync(join(tmpdir(), 'insta-tpl-gh-'));
     try {
         // The short name, not resolved.qualifiedRef: `--branch` rejects a fully-qualified ref, and
-        // git's own short-name tie-break already agrees with splitRefAndPath (spec FAQ 7.14).
+        // git's own short-name tie-break already agrees with splitRefAndPath.
         const cloned = await run(['clone', '--depth', '1', '--quiet', '--branch', resolved.ref, repoUrl(target), dir], { timeoutMs: CLONE_TIMEOUT_MS });
         if (cloned.timedOut)
             throw new Error(`timed out after ${CLONE_TIMEOUT_MS / 1000}s cloning https://github.com/${target.owner}/${target.repo}`);
@@ -294,7 +293,7 @@ export async function fetchGitHubTemplate(target, run = defaultGitRunner, parse
         if (cloned.code !== 0)
             throw new Error(unreadableRepoMessage(target, cloned.stderr));
         // The deployed commit is the one in the checkout: an annotated tag's listing entry is its tag
-        // object, and a branch can move between ls-remote and here (spec FAQ 7.10).
+        // object, and a branch can move between ls-remote and here.
         const head = await run(['-C', dir, 'rev-parse', 'HEAD'], { timeoutMs: LS_REMOTE_TIMEOUT_MS });
         // Same three outcomes the other two calls distinguish, so a timeout or a missing git here is
         // not reported as an unreadable repository.

package/dist/index.js

@@ -448,12 +448,8 @@ program.command('autoupdate [mode]').description('Show or set auto-update: on |
 program.command('__update-check', { hidden: true }).action(guard(() => selfUpdate.backgroundCheck(cliVersion())));
 // The ssh_config renewal hook. Hidden, and named with the `__` prefix that
 // trackCommand skips, because OpenSSH runs it while PARSING the config on EVERY
-// ssh/scp/`ssh -G`/IDE connection. Under the normal `compute ssh --ensure-cert`
-// path, guard's trackCommand ran afterwards regardless of the action returning
-// early -- reading config, possibly creating ~/.insta/telemetry.json, and
-// making a PostHog request with a timeout of up to 1.5s. That is a network
-// round trip on the critical path of every ordinary ssh, which is exactly what
-// the hook was specified not to do.
+// ssh/scp/`ssh -G`/IDE connection: a telemetry round trip here would sit on the
+// critical path of every ordinary ssh.
 program.command('__ssh-ensure-cert <alias>', { hidden: true })
     .action(guard((alias) => computeCmd.ensureCertForAlias(alias)));
 selfUpdate.maybeUpdate(cliVersion(), process.argv);

package/dist/observe/hook.js

@@ -1,5 +1,5 @@
 // PostToolUse hook: reads a tool-use event on stdin (Claude Code / Codex), scans every string
-// surface for credential exposure, and appends findings to ./.insta/audit.jsonl. Ported from firth.
+// surface for credential exposure, and appends findings to ./.insta/audit.jsonl.
 import { appendFileSync, mkdirSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';

package/dist/observe/install.js

@@ -1,5 +1,5 @@
 // Install the observe hook into a project's agent harness (Claude Code / Codex) and materialize
-// the standalone hook + scanner into ./.insta/observe. Ported from firth (.firth -> .insta).
+// the standalone hook + scanner into ./.insta/observe.
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';

package/dist/pack-ignore.js

@@ -139,8 +139,8 @@ function posixClass(name, negated) {
 // literal. docker hands the class to Go's regexp: a `]` right after the opening `[` (or after
 // the `^`) is a MEMBER, not the close, `\` quotes the next character, and only `^` negates, so a
 // `!` is an ordinary member. Unlike `*` and `?`, these Go regexp classes CAN match a separator.
-// Verified against moby/patternmatcher compile() on 2026-09-11: it preserves bracket expressions
-// without adding a separator exclusion (private[^x]token matches private/token).
+// moby/patternmatcher compile() preserves bracket expressions without adding a separator
+// exclusion (private[^x]token matches private/token).
 function bracket(p, start) {
     let j = start + 1;
     let negated = false;

package/dist/resolve-project.js

@@ -1,8 +1,8 @@
 // "One command, just works": when a command needs a project and the directory isn't linked
 // (and no INSTA_PROJECT_ID is set), resolve it instead of lecturing about `project link` —
 // one project auto-selects silently, several get a one-keystroke picker, and either way the
-// choice is SAVED so this happens at most once per directory. (Railway prompts every unlinked
-// machine; we persist the answer and, via the committed link file, share it with the team.)
+// choice is SAVED so this happens at most once per directory, and the committed link file shares
+// it with the team.
 import { createInterface } from 'node:readline/promises';
 export async function autoResolveProject(orgId, deps) {
     const projects = await deps.listProjects();

package/dist/template-manifest.js

@@ -125,7 +125,7 @@ export function validateManifest(m) {
             problems.push(`${where}: web services must declare a healthcheck path`);
         if (svc.healthcheck && !String(svc.healthcheck).startsWith('/'))
             problems.push(`${where}: healthcheck must be an absolute path (start with /)`);
-        // Sizing is the platform's, capped for the org's plan (insta-platform#357). Same answers the
+        // Sizing is the platform's, capped for the org's plan. Same answers the
         // publish endpoint gives, said here so an author does not upload to find out. Read as unknown:
         // the type above admits only what is SUPPORTED, and the document is a cast over YAML.parse, so
         // a refused shape arrives as a value that type does not describe.

package/dist/util.js

@@ -101,8 +101,8 @@ export function resolveThroughSymlink(path) {
 /** Linux allows 40; the exact number does not matter, only that the walk ends. */
 const MAX_SYMLINK_HOPS = 40;
 /** How to launch the default browser for `url` on `platform`. Pure so the Windows encoding is
- *  testable. On Windows NO shell may ever parse the URL: cmd.exe splits at bare `&` (which #138
- *  fixed by quoting) but ALSO expands `%…%` sequences even inside quotes, and a percent-encoded
+ *  testable. On Windows NO shell may ever parse the URL: cmd.exe splits at bare `&` (quoting
+ *  fixes that) but ALSO expands `%…%` sequences even inside quotes, and a percent-encoded
  *  OAuth redirect (`http%3A%2F%2F127.0.0.1…`) is nothing but such sequences. So the launch goes
  *  through PowerShell's -EncodedCommand: a pure-ASCII script travels as base64(UTF-16LE) — no
  *  argument parsing anywhere — and the URL itself rides as a second base64 payload INSIDE that
@@ -113,11 +113,10 @@ export function openUrlSpawn(url, platform = process.platform,
 // directory before PATH, so a planted powershell.exe beside the user's shell would win.
 systemRoot = process.env.SYSTEMROOT ?? process.env.windir ?? 'C:\\Windows') {
     if (platform === 'win32') {
-        // The URL never appears in PowerShell SOURCE at all: it travels as base64 inside the script
-        // and is decoded by .NET at runtime. Interpolating it into a quoted literal is not enough —
-        // PowerShell honors smart quotes (U+2018–U+201B) as string delimiters too, so ASCII-only
-        // escaping still leaves a breakout. The script below is pure ASCII by construction (the
-        // base64 alphabet), so no byte of any URL can terminate anything.
+        // Interpolating the URL into a quoted literal is not enough — PowerShell honors smart quotes
+        // (U+2018–U+201B) as string delimiters too, so ASCII-only escaping still leaves a breakout.
+        // The script below is pure ASCII by construction (the base64 alphabet), so no byte of any
+        // URL can terminate anything.
         const urlB64 = Buffer.from(url, 'utf8').toString('base64');
         const script = `Start-Process ([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${urlB64}')))`;
         return {
@@ -149,8 +148,7 @@ export function openUrl(url) {
 }
 export class CliExit extends Error {
     constructor() {
-        // Preserve the observable error used by direct command-unit tests that previously mocked
-        // process.exit(1) by throwing `Error('exit 1')`.
+        // Command-unit tests assert this exact message.
         super('exit 1');
         this.name = 'CliExit';
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "insta",
-  "version": "0.0.77",
+  "version": "0.0.79",
   "type": "module",
   "description": "InstaCloud CLI — a thin client of the platform control-plane API.",
   "keywords": [