@mesh-tech/mesh-cli 0.1.0 → 0.12.0

package/dist/src/utils/workflow-fingerprint.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Workspace packages whose src the agent/interpreter worker bundles as workflows.
+ * MUST stay a subset of the CI replay-gate path filter (`checks.yaml` →
+ * `replay-changes`); a drift-guard test asserts it (MESH-2093).
+ */
+export declare const WORKFLOW_PACKAGE_DIRS: string[];
+/**
+ * Walk up from `startDir` to the monorepo root (the dir with pnpm-workspace.yaml).
+ * Falls back to `startDir` if none is found.
+ */
+export declare function findRepoRoot(startDir: string): string;
+/**
+ * The set of directories whose `.ts` the worker turns into Temporal workflows.
+ *
+ * Prefers the shared workflow **packages** (agent-sdk / interpreter / contracts)
+ * when they exist — the precise, low-noise signal for the monorepo agent/interpreter
+ * dev loop. When they're absent (a **tenant repo**), falls back to the app's own
+ * worker source (`extraDirs`) so the guard isn't silently inert there (MESH-2093).
+ * Only existing dirs are returned.
+ */
+export declare function workflowSourceDirs(repoRoot: string, extraDirs?: string[]): string[];
+/**
+ * Resolve the worker service(s)' source dirs from a dev-output `services` map, so a
+ * tenant repo (no shared workflow packages) still fingerprints the code its worker
+ * actually runs. A service is a worker when its name matches `/worker/i` (best
+ * effort until dev-output carries a `type: "temporal-worker"` marker — MESH-2093).
+ */
+export declare function resolveWorkerSourceDirs(repoRoot: string, services?: Record<string, {
+    src?: string;
+}>): string[];
+/**
+ * Content fingerprint of every non-test `.ts`/`.tsx` under `dirs`. Stable across
+ * runs for identical content; changes iff a workflow source file's content
+ * changes. Returns a short hex digest ('' if no files).
+ *
+ * Each file is labelled by its path relative to `relativeTo` (when given) so the
+ * hash is stable across checkout location/renames; falls back to the absolute path
+ * otherwise.
+ */
+export declare function computeWorkflowFingerprint(dirs: string[], relativeTo?: string): string;
+/**
+ * Convenience: fingerprint an app's workflow source. Pass the dev-output `services`
+ * map so a tenant repo falls back to its worker source when the shared workflow
+ * packages aren't present.
+ */
+export declare function fingerprintWorkflowSource(appRoot: string, services?: Record<string, {
+    src?: string;
+}>): string;
+//# sourceMappingURL=workflow-fingerprint.d.ts.map

package/dist/src/utils/workflow-fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-fingerprint.d.ts","sourceRoot":"","sources":["../../../src/utils/workflow-fingerprint.ts"],"names":[],"mappings":"AA0BA;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,UAIjC,CAAC;AAIF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQrD;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,GAAE,MAAM,EAAO,GAAG,MAAM,EAAE,CAIvF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAAM,GAC9C,MAAM,EAAE,CAQV;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CA6BtF;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAAM,GAC9C,MAAM,CAIR"}

package/dist/src/utils/workflow-fingerprint.js

@@ -0,0 +1,135 @@
+/**
+ * Workflow-source fingerprint for relaunch safety (MESH-2017).
+ *
+ * A `mesh dev` relaunch (or `restart <worker>`) restarts the Temporal worker onto
+ * whatever code is current. If the WORKFLOW code changed since the session
+ * started, in-flight conversations replay against the new code and — if the change
+ * is replay-incompatible — get stranded (observed: conversation 523a4103). The
+ * replay-safety gate (MESH-2091) catches this at CI; this catches it at the *local*
+ * dev loop, where uncommitted edits haven't been through CI.
+ *
+ * We fingerprint the source the agent/interpreter worker bundles into Temporal
+ * workflows: the workflow packages agent-sdk, workflow-interpreter, agent-contracts
+ * (the same set the CI replay-gate path filter covers). A content hash (not mtime)
+ * so a `git checkout`/rebase that rewrites mtimes without changing content doesn't
+ * produce a false "code changed" warning; paths are hashed repo-root-relative so
+ * moving/renaming the checkout doesn't either.
+ *
+ * NOTE (MESH-2017 follow-up): this covers the shared workflow packages, not a
+ * tenant repo's own worker source — `workflowSourceDirs` accepts extra dirs for
+ * that, but no caller wires them yet, so in a repo without those packages the
+ * fingerprint is empty and the guard is inert. Tracked separately.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, isAbsolute, join, relative } from "node:path";
+/**
+ * Workspace packages whose src the agent/interpreter worker bundles as workflows.
+ * MUST stay a subset of the CI replay-gate path filter (`checks.yaml` →
+ * `replay-changes`); a drift-guard test asserts it (MESH-2093).
+ */
+export const WORKFLOW_PACKAGE_DIRS = [
+    "packages/agent-sdk/src",
+    "packages/workflow-interpreter/src",
+    "packages/agent-contracts/src",
+];
+const EXCLUDE = /(^|\/)(node_modules|dist|__tests__)(\/|$)|\.(test|spec)\.[cm]?tsx?$/;
+/**
+ * Walk up from `startDir` to the monorepo root (the dir with pnpm-workspace.yaml).
+ * Falls back to `startDir` if none is found.
+ */
+export function findRepoRoot(startDir) {
+    let dir = startDir;
+    for (;;) {
+        if (existsSync(join(dir, "pnpm-workspace.yaml")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return startDir;
+        dir = parent;
+    }
+}
+/**
+ * The set of directories whose `.ts` the worker turns into Temporal workflows.
+ *
+ * Prefers the shared workflow **packages** (agent-sdk / interpreter / contracts)
+ * when they exist — the precise, low-noise signal for the monorepo agent/interpreter
+ * dev loop. When they're absent (a **tenant repo**), falls back to the app's own
+ * worker source (`extraDirs`) so the guard isn't silently inert there (MESH-2093).
+ * Only existing dirs are returned.
+ */
+export function workflowSourceDirs(repoRoot, extraDirs = []) {
+    const pkgDirs = WORKFLOW_PACKAGE_DIRS.map((d) => join(repoRoot, d)).filter((d) => existsSync(d));
+    if (pkgDirs.length > 0)
+        return pkgDirs;
+    return extraDirs.filter((d) => existsSync(d));
+}
+/**
+ * Resolve the worker service(s)' source dirs from a dev-output `services` map, so a
+ * tenant repo (no shared workflow packages) still fingerprints the code its worker
+ * actually runs. A service is a worker when its name matches `/worker/i` (best
+ * effort until dev-output carries a `type: "temporal-worker"` marker — MESH-2093).
+ */
+export function resolveWorkerSourceDirs(repoRoot, services = {}) {
+    const dirs = [];
+    for (const [name, svc] of Object.entries(services)) {
+        if (/worker/i.test(name) && svc?.src) {
+            dirs.push(isAbsolute(svc.src) ? svc.src : join(repoRoot, svc.src));
+        }
+    }
+    return dirs;
+}
+/**
+ * Content fingerprint of every non-test `.ts`/`.tsx` under `dirs`. Stable across
+ * runs for identical content; changes iff a workflow source file's content
+ * changes. Returns a short hex digest ('' if no files).
+ *
+ * Each file is labelled by its path relative to `relativeTo` (when given) so the
+ * hash is stable across checkout location/renames; falls back to the absolute path
+ * otherwise.
+ */
+export function computeWorkflowFingerprint(dirs, relativeTo) {
+    const files = [];
+    for (const dir of dirs) {
+        let rels;
+        try {
+            rels = readdirSync(dir, { recursive: true });
+        }
+        catch {
+            continue; // dir removed mid-scan
+        }
+        for (const rel of rels) {
+            const p = String(rel);
+            if (/\.(ts|tsx)$/.test(p) && !EXCLUDE.test(p))
+                files.push(join(dir, p));
+        }
+    }
+    files.sort();
+    if (files.length === 0)
+        return "";
+    const h = createHash("sha256");
+    for (const f of files) {
+        try {
+            const content = readFileSync(f);
+            h.update(relativeTo ? relative(relativeTo, f) : f);
+            h.update("\0");
+            h.update(content);
+            h.update("\0");
+        }
+        catch {
+            /* unreadable/removed mid-scan — skip */
+        }
+    }
+    return h.digest("hex").slice(0, 16);
+}
+/**
+ * Convenience: fingerprint an app's workflow source. Pass the dev-output `services`
+ * map so a tenant repo falls back to its worker source when the shared workflow
+ * packages aren't present.
+ */
+export function fingerprintWorkflowSource(appRoot, services = {}) {
+    const repoRoot = findRepoRoot(appRoot);
+    const workerDirs = resolveWorkerSourceDirs(repoRoot, services);
+    return computeWorkflowFingerprint(workflowSourceDirs(repoRoot, workerDirs), repoRoot);
+}
+//# sourceMappingURL=workflow-fingerprint.js.map

package/dist/src/utils/workflow-fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-fingerprint.js","sourceRoot":"","sources":["../../../src/utils/workflow-fingerprint.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/worktree-identity.d.ts

@@ -0,0 +1,86 @@
+/** Number of distinct port blocks (block 0 reserved for the primary checkout). */
+export declare const NUM_PORT_BLOCKS = 64;
+/** First port of block 1; block 0 uses the app's preferred ports, not this range. */
+export declare const PORT_BLOCK_BASE = 40000;
+/** Ports reserved per worktree block (split into service + tunnel sub-ranges). */
+export declare const PORT_BLOCK_SIZE = 40;
+/** Service ports occupy `[base, base+SERVICE_SUBRANGE)`; tunnels take the rest. */
+export declare const PORT_BLOCK_SERVICE_SUBRANGE = 24;
+export interface WorktreeIdentity {
+    /** Absolute path to this worktree's root (git top-level). */
+    worktreeRoot: string;
+    /** True for the repo's primary checkout; false for a linked `git worktree`. */
+    isPrimary: boolean;
+    /** Human-readable sanitized basename of the worktree root (e.g. "design-registry"). */
+    slug: string;
+    /** 4 hex chars of sha256(worktreeRoot) — disambiguates same-named worktrees. */
+    hash: string;
+    /** "" for the primary checkout; else `${slug}-${hash}`. */
+    token: string;
+    /** 0 for primary (preferred ports); 1..NUM_PORT_BLOCKS-1 for linked worktrees. */
+    portBlock: number;
+    /** "" for primary; else `-${token}` — appended to Temporal/Nexus task queues (Tier 2). */
+    taskQueueSuffix: string;
+}
+/** Lowercase, hyphenate, strip non-alphanumerics; never empty. */
+export declare function sanitizeSlug(name: string): string;
+/** Stable 4-hex-char fingerprint of a worktree's absolute path. */
+export declare function worktreeHash(worktreeRoot: string): string;
+/**
+ * Map a worktree hash to a port block. Primary → 0 (preferred ports).
+ * Linked → deterministic 1..NUM_PORT_BLOCKS-1 (stable across runs for the same
+ * worktree path, so ports don't drift between launches).
+ */
+export declare function portBlockFor(hash: string, isPrimary: boolean): number;
+/** First port of a block (block 0 has no dedicated range — callers use preferred ports). */
+export declare function blockBasePort(block: number): number;
+/**
+ * Identity whose PORT BLOCK is derived from (worktree, app) — every non-port
+ * field stays worktree-scoped. A repo can hold several apps whose `mesh dev`
+ * sessions run CONCURRENTLY (e.g. scu-mesh-apps' plaid-token-manager +
+ * plaid-reporting); with a per-worktree block they draw the same ports, and
+ * the availability probe alone races services that are still booting and
+ * haven't bound yet — both sessions allocated 41800 in the wild. Same
+ * philosophy as the per-worktree blocks of MESH-2013.
+ *
+ * NOT disjoint by construction: `portBlockFor` buckets a hash into
+ * NUM_PORT_BLOCKS-1 slots, so two (worktree, app) pairs CAN land on the same
+ * block — and app-scoping raises the entity count from #worktrees to
+ * #worktrees x #apps, which makes that likelier. Sibling apps in one worktree
+ * (the case this fixes) are disjoint by default; the in-block probe and the
+ * ephemeral fallback in `allocatePorts` remain the backstop for a collision.
+ *
+ * Primary checkouts keep preferred-port semantics (block 0) — sibling apps
+ * there still share preferred ports and rely on that probe.
+ */
+export declare function withAppScopedPortBlock(wt: WorktreeIdentity, appRoot: string): WorktreeIdentity;
+/**
+ * Stack name for `mesh stack init --worktree` (MESH-2013 Slice 3): append the
+ * worktree token so concurrent worktrees deploy to distinct stacks. The SSM
+ * export paths (`apps/{app}/stacks/{stack}/...`), Temporal namespace
+ * (`{tenant}-{stack}-{app}`), and Nexus endpoint name all derive from the stack
+ * name, so one discriminator isolates all three. The primary checkout has an
+ * empty token → the base name is returned unchanged (it IS the canonical stack).
+ */
+/** Max chars of the worktree slug that reach a stack name. Deploy-time surfaces
+ * (Temporal namespace `{tenant}-{stack}-{app}`, Nexus endpoint names) have
+ * provider length limits, so we cap the human-readable slug here; the 4-hex hash
+ * still guarantees uniqueness. (The local-only token — tmux/ports — is uncapped.) */
+export declare const STACK_SLUG_MAX = 16;
+export declare function worktreeStackName(baseName: string, wt: WorktreeIdentity): string;
+/**
+ * True when `stackName` would collide across worktrees: we're in a LINKED
+ * worktree (non-empty token) but the stack name doesn't carry that token — so a
+ * concurrent `pulumi up` from another worktree on the same name hits identical
+ * SSM export paths / Temporal namespace. Drives the `mesh deploy` warning.
+ */
+export declare function stackNeedsWorktreeIsolation(stackName: string, wt: WorktreeIdentity): boolean;
+type GitRunner = (args: string[], cwd: string) => string;
+/**
+ * Resolve the worktree identity for a given cwd. Returns a primary-checkout
+ * identity (token "", block 0) when not inside a git repo, so non-repo/edge
+ * cases degrade to today's behavior rather than throwing.
+ */
+export declare function resolveWorktreeIdentity(cwd?: string, gitRunner?: GitRunner): WorktreeIdentity;
+export {};
+//# sourceMappingURL=worktree-identity.d.ts.map

package/dist/src/utils/worktree-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-identity.d.ts","sourceRoot":"","sources":["../../../src/utils/worktree-identity.ts"],"names":[],"mappings":"AA+BA,kFAAkF;AAClF,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,qFAAqF;AACrF,eAAO,MAAM,eAAe,QAAQ,CAAC;AACrC,kFAAkF;AAClF,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,mFAAmF;AACnF,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,SAAS,EAAE,OAAO,CAAC;IACnB,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,kEAAkE;AAClE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,CAIrE;AAED,4FAA4F;AAC5F,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAI9F;AAED;;;;;;;GAOG;AACH;;;qFAGqF;AACrF,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,gBAAgB,GAAG,MAAM,CAIhF;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,gBAAgB,GAAG,OAAO,CAK5F;AAED,KAAK,SAAS,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;AAKzD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,GAAE,MAAsB,EAC3B,SAAS,GAAE,SAA4B,GACtC,gBAAgB,CAmClB"}

package/dist/src/utils/worktree-identity.js

@@ -0,0 +1,164 @@
+/**
+ * Per-worktree identity for collision-free concurrent `mesh dev` (MESH-2013).
+ *
+ * Running `mesh dev` in several git worktrees at once collides on ports, tmux
+ * session names, tmpdir session state, and env-file dirs — because every one of
+ * those derives from the app's Pulumi project name, which is identical across
+ * worktrees. This module derives ONE deterministic token per worktree (from its
+ * path) that the dev launcher threads through all of those so worktrees can't
+ * step on each other.
+ *
+ * TASK QUEUES are unique by construction — `taskQueueSuffix` is `-${token}` and
+ * the token carries the 4-hex path hash. SESSION NAMES are not: the tmux name is
+ * `${projectName}-${slug}` (slug only), and the state file + env dir derive from
+ * it, so two linked worktrees whose basenames sanitize to the same slug (e.g.
+ * `.worktrees/MESH-2375` and `~/scratch/mesh-2375`) share all three. PORTS are
+ * not either: the block is a hash bucketed into NUM_PORT_BLOCKS-1 slots and is
+ * additionally scoped by app — see `withAppScopedPortBlock` below for what that
+ * does and does not guarantee.
+ *
+ * The PRIMARY checkout (the repo's main working tree) keeps its historical
+ * behavior — empty token, port block 0 (preferred ports), no session suffix —
+ * so existing muscle memory is preserved. Only LINKED worktrees get offsets.
+ *
+ * Pure helpers (`sanitizeSlug`, `worktreeHash`, `portBlockFor`, `blockBasePort`)
+ * are git-free and unit-tested; `resolveWorktreeIdentity` shells to git via an
+ * injectable runner so it can be tested without a real repo.
+ */
+import { execFileSync } from "node:child_process";
+import * as crypto from "node:crypto";
+import * as path from "node:path";
+/** Number of distinct port blocks (block 0 reserved for the primary checkout). */
+export const NUM_PORT_BLOCKS = 64;
+/** First port of block 1; block 0 uses the app's preferred ports, not this range. */
+export const PORT_BLOCK_BASE = 40000;
+/** Ports reserved per worktree block (split into service + tunnel sub-ranges). */
+export const PORT_BLOCK_SIZE = 40;
+/** Service ports occupy `[base, base+SERVICE_SUBRANGE)`; tunnels take the rest. */
+export const PORT_BLOCK_SERVICE_SUBRANGE = 24;
+/** Lowercase, hyphenate, strip non-alphanumerics; never empty. */
+export function sanitizeSlug(name) {
+    const s = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return s || "wt";
+}
+/** Stable 4-hex-char fingerprint of a worktree's absolute path. */
+export function worktreeHash(worktreeRoot) {
+    return crypto.createHash("sha256").update(worktreeRoot).digest("hex").slice(0, 4);
+}
+/**
+ * Map a worktree hash to a port block. Primary → 0 (preferred ports).
+ * Linked → deterministic 1..NUM_PORT_BLOCKS-1 (stable across runs for the same
+ * worktree path, so ports don't drift between launches).
+ */
+export function portBlockFor(hash, isPrimary) {
+    if (isPrimary)
+        return 0;
+    const n = parseInt(hash, 16);
+    return 1 + (n % (NUM_PORT_BLOCKS - 1));
+}
+/** First port of a block (block 0 has no dedicated range — callers use preferred ports). */
+export function blockBasePort(block) {
+    return PORT_BLOCK_BASE + block * PORT_BLOCK_SIZE;
+}
+/**
+ * Identity whose PORT BLOCK is derived from (worktree, app) — every non-port
+ * field stays worktree-scoped. A repo can hold several apps whose `mesh dev`
+ * sessions run CONCURRENTLY (e.g. scu-mesh-apps' plaid-token-manager +
+ * plaid-reporting); with a per-worktree block they draw the same ports, and
+ * the availability probe alone races services that are still booting and
+ * haven't bound yet — both sessions allocated 41800 in the wild. Same
+ * philosophy as the per-worktree blocks of MESH-2013.
+ *
+ * NOT disjoint by construction: `portBlockFor` buckets a hash into
+ * NUM_PORT_BLOCKS-1 slots, so two (worktree, app) pairs CAN land on the same
+ * block — and app-scoping raises the entity count from #worktrees to
+ * #worktrees x #apps, which makes that likelier. Sibling apps in one worktree
+ * (the case this fixes) are disjoint by default; the in-block probe and the
+ * ephemeral fallback in `allocatePorts` remain the backstop for a collision.
+ *
+ * Primary checkouts keep preferred-port semantics (block 0) — sibling apps
+ * there still share preferred ports and rely on that probe.
+ */
+export function withAppScopedPortBlock(wt, appRoot) {
+    if (wt.isPrimary)
+        return wt;
+    const appHash = worktreeHash(`${wt.worktreeRoot}#${path.resolve(appRoot)}`);
+    return { ...wt, portBlock: portBlockFor(appHash, false) };
+}
+/**
+ * Stack name for `mesh stack init --worktree` (MESH-2013 Slice 3): append the
+ * worktree token so concurrent worktrees deploy to distinct stacks. The SSM
+ * export paths (`apps/{app}/stacks/{stack}/...`), Temporal namespace
+ * (`{tenant}-{stack}-{app}`), and Nexus endpoint name all derive from the stack
+ * name, so one discriminator isolates all three. The primary checkout has an
+ * empty token → the base name is returned unchanged (it IS the canonical stack).
+ */
+/** Max chars of the worktree slug that reach a stack name. Deploy-time surfaces
+ * (Temporal namespace `{tenant}-{stack}-{app}`, Nexus endpoint names) have
+ * provider length limits, so we cap the human-readable slug here; the 4-hex hash
+ * still guarantees uniqueness. (The local-only token — tmux/ports — is uncapped.) */
+export const STACK_SLUG_MAX = 16;
+export function worktreeStackName(baseName, wt) {
+    if (!wt.token)
+        return baseName;
+    const cappedSlug = wt.slug.slice(0, STACK_SLUG_MAX).replace(/-+$/, "");
+    return `${baseName}-${cappedSlug}-${wt.hash}`;
+}
+/**
+ * True when `stackName` would collide across worktrees: we're in a LINKED
+ * worktree (non-empty token) but the stack name doesn't carry that token — so a
+ * concurrent `pulumi up` from another worktree on the same name hits identical
+ * SSM export paths / Temporal namespace. Drives the `mesh deploy` warning.
+ */
+export function stackNeedsWorktreeIsolation(stackName, wt) {
+    // The 4-hex hash is the stable discriminator present in every worktree stack
+    // name (`worktreeStackName` ends with `-${hash}`), and survives the slug cap —
+    // so match on it rather than the full (uncapped) token.
+    return !!wt.token && !stackName.endsWith(`-${wt.hash}`);
+}
+const defaultGitRunner = (args, cwd) => execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+/**
+ * Resolve the worktree identity for a given cwd. Returns a primary-checkout
+ * identity (token "", block 0) when not inside a git repo, so non-repo/edge
+ * cases degrade to today's behavior rather than throwing.
+ */
+export function resolveWorktreeIdentity(cwd = process.cwd(), gitRunner = defaultGitRunner) {
+    let worktreeRoot;
+    let isPrimary = true;
+    try {
+        worktreeRoot = path.resolve(gitRunner(["rev-parse", "--show-toplevel"], cwd));
+        // The common git dir is `<primary-worktree>/.git`; its parent is the primary
+        // checkout. A linked worktree's top-level differs from that parent.
+        const commonDir = gitRunner(["rev-parse", "--git-common-dir"], cwd);
+        const primaryRoot = path.resolve(path.dirname(path.resolve(cwd, commonDir)));
+        isPrimary = worktreeRoot === primaryRoot;
+    }
+    catch {
+        // Not a git repo (or git unavailable) — behave as the primary checkout.
+        return {
+            worktreeRoot: path.resolve(cwd),
+            isPrimary: true,
+            slug: sanitizeSlug(path.basename(path.resolve(cwd))),
+            hash: worktreeHash(path.resolve(cwd)),
+            token: "",
+            portBlock: 0,
+            taskQueueSuffix: "",
+        };
+    }
+    const slug = sanitizeSlug(path.basename(worktreeRoot));
+    const hash = worktreeHash(worktreeRoot);
+    const token = isPrimary ? "" : `${slug}-${hash}`;
+    return {
+        worktreeRoot,
+        isPrimary,
+        slug,
+        hash,
+        token,
+        portBlock: portBlockFor(hash, isPrimary),
+        taskQueueSuffix: token ? `-${token}` : "",
+    };
+}
+//# sourceMappingURL=worktree-identity.js.map

package/dist/src/utils/worktree-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-identity.js","sourceRoot":"","sources":["../../../src/utils/worktree-identity.ts"],"names":[],"mappings":"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"}

package/fragments/agents/AGENTS.md.hbs

@@ -0,0 +1,92 @@
+# Agent Instructions — {{titleCase name}}
+
+## This App
+
+Read these files to understand the infrastructure and configuration:
+- `index.ts` — Pulumi app definition (primitives, services, linking)
+- `Pulumi.*.yaml` — Stack config (tenant, platform, deploy mode)
+
+## Pattern
+
+Every mesh app follows 5 steps in `index.ts`:
+1. `mesh.apps.getConfig(pulumi)` — read stack config
+2. `new mesh.apps.AppEnvironment(...)` — namespace, IAM, providers
+3. Add primitives (Database, Bucket, TemporalWorker, etc.)
+4. Create services with `link()` — wires env vars, tunnels, secrets
+5. `env.register()` — finalize SSM metadata + dev outputs
+
+{{#if temporal}}
+## Temporal Workers & Clients
+
+**Always use `@mesh-tech/app-kit` factories** — never raw `@temporalio/*` setup.
+
+### Worker (`worker/src/worker.ts`)
+
+```typescript
+import { createTemporalWorker, resolveWorkflows } from "@mesh-tech/app-kit/temporal";
+import * as activities from "./activities.js";
+
+const { worker, cleanup } = await createTemporalWorker({
+  activities,
+  ...await resolveWorkflows(import.meta.url),
+});
+```
+
+`createTemporalWorker()` handles authenticated connections (M2M tokens),
+encryption codec, and OpenTelemetry — no manual setup needed.
+
+### Client (`api/src/index.ts`)
+
+```typescript
+import { createTemporalClient } from "@mesh-tech/app-kit/temporal-client";
+
+const { withClient } = await createTemporalClient();
+
+// Use withClient() for each operation — it handles auth token injection
+const result = await withClient(async (client) => {
+  const handle = await client.workflow.start("myWorkflow", { ... });
+  return handle.result();
+});
+```
+
+**Important:** Always use `withClient()` callback — don't hold a raw `Client` reference.
+The callback injects fresh auth metadata per call.
+{{/if}}
+
+{{#if database}}
+## Database
+
+Uses Prisma with the `pg` adapter. Connection via `DATABASE_URL` from `link()`.
+
+```typescript
+import { getDb } from "./db.js";
+const db = getDb();
+```
+
+Run migrations: `pnpm mesh db exec -- npx prisma migrate dev`
+{{/if}}
+
+{{#if bucket}}
+## S3 Bucket
+
+The `uploads` bucket is linked to the API service. See `api/src/storage.ts`
+for helper functions using the injected `UPLOADS_BUCKET` and `UPLOADS_REGION` env vars.
+{{/if}}
+
+## Documentation
+
+- `npx intent load @mesh-tech/app-kit#core` — the authoritative app-authoring API
+  (getConfig → AppEnvironment → primitives → link → register; arg tables + `link()` semantics)
+- The **mesh-apps** skill (`.claude/skills/mesh-apps/`) — the scaffold → wire → run → debug recipe
+- `libs/infra-components/docs/primitives/` — per-component reference (in-repo)
+
+## CLI
+
+```bash
+pnpm mesh dev              # Local development (tunnels + services in tmux)
+pnpm mesh deploy up        # Deploy to cluster
+{{#if database}}
+pnpm mesh db psql          # Interactive database session
+{{/if}}
+pnpm mesh tunnel dev       # Open tunnels without starting services
+```

package/fragments/agents/CLAUDE.md.hbs

@@ -0,0 +1,8 @@
+# CLAUDE.md — {{titleCase name}}
+
+<!-- Bridge this app's AGENTS.md into Claude's context. TanStack Intent (`intent
+     install`) writes its skill-loading guidance to AGENTS.md, but Claude Code loads
+     CLAUDE.md, not AGENTS.md — without this import the guidance never reaches Claude,
+     and intent-skill activation drops to ~0% (agents guess a non-existent bare
+     `intent` command and give up). Keep this import. See MESH-2156 / MESH-2159. -->
+@AGENTS.md

package/fragments/base/Pulumi.dev.yaml.hbs

@@ -0,0 +1,10 @@
+secretsprovider: awskms:///alias/{{tenant}}-dev-pulumi-secrets?region={{region}}
+config:
+  aws:region: {{region}}
+  mesh:tenant: {{tenant}}
+  mesh:platform:
+    name: mesh
+    env: dev
+  mesh:deploy: 'false'
+  # Deployer role for this tenant/hub — assumed via your `mesh login` session.
+  mesh:deployerRole: {{deployerRoleArn}}

package/fragments/base/Pulumi.yaml.hbs

@@ -0,0 +1,9 @@
+name: {{tenant}}-apps-{{name}}
+description: {{titleCase name}} — mesh tenant app
+backend:
+  url: s3://mesh-tenant-{{tenant}}-pulumi-state?region=us-east-2
+runtime:
+  name: nodejs
+  options:
+    packagemanager: pnpm
+    nodeargs: "--import tsx"