insta 0.0.59 → 0.0.61

package/dist/commands/observe.js

@@ -11,24 +11,36 @@ import { renderReport } from '../observe/report.js';
 import { ApiClient, requireProject } from '../api.js';
 import { info, printJson } from '../util.js';
 // Where the audit lives: the hook records at the directory it is materialized in
-// (<root>/.insta/observe/hook.js — see projectRootFor), so report/sync must anchor on the same
-// thing. The link file is the usual root, but a standalone `insta observe install` in an
-// unlinked directory has no project.json — climb for the hook itself then, so both halves agree
-// from any subdirectory. Falls back to cwd when neither exists (→ "audit log is empty").
+// (<root>/.insta/observe/hook.js — see projectRootFor), so report/sync must anchor on exactly
+// that: the NEAREST materialized hook above cwd, which is what the Codex wrapper and the Claude
+// entry run. The link file is only a fallback for a directory where no hook exists yet (it is
+// where the next install will land), then cwd (→ "audit log is empty"). Preferring the link file
+// would break the moment the two diverge — e.g. a hook materialized below a linked parent —
+// because the reader would look where the writer never writes.
 export async function auditRoot(cwd = process.cwd()) {
-    const linked = await findProjectRoot(cwd);
-    if (linked)
-        return linked;
+    const hook = nearestHookRoot(cwd);
+    if (hook)
+        return hook;
+    return (await findProjectRoot(cwd)) ?? cwd;
+}
+/** Nearest ancestor (or cwd) holding a materialized hook, or null. */
+export function nearestHookRoot(cwd) {
     let dir = resolve(cwd);
     for (;;) {
         if (existsSync(join(dir, '.insta', 'observe', 'hook.js')))
             return dir;
         const parent = dirname(dir);
         if (parent === dir)
-            return cwd;
+            return null;
         dir = parent;
     }
 }
+/** Where `install` materializes: the linked project root when inside one (so a re-link or
+ *  `observe install` from a subdirectory refreshes the project's hook instead of minting a second
+ *  one the readers never look at — same rule as writeProject), else cwd. */
+export async function installRoot(cwd = process.cwd()) {
+    return (await findProjectRoot(cwd)) ?? cwd;
+}
 async function readAudit() {
     try {
         const txt = await readFile(join(await auditRoot(), '.insta', 'audit.jsonl'), 'utf8');
@@ -46,8 +58,9 @@ function* chunk(a, n) {
         yield a.slice(i, i + n);
 }
 export async function observeInstall() {
-    const res = installObserve({ cwd: process.cwd() });
-    info(`installed observe hook (claude: ${res.claude}, codex: ${res.codex}) → ./.insta/observe`);
+    const root = await installRoot();
+    const res = installObserve({ cwd: root });
+    info(`installed observe hook (claude: ${res.claude}, codex: ${res.codex}) → ${join(root, '.insta', 'observe')}`);
     if (res.ignored.length)
         info(`  .gitignore += ${res.ignored.join(', ')}`);
     const hint = untrackHint(res.tracked);
@@ -57,7 +70,7 @@ export async function observeInstall() {
     info('run `insta observe report` to review, `insta observe sync` to upload to the project timeline');
 }
 export async function observeUninstall() {
-    uninstallObserve(process.cwd());
+    uninstallObserve(await installRoot());
     info('uninstalled observe hook');
 }
 export async function observeReport(opts) {

package/dist/commands/project.js

@@ -3,6 +3,7 @@ import { ApiClient, requireProject } from '../api.js';
 import { writeProject } from '../config.js';
 import { info, die, printJson, handleApproval, renderNextActions } from '../util.js';
 import { installObserve } from '../observe/install.js';
+import { installRoot } from './observe.js';
 import { untrackHint } from '../gitignore.js';
 import { installSkills } from '../ensure-skills.js';
 // Generic directory names that make a useless project name ("projects", "~", "tmp", …). When the
@@ -14,10 +15,12 @@ const GENERIC_DIRS = new Set([
     'app', 'apps', 'users', 'user', 'bin', 'new', 'test', 'tests',
 ]);
 // Best-effort: wire the credential-audit hook into the project (no-op if assets aren't built).
+// Anchored at the linked project root (writeProject just updated it), not cwd: a re-link from a
+// subdirectory must refresh the project's hook, not mint a second one the readers never see.
 // quiet: with --json the install still runs, but its note moves to stderr (stdout is JSON-only).
-function tryInstallObserve(quiet = false) {
+async function tryInstallObserve(quiet = false) {
     try {
-        const r = installObserve({ cwd: process.cwd() });
+        const r = installObserve({ cwd: await installRoot() });
         const say = (line) => (quiet ? process.stderr.write(line + '\n') : info(line));
         if (r.claude || r.codex)
             say('  installed observe hook (credential audit) → ./.insta/observe');
@@ -82,7 +85,7 @@ export async function projectCreate(name, opts) {
         info(`  linked ./.insta/project.json (branch ${out.defaultBranch.name})`);
         renderNextActions(out.nextActions);
     }
-    tryInstallObserve(opts.json);
+    await tryInstallObserve(opts.json);
     await installSkills({ cwd: process.cwd(), print: skillsPrint(opts.json) });
 }
 export async function projectList(opts) {
@@ -104,7 +107,7 @@ export async function projectLink(id, opts = {}) {
         printJson({ project, linked: { projectId: project.id, orgId: project.org_id, branch: 'main' } });
     else
         info(`linked project ${project.id} (${project.name})`);
-    tryInstallObserve(opts.json);
+    await tryInstallObserve(opts.json);
     await installSkills({ cwd: process.cwd(), print: skillsPrint(opts.json) });
 }
 export async function projectDelete(opts) {

package/dist/commands/template.js

@@ -1,5 +1,6 @@
 // `insta template` — browse the platform template registry and deploy a template (by registry
-// code, or from a local directory carrying insta.template.yaml) onto a branch. The deploy is a
+// code, from a local directory carrying insta.template.yaml, or from a github.com URL whose
+// manifest github-source.ts fetches with the user's own git credentials) onto a branch. The deploy is a
 // platform-side pipeline (create services → write variables → deploy → health check); the CLI
 // submits it and renders progress by polling the deployment resource.
 import { join, resolve } from 'node:path';
@@ -9,6 +10,7 @@ import * as clack from '@clack/prompts';
 import { ApiClient, ApiError, requireProject } from '../api.js';
 import { info, printJson, handleApproval, renderNextActions, CliCancel } from '../util.js';
 import { MANIFEST_FILE, collectManifestVariables, loadTemplateManifest } from '../template-manifest.js';
+import { parseGitHubTemplateUrl, fetchGitHubTemplate } from '../github-source.js';
 // One aligned row per template; numeric columns right-aligned. Plain padded columns, as the rest
 // of the CLI (storage list, compute check-domain) — no table library.
 export function templateListLines(templates) {
@@ -172,12 +174,18 @@ export function looksLikePath(target) {
 // tool should fake.
 const expandHome = (target) => target.replace(/^~(?=[/\\]|$)/, () => homedir());
 /**
- * Which deploy mode a target selects. Local mode is OPTED INTO by a path-looking target (./dir,
- * /abs, sub/dir); a bare word is ALWAYS a registry code — even when a same-named directory with a
- * manifest sits in the working directory, deploying it must be explicit (./plausible), never a
- * cwd coincidence. And a path-looking target with no manifest is a mistake, never a registry code.
+ * Which deploy mode a target selects. A URL is classified FIRST — it contains `/`, which
+ * looksLikePath would otherwise claim as a directory, and a non-GitHub URL must be named as
+ * unsupported rather than reported as a missing manifest. Then: local mode is OPTED INTO by a
+ * path-looking target (./dir, /abs, sub/dir); a bare word is ALWAYS a registry code — even when a
+ * same-named directory with a manifest sits in the working directory, deploying it must be
+ * explicit (./plausible), never a cwd coincidence. And a path-looking target with no manifest is a
+ * mistake, never a registry code.
  */
 export function deployMode(target, hasManifest = (d) => existsSync(join(d, MANIFEST_FILE))) {
+    const github = parseGitHubTemplateUrl(target);
+    if (github)
+        return { kind: 'github', target: github };
     if (!looksLikePath(target))
         return { kind: 'registry', code: target };
     const dir = resolve(process.cwd(), expandHome(target));
@@ -314,8 +322,21 @@ export async function templateDeploy(target, opts = {}, deps = {}) {
     // code, so a same-named local directory can never shadow the registry template.
     const mode = deployMode(target);
     let manifest;
+    let source;
     let vars;
-    if (mode.kind === 'local') {
+    if (mode.kind === 'github') {
+        const fetched = await (deps.fetchGitHub ?? ((t) => fetchGitHubTemplate(t)))(mode.target);
+        manifest = fetched.manifest;
+        source = fetched.source;
+        vars = collectManifestVariables(manifest);
+        // Spec 4.4: exactly ONE line in front of today's output. A second "deploying template …" line
+        // would read as a duplicate of the "deploying template <code> to branch <branch>" line below,
+        // so the manifest's code@version rides on this one instead.
+        if (!quiet) {
+            info(`fetching template ${manifest.code}@${manifest.version} from github.com/${source.repo}@${source.ref}${source.path ? ` (${source.path})` : ''} at ${source.commit.slice(0, 7)}`);
+        }
+    }
+    else if (mode.kind === 'local') {
         manifest = loadTemplateManifest(mode.dir); // parse + local validation (pinned images, described vars)
         vars = collectManifestVariables(manifest);
         if (!quiet)
@@ -331,7 +352,7 @@ export async function templateDeploy(target, opts = {}, deps = {}) {
     const onAutoResolved = quiet ? undefined : (v) => info(`  ${v.name}: ${v.generate ? `platform-generated (${v.generate})` : `default (${v.default})`}`);
     const variables = await resolveVariables(vars, given, { tty, ask, onAutoResolved });
     // The endpoint takes the branch NAME directly (branchId is its uuid alias) — no lookup needed.
-    const body = { ...(mode.kind === 'local' ? { manifest } : { templateCode: mode.code }), branch: branchName, variables };
+    const body = { ...(mode.kind === 'registry' ? { templateCode: mode.code } : { manifest }), branch: branchName, variables };
     let res;
     try {
         res = await api.rawRequest('POST', `/projects/${p.projectId}/template-deployments`, body);
@@ -355,7 +376,7 @@ export async function templateDeploy(target, opts = {}, deps = {}) {
         info(`deploying template ${codeLabel} to branch ${branchName} (${deploymentId})`);
     const dep = await watchDeployment((id) => api.request('GET', `/template-deployments/${id}`), deploymentId, quiet ? () => { } : info, deps.wait);
     if (opts.json)
-        return printJson(dep);
+        return printJson(source ? { source, ...dep } : dep);
     info(`template ${codeLabel} deployed to branch ${branchName}`);
     for (const u of deploymentUrls(dep))
         info(`  ${u}`);

package/dist/ensure-skills.js

@@ -91,16 +91,18 @@ export async function installSkills(deps) {
                 installed++;
             print(r.ok ? `  ${s.label} ✓` : `  ${s.label} failed — add manually: npx ${s.args.join(' ')}`);
         }
-        // Only when something was actually written: an offline run that failed every add has no
-        // skill dirs or lock to ignore, and a `.gitignore +=` line there would claim otherwise.
+        // The already-tracked hint is independent of this run: a repo that committed the skill dirs
+        // or the lock months ago needs the `git rm --cached` line whether or not today's adds worked.
+        const hint = untrackHint(alreadyTracked(deps.cwd, SKILL_DIRS));
+        if (hint)
+            print(hint);
+        // The ignore entries only when something was actually written: an offline run that failed
+        // every add has no new skill dirs or lock, and a `.gitignore +=` line would claim otherwise.
         if (installed === 0)
             return;
         const added = ensureGitignore(deps.cwd, SKILL_DIRS, GITIGNORE_COMMENT);
         if (added.length)
             print(`  .gitignore += ${added.join(', ')}`);
-        const hint = untrackHint(alreadyTracked(deps.cwd, SKILL_DIRS));
-        if (hint)
-            print(hint);
     }
     catch {
         /* best-effort convenience — never block the host command */

package/dist/github-source.js

@@ -0,0 +1,316 @@
+// Fetch a template manifest out of a GitHub repository, on this machine, with the user's own git
+// 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 { tmpdir } from 'node:os';
+import { join, sep } from 'node:path';
+import { loadTemplateManifest, 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;
+// 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.
+const KNOWN_GIT_HOSTS = new Set([
+    'gitlab.com', 'www.gitlab.com', 'bitbucket.org', 'www.bitbucket.org', 'gist.github.com',
+    'codeberg.org', 'git.sr.ht', 'dev.azure.com', 'ssh.dev.azure.com', 'gitea.com', 'sourceforge.net',
+]);
+const SEGMENT = /^[A-Za-z0-9_.-]+$/;
+/** Is this an address rather than a path? Only an explicit scheme/scp form, or a first segment
+ *  naming a host we recognise. A scheme-less name is far likelier to be someone's directory than
+ *  a git host, so everything else falls through to local and registry modes. */
+function isAddress(target) {
+    if (EXPLICIT_ADDRESS.test(target))
+        return true;
+    return KNOWN_GIT_HOSTS.has((target.split(/[/\\]/, 1)[0] ?? '').toLowerCase());
+}
+export function unsupportedSourceMessage(target) {
+    return `unsupported template source: ${target}. Use a registry code, a local directory, or https://github.com/<owner>/<repo>[/tree/<ref>[/<dir>]]`;
+}
+// Percent-decode first, so %2e%2e and %2f cannot smuggle a traversal past the segment check.
+function decodedSegments(parts, target) {
+    return parts.map((raw) => {
+        let seg;
+        try {
+            seg = decodeURIComponent(raw);
+        }
+        catch {
+            throw new Error(unsupportedSourceMessage(target));
+        }
+        if (!seg || seg === '.' || seg === '..' || /[/\\\0]/.test(seg))
+            throw new Error(unsupportedSourceMessage(target));
+        return seg;
+    });
+}
+/** Parse a github.com URL into owner, repo and the still-unsplit ref+path tail.
+ *  null = not URL-shaped, so the caller's local-directory and registry modes still get a look.
+ *  A URL-shaped target that is not a github.com repository URL throws (spec 4.1). */
+export function parseGitHubTemplateUrl(target) {
+    if (!GITHUB_HOST.test(target)) {
+        // Name a non-GitHub address for what it is; let everything else reach local/registry mode.
+        if (isAddress(target))
+            throw new Error(unsupportedSourceMessage(target));
+        return null;
+    }
+    // Links copied from GitHub's UI carry ?plain=1, #L1-L5 or ?tab=readme-ov-file, and none of that
+    // names a file. A `?` or `#` in a real path arrives percent-encoded, so a bare one is always the
+    // delimiter. Dropping it silently beats a "directory" called `bot?tab=readme-ov-file`.
+    const clean = target.replace(/[?#][\s\S]*$/, '');
+    const rest = clean.replace(GITHUB_HOST, '').replace(/\/+$/, '');
+    const parts = rest.split('/');
+    const owner = parts[0] ?? '';
+    const repo = (parts[1] ?? '').replace(/\.git$/i, '');
+    if (!SEGMENT.test(owner) || !SEGMENT.test(repo))
+        throw new Error(unsupportedSourceMessage(target));
+    const kind = parts[2];
+    if (kind === undefined)
+        return { owner, repo, refAndPath: '' };
+    if (kind !== 'tree' && kind !== 'blob')
+        throw new Error(unsupportedSourceMessage(target));
+    let tail = decodedSegments(parts.slice(3), target);
+    if (!tail.length)
+        throw new Error(unsupportedSourceMessage(target));
+    if (kind === 'blob') {
+        // A file link is read as its directory, and only for the manifest itself.
+        if (tail[tail.length - 1] !== MANIFEST_FILE)
+            throw new Error(unsupportedSourceMessage(target));
+        tail = tail.slice(0, -1);
+        if (!tail.length)
+            throw new Error(unsupportedSourceMessage(target));
+    }
+    return { owner, repo, refAndPath: tail.join('/') };
+}
+export const LS_REMOTE_TIMEOUT_MS = 30_000;
+export const CLONE_TIMEOUT_MS = 120_000;
+export function gitMissingMessage() {
+    return `git is required to deploy a template from a GitHub URL. Install git, or clone the repository yourself and run: insta template deploy ./<dir>`;
+}
+// git asks for nothing: no terminal credential prompt, no SSH host-key or passphrase prompt (an
+// insteadOf rewrite can send the clone over SSH). The environment stops it asking; only the
+// timeout stops it waiting.
+// GIT_SSH_COMMAND is EXTENDED, never replaced: a user's own `ssh -i <key>` IS how their private
+// repository authenticates, and overwriting it would drop the credentials this feature runs on.
+function nonInteractiveEnv(env = process.env) {
+    const ssh = env.GIT_SSH_COMMAND?.trim();
+    return {
+        GIT_TERMINAL_PROMPT: '0',
+        GIT_SSH_COMMAND: ssh ? `${ssh} -o BatchMode=yes` : 'ssh -o BatchMode=yes',
+        GCM_INTERACTIVE: 'never',
+    };
+}
+// git spawns helpers (ssh, a credential manager) that inherit its pipes, so a timeout has to take
+// the whole group. Windows has no process groups; taskkill /T walks the tree instead.
+function killTree(child) {
+    try {
+        if (process.platform === 'win32' && child.pid) {
+            // spawn reports a missing binary ASYNCHRONOUSLY: without this listener an absent taskkill
+            // becomes an uncaught ENOENT that kills the CLI, and try/catch never sees it.
+            nodeSpawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' })
+                .on('error', () => { });
+        }
+        else if (child.pid) {
+            process.kill(-child.pid, 'SIGKILL'); // negative pid addresses the group
+        }
+    }
+    catch { /* already gone */ }
+    try {
+        child.kill('SIGKILL');
+    }
+    catch { /* already gone */ }
+}
+// A settled promise does not let the CLI exit. Node keeps its event loop alive for an open pipe,
+// and a grandchild that escaped the kill still holds the write end. Releasing our read ends and
+// unref-ing the child is what actually lets the process end.
+function releaseChild(child) {
+    try {
+        child.stdout?.destroy();
+    }
+    catch { /* already closed */ }
+    try {
+        child.stderr?.destroy();
+    }
+    catch { /* already closed */ }
+    try {
+        child.unref();
+    }
+    catch { /* already gone */ }
+}
+/** spawnFn is injected so the timeout path is testable without a network (spec FAQ 7.15). */
+export function makeGitRunner(spawnFn = nodeSpawn) {
+    return (args, opts) => new Promise((resolve) => {
+        // Spawned directly, NOT through resolveSpawnable: that wrapper exists for npm-installed
+        // `.cmd` shims, and its cmd.exe hop breaks any executable path containing a space —
+        // `cmd /s /c "C:\Program Files\Git\cmd\git.exe" --version` has its quotes stripped and
+        // dies with `'C:\Program' is not recognized`. git ships a real git.exe, which spawn finds
+        // through PATHEXT by itself; a `.cmd`-only git fails ENOENT, which reads as gitMissingMessage.
+        const child = spawnFn('git', args, {
+            env: { ...process.env, ...nonInteractiveEnv() },
+            stdio: ['ignore', 'pipe', 'pipe'],
+            // Own process group on POSIX, so killTree can reach git's helpers.
+            detached: process.platform !== 'win32',
+        });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const finish = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(r);
+        };
+        const timer = setTimeout(() => {
+            killTree(child);
+            // Then let go of the pipes. Killing can miss a grandchild that changed process group, and
+            // its inherited write end would keep BOTH 'close' and the CLI's event loop waiting
+            // (measured: promise settled at 203ms, process exited at 20094ms).
+            releaseChild(child);
+            // Settle NOW. 'close' waits for every inherited pipe; waiting would void the bound.
+            finish({ code: -1, stdout, stderr, timedOut: true });
+        }, opts.timeoutMs);
+        child.stdout?.on('data', (b) => { stdout += b.toString(); });
+        child.stderr?.on('data', (b) => { stderr += b.toString(); });
+        child.on('error', (err) => finish({ code: -1, stdout, stderr: `${stderr}${err.message}`, timedOut: false }));
+        child.on('close', (code) => finish({ code: code ?? -1, stdout, stderr, timedOut: false }));
+    });
+}
+export const defaultGitRunner = makeGitRunner();
+export function repoUrl(t) {
+    return `https://github.com/${t.owner}/${t.repo}.git`;
+}
+function repoLabel(t) {
+    return `https://github.com/${t.owner}/${t.repo}`;
+}
+export function unreadableRepoMessage(t, stderr) {
+    const tail = stderr.trim().split('\n').slice(-2).join('\n');
+    return [
+        `could not read ${repoLabel(t)}: repository not found or not accessible.`,
+        'If this is a private repository, configure git credentials and retry. With GitHub CLI:',
+        '  gh auth login',
+        '  gh auth setup-git',
+        ...(tail ? [`git said: ${tail}`] : []),
+    ].join('\n');
+}
+/** Read `git ls-remote --symref`: the HEAD symref names the default branch, and every other line
+ *  is `<sha>\t<refname>`. Keyed by FULL ref, so refs/heads/x and refs/tags/x stay distinct.
+ *  Peeled entries (`^{}`) are dropped: they name a commit, not a ref anyone can clone. */
+export function parseLsRemote(stdout) {
+    let head = null;
+    const refs = new Map();
+    for (const line of stdout.split('\n')) {
+        const symref = /^ref:\s+refs\/heads\/(\S+)\s+HEAD$/.exec(line);
+        if (symref) {
+            head = symref[1];
+            continue;
+        }
+        const m = /^([0-9a-f]{40})\s+(refs\/(?:heads|tags)\/.+)$/.exec(line);
+        if (!m || m[2].endsWith('^{}'))
+            continue;
+        refs.set(m[2], m[1]);
+    }
+    return { head, refs };
+}
+/** Longest-first, because a ref may contain `/` and only the real ref list can say where it ends.
+ *  A branch beats a tag of the same name, which is what `git clone --branch` does with the short
+ *  name; qualifiedRef records that choice for the reader, the clone still gets `ref`. */
+export function splitRefAndPath(refAndPath, refs) {
+    const segments = refAndPath.split('/');
+    for (let take = segments.length; take > 0; take--) {
+        const ref = segments.slice(0, take).join('/');
+        const qualifiedRef = refs.has(`refs/heads/${ref}`) ? `refs/heads/${ref}`
+            : refs.has(`refs/tags/${ref}`) ? `refs/tags/${ref}`
+                : null;
+        if (qualifiedRef)
+            return { ref, qualifiedRef, path: segments.slice(take).join('/') };
+    }
+    return null;
+}
+/** One round trip answers two questions: the default branch, and where the ref ends. The commit
+ *  is NOT taken from here — an annotated tag lists its tag object, and a branch can move before
+ *  the clone. fetchGitHubTemplate reads it from the checkout instead (spec FAQ 7.10). */
+export async function resolveGitHubRef(t, run) {
+    // HEAD is listed EXPLICITLY: adding refspecs otherwise drops the symref line that names the
+    // default branch (measured on this repo: 375 refs unfiltered, 188 with the filter, and no
+    // `ref: refs/heads/... HEAD` unless HEAD is asked for by name).
+    const res = await run(['ls-remote', '--symref', repoUrl(t), 'HEAD', 'refs/heads/*', 'refs/tags/*'], { timeoutMs: LS_REMOTE_TIMEOUT_MS });
+    if (res.timedOut)
+        throw new Error(`timed out after ${LS_REMOTE_TIMEOUT_MS / 1000}s resolving ${repoLabel(t)}`);
+    if (/\bENOENT\b/.test(res.stderr))
+        throw new Error(gitMissingMessage());
+    if (res.code !== 0)
+        throw new Error(unreadableRepoMessage(t, res.stderr));
+    const { head, refs } = parseLsRemote(res.stdout);
+    if (!t.refAndPath) {
+        if (!head)
+            throw new Error(unreadableRepoMessage(t, 'the remote named no default branch'));
+        return { ref: head, qualifiedRef: `refs/heads/${head}`, path: '' };
+    }
+    const split = splitRefAndPath(t.refAndPath, refs);
+    if (!split)
+        throw new Error(`no branch or tag ${t.refAndPath} in ${t.owner}/${t.repo}`);
+    return split;
+}
+export function missingManifestMessage(t, r) {
+    return [
+        `no ${MANIFEST_FILE} at ${t.owner}/${t.repo}@${r.ref}:${r.path || '/'}.`,
+        `Point the URL at the directory that contains it, for example https://github.com/${t.owner}/${t.repo}/tree/${r.ref}/templates/<name>`,
+    ].join(' ');
+}
+export function escapedManifestMessage(t, r) {
+    return `${MANIFEST_FILE} at ${t.owner}/${t.repo}@${r.ref}:${r.path || '/'} resolves outside the repository — refusing to read it`;
+}
+// The clone root, symlinks resolved, so containment is compared like with like.
+function containedRealPath(root, candidate) {
+    const realRoot = realpathSync(root);
+    const real = realpathSync(candidate);
+    if (real !== realRoot && !real.startsWith(realRoot + sep))
+        return null;
+    return real;
+}
+/** 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) {
+    const resolved = await resolveGitHubRef(target, run);
+    const dir = mkdtempSync(join(tmpdir(), 'insta-tpl-gh-'));
+    try {
+        // The short name, not resolved.qualifiedRef: `--branch` rejects a fully-qualified ref, and
+        // git's own short-name tie-break already agrees with splitRefAndPath (spec FAQ 7.14).
+        const cloned = await run(['clone', '--depth', '1', '--quiet', '--branch', resolved.ref, repoUrl(target), dir], { timeoutMs: CLONE_TIMEOUT_MS });
+        if (cloned.timedOut)
+            throw new Error(`timed out after ${CLONE_TIMEOUT_MS / 1000}s cloning https://github.com/${target.owner}/${target.repo}`);
+        if (/\bENOENT\b/.test(cloned.stderr))
+            throw new Error(gitMissingMessage());
+        if (cloned.code !== 0)
+            throw new Error(unreadableRepoMessage(target, cloned.stderr));
+        // The deployed commit is the one in the checkout: an annotated tag's listing entry is its tag
+        // object, and a branch can move between ls-remote and here (spec FAQ 7.10).
+        const head = await run(['-C', dir, 'rev-parse', 'HEAD'], { timeoutMs: LS_REMOTE_TIMEOUT_MS });
+        // Same three outcomes the other two calls distinguish, so a timeout or a missing git here is
+        // not reported as an unreadable repository.
+        if (head.timedOut)
+            throw new Error(`timed out after ${LS_REMOTE_TIMEOUT_MS / 1000}s reading the clone of ${repoLabel(target)}`);
+        if (/\bENOENT\b/.test(head.stderr))
+            throw new Error(gitMissingMessage());
+        if (head.code !== 0)
+            throw new Error(unreadableRepoMessage(target, head.stderr));
+        const commit = head.stdout.trim();
+        const manifestDir = resolved.path ? join(dir, resolved.path) : dir;
+        if (!existsSync(join(manifestDir, MANIFEST_FILE)))
+            throw new Error(missingManifestMessage(target, resolved));
+        // A committed symlink can point anywhere; only the resolved path proves what is being read.
+        const real = containedRealPath(dir, join(manifestDir, MANIFEST_FILE));
+        if (!real || !statSync(real).isFile())
+            throw new Error(escapedManifestMessage(target, resolved));
+        const manifest = load(manifestDir);
+        return {
+            source: { repo: `${target.owner}/${target.repo}`, ref: resolved.ref, path: resolved.path, commit },
+            manifest,
+        };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=github-source.js.map

package/dist/index.js

@@ -132,7 +132,7 @@ svc.command('add [type] [name]').description('Provision a service on demand (ass
     .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('--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 1; larger sizes are paid and plan-capped). Volume services keep 1 machine and stop (cold wake) instead of suspend when idle')
+    .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) => {
     const a = await resolveServiceArgs(type, name, serviceArgsDeps(o.json), o);
@@ -220,7 +220,7 @@ compute.command('restart [service]').description("Restart a compute service by r
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => computeCmd.computeRestart(service, o)));
 compute.command('status [service]').description("Show a compute service's desired vs. live state")
     .option('--json').option('--branch <branch>', 'branch (default: current)').action(guard((service, o) => computeCmd.computeStatus(service, o)));
-compute.command('limits [service]').description("Show or set a compute service's resource ceiling (paid plans). --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")
+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')
@@ -231,7 +231,7 @@ const execCmd = compute.command('exec [service]').description("Run a one-shot co
 // new option cannot reach the CLI surface while the split still reads it as part of the command.
 for (const [flags, description] of computeCmd.EXEC_OPTIONS)
     execCmd.option(flags, description);
-compute.command('volume [service]').description("Show, attach, grow, or delete a compute service's persistent /data volume. No flag: print size, mount path, and the plan cap (any plan). --size on a volumeless service ATTACHES one (any plan at the default 1Gi; larger is paid and plan-capped; the disk mounts at /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")
+compute.command('volume [service]').description("Show, attach, grow, or delete a compute service's persistent /data volume. No flag: print size, mount path, and the plan cap (any plan). --size on a volumeless service ATTACHES one (any plan at the default 10Gi, the free cap; larger is paid and plan-capped; the disk mounts at /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('--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)));
@@ -243,7 +243,7 @@ db.command('url').description('Print the postgres connection string (DSN) — ba
 db.command('connect').description("Open an interactive psql session on the postgres service (needs psql on PATH; gated: secrets.read). A suspended instance wakes on connect — the first prompt can take a few seconds. Exits with psql's own exit code")
     .option('--branch <branch>', 'branch (default: current)').option('--group <g>', 'postgres service name (default: the sole/default one)')
     .action(guard((o) => dbCmd.dbConnect(o)));
-db.command('limits').description("Show or set a postgres service's resource ceiling (paid plans; insta-db-backed only). Moves both directions")
+db.command('limits').description("Show or set a postgres service's resource ceiling (any plan within the free cap, paid above it; insta-db-backed only). Moves both directions")
     .option('--cpu <n>', "vCPU ceiling, e.g. 2 or 2500m").option('--memory <size>', "memory ceiling, e.g. 4Gi")
     .option('--json').option('--branch <branch>', 'branch (default: current)').option('--group <g>', 'postgres service name (default: the sole/default one)')
     .action(guard((o) => dbCmd.dbLimits(o)));
@@ -281,12 +281,12 @@ storage.command('delete <key>').description('DELETES one object from the bucket
     .option('--service <name>', 'storage service (default: the sole one on the branch)')
     .option('--branch <b>', 'branch (default: current)').option('--json')
     .action(guard((key, o) => storageCmd.storageDelete(key, o)));
-// ---- templates (registry + local insta.template.yaml deploys) ----
-const tpl = program.command('template').description('Browse and deploy app templates (registry, or a local dir with insta.template.yaml)');
+// ---- templates (registry, local insta.template.yaml, or a GitHub URL) ----
+const tpl = program.command('template').description('Browse and deploy app templates (registry, a local dir, or a GitHub URL)');
 tpl.command('list').description('List templates in the platform registry').option('--json').action(guard((o) => template.templateList(o)));
 tpl.command('info <code>').description('Show a template: version, upstream pin, services, and its required/optional variables')
     .option('--json').action(guard((code, o) => template.templateInfo(code, o)));
-tpl.command('deploy <code-or-dir>').description('Deploy a template onto a branch — a registry code, or a local directory containing insta.template.yaml (a path-looking target is always read as a directory). Missing required variables are prompted for on a terminal; generator-backed (secret:N) and defaulted ones are resolved by the platform')
+tpl.command('deploy <code-or-dir-or-url>').description('Deploy a template onto a branch — a registry code, a local directory containing insta.template.yaml (a path-looking target is always read as a directory), or a github.com URL (https://github.com/<owner>/<repo>[/tree/<ref>[/<dir>]]) whose manifest is fetched with your own git credentials. Missing required variables are prompted for on a terminal; generator-backed (secret:N) and defaulted ones are resolved by the platform')
     .option('--branch <b>', 'target branch (default: current)')
     .option('--set <NAME=value>', 'set a template variable (repeatable)', (v, prev) => [...prev, v], [])
     .option('-y, --yes', 'non-interactive: missing required variables fail with a --set list instead of prompting')

package/dist/observe/install.js

@@ -84,12 +84,15 @@ function claudeEntry() {
 // a fresh clone with no ./.insta anywhere above is a silent no-op. The script must stay free of
 // characters either shell rewrites inside double quotes: `$` and backticks (sh), `%` and `!`
 // (cmd.exe), and `"` (both). Codex has each user trust the entry before it runs, so shareable is safe.
+// Exit code: the hook's own status when it ran; 0 when it could not be started or was killed
+// (status null) — every other arm of this install is silent best-effort, and Codex reports any
+// non-zero exit as a failed hook after EVERY tool call, which is worse than a missed audit line.
 const CODEX_HOOK_SCRIPT = [
     "const f=require('fs'),p=require('path'),c=require('child_process');",
     'let d=process.cwd();',
     'for(;;){',
     "const h=p.join(d,'.insta/observe/hook.js');",
-    "if(f.existsSync(h)){const r=c.spawnSync(process.execPath,[h],{stdio:'inherit'});process.exitCode=r.status===null?1:r.status;break}",
+    "if(f.existsSync(h)){const r=c.spawnSync(process.execPath,[h],{stdio:'inherit'});process.exitCode=r.status===null?0:r.status;break}",
     'const u=p.dirname(d);if(u===d)break;d=u}',
 ].join('');
 function codexEntry() {

package/package.json

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