insta 0.1.1 → 0.1.3

package/README.md

@@ -224,6 +224,7 @@ build never reaches a production installer.
 | `insta redis` · `mysql` · `mongodb` | `query` · `status` · `limits` · `volume` · `always-on` · `logs` · `metrics` |
 | `insta storage` | `list` · `get` · `delete` · `set-access` |
 | `insta build [dir]` · `deploy [dir]` | Verify a source dir would build; deploy a source directory (built remotely) or `--image <url>`. `insta build logs <id>` reads source-build output: `--source archive` (default) uses the deploy operation ID, `--source github` uses a GitHub build ID; `--follow` watches output, `--json` returns one snapshot |
+| `insta cron` | Branch-scoped HTTP schedules: `list` · `create` · `show` · `edit` · `pause` · `resume` · `delete` · `run` · `runs` · `preview`. Expressions are UTC and so is every time printed; `run` is one EXTRA execution and does not consume the next scheduled tick; header values are write-only, so `show` lists header names only |
 | `insta run <cmd>` | Run a command with the branch bundle injected, nothing written to disk |
 | `insta template` | `list` · `info` · `deploy` |
 | `insta billing` | Current cycle overview; `subscribe <tier>` · `portal` · `usage` |

package/dist/api.js

@@ -2,7 +2,7 @@
 // 2xx (including 202 approval_required) returns the parsed body; >=400 throws ApiError.
 import { readGlobal, readPersistedGlobal, writeGlobal, readProject, persistAutoLink, resolveProjectLink, foreignLinkMessage } from './config.js';
 import { autoResolveProject, promptChoice } from './resolve-project.js';
-import { die } from './util.js';
+import { approvalHint, die } from './util.js';
 import { USER_AGENT } from './version.js';
 import { agentHeaders, agentMode } from './agent.js';
 export class ApiError extends Error {
@@ -19,8 +19,9 @@ export class ApiError extends Error {
 }
 export class AgentApprovalRequired extends Error {
     body;
+    // The platform's message already carries the review link; a runtime that sends none gets the CLI's own hint.
     constructor(body) {
-        super(body.message ?? `approval required: ${body.approvalId}`);
+        super(body.message ?? approvalHint(body));
         this.body = body;
     }
 }
@@ -104,6 +105,8 @@ export class ApiClient {
     }
     async fetch(method, path, body, auth, scope = {}) {
         const headers = { 'Content-Type': 'application/json', 'Insta-Hints': '1', 'User-Agent': USER_AGENT };
+        if (scope.headers)
+            Object.assign(headers, scope.headers);
         if (auth && this.cfg.accessToken)
             headers.Authorization = `Bearer ${this.cfg.accessToken}`;
         const payload = body === undefined ? undefined : JSON.stringify(body);

package/dist/commands/compute.js

@@ -653,13 +653,18 @@ export function volumeLines(name, volume, cap, type = 'compute') {
         : 'grow with --size (grow-only); the volume cannot be deleted — remove the service instead';
     return [
         `${type} ${name}: volume ${volume.sizeGib}Gi at ${volume.mountPath}  (plan max ${cap.volumeGib}Gi)`,
+        ...(volume.pending && volume.appliedMountPath != null ? [`  pending: ${volume.appliedMountPath ?? '(not deployed)'} → ${volume.mountPath}; deploy to apply (restarts the service). Application configuration is not updated automatically.`] : []),
         `  billing is actual data stored — the size is a cap, not a price; ${grow}`,
     ];
 }
 // Render the PUT result. Pure, exported for tests. `attached` comes from the backend and is what
 // tells a FIRST attach (no disk yet — it mounts on the next deploy) apart from a grow (the live
 // disk was already extended); the wire size is authoritative in both cases.
-export function volumeWriteLine(name, body, type = 'compute') {
+export function volumeWriteLine(name, body, type = 'compute', sizeRequested = true) {
+    const pending = body.volume.pending && body.volume.appliedMountPath != null
+        ? `; mount path ${body.volume.appliedMountPath} → ${body.volume.mountPath} pending — deploy or restart to apply. Update application paths and startup commands yourself.` : '';
+    if (body.changed === false && !body.attached)
+        return `${type} ${name}: volume unchanged: ${body.volume.sizeGib}Gi at ${body.volume.mountPath}${pending}`;
     if (body.attached) {
         // Only a compute service has a deploy step for the mount to wait on; a managed database has
         // no deploy, so its disk is simply mounted.
@@ -668,7 +673,7 @@ export function volumeWriteLine(name, body, type = 'compute') {
             : `mounts at ${body.volume.mountPath}`;
         return `${type} ${name}: volume ${body.volume.sizeGib}Gi attached — ${mounts}  (plan max ${body.cap.volumeGib}Gi)`;
     }
-    return `${type} ${name}: volume grown to ${body.volume.sizeGib}Gi at ${body.volume.mountPath}  (plan max ${body.cap.volumeGib}Gi)`;
+    return `${type} ${name}: volume ${sizeRequested ? 'grown to ' : ''}${body.volume.sizeGib}Gi at ${body.volume.mountPath}  (plan max ${body.cap.volumeGib}Gi)${pending}`;
 }
 // Render the DELETE result. Pure, exported for tests. Deleting is the only way off the volume
 // path (there is no detach), so the line says what came back with it: the two constraints the
@@ -702,10 +707,10 @@ export function volumeDeleteError(e) {
 // 403/400 messages carry the upgrade hints and must reach the user verbatim (the guard prints
 // ApiError messages as-is).
 export async function serviceVolume(type, serviceName, opts) {
+    if (opts.size !== undefined && !opts.size.trim())
+        throw new Error('--size must not be empty; specify a whole Gi value or omit --size for a path-only edit');
     if (opts.delete && opts.mountPath !== undefined)
         throw new Error('--delete cannot be combined with --mount-path');
-    if (opts.mountPath !== undefined && !opts.size)
-        throw new Error('--mount-path requires --size when attaching a volume');
     if (opts.delete && opts.size)
         throw new Error('--delete cannot be combined with --size (one changes the volume, the other destroys it)');
     const api = await ApiClient.load();
@@ -728,7 +733,7 @@ export async function serviceVolume(type, serviceName, opts) {
         info(volumeDeleteLine(res.body.service?.name ?? svc.name, type));
         return;
     }
-    if (!opts.size) {
+    if (!opts.size && opts.mountPath === undefined) {
         const r = await api.request('GET', `/projects/${p.projectId}/services/${svc.id}/volume`);
         if (opts.json)
             return printJson(r);
@@ -736,13 +741,18 @@ export async function serviceVolume(type, serviceName, opts) {
             info(line);
         return;
     }
-    const sizeGib = parseVolumeGib(opts.size);
+    if (opts.mountPath !== undefined && opts.size === undefined) {
+        const current = await api.request('GET', `/projects/${p.projectId}/services/${svc.id}/volume`);
+        if (!current.volume)
+            throw new Error(`no volume attached; attach one with insta compute volume ${svc.name} --size <gi> --mount-path ${opts.mountPath}`);
+    }
+    const sizeGib = opts.size === undefined ? undefined : parseVolumeGib(opts.size);
     const res = await api.rawRequest('PUT', `/projects/${p.projectId}/services/${svc.id}/volume`, { sizeGib, ...(opts.mountPath !== undefined ? { mountPath: opts.mountPath } : {}) });
     if (handleApproval(res, opts.json))
         return;
     if (opts.json)
         return printJson(res.body);
-    info(volumeWriteLine(res.body.service?.name ?? svc.name, res.body, type));
+    info(volumeWriteLine(res.body.service?.name ?? svc.name, res.body, type, opts.size !== undefined));
 }
 export const computeVolume = (serviceName, opts) => serviceVolume('compute', serviceName, opts);
 // Show or set a compute service's ceiling. With no --memory it PRINTS the current limits and the
@@ -1972,4 +1982,24 @@ export function hostPatternFor(host, suffixes) {
     const parts = host.split('.');
     return [parts[0], '*', ...parts.slice(2)].join('.');
 }
+export async function computeStartCommand(serviceName, opts) {
+    if (opts.set !== undefined && opts.clear)
+        throw new Error('use --set or --clear, not both');
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    const { services } = await api.request('GET', `/projects/${p.projectId}/services${q(opts.branch ?? p.branch)}`);
+    const svc = resolveSoleService(services, 'compute', serviceName);
+    if (opts.set === undefined && !opts.clear) {
+        if (opts.json)
+            return printJson({ service: svc });
+        info(`compute ${svc.name}: startup command ${svc.start_command || '(image default)'}`);
+        return;
+    }
+    const res = await api.rawRequest('PATCH', `/projects/${p.projectId}/services/${svc.id}`, { startCommand: opts.clear ? '' : opts.set });
+    if (handleApproval(res, opts.json))
+        return;
+    if (opts.json)
+        return printJson(res.body);
+    info('Startup command saved; deploy or restart after staging the volume path. CLI secrets changes deploy immediately; use Console to combine variable, command and path changes.');
+}
 //# sourceMappingURL=compute.js.map

package/dist/commands/cron.js

@@ -0,0 +1,519 @@
+// `insta cron` — schedules that send one HTTP request on a cron expression, to a compute service of
+// the project or to an external URL.
+//
+// Three properties of the platform API shape this whole module, and none of them is plumbing:
+//
+//   1. A job is addressed by NAME here and by ID on the wire (names are unique per project+branch),
+//      so every subcommand resolves name → id from the branch listing first, exactly as
+//      resolve-service.ts resolves a service.
+//   2. Times are UTC. The expression is evaluated in UTC by the platform and this prints every
+//      timestamp as UTC with the Z visible: a job pinned to UTC does NOT keep a fixed local time,
+//      so a localised column would read correctly today and lie twice a year, in both directions.
+//   3. Header VALUES are write-only — the request config is encrypted at rest and no read decrypts
+//      it. `show` can therefore list header NAMES and nothing else, and `edit` REPLACES the request
+//      rather than merging into one it cannot read (see cronEditWarnings).
+import { randomUUID } from 'node:crypto';
+import { ApiClient, ApiError, requireProject } from '../api.js';
+import { die, handleApproval, info, printJson, refuse } from '../util.js';
+import { q, resolveSoleService } from './services.js';
+// ---- pure, unit-tested helpers (throw plain Errors; the CLI guard turns them into clean output) ----
+// The API's own bounds (openapi/schemas/cron.ts), enforced here so junk fails before any network or
+// config access — the parsePort lesson: `Number('5s')` is NaN and NaN serializes to null on the wire.
+const MIN_TIMEOUT_MS = 1000;
+const MAX_TIMEOUT_MS = 300_000;
+const MAX_RUNS_PAGE = 100;
+export const CRON_METHODS = ['GET', 'POST'];
+/** Parse `--method`. Case-insensitive, because a method is conventionally written in caps and a
+ *  shell user types what they read in the docs. */
+export function parseMethod(raw) {
+    const m = raw.trim().toUpperCase();
+    if (!CRON_METHODS.includes(m))
+        throw new Error(`method must be ${CRON_METHODS.join('|')}, got: ${raw}`);
+    return m;
+}
+/** Parse `--timeout <ms>`. Decimal digits only, as parsePort: `0x1388` is a typo, not 5000. */
+export function parseTimeout(raw) {
+    const m = /^\s*(\d+)\s*$/.exec(raw);
+    const n = m ? Number(m[1]) : NaN;
+    if (!Number.isInteger(n) || n < MIN_TIMEOUT_MS || n > MAX_TIMEOUT_MS) {
+        throw new Error(`--timeout must be an integer between ${MIN_TIMEOUT_MS} and ${MAX_TIMEOUT_MS} ms, got: ${raw}`);
+    }
+    return n;
+}
+/** Parse `--limit <n>` for run history, inside the page the API serves. */
+export function parseRunLimit(raw) {
+    const m = /^\s*(\d+)\s*$/.exec(raw);
+    const n = m ? Number(m[1]) : NaN;
+    if (!Number.isInteger(n) || n < 1 || n > MAX_RUNS_PAGE)
+        throw new Error(`--limit must be an integer 1..${MAX_RUNS_PAGE}, got: ${raw}`);
+    return n;
+}
+/**
+ * Parse one `--header k=v`. Split on the FIRST `=` only: a header value is free-form and routinely
+ * contains one (`authorization=Bearer a=b`, any base64 padding), so splitting on every `=` would
+ * quietly truncate exactly the credentials this flag exists to carry.
+ */
+export function parseHeader(raw) {
+    const at = raw.indexOf('=');
+    if (at < 1)
+        throw new Error(`--header must be name=value, got: ${raw}`);
+    const name = raw.slice(0, at).trim();
+    if (!name)
+        throw new Error(`--header must be name=value, got: ${raw}`);
+    return [name, raw.slice(at + 1)];
+}
+/**
+ * Collect repeated `--header` flags. A name given twice is an error rather than last-wins: the
+ * request carries one value per header, and silently dropping one of two credentials an agent
+ * passed is the failure that shows up later as a 401 nobody can explain.
+ */
+export function parseHeaders(list) {
+    const out = {};
+    for (const raw of list) {
+        const [name, value] = parseHeader(raw);
+        // Header names are case-insensitive on the wire, so a case-varied repeat is the same repeat.
+        const clash = Object.keys(out).find((k) => k.toLowerCase() === name.toLowerCase());
+        if (clash !== undefined)
+            throw new Error(`--header ${name} given twice (also as ${clash}) — a header carries one value`);
+        out[name] = value;
+    }
+    return out;
+}
+/** Resolve a cron job by the name the CLI addresses it with (mirrors resolveServiceId). */
+export function resolveJob(jobs, name) {
+    const job = jobs.find((j) => j.name === name);
+    if (!job)
+        throw new Error(`cron job not found: ${name}`);
+    return job;
+}
+/**
+ * A timestamp as UTC, with the marker visible: `2026-09-17 14:05:00Z`.
+ *
+ * Never localised. The expression is evaluated in UTC, so `0 3 * * *` fires at 03:00Z year-round —
+ * rendering that as a local time would show two different wall clocks across a DST boundary for a
+ * schedule that never moved, and the operator reading the column would blame the scheduler.
+ */
+export function fmtUtc(iso) {
+    if (!iso)
+        return '—';
+    const m = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2})/.exec(iso);
+    return m ? `${m[1]} ${m[2]}Z` : iso;
+}
+/**
+ * One-line rendering of where a job sends its request. The service and its path are separated by an
+ * arrow rather than concatenated: `compute/api/api/cron` hides where the service name ends, and the
+ * service half is the part a reader has to match against `insta services list`.
+ */
+export function targetLine(t, serviceName) {
+    return t.kind === 'external' ? t.url : `${serviceName ? `compute/${serviceName}` : `service ${t.serviceId}`} → ${t.path}`;
+}
+/** One `cron list` row. Pure, so the columns are unit-tested (a template string nothing asserts on
+ *  silently loses a segment — the serviceListLine lesson). */
+export function jobListLine(j, serviceName) {
+    return `${j.name}  [${j.enabled ? 'enabled' : 'paused'}]  ${j.expression}  next ${fmtUtc(j.next_run_at)}  ${targetLine(j.target, serviceName)}  ${j.id}`;
+}
+/** The retry policy in one cell, with the platform's own defaults named when the job sets none. */
+export function retryLine(p) {
+    const statuses = p.retryableStatuses?.length ? `  retry on ${p.retryableStatuses.join(',')}` : '';
+    const age = p.maxRunAgeMs !== undefined ? `  give up after ${p.maxRunAgeMs}ms` : '';
+    return `platform ${p.platformMaxRetries ?? 2}, application ${p.applicationMaxRetries ?? 0}${statuses}${age}`;
+}
+/** `cron show`, as lines. */
+export function jobShowLines(j, serviceName) {
+    const lines = [
+        `cron/${j.name}  [${j.enabled ? 'enabled' : 'paused'}]  on ${j.branch}  ${j.id}`,
+        `  expression   ${j.expression}  (${j.timezone})`,
+        `  next run     ${fmtUtc(j.next_run_at)}`,
+        `  target       ${targetLine(j.target, serviceName)}`,
+        `  request      ${j.request.method}  timeout ${j.request_timeout_ms}ms`,
+    ];
+    // Names, never values: the request config is encrypted at rest and no read decrypts it. Saying so
+    // beats an empty "value" column that reads as "this header is set to nothing".
+    lines.push(j.request.headerNames.length
+        ? `  headers      ${j.request.headerNames.join(', ')}  (names only — values are encrypted at rest and never returned)`
+        : '  headers      (none)');
+    lines.push(`  retry        ${retryLine(j.retry_policy)}`);
+    lines.push(`  revision     ${j.revision}  (the If-Match an edit is conditioned on)`);
+    lines.push(`  created      ${fmtUtc(j.created_at)}   updated ${fmtUtc(j.updated_at)}`);
+    return lines;
+}
+/**
+ * One `cron runs` row. This is the surface an operator (or an agent) reads when a job is
+ * misbehaving, so it carries the facts that separate the possible causes: the wake and the request
+ * are timed apart because a slow cold start is the platform's problem and a slow response is the
+ * target's, and the HTTP status distinguishes "your endpoint said no" from "nothing was ever sent".
+ */
+export function runListLine(row) {
+    const { run, attempts } = row;
+    const last = attempts?.length ? attempts[attempts.length - 1] : undefined;
+    // Fall back to the counters when the attempts could not be read: a retried run has made
+    // 1 + retries attempts, and the count is still worth printing without them.
+    const count = attempts ? attempts.length : run.platform_retry_count + run.application_retry_count + 1;
+    const timing = last
+        ? `wake ${last.wake_ms ?? '—'}ms  req ${last.request_ms ?? '—'}ms`
+        : attempts ? 'wake —  req —' : 'wake ?  req ?';
+    const outcome = last?.http_status != null
+        ? `http ${last.http_status}`
+        : last?.failure_kind
+            ? `${last.failure_kind}${last.error_code ? ` (${last.error_code})` : ''}`
+            : run.skip_reason ? `skipped: ${run.skip_reason}` : '—';
+    return [
+        fmtUtc(run.scheduled_at),
+        // 10, the width of the longest status the platform has (`retry_wait`): a column padded to the
+        // second-longest is a column that jumps exactly when the history gets interesting.
+        run.status.padEnd(10),
+        run.trigger_type.padEnd(9),
+        `${count} attempt${count === 1 ? '' : 's'}`.padEnd(11),
+        timing.padEnd(24),
+        outcome.padEnd(16),
+        run.id,
+    ].join('  ');
+}
+/** `cron preview`, as lines. Invalid is an ANSWER here, not a transport error (the API says so too). */
+export function previewLines(expression, p) {
+    if (!p.valid)
+        return [`invalid cron expression: ${p.error ?? 'unparseable'}`];
+    return [`${expression}  ${p.description}  (UTC)`, ...p.next.map((n) => `  ${fmtUtc(n)}`)];
+}
+/** What to say when a PATCH loses the If-Match race. Never a silent re-read: the schedule moved
+ *  under this command, and re-reading to retry is how one of the two edits disappears. */
+export function conflictLines(name, revision, what) {
+    return [
+        `refusing to ${what}: cron job ${name} changed since revision ${revision} — someone (or something) else edited it while this command was running.`,
+        `nothing was written. read it again and decide:  insta cron show ${name}`,
+    ];
+}
+/** True when any flag that shapes the stored request was given. */
+export function namesRequest(o) {
+    return o.method !== undefined || o.body !== undefined || (o.header?.length ?? 0) > 0;
+}
+/** True when any flag that names a target was given. */
+export function namesTarget(o) {
+    return o.url !== undefined || o.service !== undefined || o.path !== undefined;
+}
+/**
+ * Validate the target flags. Not merged with target building: building needs the service listing
+ * (a network round trip), and a command whose flags contradict each other must fail before it.
+ * `partial` is the edit case, where naming no target at all means "leave it alone".
+ */
+export function assertTargetFlags(o, partial = false) {
+    if (o.url && o.service)
+        throw new Error('--url and --service name two different targets — pass one');
+    if (o.path !== undefined && !o.service)
+        throw new Error('--path applies to --service (an external target carries its path in the --url)');
+    if (!partial && !o.url && !o.service)
+        throw new Error('name a target: --url <https://…> or --service <name> [--path /api/cron]');
+    if (o.url !== undefined && !/^https?:\/\//i.test(o.url))
+        throw new Error(`--url must be an absolute http(s) URL, got: ${o.url}`);
+    if (o.path !== undefined && !o.path.startsWith('/'))
+        throw new Error(`--path must start with /, got: ${o.path}`);
+}
+/** The stored request, from the flags alone. `undefined` when no flag shaped one. */
+export function buildRequest(o) {
+    if (!namesRequest(o))
+        return undefined;
+    const method = o.method ? parseMethod(o.method) : o.body !== undefined ? 'POST' : 'GET';
+    // A body on a GET is a typo with a plausible-looking outcome: the platform would send it and most
+    // targets would ignore it, so the job would run "fine" and do nothing. `--body` alone implies
+    // POST; `--body` with an explicit `--method GET` is a contradiction and says so.
+    if (o.body !== undefined && method !== 'POST')
+        throw new Error('--body is sent on POST only — drop --method GET, or drop --body');
+    const headers = o.header?.length ? parseHeaders(o.header) : undefined;
+    return { method, ...(headers ? { headers } : {}), ...(o.body !== undefined ? { body: o.body } : {}) };
+}
+/**
+ * What an edit that reshapes the request is about to LOSE.
+ *
+ * The API replaces `request` wholesale — it cannot merge, because a deep merge cannot express
+ * "remove this header", and the CLI could not merge either even if the API did: header values are
+ * write-only, so the values currently stored are unreadable here. Anything the new flags do not
+ * re-supply is therefore gone, and the one thing this command must not do is drop a credential
+ * without saying which one.
+ */
+export function cronEditWarnings(current, next) {
+    const out = [];
+    const kept = new Set(Object.keys(next.headers ?? {}).map((h) => h.toLowerCase()));
+    const dropped = current.headerNames.filter((n) => !kept.has(n.toLowerCase()));
+    if (dropped.length) {
+        out.push(`warning: the stored request is replaced, not merged (header values are write-only and cannot be read back) — these headers are dropped: ${dropped.join(', ')}`);
+    }
+    // The METHOD is part of the request being replaced, and changing it is the quietest way to break
+    // a job: `--header` alone on a POST job re-shapes the whole request, and the default method for a
+    // request with no --body is GET. The job then runs, answers 200, and does nothing.
+    if (current.method !== next.method) {
+        out.push(`warning: the request method changes ${current.method} → ${next.method} — pass --method ${current.method} to keep it`);
+    }
+    // The BODY cannot be read back either, so its loss cannot be detected by comparing; what CAN be
+    // said is when the stored request was one that carries a body and the new flags supply none.
+    // Silence here was the actual gap: the command promised to name what it drops and named only
+    // headers, so a POST job edited with `--header` alone lost its payload without a word.
+    if (current.method === 'POST' && next.body === undefined) {
+        out.push('warning: the stored request body (write-only, and not readable here) is dropped — re-supply it with --body, or pass --method GET if the job should stop sending one');
+    }
+    return out;
+}
+// ---- API plumbing ----
+const jobsPath = (projectId) => `/projects/${projectId}/cron-jobs`;
+/** Injected whole in tests; resolved from the config and the linked project otherwise. */
+async function context(opts, injected) {
+    if (injected)
+        return injected;
+    const api = await ApiClient.load();
+    const p = await requireProject();
+    return { api, projectId: p.projectId, branch: opts.branch ?? p.branch };
+}
+async function listJobs(c) {
+    const { jobs } = await c.api.request('GET', `${jobsPath(c.projectId)}${q(c.branch)}`);
+    return jobs;
+}
+/** Name → the job itself: the listing is the resolution step, as it is for services. */
+async function findJob(c, name) {
+    return resolveJob(await listJobs(c), name);
+}
+/** The compute service a `--service <name>` target names, resolved on the same branch as the job. */
+async function computeTarget(c, name, path) {
+    const { services } = await c.api.request('GET', `/projects/${c.projectId}/services${q(c.branch)}`);
+    return { kind: 'service', serviceId: resolveSoleService(services, 'compute', name).id, path };
+}
+/** Service id → name, so a target reads as `compute/api/cron` instead of a uuid. Best effort: a
+ *  target in another project of the org is legal and simply has no name on this branch. */
+async function serviceNames(c, jobs) {
+    if (!jobs.some((j) => j.target.kind === 'service'))
+        return new Map();
+    try {
+        const { services } = await c.api.request('GET', `/projects/${c.projectId}/services${q(c.branch)}`);
+        return new Map(services.map((s) => [s.id, s.name]));
+    }
+    catch {
+        return new Map();
+    }
+}
+function targetOf(c, o, fallbackPath = '/') {
+    return o.url ? { kind: 'external', url: o.url } : computeTarget(c, o.service, o.path ?? fallbackPath);
+}
+/**
+ * PATCH conditioned on the revision that was just read. A 409 is reported, never retried: the
+ * schedule changed between the read and the write, and re-reading to apply the patch on top is
+ * precisely how the other edit disappears.
+ */
+async function patchJob(c, job, patch, what, json) {
+    try {
+        const res = await c.api.rawRequest('PATCH', `${jobsPath(c.projectId)}/${job.id}`, patch, {
+            headers: { 'If-Match': String(job.revision) },
+        });
+        if (handleApproval(res, json))
+            return null;
+        return res.body.job;
+    }
+    catch (e) {
+        if (e instanceof ApiError && e.status === 409)
+            refuse(conflictLines(job.name, job.revision, what));
+        throw e;
+    }
+}
+/** Run detail, one request per run — bounded, so a 100-run page cannot open 100 sockets at once. */
+async function mapLimit(items, limit, fn) {
+    const out = new Array(items.length);
+    let cursor = 0;
+    const worker = async () => {
+        for (;;) {
+            const i = cursor++;
+            const item = items[i];
+            if (item === undefined)
+                return;
+            out[i] = await fn(item);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return out;
+}
+const RUN_DETAIL_CONCURRENCY = 5;
+// ---- commands ----
+export async function cronList(opts = {}, injected) {
+    const c = await context(opts, injected);
+    const jobs = await listJobs(c);
+    if (opts.json)
+        return printJson(jobs);
+    if (!jobs.length)
+        return info(`(no cron jobs on ${c.branch ?? 'default'} — add one with \`insta cron create <name> "<expression>" --url <https://…>\`)`);
+    const names = await serviceNames(c, jobs);
+    for (const j of jobs)
+        info(jobListLine(j, j.target.kind === 'service' ? names.get(j.target.serviceId) : undefined));
+}
+export async function cronCreate(name, expression, opts = {}, injected) {
+    // Flag validation first, before any config or network access: a contradictory command must not
+    // reach the point where half of it has happened.
+    assertTargetFlags(opts);
+    const request = buildRequest(opts);
+    const timeout = opts.timeout === undefined ? undefined : parseTimeout(opts.timeout);
+    const c = await context(opts, injected);
+    const target = await targetOf(c, opts);
+    const res = await c.api.rawRequest('POST', jobsPath(c.projectId), {
+        name,
+        expression,
+        ...(c.branch ? { branch: c.branch } : {}),
+        target,
+        ...(request ? { request } : {}),
+        ...(timeout !== undefined ? { requestTimeoutMs: timeout } : {}),
+    });
+    if (handleApproval(res, opts.json))
+        return;
+    const job = res.body.job;
+    if (opts.json)
+        return printJson(job);
+    info(`created cron job ${job.name} on ${job.branch} (${job.id})`);
+    info(`  ${job.expression} (${job.timezone}) — next run ${fmtUtc(job.next_run_at)}`);
+}
+export async function cronShow(name, opts = {}, injected) {
+    const c = await context(opts, injected);
+    const job = await findJob(c, name);
+    if (opts.json)
+        return printJson(job);
+    const names = await serviceNames(c, [job]);
+    for (const line of jobShowLines(job, job.target.kind === 'service' ? names.get(job.target.serviceId) : undefined))
+        info(line);
+}
+export async function cronEdit(name, opts = {}, injected) {
+    assertTargetFlags(opts, true);
+    const request = buildRequest(opts);
+    const timeout = opts.timeout === undefined ? undefined : parseTimeout(opts.timeout);
+    if (!namesTarget(opts) && !request && timeout === undefined && opts.expression === undefined && opts.name === undefined) {
+        throw new Error('nothing to change — pass --expression, --url/--service/--path, --method/--header/--body, --timeout or --name');
+    }
+    const c = await context(opts, injected);
+    const job = await findJob(c, name);
+    const target = namesTarget(opts)
+        // An edit that moves a service target keeps the path it had unless --path says otherwise.
+        ? await targetOf(c, opts, job.target.kind === 'service' ? job.target.path : '/')
+        : undefined;
+    if (request)
+        for (const w of cronEditWarnings(job.request, request))
+            process.stderr.write(`${w}\n`);
+    const updated = await patchJob(c, job, {
+        ...(opts.name !== undefined ? { name: opts.name } : {}),
+        ...(opts.expression !== undefined ? { expression: opts.expression } : {}),
+        ...(target ? { target } : {}),
+        ...(request ? { request } : {}),
+        ...(timeout !== undefined ? { requestTimeoutMs: timeout } : {}),
+    }, 'edit', opts.json);
+    if (!updated)
+        return;
+    if (opts.json)
+        return printJson(updated);
+    info(`updated cron job ${updated.name} (revision ${updated.revision}) — next run ${fmtUtc(updated.next_run_at)}`);
+}
+export async function cronPause(name, opts = {}, injected) {
+    await setEnabled(name, false, opts, injected);
+}
+export async function cronResume(name, opts = {}, injected) {
+    await setEnabled(name, true, opts, injected);
+}
+async function setEnabled(name, enabled, opts, injected) {
+    const c = await context(opts, injected);
+    const job = await findJob(c, name);
+    const updated = await patchJob(c, job, { enabled }, enabled ? 'resume' : 'pause', opts.json);
+    if (!updated)
+        return;
+    if (opts.json)
+        return printJson(updated);
+    info(enabled
+        ? `resumed cron job ${updated.name} — next run ${fmtUtc(updated.next_run_at)}`
+        : `paused cron job ${updated.name} — it will not fire until \`insta cron resume ${updated.name}\``);
+}
+export async function cronDelete(name, opts = {}, injected) {
+    const c = await context(opts, injected);
+    const job = await findJob(c, name);
+    // No prompt, a refusal: there is no terminal in the caller an agent or CI runs from, and a
+    // question asked into a pipe either hangs or is answered by whatever byte arrives next.
+    if (!opts.yes) {
+        refuse([
+            `refusing to delete cron job ${job.name} on ${job.branch} (${job.expression} ${job.timezone}) without --yes.`,
+            `its run history is retained, but the schedule stops firing immediately:  insta cron delete ${name} --yes`,
+        ]);
+    }
+    const res = await c.api.rawRequest('DELETE', `${jobsPath(c.projectId)}/${job.id}`);
+    if (handleApproval(res, opts.json))
+        return;
+    if (opts.json)
+        return printJson({ ok: true, deleted: { id: job.id, name: job.name, branch: job.branch } });
+    info(`deleted cron job ${job.name} from ${job.branch} — its run history is retained`);
+}
+export async function cronRun(name, opts = {}, injected) {
+    const c = await context(opts, injected);
+    const job = await findJob(c, name);
+    // Minted ONCE per invocation, outside the request call. The API client replays a request after a
+    // 401 refresh, and a key minted per HTTP attempt would make that replay a second execution of the
+    // job — which is the exact duplicate the platform requires this header to prevent.
+    const idempotencyKey = randomUUID();
+    const res = await c.api.rawRequest('POST', `${jobsPath(c.projectId)}/${job.id}/runs`, undefined, {
+        headers: { 'Idempotency-Key': idempotencyKey },
+    });
+    if (handleApproval(res, opts.json))
+        return;
+    const runId = res.body.runId;
+    if (opts.json)
+        return printJson({ runId, job: { id: job.id, name: job.name }, idempotencyKey });
+    info(`triggered cron job ${job.name} — run ${runId} accepted (read it with \`insta cron runs ${name}\`)`);
+    // A manual run is an EXTRA execution: the platform does not move next_run_at for it, and an
+    // operator firing a job by hand at 02:59 should not expect the 03:00 tick to have been consumed.
+    //
+    // Only when there IS a next run. A paused job accepts a manual run — pause governs the clock, not
+    // the operator — and it has no next_run_at, so the sentence below would promise a scheduled
+    // execution that is not coming and print the em dash `fmtUtc` uses for "none" in the middle of it.
+    if (job.enabled) {
+        info(`  the scheduled run at ${fmtUtc(job.next_run_at)} still happens — a manual run is an extra execution`);
+    }
+    else {
+        info(`  ${job.name} is paused and stays paused — this run is the only one (\`insta cron resume ${name}\` starts the schedule again)`);
+    }
+}
+export async function cronRuns(name, opts = {}, injected) {
+    const limit = opts.limit === undefined ? undefined : parseRunLimit(opts.limit);
+    const c = await context(opts, injected);
+    const job = await findJob(c, name);
+    const { runs } = await c.api.request('GET', `${jobsPath(c.projectId)}/${job.id}/runs${limit === undefined ? '' : `?limit=${limit}`}`);
+    // The listing carries the run rows; the wake/request split and the HTTP status live on the
+    // ATTEMPTS, which are only readable one run at a time. That is an extra request per row, which is
+    // worth it: without them this command answers "it failed" and an operator still has to go and ask
+    // what failed. A run whose detail cannot be read degrades to counters rather than failing the page.
+    const rows = await mapLimit(runs, RUN_DETAIL_CONCURRENCY, async (run) => {
+        try {
+            const d = await c.api.request('GET', `${jobsPath(c.projectId)}/${job.id}/runs/${run.id}`);
+            return { run, attempts: d.attempts };
+        }
+        catch {
+            return { run, attempts: null };
+        }
+    });
+    if (opts.json)
+        return printJson(rows.map((r) => ({ ...r.run, attempts: r.attempts })));
+    if (!rows.length)
+        return info(`(no runs yet for ${job.name} — trigger one with \`insta cron run ${name}\`)`);
+    info(`runs of cron/${job.name} on ${job.branch} — times are UTC`);
+    for (const row of rows)
+        info(runListLine(row));
+}
+export async function cronPreview(expression, opts = {}, injected) {
+    // The answer depends on nothing but the expression, but the route is project-scoped (membership is
+    // what keeps an open parser endpoint off the internet) — so this resolves a project like every
+    // other command, and asks the SAME parser that create() validates with rather than shipping a
+    // second cron implementation in the CLI that could disagree with the materializer.
+    const c = await context({}, injected);
+    const res = await c.api.rawRequest('POST', `${jobsPath(c.projectId)}/preview`, { expression });
+    if (handleApproval(res, opts.json))
+        return;
+    const preview = res.body;
+    if (opts.json) {
+        printJson(preview);
+        // An invalid expression is a legitimate answer from the API and a failed command here: a script
+        // that pipes this into `insta cron create` must be able to branch on the exit code.
+        if (!preview.valid)
+            process.exitCode = 1;
+        return;
+    }
+    if (!preview.valid)
+        die(`invalid cron expression: ${preview.error ?? 'unparseable'}`);
+    for (const line of previewLines(expression, preview))
+        info(line);
+}
+//# sourceMappingURL=cron.js.map

package/dist/commands/domain.js

@@ -1,4 +1,5 @@
 import { ApiClient } from '../api.js';
+import { readProject } from '../config.js';
 import { info, printJson, handleApproval, die } from '../util.js';
 import { presentUrl, resolveOrgId } from './billing.js';
 import { domainDeps, domainTarget, setDomain, checkDomain, removeDomain } from './compute.js';
@@ -101,11 +102,16 @@ function domainLines(d, linked = true) {
     }
     // The zone answers elsewhere, so nothing published here resolves and an attach is refused. The
     // repair is a next action, so it follows `linked` like the others: under --org it would name this org.
+    // Managed custody is the opposite case — the zone answers from InstaCloud's own nameservers, and
+    // attach works exactly as under the registrar — so `delegated` stays false there and only the
+    // custody line says where the zone lives.
     if (d.delegated) {
         out.push(`  delegated to ${d.nameservers.join(', ')}${linked ? '' : ' — attach is refused'}`);
         if (linked)
             out.push(`  attach is refused until: insta domain nameservers reset ${d.domainName}`);
     }
+    if (d.custody === 'managed')
+        out.push(`  zone managed by InstaCloud (${d.nameservers.join(', ')}) — attach works as usual`);
     const w = Math.max(0, ...d.hostnames.map((x) => x.hostname.length));
     for (const h of d.hostnames)
         out.push(`  ${h.hostname.padEnd(w)}  ${h.state}${h.service ? ` → ${h.service}` : ''}${h.reason ? ` — ${h.reason}` : ''}`);
@@ -146,6 +152,43 @@ export async function domainStatus(name, opts, deps) {
 }
 // ---- nameservers and transferring out ----
 const domainPath = (orgId, domainName) => `/orgs/${orgId}/domains/${encodeURIComponent(domainName)}`;
+/**
+ * Move a bought domain's DNS onto an InstaCloud-managed zone. This is what makes an APEX serve:
+ * under the registrar's nameservers the apex flattens to shared proxy addresses no certificate
+ * authority will vouch for, and the hostname can never verify. Delegation copies every record —
+ * the platform's and yours — into the managed zone first, then switches the nameservers, so a
+ * hostname that was serving keeps serving; a hostname that failed BECAUSE the zone had been
+ * delegated away is revived to pending on its own. 202 approval_required in agent mode
+ * (domain.delegate); the platform requires org admin either way.
+ */
+export async function domainDelegate(domainName, opts, deps) {
+    const { api, orgId } = await orgDeps(opts, deps);
+    // The org route still signs for a PROJECT in agent mode — `domain.delegate` is read there, the
+    // same precedent `buy` documents above — but a user token needs none, so the link stays optional
+    // and the verb keeps working from an unlinked directory. The link only counts when it belongs to
+    // the org being mutated: under `--org` naming ANOTHER org, signing with this directory's project
+    // would evaluate authorization against the wrong project's policy, so the call goes projectless
+    // and the platform's org-administration path judges it instead.
+    const link = deps?.project ?? (await readProject()) ?? undefined;
+    const projectId = link && link.orgId === orgId ? link.projectId : undefined;
+    const res = await api.rawRequest('POST', `${domainPath(orgId, domainName)}/delegate`, undefined, projectId ? { projectId } : undefined);
+    if (handleApproval(res, opts.json))
+        return;
+    if (opts.json)
+        return printJson(res.body);
+    const d = res.body;
+    for (const line of domainLines(d, !opts.org))
+        info(line);
+    // Hostname re-verification is the platform's own loop; the reader's next move is to watch it —
+    // in the org the delegate just acted on, so an explicit --org rides along. But the platform
+    // revives only delegation-caused failures: when every hostname is still failed in this very
+    // answer, nothing is converging and the watch hint would contradict the `nothing serving —
+    // attach` line domainLines just printed, which IS the remedy there (attach works as usual
+    // under managed custody).
+    if (!d.hostnames.length || d.hostnames.some((h) => h.state !== 'failed')) {
+        info(`hostnames re-verify on the managed zone by themselves — watch: insta domain status ${d.domainName}${opts.org ? ` --org ${opts.org}` : ''}`);
+    }
+}
 export async function domainNameserversSet(domainName, hosts, opts, deps) {
     const nameservers = hosts.flatMap((h) => h.split(/[\s,]+/)).map((h) => h.replace(/\.$/, '')).filter(Boolean);
     if (!nameservers.length)

package/dist/commands/github.js

@@ -41,7 +41,7 @@ export function parseWatchPaths(raw) {
         throw new Error("watch paths need at least one pattern, e.g. 'apps/web/**,packages/ui/**' (quote them, or the shell expands the *)");
     return out;
 }
-// Build/start come from detection only: the platform's nixpacks lane fails a build whose commands differ from it.
+// Persisted commands constrain builder selection; automatic detection must leave them unset.
 // autoDeploy rides along only when switched off: a public repo 400s on autoDeploy: true.
 export function sourceBody(src, c, o) {
     const repo = src.source === 'app'
@@ -50,8 +50,6 @@ export function sourceBody(src, c, o) {
     return {
         ...repo,
         rootDir: c.rootDir,
-        buildCommand: c.buildCommand,
-        startCommand: c.startCommand,
         port: o.port !== undefined ? parsePort(o.port) : c.port,
         ...(o.repoBranch ? { branch: o.repoBranch } : {}),
         ...(o.autoDeploy === false ? { autoDeploy: false } : {}),

package/dist/index.js

@@ -20,6 +20,7 @@ import * as services from './commands/services.js';
 import { resolveServiceArgs, serviceArgsDeps } from './resolve-service.js';
 import * as regions from './commands/regions.js';
 import * as secretsCmd from './commands/secrets.js';
+import * as cronCmd from './commands/cron.js';
 import { deploy } from './commands/deploy.js';
 import { build } from './commands/build.js';
 import { buildLogs } from './commands/build-logs.js';
@@ -136,7 +137,7 @@ svc.command('add [type] [name]').description('Provision a service on demand (ass
     .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 (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('--mount-path <path>', 'compute only: container mount path for a new volume (requires --volume; default /data; fixed after attachment)')
+    .option('--mount-path <path>', 'compute only: container mount path for a new volume (requires --volume; default /data)')
     .option('--volume <gi>', 'compute only: attach a persistent volume of this many whole Gi (also attachable later: `insta compute volume <name> --size <gi>`). Any plan may attach up to its own plan cap (10Gi free, 50Gi paid by default; the bare `insta compute volume <name>` read prints it as plan max); a size above the free cap is paid. Volume services keep 1 machine and stop (cold wake) instead of suspend when idle')
     .option('--json')
     .action(guard(async (type, name, o) => {
@@ -190,6 +191,60 @@ sec.command('sources').description('List service credential sources available fo
     .action(guard((o) => secretsCmd.secretsSources(o)));
 sec.command('tree').description('Show secrets as project → branch → service → secrets').option('--json')
     .action(guard((o) => secretsCmd.secretsTree(o)));
+// ---- cron (branch-scoped schedules that send one HTTP request) ----
+// Every expression is evaluated in UTC and every time printed is UTC: a cron pinned to UTC does not
+// keep a fixed local time, so a localised column would quietly lie across a DST boundary.
+const cron = program.command('cron').description('Schedule HTTP calls on a branch — a compute service of the project, or an external URL. Expressions and every printed time are UTC');
+// The repeatable --header collector, declared once: commander needs the same reducer on create and
+// edit, and two copies is how they drift apart.
+const headerOption = (c) => c.option('--header <name=value>', 'request header, repeatable (split on the first = so a value may contain one). Values are encrypted at rest and are NEVER returned by a read — `cron show` lists header names only', (v, prev) => [...prev, v], []);
+cron.command('list').description('List the branch\'s cron jobs: state, expression, next UTC run and target')
+    .option('--branch <branch>', 'branch (default: current)').option('--json')
+    .action(guard((o) => cronCmd.cronList(o)));
+headerOption(cron.command('create <name> <expression>'))
+    .description('Create a cron job. The expression is a 5-field cron expression in UTC (quote it — the shell eats the *). Name a target with --url or --service')
+    .option('--url <url>', 'external target: an absolute http(s) URL')
+    .option('--service <name>', "internal target: a compute service on this branch — the worker resolves its live route at send time, so a redeploy can't leave the job firing at a dead host")
+    .option('--path <path>', 'request path on the --service target, leading slash (default /)')
+    .option('--method <method>', 'GET or POST (default GET, or POST when --body is given)')
+    .option('--body <json>', 'request body — POST only')
+    .option('--timeout <ms>', 'request timeout, 1000..300000 ms; excludes cold start (the wake is timed separately)')
+    .option('--branch <branch>', 'branch (default: current)').option('--json')
+    .action(guard((name, expression, o) => cronCmd.cronCreate(name, expression, o)));
+cron.command('show <name>').description('Show one cron job: schedule, next UTC run, target, request (header NAMES only — values are write-only), retry policy and the revision an edit is conditioned on')
+    .option('--branch <branch>', 'branch (default: current)').option('--json')
+    .action(guard((name, o) => cronCmd.cronShow(name, o)));
+headerOption(cron.command('edit <name>'))
+    .description('Change a cron job. The request is REPLACED, not merged (header values cannot be read back, so anything --header does not re-supply is dropped — the command names what it drops). Conditioned on the revision just read: a concurrent edit fails rather than clobbering')
+    .option('--expression <expr>', 'new 5-field cron expression (UTC; quote it)')
+    .option('--name <new-name>', 'rename the job')
+    .option('--url <url>', 'external target: an absolute http(s) URL')
+    .option('--service <name>', 'internal target: a compute service on this branch')
+    .option('--path <path>', 'request path on the --service target (default: the path it already had)')
+    .option('--method <method>', 'GET or POST')
+    .option('--body <json>', 'request body — POST only')
+    .option('--timeout <ms>', 'request timeout, 1000..300000 ms')
+    .option('--branch <branch>', 'branch (default: current)').option('--json')
+    .action(guard((name, o) => cronCmd.cronEdit(name, o)));
+cron.command('pause <name>').description('Stop a cron job firing, keeping its definition and history')
+    .option('--branch <branch>', 'branch (default: current)').option('--json')
+    .action(guard((name, o) => cronCmd.cronPause(name, o)));
+cron.command('resume <name>').description('Let a paused cron job fire again from the next tick')
+    .option('--branch <branch>', 'branch (default: current)').option('--json')
+    .action(guard((name, o) => cronCmd.cronResume(name, o)));
+cron.command('delete <name>').description('Delete a cron job — it stops firing immediately; its run history is retained')
+    .option('-y, --yes', 'required: confirm the deletion (there is no prompt, in a terminal or out of one)')
+    .option('--branch <branch>', 'branch (default: current)').option('--json')
+    .action(guard((name, o) => cronCmd.cronDelete(name, o)));
+cron.command('run <name>').description('Trigger one run now. An EXTRA execution — the next scheduled run still happens. Sent with an Idempotency-Key minted once, so a retried request cannot fire the job twice')
+    .option('--branch <branch>', 'branch (default: current)').option('--json')
+    .action(guard((name, o) => cronCmd.cronRun(name, o)));
+cron.command('runs <name>').description('Run history, most recent first: status, trigger, attempts, the wake/request split (a slow wake is the platform, a slow request is your endpoint) and the HTTP status')
+    .option('--limit <n>', 'number of runs, 1..100 (default 20)')
+    .option('--branch <branch>', 'branch (default: current)').option('--json')
+    .action(guard((name, o) => cronCmd.cronRuns(name, o)));
+cron.command('preview <expression>').description('Validate an expression and print its next five UTC fire times — answered by the same parser the scheduler uses. Exits 1 when the expression is invalid')
+    .option('--json').action(guard((expression, o) => cronCmd.cronPreview(expression, o)));
 // ---- domain (bought here, or bring your own; hostnames on compute services; DNS of bought zones) ----
 const dom = program.command('domain').description('Domains: buy through InstaCloud or bring your own — attach / check / detach hostnames on compute services; DNS records of bought domains');
 dom.command('search <keyword>').description('Search purchasable names with prices (a label like "myapp" or a full name like "myapp.com")')
@@ -214,11 +269,14 @@ dom.command('list').description("Domains bought through InstaCloud in this org
 dom.command('status <name>').description("A bought domain's order and attach state")
     .option('--org <id>', "target org (default: linked project's org)").option('--json')
     .action(guard((name, o) => domainCmd.domainStatus(name, o)));
-const ns = dom.command('nameservers').description("Delegate a bought domain's zone to nameservers you name, or put it back on InstaCloud's registrar");
-ns.command('set <domain> <nameservers...>').description("Delegate the zone — the nameservers must already host it. Every hostname the domain serves stops answering, unless they are the registrar's own: the records an attach published live in the zone you are leaving")
+dom.command('delegate <domain>').description("Move a bought domain's DNS onto an InstaCloud-managed zone — the way an apex hostname gets a certificate and serves. Every record is copied first and the nameservers switch after, so serving hostnames stay up and ones that failed by delegating away revive on their own. While managed, `domain records` answers 409 for every verb (managed-zone record editing is not covered yet); `nameservers reset` is the way back (org admin; gated: domain.delegate — agent mode gates from a linked project, an unlinked --org call falls under org administration instead)")
+    .option('--org <id>', "target org (default: linked project's org)").option('--json')
+    .action(guard((domain, o) => domainCmd.domainDelegate(domain, o)));
+const ns = dom.command('nameservers').description("Delegate a bought domain's zone to nameservers you name, or put it back on InstaCloud's registrar — for InstaCloud's own managed zone, use `insta domain delegate`");
+ns.command('set <domain> <nameservers...>').description("Delegate the zone to nameservers of YOURS — they must already host it. Every hostname the domain serves stops answering, unless they are the registrar's own: the records an attach published live in the zone you are leaving. To keep hostnames serving on InstaCloud-run nameservers instead, use `insta domain delegate`")
     .option('--org <id>', "target org (default: linked project's org)").option('--json')
     .action(guard((domain, hosts, o) => domainCmd.domainNameserversSet(domain, hosts, o)));
-ns.command('reset <domain>').description("Put the zone back on the registrar's own nameservers; a hostname it took down is re-attached with `insta domain attach`")
+ns.command('reset <domain>').description("Put the zone back on the registrar's own nameservers — from your own delegation or from an InstaCloud-managed zone alike; a hostname `set` took down is re-attached with `insta domain attach`, one a managed zone was serving re-verifies on its own")
     .option('--org <id>', "target org (default: linked project's org)").option('--json')
     .action(guard((domain, o) => domainCmd.domainNameserversReset(domain, o)));
 const xfer = dom.command('transfer').description('Take a bought domain to another registrar — open the lock, then read the code (all three need org admin)');
@@ -315,8 +373,13 @@ compute.command('watch-paths [service]').description("Show or change which paths
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => githubCmd.computeWatchPaths(service, o)));
 compute.command('disconnect-repo [service]').description('Disconnect the GitHub repository from a compute service. The service keeps running its current image; pushes no longer deploy it, and its build history stays')
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => githubCmd.computeDisconnectRepo(service, o)));
-compute.command('volume [service]').description("Show, attach, grow, or delete a compute service's persistent volume. No flag: print size, mount path, and the plan cap (any plan). --size on a volumeless service ATTACHES one (any plan up to its own plan cap — 10Gi free, 50Gi paid by default — which is also what a disk with no size named is born at; a size above the free cap is paid; the disk mounts at --mount-path (default /data) on the next deploy); on a volume-bearing one it grows (paid plans; grow-only — a provisioned disk cannot shrink). --delete DESTROYS the disk and ALL its data immediately (no detach, no undo; billing stops now, and suspend fast-wake + scale-out return). Billing is actual data stored — the size is a cap, not a price")
-    .option('--mount-path <path>', 'container mount path for a new volume (requires --size; default /data; fixed after attachment)')
+compute.command('start-command [service]').description('Show or stage a compute startup command for the next deployment. Runs through sh -c; --clear restores the image default. Stage the volume path and command before deploying. CLI secrets writes redeploy immediately; use Console to combine variables, path and command in one deployment.')
+    .option('--set <command>', 'startup command to use on the next deploy')
+    .option('--clear', 'use the image default command on the next deploy')
+    .option('--json').option('--branch <branch>', 'branch (default: current)')
+    .action(guard((service, o) => computeCmd.computeStartCommand(service, o)));
+compute.command('volume [service]').description("Show, attach, grow, remount, or delete a compute service's persistent volume. --mount-path alone stages an existing volume path change, pending until deploy or restart; an unchanged normalized path is a no-op readback. No flag: print size, mount path, and the plan cap (any plan). --size on a volumeless service ATTACHES one (any plan up to its own plan cap — 10Gi free, 50Gi paid by default — which is also what a disk with no size named is born at; a size above the free cap is paid; the disk mounts at --mount-path (default /data) on the next deploy); on a volume-bearing one it grows (paid plans; grow-only — a provisioned disk cannot shrink). --delete DESTROYS the disk and ALL its data immediately (no detach, no undo; billing stops now, and suspend fast-wake + scale-out return). Billing is actual data stored — the size is a cap, not a price")
+    .option('--mount-path <path>', 'configure mount path; existing volume changes apply on the next deploy (restarts the service)')
     .option('--size <gi>', 'new size in whole Gi, e.g. 10 (must be ≥ the current size)')
     .option('--delete', 'destroy the volume and ALL its data (irreversible; download anything you need first)')
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => computeCmd.computeVolume(service, o)));

package/dist/template-manifest.js

@@ -14,6 +14,9 @@ export const MANIFEST_FILE = 'insta.template.yaml';
 const CODE_RE = /^[a-z0-9][a-z0-9-]{0,38}$/;
 export const ENV_NAME_RE = /^[A-Z][A-Z0-9_]{0,63}$/;
 const GENERATOR_RE = /^secret:([1-9]\d{0,2})$/;
+// The platform provisions these and owns everything about them (platform templateManifest.ts).
+const MANAGED_TYPES = ['postgres', 'redis', 'mysql', 'mongodb'];
+const MANIFEST_TYPES = ['web', 'worker', ...MANAGED_TYPES];
 // What counts as a digest is the PLATFORM's call, not ours: registry.ts's DIGEST regex, verbatim.
 const DIGEST = /^sha256:[a-f0-9]{64}$/;
 // Why an image must carry a pin: a template is a reproducible deploy, and a tagless ref (implicit
@@ -78,17 +81,19 @@ export function validateManifest(m) {
     for (const name of names) {
         const svc = services[name] ?? {};
         const where = `services.${name}`;
-        if (svc.type !== 'web' && svc.type !== 'worker' && svc.type !== 'postgres') {
-            problems.push(`${where}.type must be web, worker or postgres`);
+        // typeof, not String(): a YAML array like [redis] would otherwise stringify to its lone element.
+        const type = typeof svc.type === 'string' ? svc.type : undefined;
+        if (!type || !MANIFEST_TYPES.includes(type)) {
+            problems.push(`${where}.type must be one of ${MANIFEST_TYPES.join(', ')}`);
         }
-        // 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') {
+        // A managed datastore 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 (type && MANAGED_TYPES.includes(type)) {
             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 })`);
+                    problems.push(`${where}.${field}: a ${type} service is platform-managed and carries no ${field} — declare it bare ({ type: ${type} })`);
                 }
             }
             const groups = ['fixed', 'generated', 'platform', 'required', 'optional'];
@@ -97,7 +102,7 @@ export function validateManifest(m) {
                 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 })`);
+                    problems.push(`${where}.env: a ${type} service is platform-managed and carries no env — declare it bare ({ type: ${type} })`);
                 }
             }
             continue;
@@ -121,6 +126,16 @@ export function validateManifest(m) {
         if (svc.port !== undefined && (!Number.isInteger(svc.port) || svc.port < 1 || svc.port > 65535)) {
             problems.push(`${where}: port must be an integer between 1 and 65535, got: ${svc.port}`);
         }
+        // A worker is PORTLESS: the platform deploys it as its own port-0 service, so nothing is routed
+        // to it and nothing probes it. The server's three refusals, said here before the upload.
+        if (svc.type === 'worker') {
+            if (svc.port !== undefined)
+                problems.push(`${where}.port: a worker has no routed port — remove it (a worker is portless; declare type: web to serve HTTP)`);
+            if (svc.healthcheck !== undefined)
+                problems.push(`${where}.healthcheck: a worker has no HTTP endpoint to probe — its health is the machine's state; remove it (or declare type: web)`);
+            if (svc.alwaysOn === false)
+                problems.push(`${where}.alwaysOn: a worker cannot scale to zero — nothing is routed to it, so nothing would wake it; remove alwaysOn or set it true`);
+        }
         if (svc.type === 'web' && !svc.healthcheck)
             problems.push(`${where}: web services must declare a healthcheck path`);
         if (svc.healthcheck && !String(svc.healthcheck).startsWith('/'))
@@ -164,6 +179,23 @@ export function validateManifest(m) {
             }
         }
     }
+    // A managed datastore has no url or host to address, mirroring the platform's env.fixed check.
+    for (const name of names) {
+        const svc = services[name] ?? {};
+        for (const [varName, raw] of Object.entries(svc.env?.fixed ?? {})) {
+            for (const m of String(raw).matchAll(/\$\{([^}]+)\}/g)) {
+                const ref = m[1].trim();
+                const svcRef = /^services\.([a-z0-9-]+)\.(url|host)$/.exec(ref);
+                if (!svcRef)
+                    continue;
+                const target = services[svcRef[1]];
+                const targetType = target && typeof target.type === 'string' ? target.type : undefined;
+                if (targetType && MANAGED_TYPES.includes(targetType)) {
+                    problems.push(`services.${name}.env.fixed.${varName}: '${svcRef[1]}' is a managed ${targetType}, so it has no url or host. Use its platform credentials instead: \${{services.${svcRef[1]}.<KEY>}} under env.platform`);
+                }
+            }
+        }
+    }
     return problems;
 }
 /**

package/dist/util.js

@@ -204,12 +204,20 @@ export function handleApproval(res, json) {
     if (res.status === 202 && res.body?.status === 'approval_required') {
         if (json)
             printJson(res.body);
-        process.stderr.write(`approval required for ${res.body.action} — run: insta agent approvals approve ${res.body.approvalId}\n`);
+        process.stderr.write(`${approvalHint(res.body)}\n`);
         process.exitCode = 2;
         return true;
     }
     return false;
 }
+// The one-line hint for a gated request. `url` is the console page for THIS request, built by the
+// platform (only it knows which console fronts it — prod, staging, self-hosted); it comes first
+// because a click is the fastest route to approval and terminals link it. An older platform or the
+// OSS runtime sends no url, and the CLI command alone still stands.
+export function approvalHint(body) {
+    const review = body.url ? `review it at ${body.url} or ` : '';
+    return `approval required for ${body.action} — ${review}run: insta agent approvals approve ${body.approvalId}`;
+}
 // Neutral op → an `insta` command string. Unknown ops fall back to reason-only (no crash). The
 // platform names an observability target with its component word (`db` for postgres); the CLI
 // groups by service type, so the target becomes the parent command.

package/package.json

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