insta 0.0.61 → 0.0.63

package/README.md

@@ -121,10 +121,15 @@ only. Provider-minted service credentials (`DATABASE_URL`, `BUCKET_NAME`,
 
 ### Destructive actions can require approval
 
-Reading secrets, deploying, deleting a project or branch, and changing services are
-governed by a per-project policy. Where the policy says `approve`, the command stops and
-prints an approval id for an admin to grant with `insta approvals approve <id>`. Run
-`insta policy get` for the live policy.
+Agent requests are governed by the project's `agent-policy`; human requests use normal RBAC.
+Where the agent policy says `approve`, the command stops and prints an approval id for a human
+admin to grant with `insta approvals approve <id>`. The agent then retries the unchanged request.
+Run `insta --agent agent-policy get --json` for stored overrides, `defaultRules`, `effectiveRules`,
+`bootstrapRules` and `ruleNotes`. Rules distinguish no affected branches (`project`), unprotected
+branches and protected branches. They describe policy, not authorization: RBAC, session checks,
+actual affected resources and compound actions still apply. An empty override object does not
+mean rules are unavailable. Text output also lists effective rules. The old `policy` command and approval
+`--always` option have been removed.
 
 ### Agents get the same surface
 
@@ -213,7 +218,7 @@ build never reaches a production installer.
 | `insta metrics` · `logs` · `events` | Service metrics; runtime logs (`--deploy` for deploy events); audit timeline |
 | `insta usage` · `billing` | Usage by billing dimension; `billing upgrade` · `billing portal` |
 | `insta approvals` | `list` · `approve` · `deny` |
-| `insta policy` | `get` · `set <action> <decision>` |
+| `insta agent-policy` | `get` · `set <mode>` · `protect-branch` · `unprotect-branch` · `rule set <action> <decision>` · `revoke-sessions` |
 | `insta observe` | `install` · `uninstall` · `report` · `sync` — local credential audit |
 | `insta feedback` | Report an InstaCloud-side hurdle (bug / feature-request / friction) to the team — never for the app you are building; works logged-out |
 | `insta upgrade` · `autoupdate` | Update the CLI; show or set auto-update |

package/dist/agent.js

@@ -0,0 +1,86 @@
+import { createHash, generateKeyPairSync, randomUUID, sign } from 'node:crypto';
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { findProjectRoot, readProject } from './config.js';
+import { alreadyTracked, ensureGitignore } from './gitignore.js';
+let mode = null;
+export function detectAgent(explicit, env = process.env) {
+    const client = env.CODEX_THREAD_ID || env.CODEX_CI === '1' ? 'codex'
+        : env.CLAUDECODE === '1' ? 'claude-code'
+            : env.CURSOR_AGENT === '1' ? 'cursor' : 'unknown';
+    return explicit || client !== 'unknown' ? { source: explicit ? 'cli-explicit' : 'cli-detected', client } : null;
+}
+export function configureAgent(value) { mode = value; }
+export function agentMode() { return mode; }
+const hash = (v) => createHash('sha256').update(v).digest('hex');
+export function canonicalTarget(path) {
+    const url = new URL(path, 'https://platform.invalid');
+    return url.pathname + url.search;
+}
+const guidance = 'agent session missing, expired, or for another project/environment — run `insta setup agent`';
+export async function issueAgentSession(api, projectId) {
+    const pair = generateKeyPairSync('ed25519');
+    const client = mode?.client ?? detectAgent(false)?.client ?? 'unknown';
+    const out = await api.request('POST', '/agent/sessions', {
+        projectId, client, publicKey: pair.publicKey.export({ type: 'spki', format: 'pem' }).toString(),
+    });
+    return { ...out, client, apiUrl: api.apiUrl.replace(/\/+$/, ''), privateKey: pair.privateKey.export({ type: 'pkcs8', format: 'pem' }).toString() };
+}
+export async function saveAgentSession(session, cwd = process.cwd()) {
+    const root = await findProjectRoot(cwd) ?? cwd;
+    const rel = '.insta/agent-session.json';
+    if (alreadyTracked(root, [rel]).length)
+        throw new Error('agent-session.json is tracked by Git; untrack it before running insta setup agent');
+    ensureGitignore(root, [rel], '# Local agent credentials');
+    const dir = join(root, '.insta');
+    await mkdir(dir, { recursive: true });
+    const temp = join(dir, `.agent-session-${randomUUID()}.tmp`);
+    // Ignore crash leftovers too; temporary files contain the same private material.
+    ensureGitignore(root, ['.insta/.agent-session-*.tmp']);
+    await writeFile(temp, JSON.stringify(session, null, 2), { mode: 0o600 });
+    await rename(temp, join(root, rel));
+    await chmod(join(root, rel), 0o600);
+}
+export async function setupProjectAgentSession(api, projectId) {
+    const id = projectId ?? (await readProject())?.projectId;
+    if (!id)
+        return false;
+    await saveAgentSession(await issueAgentSession(api, id));
+    return true;
+}
+export async function loadAgentSession(apiUrl, projectId, cwd = process.cwd()) {
+    try {
+        const root = await findProjectRoot(cwd) ?? cwd;
+        const session = JSON.parse(await readFile(join(root, '.insta/agent-session.json'), 'utf8'));
+        if (session.projectId !== projectId || session.apiUrl !== apiUrl.replace(/\/+$/, '') || !session.token || !session.privateKey
+            || !Number.isFinite(Date.parse(session.expiresAt)) || Date.parse(session.expiresAt) <= Date.now())
+            throw new Error();
+        return session;
+    }
+    catch {
+        throw new Error(guidance);
+    }
+}
+export async function agentHeaders(api, method, path, rawBody) {
+    if (!mode)
+        return {};
+    if (canonicalTarget(path) === '/agent/sessions' && method === 'POST')
+        return {
+            'Insta-Actor-Type': 'agent', 'Insta-Agent-Source': mode.source, 'Insta-Agent-Client': mode.client,
+        };
+    const target = canonicalTarget(path);
+    const match = target.match(/^\/projects\/([^/?]+)/);
+    // Account reads/project creation have no project policy yet. Mint a short-lived bootstrap
+    // assertion in memory. It cannot access project routes; never downgrade to a human request.
+    const session = match ? await loadAgentSession(api.apiUrl, decodeURIComponent(match[1])) : await issueAgentSession(api);
+    const timestamp = String(Math.floor(Date.now() / 1000));
+    const nonce = randomUUID();
+    const proof = [method.toUpperCase(), target, hash(rawBody), session.agentSessionId, timestamp, nonce, mode.source, session.client].join('\n');
+    return {
+        'Insta-Actor-Type': 'agent', 'Insta-Agent-Session': session.agentSessionId,
+        'Insta-Agent-Session-Token': session.token, 'Insta-Agent-Source': mode.source,
+        'Insta-Agent-Client': session.client, 'Insta-Agent-Timestamp': timestamp,
+        'Insta-Agent-Nonce': nonce, 'Insta-Agent-Signature': sign(null, Buffer.from(proof), session.privateKey).toString('base64url'),
+    };
+}
+//# sourceMappingURL=agent.js.map

package/dist/api.js

@@ -4,6 +4,7 @@ import { readGlobal, writeGlobal, readProject, writeProject } from './config.js'
 import { autoResolveProject, promptChoice } from './resolve-project.js';
 import { die } from './util.js';
 import { USER_AGENT } from './version.js';
+import { agentHeaders, agentMode } from './agent.js';
 export class ApiError extends Error {
     status;
     body;
@@ -16,6 +17,13 @@ export class ApiError extends Error {
         this.name = 'ApiError';
     }
 }
+export class AgentApprovalRequired extends Error {
+    body;
+    constructor(body) {
+        super(body.message ?? `approval required: ${body.approvalId}`);
+        this.body = body;
+    }
+}
 // Store a durable insta_ key as the credential: set it as the bearer and drop any refresh token (an insta_ key never rotates; a stale one would leak to /auth/refresh on a 401).
 export function storeApiKeyCredential(cfg, token, user) {
     cfg.accessToken = token;
@@ -53,6 +61,8 @@ 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);
+        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;
@@ -76,6 +86,8 @@ 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}`;
+        if (auth)
+            Object.assign(headers, await agentHeaders(this, method, path, body === undefined ? '' : JSON.stringify(body)));
         const res = await this.fetchImpl(this.apiUrl + path, {
             method,
             headers,
@@ -113,6 +125,8 @@ export async function requireProject() {
     const p = await readProject();
     if (p)
         return p;
+    if (agentMode())
+        die('agent mode requires a linked project — run `insta setup agent --project <id>`');
     // One command, just works: unlinked ≠ error. Resolve the project (auto when there's one,
     // one-keystroke picker when several) and persist the choice so this happens once per dir.
     const api = await ApiClient.load();

package/dist/commands/agent-policy.js

@@ -0,0 +1,72 @@
+import { ApiClient, requireProject } from '../api.js';
+import { handleApproval, info, printJson } from '../util.js';
+async function current() {
+    const api = await ApiClient.load();
+    const project = await requireProject();
+    const path = `/projects/${project.projectId}/agent-policy`;
+    const out = await api.request('GET', path);
+    return { api, project, path, policy: out.policy, out };
+}
+export function displayPolicy(out, opts, output = { info, printJson }) {
+    const { info, printJson } = output;
+    const { policy, agentSessionEpoch } = out;
+    if (opts.json)
+        return printJson(out);
+    info(`agent policy: ${policy.mode}\nprotected branches: ${policy.protectedBranchIds.join(', ') || '(none)'}\nsession epoch: ${agentSessionEpoch}`);
+    if (out.effectiveRules) {
+        for (const [scope, rules] of Object.entries(out.effectiveRules)) {
+            info(`\n${scope}:`);
+            for (const [action, decision] of Object.entries(rules))
+                info(`  ${action}: ${decision}`);
+        }
+        info(`\nbootstrap: project.create = ${out.bootstrapRules?.['project.create'] ?? '(not reported)'}`);
+        for (const note of out.ruleNotes ?? [])
+            info(note);
+    }
+    else
+        info('This Platform does not expose resolved rules; upgrade Platform to inspect defaults.');
+}
+export async function get(opts) {
+    const { out } = await current();
+    // Forward the public response, never the internal API client (which holds credentials).
+    displayPolicy(out, opts);
+}
+async function update(change, opts) {
+    const state = await current();
+    await change(state.policy, state);
+    const result = await state.api.rawRequest('PUT', state.path, state.policy);
+    if (handleApproval(result, opts.json))
+        return;
+    if (opts.json)
+        return printJson(result.body);
+    info(`agent policy updated: ${result.body.policy.mode}`);
+}
+export async function set(mode, opts) {
+    const normalized = mode.replace(/-/g, '_');
+    if (!['full_access', 'read_only', 'branch_developer'].includes(normalized))
+        throw new Error('mode must be full-access, read-only, or branch-developer');
+    return update(policy => { policy.mode = normalized; }, opts);
+}
+export async function protect(branch, enabled, opts) {
+    return update(async (policy, { api, project }) => {
+        const { branches } = await api.request('GET', `/projects/${project.projectId}/branches`);
+        const found = branches.find((b) => b.id === branch || b.name === branch);
+        if (!found)
+            throw new Error('branch not found');
+        policy.protectedBranchIds = enabled ? [...new Set([...policy.protectedBranchIds, found.id])] : policy.protectedBranchIds.filter((id) => id !== found.id);
+    }, opts);
+}
+export async function rule(action, decision, opts) {
+    if (!['allow', 'deny', 'approve'].includes(decision))
+        throw new Error('decision must be allow, deny, or approve');
+    return update(policy => { policy.branchDeveloperRules[action] = decision; }, opts);
+}
+export async function revoke(opts) {
+    const api = await ApiClient.load();
+    const project = await requireProject();
+    const out = await api.request('POST', `/projects/${project.projectId}/agent-sessions/revoke`);
+    if (opts.json)
+        return printJson(out);
+    info(`all project agent sessions revoked (epoch ${out.agentSessionEpoch})`);
+}
+//# sourceMappingURL=agent-policy.js.map

package/dist/commands/compute.js

@@ -429,6 +429,8 @@ function operandIndices(argv, from, to = argv.length) {
 function execCommandIndex(argv) {
     for (let cursor = 2; cursor < argv.length; cursor++) {
         const token = argv[cursor];
+        if (token === '--agent')
+            continue;
         if (token.startsWith('-'))
             return -1; // a global flag, or `--`: either way not our command path
         return token === 'compute' && argv[cursor + 1] === 'exec' ? cursor : -1;
@@ -589,7 +591,7 @@ export async function computeAlwaysOn(mode, serviceName, opts) {
     if (opts.json)
         return printJson(res.body);
     const on = res.body.service?.always_on;
-    info(`compute ${res.body.service?.name ?? id}: always-on ${on ? 'ENABLED — machines stay warm (no cold starts; idle RAM bills at actual usage)' : 'disabled — scales to zero when idle (default)'}`);
+    info(`compute ${res.body.service?.name ?? id}: always-on ${on ? 'ENABLED — machines stay warm (no cold starts; idle RAM bills at actual usage)' : 'disabled — scales to zero when idle'}`);
 }
 // ---- limits (the resource ceiling; paid plans) ----
 // Parse a human memory value into MB: "512", "512mb", "1gb", "2g", "1.5gb".

package/dist/commands/govern.js

@@ -28,10 +28,10 @@ export async function approvalsList(opts) {
 export async function approvalsApprove(id, opts) {
     const api = await ApiClient.load();
     const p = await requireProject();
-    const out = await api.request('POST', `/projects/${p.projectId}/approvals/${id}/approve`, { always: !!opts.always });
+    const out = await api.request('POST', `/projects/${p.projectId}/approvals/${id}/approve`, {});
     if (opts.json)
         return printJson(out);
-    info(`approved ${out.approval.action} (${id})${opts.always ? ' — policy set to allow' : ''}`);
+    info(`approved ${out.approval.action} (${id})`);
 }
 export async function approvalsDeny(id, opts = {}) {
     const api = await ApiClient.load();
@@ -41,21 +41,4 @@ export async function approvalsDeny(id, opts = {}) {
         return printJson(out);
     info(`denied ${out.approval.action} (${id})`);
 }
-export async function policyGet(opts) {
-    const api = await ApiClient.load();
-    const p = await requireProject();
-    const { policy } = await api.request('GET', `/projects/${p.projectId}/policy`);
-    if (opts.json)
-        return printJson(policy);
-    for (const [action, decision] of Object.entries(policy))
-        info(`${action}: ${decision}`);
-}
-export async function policySet(action, decision, opts = {}) {
-    const api = await ApiClient.load();
-    const p = await requireProject();
-    const out = await api.request('PUT', `/projects/${p.projectId}/policy/${action}`, { decision });
-    if (opts.json)
-        return printJson({ action, decision, ...(out ?? {}) });
-    info(`policy ${action} = ${decision}`);
-}
 //# sourceMappingURL=govern.js.map

package/dist/commands/project.js

@@ -1,4 +1,5 @@
 import { homedir } from 'node:os';
+import { agentMode, setupProjectAgentSession } from '../agent.js';
 import { ApiClient, requireProject } from '../api.js';
 import { writeProject } from '../config.js';
 import { info, die, printJson, handleApproval, renderNextActions } from '../util.js';
@@ -76,6 +77,8 @@ export async function projectCreate(name, opts) {
     const orgId = await resolveOrg(api, opts.org);
     const out = await api.request('POST', `/orgs/${orgId}/projects`, { name: resolved });
     await writeProject({ projectId: out.project.id, orgId, branch: out.defaultBranch.name });
+    if (agentMode())
+        await setupProjectAgentSession(api, out.project.id);
     if (opts.json) {
         printJson({ ...out, linked: { projectId: out.project.id, orgId, branch: out.defaultBranch.name } });
     }
@@ -101,6 +104,8 @@ export async function projectList(opts) {
 }
 export async function projectLink(id, opts = {}) {
     const api = await ApiClient.load();
+    if (agentMode())
+        await setupProjectAgentSession(api, id);
     const { project } = await api.request('GET', `/projects/${id}`);
     await writeProject({ projectId: project.id, orgId: project.org_id, branch: 'main' });
     if (opts.json)

package/dist/commands/services.js

@@ -85,7 +85,10 @@ 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 } : {}),
-        ...(opts.alwaysOn ? { alwaysOn: true } : {}),
+        // 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.
+        ...(opts.alwaysOn !== undefined ? { alwaysOn: opts.alwaysOn } : {}),
         ...(opts.volume !== undefined ? { volumeGib: parseVolumeGib(opts.volume) } : {}),
     };
 }
@@ -102,8 +105,9 @@ export async function servicesAdd(type, name, opts = {}) {
             throw new Error('--port is only valid for compute services');
         parsePort(opts.port); // junk fails here, before any config/network access
     }
-    if (opts.alwaysOn && type !== 'compute')
-        throw new Error('--always-on is only valid for compute services (for postgres, use `insta db always-on on` after creation)');
+    // Presence, not truthiness: `--no-always-on` is an explicit false and is just as compute-only.
+    if (opts.alwaysOn !== undefined && type !== 'compute')
+        throw new Error('--always-on / --no-always-on is only valid for compute services (for postgres, use `insta db always-on on|off` after creation)');
     if (opts.volume !== undefined) {
         if (type !== 'compute')
             throw new Error('--volume is only valid for compute services (postgres has one by default — grow it with `insta db volume --size`)');

package/dist/commands/setup.js

@@ -11,6 +11,7 @@ import { join } from 'node:path';
 import os from 'node:os';
 import { createInterface } from 'node:readline';
 import { ApiClient } from '../api.js';
+import { setupProjectAgentSession } from '../agent.js';
 import { readPersistedGlobal, resolveEnv } from '../config.js';
 import { DEFAULT_ENV, ENVS, ENV_NAMES, envForApiUrl, envFromEnvVar, isEnvName, mcpServerName } from '../env.js';
 import { info, openUrl } from '../util.js';
@@ -362,7 +363,7 @@ export async function setupAgent(opts, run = defaultRunner, mint, installConfigs
     login: () => loginDevice({}, openUrl),
     stdinTty: canPromptViaTty(),
     stdoutTty: !!process.stdout.isTTY,
-}, link = projectLink, create = (n) => projectCreate(n, {})) {
+}, link = projectLink, create = (n) => projectCreate(n, {}), enroll = async () => setupProjectAgentSession(await ApiClient.load())) {
     if (!opts.yes && !process.stdout.isTTY) {
         info('non-interactive shell — assuming -y');
     }
@@ -457,6 +458,13 @@ export async function setupAgent(opts, run = defaultRunner, mint, installConfigs
             }
         }
     }
+    if (loggedIn) {
+        if (await enroll())
+            info('✓ Project agent session ready (expires in 24 hours; refresh with insta setup agent)');
+    }
+    else {
+        info('  project agent session not created — run `insta login`, then `insta setup agent`');
+    }
     // THE summary line. The restart note exists because config-file agents only read their MCP
     // config at startup; the skill files need no restart.
     const mcpOk = claude === 'new' || claude === 'existing' || others.length > 0;

package/dist/config.js

@@ -2,6 +2,7 @@
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { ensureGitignore } from './gitignore.js';
 import { DEFAULT_ENV, ENVS, envForApiUrl, envFromEnvVar, normalizeUrl } from './env.js';
 const GLOBAL_DIR = join(homedir(), '.insta');
 const GLOBAL_FILE = join(GLOBAL_DIR, 'config.json');
@@ -125,6 +126,7 @@ export async function readProject(cwd = process.cwd()) {
 export async function writeProject(c, cwd = process.cwd()) {
     const target = (await findProjectRoot(cwd)) ?? cwd;
     await mkdir(join(target, PROJECT_DIR), { recursive: true });
+    ensureGitignore(target, ['.insta/agent-session.json'], '# Local agent credentials');
     await writeFile(join(target, PROJECT_DIR, PROJECT_FILE), JSON.stringify(c, null, 2));
 }
 //# sourceMappingURL=config.js.map

package/dist/github-source.js

@@ -2,13 +2,17 @@
 // credentials. Parsing, ref resolution and the shallow clone live here; the deploy path stays in
 // commands/template.ts. See docs/superpowers/specs/2026-09-04-template-deploy-github-url-design.md.
 import { spawn as nodeSpawn } from 'node:child_process';
-import { mkdtempSync, rmSync, existsSync, realpathSync, statSync } from 'node:fs';
+import { mkdtempSync, rmSync, existsSync, realpathSync, statSync, readFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, sep } from 'node:path';
-import { loadTemplateManifest, MANIFEST_FILE } from './template-manifest.js';
+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.
-const EXPLICIT_ADDRESS = /^[a-z][a-z0-9+.-]*:\/\/|^[^/\\]+@[^/\\]+:/i;
+// 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
+// drive letter (`C:\src`, `C:/src`) stays a path.
+const EXPLICIT_ADDRESS = /^[a-z][a-z0-9+.-]+:|^[^/\\]+@[^/\\]+:/i;
 // Scheme-less first segments we still read as a host. A bare `<name>/<path>` is otherwise a LOCAL
 // PATH: `v1.0/templates` and `my.app/bot` are directories, and reading every dotted first segment
 // as a host broke them. Only names that unambiguously host code belong here.
@@ -251,6 +255,11 @@ export async function resolveGitHubRef(t, run) {
         throw new Error(`no branch or tag ${t.refAndPath} in ${t.owner}/${t.repo}`);
     return split;
 }
+/** What to call the manifest in a message: where the user pointed, never the temporary clone that
+ *  is deleted before they read it. */
+export function manifestLabel(t, r) {
+    return `${t.owner}/${t.repo}@${r.ref}:${r.path ? `${r.path}/` : ''}${MANIFEST_FILE}`;
+}
 export function missingManifestMessage(t, r) {
     return [
         `no ${MANIFEST_FILE} at ${t.owner}/${t.repo}@${r.ref}:${r.path || '/'}.`,
@@ -271,7 +280,7 @@ function containedRealPath(root, candidate) {
 /** Resolve the ref, shallow-clone it, read the commit that was checked out, prove the manifest
  *  sits inside the clone, parse it, delete the clone. Nothing on disk outlives this call: not the
  *  variable prompt, not the POST, not the watcher. */
-export async function fetchGitHubTemplate(target, run = defaultGitRunner, load = loadTemplateManifest) {
+export async function fetchGitHubTemplate(target, run = defaultGitRunner, parse = parseManifestYaml) {
     const resolved = await resolveGitHubRef(target, run);
     const dir = mkdtempSync(join(tmpdir(), 'insta-tpl-gh-'));
     try {
@@ -303,7 +312,9 @@ export async function fetchGitHubTemplate(target, run = defaultGitRunner, load =
         const real = containedRealPath(dir, join(manifestDir, MANIFEST_FILE));
         if (!real || !statSync(real).isFile())
             throw new Error(escapedManifestMessage(target, resolved));
-        const manifest = load(manifestDir);
+        // Read and parse separately so a validation failure names where the user pointed. Handing the
+        // loader a directory makes it report the temp path, which is gone by the time they see it.
+        const manifest = parse(readFileSync(real, 'utf8'), manifestLabel(target, resolved));
         return {
             source: { repo: `${target.owner}/${target.repo}`, ref: resolved.ref, path: resolved.path, commit },
             manifest,

package/dist/index.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
-import { ApiError } from './api.js';
+import { configureAgent, detectAgent } from './agent.js';
+import * as agentPolicy from './commands/agent-policy.js';
+import { ApiError, AgentApprovalRequired } from './api.js';
 import { CliCancel, CliExit, fail, relayedExitCode } from './util.js';
 import { trackCommand } from './telemetry.js';
 import { cliVersion } from './version.js';
@@ -32,6 +34,14 @@ import { billing, billingUpgrade, billingPortal } from './commands/billing.js';
 import * as selfUpdate from './commands/upgrade.js';
 import * as feedbackCmd from './commands/feedback.js';
 function onError(e) {
+    if (e instanceof AgentApprovalRequired) {
+        if (process.argv.includes('--json'))
+            process.stdout.write(JSON.stringify(e.body) + '\n');
+        else
+            process.stderr.write(e.message + '\n');
+        process.exitCode = 2;
+        return;
+    }
     if (e instanceof CliExit || e instanceof CliCancel)
         return;
     if (e instanceof ApiError)
@@ -64,6 +74,8 @@ const program = new Command();
 // against the subcommand's own (identically-named) option instead.
 program.enablePositionalOptions();
 program.name('insta').description('InstaCloud CLI — manage projects, branches, secrets, deploys').version(cliVersion());
+program.option('--agent', 'run as an agent with a verified project session and project agent policy');
+program.hook('preAction', () => configureAgent(detectAgent(!!program.opts().agent)));
 // ---- auth ----
 program.command('login').description('Log in — bare: sign in from your browser (any account type); or --email <email> + password, --oauth <github|google>, --device (headless), --api-key <insta_…> (headless, durable token)')
     .option('--email <email>', 'account email (email + password login)')
@@ -131,7 +143,8 @@ svc.command('add [type] [name]').description('Provision a service on demand (ass
     .option('--public', 'storage only: serve the bucket with anonymous public-read (default private)')
     .option('--image <url>', 'compute only: run this container image at creation')
     .option('--port <n>', 'compute only: port the image listens on (default 8080)')
-    .option('--always-on', 'compute only: create as always-on — never scales to zero (all plans; billing is actual usage either way)')
+    .option('--always-on', 'compute only: create as always-on — never scales to zero (the default for new compute services; all plans; billing is actual usage either way)')
+    .option('--no-always-on', 'compute only: create as scale-to-zero — idle machines suspend and wake on the next request')
     .option('--volume <gi>', 'compute only: attach a persistent /data volume of this many whole Gi (also attachable later: `insta compute volume <name> --size <gi>`; any plan may attach at the default 10 (the free cap, on every plan); larger sizes are paid and plan-capped). Volume services keep 1 machine and stop (cold wake) instead of suspend when idle')
     .option('--json')
     .action(guard(async (type, name, o) => {
@@ -223,7 +236,7 @@ compute.command('status [service]').description("Show a compute service's desire
 compute.command('limits [service]').description("Show or set a compute service's resource ceiling (any plan within the free cap; raising above it needs a paid plan). --memory is the dial; cpu derives from it unless --cpu is given. Billing is actual usage — the ceiling caps what the app may burn, it is not a price")
     .option('--memory <size>', 'memory ceiling, e.g. 512mb or 1gb').option('--cpu <n>', 'vCPU ceiling override (provider sizes: 1, 2, 4, 6, 8)')
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => computeCmd.computeLimits(service, o)));
-compute.command('always-on <mode> [service]').description('Set a compute service always-on (mode: on|off). on = machines never scale to zero; off = default scale-to-zero. All plans; billing is actual usage either way')
+compute.command('always-on <mode> [service]').description('Set a compute service always-on (mode: on|off). on = machines never scale to zero (the default for new compute services); off = scale-to-zero. All plans; billing is actual usage either way')
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((mode, service, o) => computeCmd.computeAlwaysOn(mode, service, o)));
 const execCmd = compute.command('exec [service]').description("Run a one-shot command inside a compute service's machine (`insta compute exec [service] -- <command> [args…]`) — no interactive shell/PTY: `command` is argv, no shell is invoked (use [\"sh\", \"-c\", \"...\"] for shell features). Wakes the machine first if it's scaled to zero — expect a few seconds of latency, billed as uptime, not an error. Exits with the remote command's own exit code (agents rely on this)")
     .action(guard((service, o) => computeCmd.computeExec(service, execCommand, o, { windowsFallback: execWindowsFallback })));
@@ -323,7 +336,7 @@ program.command('events').description('Show the audit + agent-event timeline').o
 // ---- approvals ----
 const ap = program.command('approvals').description('Governance approvals (HITL)');
 ap.command('list').option('--status <s>', 'pending|granted|denied|consumed').option('--json').action(guard((o) => govern.approvalsList(o)));
-ap.command('approve <id>').option('--always', 'also set the policy to allow').option('--json').action(guard((id, o) => govern.approvalsApprove(id, o)));
+ap.command('approve <id>').option('--json').action(guard((id, o) => govern.approvalsApprove(id, o)));
 ap.command('deny <id>').option('--json').action(guard((id, o) => govern.approvalsDeny(id, o)));
 // ---- observe (local credential audit) ----
 const ob = program.command('observe').description('Local credential-audit hook');
@@ -332,9 +345,16 @@ ob.command('uninstall').action(guard(() => observe.observeUninstall()));
 ob.command('report').description('Render the local credential audit').option('--json').action(guard((o) => observe.observeReport(o)));
 ob.command('sync').description('Upload findings into the project timeline').action(guard(() => observe.observeSync()));
 // ---- policy ----
-const pol = program.command('policy').description('Governance policy');
-pol.command('get').option('--json').action(guard((o) => govern.policyGet(o)));
-pol.command('set <action> <decision>').description('action: secrets.read|secrets.write|deploy|project.delete|branch.delete|service.add|service.remove|service.scale|service.upgrade|service.setAccess|storage.read|storage.write|storage.delete; decision: allow|deny|approve').option('--json').action(guard((a, d, o) => govern.policySet(a, d, o)));
+const agentPol = program.command('agent-policy').description('Project agent access policy');
+agentPol.command('get').option('--json').action(guard((o) => agentPolicy.get(o)));
+agentPol.command('set <mode>').description('full-access | read-only | branch-developer')
+    .option('--json').action(guard((mode, o) => agentPolicy.set(mode, o)));
+agentPol.command('protect-branch <branch>').option('--json').action(guard((branch, o) => agentPolicy.protect(branch, true, o)));
+agentPol.command('unprotect-branch <branch>').option('--json').action(guard((branch, o) => agentPolicy.protect(branch, false, o)));
+agentPol.command('rule').command('set <action> <decision>').description('Set an unprotected-branch rule: allow | deny | approve')
+    .option('--json').action(guard((action, decision, o) => agentPolicy.rule(action, decision, o)));
+agentPol.command('revoke-sessions').description('Revoke ALL CLI agent sessions for this project')
+    .option('--json').action(guard((o) => agentPolicy.revoke(o)));
 // ---- feedback (agent + human hurdle reports → the InstaCloud team) ----
 program.command('feedback')
     .description('Report an InstaCloud-side hurdle (bug / missing feature / friction) to the InstaCloud team — about the insta toolkit itself, NEVER about the app you are building. Works logged-out and unlinked.')

package/dist/telemetry.js

@@ -39,7 +39,7 @@ const SAFE_ARGS = {
     'compute always-on': { 0: ON_OFF }, 'db always-on': { 0: ON_OFF }, metrics: { 0: TARGET }, logs: { 0: TARGET },
     'template info': { 0: SLUG }, 'billing upgrade': { 0: oneOf(['pro', 'team']) },
     'approvals approve': { 0: ID }, 'approvals deny': { 0: ID },
-    'policy set': { 0: POLICY_ACTION, 1: oneOf(['allow', 'deny', 'approve']) }, autoupdate: { 0: ON_OFF },
+    'agent-policy rule set': { 0: POLICY_ACTION, 1: oneOf(['allow', 'deny', 'approve']) }, autoupdate: { 0: ON_OFF },
 };
 const SAFE_OPTIONS = {
     org: ID, project: ID, region: REGION, env: ENV, oauth: oneOf(['github', 'google']),

package/dist/template-manifest.js

@@ -78,8 +78,30 @@ export function validateManifest(m) {
     for (const name of names) {
         const svc = services[name] ?? {};
         const where = `services.${name}`;
-        if (svc.type !== 'web' && svc.type !== 'worker')
-            problems.push(`${where}.type must be web or worker`);
+        if (svc.type !== 'web' && svc.type !== 'worker' && svc.type !== 'postgres') {
+            problems.push(`${where}.type must be web, worker or postgres`);
+        }
+        // A managed postgres service is BARE: the platform owns its image, port, sizing, credentials
+        // and env, so every other rule below would be asking about fields it must not carry. Mirrors
+        // the platform's own check (provisioning/templateManifest.ts) so an author hears it here.
+        if (svc.type === 'postgres') {
+            const bare = svc;
+            for (const field of ['image', 'build', 'port', 'healthcheck', 'volume', 'volumeGib', 'spec', 'alwaysOn']) {
+                if (bare[field] !== undefined) {
+                    problems.push(`${where}.${field}: a postgres service is platform-managed and carries no ${field} — declare it bare ({ type: postgres })`);
+                }
+            }
+            const groups = ['fixed', 'generated', 'platform', 'required', 'optional'];
+            const envShell = bare.env;
+            if (envShell !== undefined) {
+                const emptyShell = !!envShell && typeof envShell === 'object' && !Array.isArray(envShell)
+                    && Object.entries(envShell).every(([g, v]) => groups.includes(g) && !!v && typeof v === 'object' && !Array.isArray(v) && Object.keys(v).length === 0);
+                if (!emptyShell) {
+                    problems.push(`${where}.env: a postgres service is platform-managed and carries no env — declare it bare ({ type: postgres })`);
+                }
+            }
+            continue;
+        }
         if (svc.image && svc.build)
             problems.push(`${where}: image and build are mutually exclusive`);
         if (!svc.image && !svc.build)

package/package.json

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