@sequenceholdings/studio-cli 0.1.11 → 0.1.13

package/README.md

@@ -97,13 +97,15 @@ You can always add or override environments yourself in
 `~/.config/lattice/config.toml` (user entries win over discovered ones):
 
 ```toml
+# Must come before any [env.*] table — TOML attaches bare keys to the
+# preceding table, so a trailing default_env is silently ignored.
+default_env = "local"
+
 [env.local]
 url = "http://localhost:5001"
 
 [env.my-atlas]
 url = "https://atlas.example.com"
-
-default_env = "local"
 ```
 
 Pass `--env <name>` (or `-e <name>`) on commands that talk to the platform.
@@ -121,6 +123,7 @@ the artifact folder's `.artifact-studio/config.json` `defaultEnv` (set by
 | `seq-studio process lint` | Static checks (graph, return contracts, agent schema, timeouts) |
 | `seq-studio process plan -e <env>` | Build bundle, diff against currently-active version |
 | `seq-studio process apply -e <env> [--only <id1,id2>]` | Build → register bundle → promote each process. `--only` promotes just the named process ids (the bundle still contains the whole root — registration is inert) |
+| `seq-studio process apply --repo processes/<name> [--ref <r>] -e <env> [--only <id1,id2>]` | Same as above, but materializes the source from a platform git-service repo. Pinned commit SHA is injected as bundle provenance. Requires `ATLAS_GIT_PAT` (or `AUTH0_M2M_CLIENT_SECRET` for CI) |
 | `seq-studio process test -e <env>` | CI wrapper: lint + plan, non-zero exit on errors or BREAKING diffs |
 | `seq-studio process simulate <id>` | In-process walk with stubbed runners (offline) |
 | `seq-studio process bundle build [-o file.json]` | Build a bundle locally |
@@ -129,6 +132,25 @@ the artifact folder's `.artifact-studio/config.json` `defaultEnv` (set by
 | `seq-studio process bundle list [-e <env>] [--limit N] [--cursor <hash>]` | List registered bundles (paginated; CLI auto-fetches all pages) |
 | `seq-studio process bundle publish <hash or bundle.json> [-e <env>]` | Register a local bundle (no promote) |
 
+### Remote source for `apply`
+
+`apply` can deploy a process from the platform git service instead of a local
+checkout:
+
+```bash
+seq-studio process apply --repo processes/my-process -e staging
+seq-studio process apply --repo processes/my-process --ref v1.2.0 -e production
+```
+
+The source is materialized to a temp dir, dependencies are installed from the
+committed `pnpm-lock.yaml` (must be Chainguard-resolved), process definitions
+are discovered, the bundle is built with the pinned commit as provenance, and the
+temp tree is cleaned up — even on error. Only the `processes` namespace is
+accepted; other namespaces (artifacts, managed-functions) are rejected.
+
+Auth: same as `artifact deploy --repo` — `ATLAS_GIT_PAT` for the smart-HTTP
+clone path, or `AUTH0_M2M_CLIENT_SECRET` for CI's JSON materialize path.
+
 ### Process discovery
 
 `seq-studio` walks the current working directory for any subfolder

package/dist/bin.js

@@ -1,8 +1,14 @@
 #!/usr/bin/env node
 import { run } from './main.js';
+import { maybeNotifyUpdate } from './update-check.js';
 run()
-    .then((code) => process.exit(code))
     .catch((error) => {
     console.error(error instanceof Error ? error.message : error);
-    process.exit(1);
+    return 1;
+})
+    // The update notice runs after the command so it never delays real output,
+    // and it is best-effort (never throws, never changes the exit code).
+    .then(async (code) => {
+    await maybeNotifyUpdate();
+    process.exit(code);
 });

package/dist/config.d.ts

@@ -38,6 +38,16 @@ export interface ResolvedEnv {
     name: string;
     url: string;
 }
+/**
+ * Copy-pasteable fallback when the discovery catalog is unavailable.
+ *
+ * The `[env.*]` table is safe to append to an existing config.toml. We
+ * intentionally omit `default_env` from the snippet — appending it after
+ * an existing `[env.*]` table would scope it into that table (TOML bare-key
+ * rule) and silently no-op. Callers who want a default should put
+ * `default_env = "..."` at the top of the file, before any table.
+ */
+export declare function manualEnvConfigHint(): string;
 /**
  * Resolve `--env <name>` against the effective config. Falls back to the
  * config's `defaultEnv` when no name is passed. Throws a clear error when

package/dist/config.js

@@ -82,18 +82,40 @@ export async function writeConfig(config) {
     // smol-toml's stringify can't accept arbitrary nested keys via the
     // `env.<name>` syntax directly; we build it manually for stable
     // ordering and clean output.
-    const lines = [];
+    //
+    // `default_env` MUST come before any `[env.*]` table. In TOML, a bare
+    // key after a table header belongs to that table — putting it last
+    // would silently attach it to the final `[env.*]` and `readConfig`
+    // (which only reads top-level `default_env`) would ignore it.
+    const lines = [`default_env = "${config.defaultEnv}"`, ''];
     for (const [name, value] of Object.entries(config.envs)) {
         lines.push(`[env.${name}]`);
         lines.push(`url = ${stringifyToml({ url: value.url }).trim().replace(/^url = /, '')}`);
         lines.push('');
     }
-    lines.push(`default_env = "${config.defaultEnv}"`);
     await writeFile(path, lines.join('\n') + '\n', { encoding: 'utf8', mode: 0o600 });
 }
 /** Shared hint appended to visibility errors at the anonymous/partner tiers. */
 const DISCOVERY_HINT = 'If you expect more environments, authenticate (seq-studio login, or set ' +
     'AUTH0_M2M_CLIENT_SECRET) and run: seq-studio envs refresh';
+/**
+ * Copy-pasteable fallback when the discovery catalog is unavailable.
+ *
+ * The `[env.*]` table is safe to append to an existing config.toml. We
+ * intentionally omit `default_env` from the snippet — appending it after
+ * an existing `[env.*]` table would scope it into that table (TOML bare-key
+ * rule) and silently no-op. Callers who want a default should put
+ * `default_env = "..."` at the top of the file, before any table.
+ */
+export function manualEnvConfigHint() {
+    return (`Or add an environment manually in ${configPath()} (append-safe):\n` +
+        `\n` +
+        `  [env.my-env]\n` +
+        `  url = "https://your-atlas-host.example.com"\n` +
+        `\n` +
+        `To make it the default, put \`default_env = "my-env"\` at the TOP of ` +
+        `that file — before any [env.*] table.`);
+}
 /**
  * Resolve `--env <name>` against the effective config. Falls back to the
  * config's `defaultEnv` when no name is passed. Throws a clear error when

package/dist/envs/commands.js

@@ -1,4 +1,5 @@
-import { readConfig, configPath } from '../config.js';
+import { tryGetAccessToken } from '../auth.js';
+import { readConfig, configPath, manualEnvConfigHint } from '../config.js';
 import { bootstrapUrl, fetchCatalog, readCachedCatalog, } from '../env-catalog.js';
 const ENVS_USAGE = `usage:
   seq-studio envs list      show the environments visible to your identity
@@ -30,6 +31,24 @@ export async function runEnvsCommand(sub, _rest) {
             return 1;
     }
 }
+/**
+ * Tier `anonymous` means "no catalog cached", not necessarily "no token".
+ * Shared by list + refresh so they don't contradict each other.
+ */
+async function printNoCatalogGuidance(log = console.log) {
+    const token = await tryGetAccessToken();
+    log('');
+    if (token) {
+        log(`Logged in, but no environment catalog is cached against ${bootstrapUrl()} — ` +
+            'only "local" (plus any config.toml entries) is visible. Run: seq-studio envs refresh');
+    }
+    else {
+        log('Not authenticated — only "local" is visible. Authenticate with ' +
+            '`seq-studio login` (or set AUTH0_M2M_CLIENT_SECRET), then run: seq-studio envs refresh');
+    }
+    log('');
+    log(manualEnvConfigHint());
+}
 async function listCommand() {
     const [config, catalog] = await Promise.all([readConfig(), readCachedCatalog()]);
     const discovered = new Set(catalog?.environments.map((env) => env.name) ?? []);
@@ -48,9 +67,7 @@ async function listCommand() {
         console.log(`  ${name.padEnd(width)}  ${url}  (${source})`);
     }
     if (config.tier === 'anonymous') {
-        console.log('');
-        console.log('Not authenticated — only "local" is visible. Authenticate with ' +
-            '`seq-studio login` (or set AUTH0_M2M_CLIENT_SECRET), then run: seq-studio envs refresh');
+        await printNoCatalogGuidance();
     }
     return 0;
 }
@@ -61,12 +78,12 @@ async function refreshCommand() {
     }
     catch (err) {
         console.error(`envs refresh: FAIL — ${err instanceof Error ? err.message : String(err)}`);
+        console.error('');
+        console.error(manualEnvConfigHint());
         return 1;
     }
     if (!catalog) {
-        console.log(`Not authenticated against ${bootstrapUrl()} — catalog cleared; only ` +
-            '"local" (plus any config.toml entries) is visible.\n' +
-            'Authenticate with `seq-studio login` (or set AUTH0_M2M_CLIENT_SECRET) and retry.');
+        await printNoCatalogGuidance();
         return 0;
     }
     console.log(`tier: ${catalog.tier} — ${catalog.environments.length} environment(s) cached.`);

package/dist/login.d.ts

@@ -7,6 +7,12 @@ interface LoginOptions {
 }
 export declare function openSystemBrowser(authorizationUrl: string): Promise<void>;
 export declare function loginWithPkce({ fetchImpl, now, openBrowser, port, timeoutMs, }: LoginOptions): Promise<void>;
+/**
+ * Best-effort catalog refresh after a successful login. Drop the old cache
+ * first so a prior identity's tier never lingers; discovery failures must not
+ * fail login. Exported for unit tests.
+ */
+export declare function refreshCatalogAfterLogin(): Promise<void>;
 export declare function login(): Promise<void>;
 export declare function logout(): Promise<void>;
 export {};

package/dist/login.js

@@ -5,7 +5,8 @@ import { spawn } from 'node:child_process';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { AUTH0_AUDIENCE, AUTH0_CLIENT_ID, AUTH0_DOMAIN, saveTokens, seqapiTokenPath, } from './auth.js';
-import { clearCatalog, fetchCatalog } from './env-catalog.js';
+import { manualEnvConfigHint } from './config.js';
+import { bootstrapUrl, clearCatalog, fetchCatalog } from './env-catalog.js';
 const DEFAULT_REDIRECT_PORT = 5099;
 const DEFAULT_LOGIN_TIMEOUT_MS = 300_000;
 function base64Url(input) {
@@ -193,25 +194,32 @@ export async function loginWithPkce({ fetchImpl = fetch, now = Date.now, openBro
         expires_at: now() / 1_000 + tokens.expiresIn,
     });
 }
-export async function login() {
-    await loginWithPkce({});
-    console.log(`Authenticated. Tokens saved to ${seqapiTokenPath()}.`);
-    // Refresh the environment catalog for the new identity immediately, so a
-    // previously cached catalog from another identity (or tier) never lingers
-    // past a login. Drop the old cache first — if the refresh below fails, the
-    // prior identity's catalog must not survive the login either.
-    // Best-effort: discovery being unreachable must not fail login.
+/**
+ * Best-effort catalog refresh after a successful login. Drop the old cache
+ * first so a prior identity's tier never lingers; discovery failures must not
+ * fail login. Exported for unit tests.
+ */
+export async function refreshCatalogAfterLogin() {
     await clearCatalog();
     try {
         const catalog = await fetchCatalog();
         if (catalog) {
             console.log(`Environment catalog refreshed (tier: ${catalog.tier}, ` +
                 `${catalog.environments.length} environment(s)).`);
+            return;
         }
     }
     catch {
-        console.log('Could not refresh the environment catalog — run: seq-studio envs refresh');
+        // Network / non-auth discovery errors fall through to the same hint.
     }
+    console.log(`Could not load the environment catalog from ${bootstrapUrl()} — ` +
+        'run: seq-studio envs refresh');
+    console.log(manualEnvConfigHint());
+}
+export async function login() {
+    await loginWithPkce({});
+    console.log(`Authenticated. Tokens saved to ${seqapiTokenPath()}.`);
+    await refreshCatalogAfterLogin();
 }
 /**
  * Pre-unification artifact-studio token file. `seq-studio artifact` commands

package/dist/main.js

@@ -30,6 +30,7 @@ const TOP_LEVEL_USAGE = `usage:
   seq-studio login                   authenticate in the browser
   seq-studio logout                  remove cached user tokens
   seq-studio doctor [-e <env>]       diagnose config, auth, and writer gate
+  seq-studio version                 print the installed version
   seq-studio help                    show this message
 
   Authenticate with: seq-studio login
@@ -41,6 +42,7 @@ const PROCESS_USAGE = `usage:
   seq-studio process lint
   seq-studio process plan [-e <env>]
   seq-studio process apply [-e <env>] [--only <id1,id2,...>]
+  seq-studio process apply --repo processes/<name> [--ref <r>] -e <env> [--only <id1,id2,...>]
   seq-studio process promote <processId> --version <v> [-e <env>]
   seq-studio process pull <processId> [--version <v>] [-e <env>] [--out <dir>] [--no-children]
   seq-studio process test [-e <env>] [--offline]
@@ -92,6 +94,13 @@ export async function run(argv = process.argv.slice(2)) {
         case 'login':
         case 'logout':
             return runSessionCommand({ argument: sub, command: namespace });
+        case 'version':
+        case '--version':
+        case '-v': {
+            const { currentVersion } = await import('./update-check.js');
+            console.log(currentVersion());
+            return 0;
+        }
         case 'doctor':
             return doctorCommand(parseArgs([sub, ...rest].filter(Boolean)));
         default:

package/dist/orm/delegate.d.ts

@@ -5,4 +5,13 @@
  * `artifact`): resolve `--env` from `~/.config/lattice/config.toml`, set
  * SEQUENCE_ORM_BASE_URL, share the seqapi token, forward argv.
  */
+/**
+ * Classify an ERR_MODULE_NOT_FOUND from importing `@sequenceholdings/orm/cli`:
+ * is the orm package itself absent, or is it present but a dependency (e.g.
+ * drizzle-orm) failed to resolve? Match the MISSING specifier (the quoted name
+ * after "Cannot find package/module"), never the whole message: a transitive
+ * failure's text includes the importer path (`.../node_modules/@sequenceholdings/orm/...`),
+ * so a substring check would misread a missing dep as the orm package itself.
+ */
+export declare function isOrmPackageMissing(message: string): boolean;
 export declare function runOrmCommand(sub: string | undefined, rest: string[]): Promise<number>;

package/dist/orm/delegate.js

@@ -19,6 +19,18 @@ const ORM_USAGE = `usage:
   discovered after you authenticate).
   Authenticate with: seq-studio login
 `;
+/**
+ * Classify an ERR_MODULE_NOT_FOUND from importing `@sequenceholdings/orm/cli`:
+ * is the orm package itself absent, or is it present but a dependency (e.g.
+ * drizzle-orm) failed to resolve? Match the MISSING specifier (the quoted name
+ * after "Cannot find package/module"), never the whole message: a transitive
+ * failure's text includes the importer path (`.../node_modules/@sequenceholdings/orm/...`),
+ * so a substring check would misread a missing dep as the orm package itself.
+ */
+export function isOrmPackageMissing(message) {
+    const specifier = message.match(/Cannot find (?:package|module) '([^']+)'/)?.[1];
+    return specifier === '@sequenceholdings/orm' || (specifier?.startsWith('@sequenceholdings/orm/') ?? false);
+}
 export async function runOrmCommand(sub, rest) {
     if (!sub || sub === 'help' || sub === '--help' || sub === '-h') {
         console.log(ORM_USAGE);
@@ -42,8 +54,15 @@ export async function runOrmCommand(sub, rest) {
     }
     catch (err) {
         if (err.code === 'ERR_MODULE_NOT_FOUND') {
-            console.error('seq-studio orm requires @sequenceholdings/orm, which is not included ' +
-                'in this installation. It is available to Sequence-internal setups only.');
+            const message = err instanceof Error ? err.message : String(err);
+            if (isOrmPackageMissing(message)) {
+                console.error('seq-studio orm needs the @sequenceholdings/orm package. Install it alongside the CLI:\n' +
+                    '  npm install @sequenceholdings/orm');
+            }
+            else {
+                console.error('@sequenceholdings/orm is installed but a dependency failed to load. Reinstall dependencies, then retry.\n' +
+                    `  ${message}`);
+            }
             return 1;
         }
         throw err;

package/dist/process/build.d.ts

@@ -8,7 +8,14 @@ export type ResolveProcessPin = (processId: string, version?: string) => Promise
     version: string;
     bundleHash: string;
 } | null>;
-export declare function buildBundleFromProcesses(defs: readonly LoadedProcess[], options?: {
+export interface BuildBundleOptions {
     resolveProcessPin?: ResolveProcessPin;
-}): Promise<LatticeBundle>;
+    /** Override git provenance instead of reading from the local working tree. */
+    provenance?: {
+        gitCommit: string | null;
+        gitBranch: string | null;
+        gitDirty: boolean | null;
+    };
+}
+export declare function buildBundleFromProcesses(defs: readonly LoadedProcess[], options?: BuildBundleOptions): Promise<LatticeBundle>;
 export declare function summarizeBundle(bundle: LatticeBundle): LatticeBundleSummary;

package/dist/process/build.js

@@ -20,9 +20,12 @@ export async function buildBundleFromProcesses(defs, options) {
             return options.resolveProcessPin(processId, version);
         });
     }
+    const metadata = options?.provenance
+        ? collectGitMetadataWithOverrides(options.provenance)
+        : collectGitMetadata();
     // Manifest, hash, version, and co-located subprocess pins are all derived in
     // the SDK so a CLI-built bundle is byte-identical to a server-applied one.
-    return finalizeBundleIdentity({ processes, metadata: collectGitMetadata() });
+    return finalizeBundleIdentity({ processes, metadata });
 }
 async function resolveSubprocessPinsInProcesses(processes, resolve) {
     const pins = [];
@@ -266,6 +269,11 @@ function serializeNodeMetadata(node) {
                 on_branch_error: parallel.on_branch_error,
                 join_source: toSource(parallel.join),
             };
+            // Serialized only when non-default ('eager') so existing barrier
+            // bundles keep their hashes; a missing field reads as 'barrier'.
+            if (parallel.join_mode === 'eager') {
+                pmeta.join_mode = 'eager';
+            }
             if (parallel.max_concurrency !== undefined) {
                 pmeta.max_concurrency = parallel.max_concurrency;
             }
@@ -348,6 +356,15 @@ function collectGitMetadata() {
         git_dirty: get('git status --porcelain') !== '',
     };
 }
+function collectGitMetadataWithOverrides(provenance) {
+    return {
+        created_at: new Date().toISOString(),
+        created_by: process.env['USER'] ?? null,
+        git_commit: provenance.gitCommit,
+        git_branch: provenance.gitBranch,
+        git_dirty: provenance.gitDirty ?? false,
+    };
+}
 export function summarizeBundle(bundle) {
     return {
         name: bundle.manifest.bundle.name,

package/dist/process/codegen.js

@@ -171,6 +171,8 @@ function emitNode(node, ctx) {
                 par.supervisor_retry !== undefined ? `  supervisor_retry: ${pretty(par.supervisor_retry, 1)},` : null,
                 bindings(m.bindings),
                 `  on_branch_error: ${lit(par.on_branch_error)},`,
+                // Only 'eager' is ever serialized (barrier is the omitted default).
+                par.join_mode === 'eager' ? `  join_mode: ${lit('eager')},` : null,
                 `  join: ${par.join_source},`,
                 mapper('input', m.input_mapper_source),
                 tail,

package/dist/process/commands.d.ts

@@ -9,6 +9,25 @@ export interface ParsedArgs {
     flags: Record<string, string | true>;
 }
 export declare function parseArgs(rest: string[]): ParsedArgs;
+export type ProcessSourceSpec = {
+    kind: 'local';
+} | {
+    kind: 'git-service';
+    namespace: string;
+    name: string;
+    ref?: string;
+};
+/**
+ * Parse the process-apply source flags. `--repo processes/<name>` materializes
+ * from the platform git service; absent means local (cwd / LATTICE_PROCESSES_ROOT).
+ * `--git-url` is passed through to the underlying `resolveArtifactSource` when
+ * the repo flag is a full ns/name pair (future); today only git-service is
+ * supported.
+ *
+ * Process repos live exclusively in the `processes` namespace — other namespaces
+ * (artifacts, managed-functions) are rejected to avoid cross-kind accidents.
+ */
+export declare function parseProcessSourceSpec(flags: Record<string, string | true>): ProcessSourceSpec;
 export declare function initCommand(args: ParsedArgs): Promise<number>;
 export declare function lintCommand(args: ParsedArgs): Promise<number>;
 export declare function planCommand(args: ParsedArgs): Promise<number>;

package/dist/process/commands.js

@@ -21,6 +21,8 @@ import { lintProcesses, formatLintResult } from './lint.js';
 import { diffBundleAgainstActive, formatPlanDiff, } from './plan-diff.js';
 import { simulateProcess, formatSimulateResult } from './simulate.js';
 import { buildAgentSchemaLoader } from './agent-loader.js';
+import { resolveArtifactSource, } from '@sequenceholdings/artifact-studio/source-resolver';
+import { prepareProcessBuildRoot } from './repo-install.js';
 export function parseArgs(rest) {
     const positional = [];
     const flags = {};
@@ -106,6 +108,39 @@ async function getEnvAndToken(args) {
     }
     return { env, token };
 }
+/**
+ * Parse the process-apply source flags. `--repo processes/<name>` materializes
+ * from the platform git service; absent means local (cwd / LATTICE_PROCESSES_ROOT).
+ * `--git-url` is passed through to the underlying `resolveArtifactSource` when
+ * the repo flag is a full ns/name pair (future); today only git-service is
+ * supported.
+ *
+ * Process repos live exclusively in the `processes` namespace — other namespaces
+ * (artifacts, managed-functions) are rejected to avoid cross-kind accidents.
+ */
+export function parseProcessSourceSpec(flags) {
+    const repo = typeof flags.repo === 'string' ? flags.repo : undefined;
+    const ref = typeof flags.ref === 'string' ? flags.ref : undefined;
+    if (flags.repo === true)
+        throw new Error('--repo requires a value: --repo processes/<name>');
+    if (flags.ref === true)
+        throw new Error('--ref requires a value.');
+    if (ref && !repo)
+        throw new Error('--ref only applies together with --repo.');
+    if (ref && ref.startsWith('-'))
+        throw new Error(`--ref must not start with "-" (got "${ref}").`);
+    if (!repo)
+        return { kind: 'local' };
+    const parts = repo.split('/');
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+        throw new Error(`--repo must be "processes/<name>" (got "${repo}").`);
+    }
+    if (parts[0] !== 'processes') {
+        throw new Error(`Process deploys require the "processes" namespace — got "${parts[0]}". ` +
+            `Use --repo processes/<name>.`);
+    }
+    return { kind: 'git-service', namespace: parts[0], name: parts[1], ref };
+}
 // ---------------------------------------------------------------------------
 // init
 // ---------------------------------------------------------------------------
@@ -199,18 +234,18 @@ async function tryBuildAgentLoader(args) {
 // ---------------------------------------------------------------------------
 // plan
 // ---------------------------------------------------------------------------
-async function buildBundleForPublish(args, defs) {
+async function buildBundleForPublish(args, defs, provenance) {
     const hasSubprocess = defs.some((d) => d.process.nodes.some((n) => n.kind === 'subprocess'));
     try {
         const { env, token } = await getEnvAndToken(args);
         const resolveProcessPin = buildResolveProcessPinFromEnv(env, token);
-        return await buildBundleFromProcesses(defs, { resolveProcessPin });
+        return await buildBundleFromProcesses(defs, { resolveProcessPin, provenance });
     }
     catch (err) {
         if (hasSubprocess) {
             throw new Error('subprocess nodes require -e <env> and `seq-studio login` to resolve child process versions', { cause: err });
         }
-        return await buildBundleFromProcesses(defs);
+        return await buildBundleFromProcesses(defs, { provenance });
     }
 }
 export async function planCommand(args) {
@@ -334,8 +369,36 @@ export function resolveOnlyIds({ only, knownIds, }) {
     return { ids };
 }
 export async function applyCommand(args) {
+    const spec = parseProcessSourceSpec(args.flags);
+    if (spec.kind === 'git-service') {
+        return applyFromRepo(args, spec);
+    }
+    return applyLocal(args);
+}
+async function applyLocal(args) {
     const { env, token } = await getEnvAndToken(args);
     const defs = await loadProcessDefinitions();
+    return registerAndPromote({ args, env, token, defs });
+}
+async function applyFromRepo(args, spec) {
+    const { env, token } = await getEnvAndToken(args);
+    const source = await resolveArtifactSource({ kind: 'git-service', namespace: spec.namespace, name: spec.name, ref: spec.ref }, { baseUrl: env.url, token });
+    try {
+        await prepareProcessBuildRoot(source.dir);
+        const defs = await loadProcessDefinitions(source.dir);
+        return await registerAndPromote({
+            args,
+            env,
+            token,
+            defs,
+            provenance: source.provenance,
+        });
+    }
+    finally {
+        await source.cleanup();
+    }
+}
+async function registerAndPromote({ args, env, token, defs, provenance, }) {
     const onlyResult = resolveOnlyIds({
         only: args.flags.only,
         knownIds: new Set(defs.map((d) => d.process.id)),
@@ -357,7 +420,7 @@ export async function applyCommand(args) {
         console.error('\napply FAILED — lint rejected the bundle');
         return 1;
     }
-    const bundle = await buildBundleForPublish(args, defs);
+    const bundle = await buildBundleForPublish(args, defs, provenance);
     console.log(`[seq-studio] built bundle ${bundle.bundle_hash.slice(0, 12)} ` +
         `(${bundle.processes.length} process(es))`);
     // We send only the bundle. `created_by` (and `promoted_by` for the
@@ -668,7 +731,7 @@ export async function doctorCommand(args) {
         lines.push(`config: ok — default_env=${config.defaultEnv}, envs=${Object.keys(config.envs).join(',')}`);
         lines.push(`tier: ${config.tier}` +
             (config.tier === 'anonymous'
-                ? ' — authenticate and run `seq-studio envs refresh` to discover more environments'
+                ? ' — no environment catalog cached; run `seq-studio envs refresh` to discover more environments'
                 : ''));
     }
     const requested = typeof args.flags.env === 'string' ? args.flags.env : undefined;

package/dist/process/discover.d.ts

@@ -28,5 +28,8 @@ export declare function findProcessRoot(): Promise<string>;
  * Load every `<dir>/process.ts` under the configured root. Each module
  * must `export default defineProcess(...)`. Process ids must be unique
  * across the set — duplicates throw.
+ *
+ * @param explicitRoot  When supplied, overrides LATTICE_PROCESSES_ROOT and cwd.
+ *   Used by `--repo` deploys to point discovery at the materialized temp tree.
  */
-export declare function loadProcessDefinitions(): Promise<readonly LoadedProcess[]>;
+export declare function loadProcessDefinitions(explicitRoot?: string): Promise<readonly LoadedProcess[]>;

package/dist/process/discover.js

@@ -55,9 +55,12 @@ export async function findProcessRoot() {
  * Load every `<dir>/process.ts` under the configured root. Each module
  * must `export default defineProcess(...)`. Process ids must be unique
  * across the set — duplicates throw.
+ *
+ * @param explicitRoot  When supplied, overrides LATTICE_PROCESSES_ROOT and cwd.
+ *   Used by `--repo` deploys to point discovery at the materialized temp tree.
  */
-export async function loadProcessDefinitions() {
-    const root = await findProcessRoot();
+export async function loadProcessDefinitions(explicitRoot) {
+    const root = explicitRoot ?? (await findProcessRoot());
     const entries = await readdir(root);
     const found = [];
     const seenIds = new Set();

package/dist/process/lint.js

@@ -402,17 +402,66 @@ async function lintAgent(processId, node, errors, warnings, loadAgentSchemaEdgeI
         });
     }
 }
+/**
+ * Matches an undecided-sentinel return in a serialized join source: the
+ * literal `{ undecided: true }` (the correct authored form — reducers run in
+ * a vm with no module imports in scope) or a `JOIN_UNDECIDED` reference
+ * (recognized so the eager no-sentinel warning doesn't double-fire on top of
+ * the closure-scope warning that already flags the out-of-scope import).
+ */
+const UNDECIDED_SENTINEL_RE = /\bundecided\s*:\s*true\b|\bJOIN_UNDECIDED\b/;
 /**
  * Lint a parallel node's `join` reducer the way we lint automation fns:
  * scan the serialized source for literal `edge_id: '…'` returns and confirm
  * each is in the parallel node's own outgoing_edges. The reducer chooses the
  * parallel node's exit edge, so a typo there is a routing bug the orchestrator
  * would only surface at run time.
+ *
+ * join_mode checks: a BARRIER join returning the `{undecided: true}` sentinel
+ * is an authoring error (the runner fails the block at runtime), and an EAGER
+ * join that never returns the sentinel decides on the first settlement —
+ * legal but suspicious, so it warns. No static engine check is possible for
+ * eager blocks: the execution engine is chosen per RUN (`{"engine": ...}` +
+ * environment rollout policy), not per process — the Trigger-only limitation
+ * is enforced at runtime (an eager block on a Temporal run fails with a clear
+ * unsupported error at branch resolution).
  */
 function lintParallelJoin(processId, node, errors, warnings) {
     const join = node.join;
     const source = typeof join === 'function' ? join.toString() : '';
     const outgoingIds = new Set(node.outgoing_edges.map((e) => e.id));
+    const joinMode = node.join_mode ?? 'barrier';
+    const returnsUndecided = UNDECIDED_SENTINEL_RE.test(source);
+    if (joinMode === 'eager') {
+        if (typeof join !== 'function') {
+            // defineParallelNode already rejects this; belt-and-suspenders for
+            // hand-built definitions that bypassed the SDK constructor.
+            errors.push({
+                process_id: processId,
+                node_id: node.id,
+                message: `join_mode 'eager' requires an explicit join reducer`,
+            });
+        }
+        if (!returnsUndecided) {
+            warnings.push({
+                process_id: processId,
+                node_id: node.id,
+                message: `join_mode is 'eager' but the join source never returns the ` +
+                    `{undecided: true} sentinel — the block will decide on the FIRST ` +
+                    `branch settlement; confirm that is intended`,
+            });
+        }
+    }
+    else if (returnsUndecided) {
+        errors.push({
+            process_id: processId,
+            node_id: node.id,
+            message: `parallel join returns the {undecided: true} sentinel but join_mode ` +
+                `is 'barrier' (the default) — the sentinel is only meaningful with ` +
+                `join_mode: 'eager'; at runtime the block FAILS when a barrier join ` +
+                `returns it`,
+        });
+    }
     const literals = new Set();
     for (const match of source.matchAll(EDGE_ID_LITERAL_RE)) {
         if (match[1])

package/dist/process/repo-install.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Remote-install helper for `process apply --repo`. Installs dependencies
+ * in a materialized process repo so `tsx` can import `process.ts` modules.
+ *
+ * Re-uses the artifact-studio trusted-install pipeline:
+ *   1. Require `package.json` and `pnpm-lock.yaml` (no floating installs)
+ *   2. Strip install-control files (.npmrc, pnpm-workspace.yaml, pnpm hooks)
+ *   3. Full trust validation: registry-only specs, no patches, no symlinks,
+ *      Chainguard lockfile with repo/commit/directory/tarball checks
+ *   4. Run pinned pnpm with frozen lockfile, ignore-scripts, prod-only
+ */
+/**
+ * Install dependencies in a materialized remote process repo. Process repos
+ * deployed from git-service must carry a `package.json` (process.ts files
+ * import `@sequenceholdings/lattice/define` and the module won't resolve
+ * without node_modules) and a Chainguard-resolved `pnpm-lock.yaml`.
+ *
+ * Throws when either file is missing or when the tree fails the full
+ * trusted-install validation.
+ */
+export declare function prepareProcessBuildRoot(dir: string): Promise<void>;

package/dist/process/repo-install.js

@@ -0,0 +1,83 @@
+/**
+ * Remote-install helper for `process apply --repo`. Installs dependencies
+ * in a materialized process repo so `tsx` can import `process.ts` modules.
+ *
+ * Re-uses the artifact-studio trusted-install pipeline:
+ *   1. Require `package.json` and `pnpm-lock.yaml` (no floating installs)
+ *   2. Strip install-control files (.npmrc, pnpm-workspace.yaml, pnpm hooks)
+ *   3. Full trust validation: registry-only specs, no patches, no symlinks,
+ *      Chainguard lockfile with repo/commit/directory/tarball checks
+ *   4. Run pinned pnpm with frozen lockfile, ignore-scripts, prod-only
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ARTIFACT_BUILD_PNPM, buildControlledArtifactNpmrc, } from '@sequenceholdings/artifact-studio/prepare-build';
+import { stripInstallControlFiles } from '@sequenceholdings/artifact-studio/sanitize-remote-tree';
+import { ArtifactInstallTrustError, assertTrustedArtifactInstallTree, } from '@sequenceholdings/artifact-studio/trusted-install';
+class ProcessInstallError extends Error {
+    name = 'ProcessInstallError';
+}
+/**
+ * Install dependencies in a materialized remote process repo. Process repos
+ * deployed from git-service must carry a `package.json` (process.ts files
+ * import `@sequenceholdings/lattice/define` and the module won't resolve
+ * without node_modules) and a Chainguard-resolved `pnpm-lock.yaml`.
+ *
+ * Throws when either file is missing or when the tree fails the full
+ * trusted-install validation.
+ */
+export async function prepareProcessBuildRoot(dir) {
+    if (!existsSync(join(dir, 'package.json'))) {
+        throw new ProcessInstallError('Remote process repos must include a package.json with @sequenceholdings/lattice as a dependency.');
+    }
+    if (!existsSync(join(dir, 'pnpm-lock.yaml'))) {
+        throw new ProcessInstallError('Remote process deploy requires pnpm-lock.yaml — run `pnpm install` locally and commit the lockfile.');
+    }
+    const stripped = stripInstallControlFiles(dir);
+    if (stripped.length > 0) {
+        console.warn(`[seq-studio] stripped install-control files from remote tree: ${stripped.join(', ')}`);
+    }
+    try {
+        assertTrustedArtifactInstallTree(dir);
+    }
+    catch (error) {
+        if (error instanceof ArtifactInstallTrustError) {
+            throw new ProcessInstallError(`Remote process repo is not trusted for install: ${error.message}`);
+        }
+        throw error;
+    }
+    await rm(join(dir, 'node_modules'), { recursive: true, force: true });
+    const configDir = await mkdtemp(join(tmpdir(), 'process-pnpm-'));
+    const controlledNpmrc = join(configDir, '.npmrc');
+    const userNpmrcPath = process.env.npm_config_userconfig ?? join(homedir(), '.npmrc');
+    console.log(`[seq-studio] installing process dependencies (frozen lockfile, prod only) via ${ARTIFACT_BUILD_PNPM}…`);
+    try {
+        await writeFile(controlledNpmrc, buildControlledArtifactNpmrc(userNpmrcPath), { mode: 0o600 });
+        const spawnOpts = {
+            cwd: configDir,
+            stdio: 'inherit',
+            env: { ...process.env, npm_config_userconfig: controlledNpmrc },
+        };
+        execFileSync('npx', [
+            '--yes',
+            ARTIFACT_BUILD_PNPM,
+            '--dir',
+            dir,
+            'install',
+            '--frozen-lockfile',
+            '--ignore-scripts',
+            '--prod',
+        ], spawnOpts);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new ProcessInstallError(`process dependency install failed (${ARTIFACT_BUILD_PNPM}). ` +
+            `Run \`pnpm install\` locally and commit pnpm-lock.yaml. (${detail})`);
+    }
+    finally {
+        await rm(configDir, { recursive: true, force: true });
+    }
+}

package/dist/process/simulate.js

@@ -10,7 +10,7 @@
  *   - Stubs automation runner identically — native handlers live in the
  *     Atlas image and can't execute here
  */
-import { DEFAULT_MAX_FANOUT_WIDTH, } from '@sequenceholdings/lattice/define';
+import { DEFAULT_MAX_FANOUT_WIDTH, isJoinUndecided, } from '@sequenceholdings/lattice/define';
 import { extractOutputState, mergeRunState } from '@sequenceholdings/lattice';
 const DEFAULT_MAX_ITERATIONS = 1000;
 const DEFAULT_MAX_REVISITS = 100;
@@ -246,7 +246,20 @@ async function simulateParallel(args, node) {
             item: br.item,
         });
     }
+    // The simulator settles every branch before joining, so an EAGER join sees
+    // the all-settled case (its incremental undecided passes aren't modelled —
+    // simulate verifies topology/routing, not settlement timing). In that case
+    // the eager contract requires a decision; surface a sentinel return as the
+    // same clear error the runtime raises instead of a confusing edge failure.
     const joinOutput = node.join(results, args.ctx);
+    if (isJoinUndecided(joinOutput)) {
+        throw new Error(node.join_mode === 'eager'
+            ? `parallel node "${node.id}": eager join returned {undecided: true} with ` +
+                `every branch settled — an eager join must decide once nothing is pending`
+            : `parallel node "${node.id}": join returned the {undecided: true} sentinel ` +
+                `but join_mode is 'barrier' — the sentinel is only meaningful with ` +
+                `join_mode: 'eager'`);
+    }
     return foldBranchState(joinOutput, results);
 }
 /**

package/dist/update-check-refresh.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/update-check-refresh.js

@@ -0,0 +1,9 @@
+/**
+ * Detached background entry spawned by maybeNotifyUpdate() when the update
+ * cache is stale. Polls the npm registry once and persists the result so
+ * the *next* command can print the notice without any foreground network.
+ */
+import { refreshUpdateCache } from './update-check.js';
+refreshUpdateCache().catch(() => {
+    // Best-effort: nothing to report to — the parent process is long gone.
+});

package/dist/update-check.d.ts

@@ -0,0 +1,27 @@
+/** The version of this installed package (dist/../package.json). */
+export declare function currentVersion(): string;
+export declare function updateCheckCachePath(): string;
+/** Exclusive-create marker that makes "who spawns the refresh?" atomic. */
+export declare function updateCheckClaimPath(): string;
+/**
+ * True when `candidate` is a strictly newer semver than `current`.
+ * Prerelease suffixes are ignored — the published channel is plain
+ * major.minor.patch and this only drives a notice, not resolution.
+ */
+export declare function isNewerVersion(candidate: string, current: string): boolean;
+/**
+ * Poll the registry and persist the result. Runs in the detached background
+ * process (see update-check-refresh.ts) — never on a command's exit path.
+ * Failed fetches still record `lastCheckedAt` (keeping any previously known
+ * version) so attempts are throttled to once per interval either way. The
+ * cache file is written *only* here, so a foreground path can never clobber
+ * a fresher result. Releases the spawn claim when done.
+ */
+export declare function refreshUpdateCache(): Promise<void>;
+/**
+ * Print a strong upgrade recommendation to stderr when the cached registry
+ * state says a newer version is published, and kick off a detached refresh
+ * when the cache is stale. Reads only local state — adds no network latency
+ * to the command. Never throws.
+ */
+export declare function maybeNotifyUpdate(): Promise<void>;

package/dist/update-check.js

@@ -0,0 +1,200 @@
+import { spawn } from 'node:child_process';
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Update notice: tell interactive users when a newer version of the CLI is
+ * on npm, and strongly recommend upgrading.
+ *
+ * Zero foreground latency is the design constraint. The command path only
+ * ever *reads* the on-disk cache (~/.config/lattice/update-check.json) and
+ * prints; the registry poll runs in a detached background process spawned
+ * at most once per CHECK_INTERVAL_MS — including after failures, which
+ * record their attempt time so a downed registry doesn't retry on every
+ * command. An exclusive claim file elects a single refresher even across
+ * concurrent CLI invocations. The notice is therefore at most one
+ * invocation stale, which is the standard update-notifier trade-off.
+ *
+ * The notice goes to stderr and only when stderr is a TTY, so scripted /
+ * piped / CI invocations never see it. Opt out entirely with
+ * SEQ_STUDIO_NO_UPDATE_CHECK=1. Everything is best-effort: failures are
+ * silent and never affect the command's exit code.
+ */
+const PACKAGE_NAME = '@sequenceholdings/studio-cli';
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 5000;
+/** A claim older than this belongs to a refresher that died — take it over. */
+const CLAIM_TTL_MS = 10 * 60 * 1000;
+/** The version of this installed package (dist/../package.json). */
+export function currentVersion() {
+    const packageJsonPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+    const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    const version = typeof parsed === 'object' && parsed !== null ? Reflect.get(parsed, 'version') : null;
+    return typeof version === 'string' ? version : '0.0.0';
+}
+export function updateCheckCachePath() {
+    return join(homedir(), '.config', 'lattice', 'update-check.json');
+}
+/** Exclusive-create marker that makes "who spawns the refresh?" atomic. */
+export function updateCheckClaimPath() {
+    return updateCheckCachePath() + '.claim';
+}
+/**
+ * True when `candidate` is a strictly newer semver than `current`.
+ * Prerelease suffixes are ignored — the published channel is plain
+ * major.minor.patch and this only drives a notice, not resolution.
+ */
+export function isNewerVersion(candidate, current) {
+    const parse = (v) => v
+        .replace(/^v/, '')
+        .split('-')[0]
+        .split('.')
+        .map((part) => Number.parseInt(part, 10) || 0);
+    const [a, b] = [parse(candidate), parse(current)];
+    for (let i = 0; i < 3; i++) {
+        const diff = (a[i] ?? 0) - (b[i] ?? 0);
+        if (diff !== 0)
+            return diff > 0;
+    }
+    return false;
+}
+async function readCache() {
+    try {
+        const parsed = JSON.parse(await readFile(updateCheckCachePath(), 'utf8'));
+        if (typeof parsed !== 'object' || parsed === null)
+            return null;
+        const candidate = parsed;
+        if (typeof candidate.lastCheckedAt !== 'number')
+            return null;
+        if (typeof candidate.latestVersion !== 'string' && candidate.latestVersion !== null) {
+            return null;
+        }
+        return { lastCheckedAt: candidate.lastCheckedAt, latestVersion: candidate.latestVersion };
+    }
+    catch {
+        return null;
+    }
+}
+async function writeCache(cache) {
+    const path = updateCheckCachePath();
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(cache, null, 2) + '\n', 'utf8');
+}
+async function fetchLatestVersion() {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const response = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, { signal: controller.signal });
+        if (!response.ok)
+            return null;
+        const body = (await response.json());
+        return typeof body.version === 'string' ? body.version : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Poll the registry and persist the result. Runs in the detached background
+ * process (see update-check-refresh.ts) — never on a command's exit path.
+ * Failed fetches still record `lastCheckedAt` (keeping any previously known
+ * version) so attempts are throttled to once per interval either way. The
+ * cache file is written *only* here, so a foreground path can never clobber
+ * a fresher result. Releases the spawn claim when done.
+ */
+export async function refreshUpdateCache() {
+    try {
+        const previous = await readCache();
+        const fetched = await fetchLatestVersion();
+        await writeCache({
+            lastCheckedAt: Date.now(),
+            latestVersion: fetched ?? previous?.latestVersion ?? null,
+        });
+    }
+    finally {
+        await rm(updateCheckClaimPath(), { force: true }).catch(() => { });
+    }
+}
+/**
+ * Atomically claim the right to spawn a refresh. The `wx` flag makes the
+ * create exclusive at the filesystem level, so concurrent CLI processes
+ * racing past a stale cache elect exactly one refresher. A claim whose
+ * mtime exceeds CLAIM_TTL_MS is from a refresher that died before releasing
+ * it — take it over so refreshes can't wedge forever.
+ */
+async function tryClaimRefresh() {
+    const path = updateCheckClaimPath();
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, String(process.pid), { flag: 'wx' });
+        return true;
+    }
+    catch {
+        try {
+            const { mtimeMs } = await stat(path);
+            if (Date.now() - mtimeMs < CLAIM_TTL_MS)
+                return false;
+            await rm(path, { force: true });
+            await writeFile(path, String(process.pid), { flag: 'wx' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/** CI conventionally sets CI=true; some environments set CI=false to mean "not CI". */
+function isCiEnvironment() {
+    const value = process.env['CI']?.trim().toLowerCase();
+    return value !== undefined && value !== '' && value !== 'false' && value !== '0';
+}
+function spawnBackgroundRefresh() {
+    const script = join(dirname(fileURLToPath(import.meta.url)), 'update-check-refresh.js');
+    const child = spawn(process.execPath, [script], { detached: true, stdio: 'ignore' });
+    // Spawn failures surface as an async 'error' event; without a listener that
+    // becomes an unhandled event that could crash the CLI after its command
+    // already succeeded. The refresh is best-effort — swallow it.
+    child.on('error', () => { });
+    child.unref();
+}
+/**
+ * Print a strong upgrade recommendation to stderr when the cached registry
+ * state says a newer version is published, and kick off a detached refresh
+ * when the cache is stale. Reads only local state — adds no network latency
+ * to the command. Never throws.
+ */
+export async function maybeNotifyUpdate() {
+    try {
+        if (process.env['SEQ_STUDIO_NO_UPDATE_CHECK']?.trim())
+            return;
+        if (isCiEnvironment())
+            return;
+        if (!process.stderr.isTTY)
+            return;
+        const cache = await readCache();
+        if (!cache || Date.now() - cache.lastCheckedAt > CHECK_INTERVAL_MS) {
+            // Exactly one process refreshes: the exclusive claim file elects a
+            // single refresher even across concurrent CLI invocations, and the
+            // foreground never writes the cache itself (so it can't clobber a
+            // fresher background result).
+            if (await tryClaimRefresh())
+                spawnBackgroundRefresh();
+        }
+        const latest = cache?.latestVersion;
+        const current = currentVersion();
+        if (!latest || !isNewerVersion(latest, current))
+            return;
+        process.stderr.write('\n' +
+            `seq-studio ${current} is out of date — ${latest} is available.\n` +
+            'We highly recommend updating: fixes and environment changes land there first.\n' +
+            `  pnpm add -g ${PACKAGE_NAME}@latest   (or: npm install -g ${PACKAGE_NAME}@latest)\n`);
+    }
+    catch {
+        // Best-effort by design — an update notice must never break a command.
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sequenceholdings/studio-cli",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Unified Sequence Studio CLI — `seq-studio process` (Lattice), `seq-studio artifact` (Artifact Studio), `seq-studio functions` / `secrets`, `seq-studio repos` (platform git-service), and `seq-studio auth pat` (git-service PATs). Includes Auth0 browser login shared with seqapi.",
   "license": "UNLICENSED",
   "repository": {
@@ -40,8 +40,8 @@
     "smol-toml": "^1.4.2",
     "tsx": "^4.20.3",
     "zod": "^4.1.13",
-    "@sequenceholdings/artifact-studio": "0.1.11",
-    "@sequenceholdings/lattice": "0.1.1"
+    "@sequenceholdings/artifact-studio": "0.1.12",
+    "@sequenceholdings/lattice": "0.1.2"
   },
   "peerDependencies": {
     "@sequenceholdings/orm": "0.1.1"