@cowliss/cli 0.10.0 → 0.12.0

package/dist/index.js

@@ -173,6 +173,8 @@ const SYSTEM_EVENT_PREFIX = "system.";
 * system.profile_deleted is the provider-recorded fact that a provider
 * (e.g. Clerk `user.deleted`) deleted the user upstream — a marker event
 * only, with no deletion semantics (hard-delete belongs to GDPR erasure);
+* system.signed_up and system.logged_in are the same shape for the other end
+* of that lifecycle (Clerk `user.created` and `session.created`);
 * system.email_clicked is a link click reported by SES feedback.
 *
 * Rows carrying one of these names get `system: true` so the usage meter
@@ -187,6 +189,17 @@ const SYSTEM_EVENTS = {
 	consentRevoked: "system.consent_revoked",
 	profileDeleted: "system.profile_deleted",
 	/**
+	* The provider's account lifecycle, as facts rather than as profile state:
+	* a profile can predate its `user.created` (an SDK identify or a
+	* membership delivery may have created it first), so these name what the
+	* provider reported, not what Cowliss did. `signedUp` is the trigger for a
+	* welcome journey fed by a provider source, which `emailRegistered` only
+	* approximates (it fires on an address change too, and never for a
+	* profile with no address). `loggedIn` is one row per session start.
+	*/
+	signedUp: "system.signed_up",
+	loggedIn: "system.logged_in",
+	/**
 	* A write's identifiers named more than one profile and Cowliss merged
 	* them (ticket 69). Lands on the survivor's timeline carrying
 	* `mergedProfileIds`, the ids folded into it.
@@ -220,6 +233,12 @@ const EXECUTION_LIMITS = {
 const PUSH_LIMITS = {
 	journeys: 100,
 	templates: 200,
+	/**
+	* Segment files (ADR 0023). A segment is a predicate list, not a bundle, so
+	* the ceiling is about how many audiences one program describes rather than
+	* about bytes; a journey's own inline definition costs nothing here.
+	*/
+	segments: 100,
 	bundleBytes: 2097152,
 	sourceBytes: 5242880
 };
@@ -2799,6 +2818,12 @@ var PrimaryKey = class {
 	}
 };
 
+//#endregion
+//#region ../../node_modules/.pnpm/drizzle-orm@0.45.2_postgres@3.4.9/node_modules/drizzle-orm/sql/expressions/conditions.js
+function isNull(value) {
+	return sql`${value} is null`;
+}
+
 //#endregion
 //#region ../../node_modules/.pnpm/drizzle-zod@0.8.3_drizzle-orm@0.45.2_postgres@3.4.9__zod@4.4.3/node_modules/drizzle-zod/index.mjs
 const CONSTANTS = {
@@ -4120,17 +4145,22 @@ const insertQuarantineEntrySchema = createInsertSchema(quarantineEntries);
 * A segment belongs to one app (ADR 0022) and sees only that app's profiles
 * and that app's events.
 *
-* A row is either standalone (built in the dashboard, `journey_key` null) or
-* owned by one journey whose trigger inlined its definition (ADR 0016). An
-* owned row is named after its journey's key, is written only by the push,
-* and goes when the journey does — which is what the composite foreign key
-* says: it points at `journeys(org_id, key)` and cascades. A null
-* `journey_key` satisfies it vacuously (MATCH SIMPLE), so standalone rows
-* are unconstrained.
+* A row comes from one of three places, which `source` and `journey_key`
+* answer together: built in the dashboard (`dashboard`, no journey), pushed
+* from a `segments/` file (`push`, no journey — ADR 0023), or owned by one
+* journey whose trigger inlined its definition (`push` and that journey —
+* ADR 0016). So `source = 'push'` is exactly "the repository writes this
+* one", which is the whole of the dashboard's edit refusal, and
+* `journey_key` says which of the two pushed forms it is. An owned row is
+* named after its journey's key and goes when the journey does — which is
+* what the composite foreign key says: it points at `journeys(org_id, key)`
+* and cascades. A null `journey_key` satisfies it vacuously (MATCH SIMPLE),
+* so the other two forms are unconstrained.
 *
 * Timestamps use millisecond precision, same rationale as apps: JS Dates
 * carry ms only and cursor pagination compares createdAt for equality.
 */
+const segmentSourceEnum = pgEnum("segment_source", ["dashboard", "push"]);
 const segments$1 = pgTable("segments", {
 	id: text("id").primaryKey(),
 	orgId: text("org_id").notNull(),
@@ -4138,8 +4168,12 @@ const segments$1 = pgTable("segments", {
 	appId: text("app_id").notNull(),
 	name: text("name").notNull(),
 	description: text("description"),
+	/** The author's labels on a pushed segment; empty for a dashboard one. */
+	tags: text("tags").array().notNull().default(sql`'{}'::text[]`),
 	definition: jsonb("definition").$type().notNull(),
-	/** The journey that owns this row, or null for a standalone segment. */
+	/** Who writes this row: the dashboard, or a push. */
+	source: segmentSourceEnum("source").notNull().default("dashboard"),
+	/** The journey that owns this row, or null when no journey does. */
 	journeyKey: text("journey_key"),
 	createdAt: createdAt(),
 	updatedAt: updatedAt()
@@ -4320,6 +4354,7 @@ const sources$1 = pgTable("sources", {
 }, (table) => [
 	index("sources_org_id_idx").on(table.orgId),
 	index("sources_app_id_idx").on(table.appId),
+	uniqueIndex("sources_app_kind_live_idx").on(table.orgId, table.appId, table.kind).where(isNull(table.archivedAt)),
 	foreignKey({
 		columns: [table.orgId, table.appId],
 		foreignColumns: [apps$1.orgId, apps$1.id],
@@ -4900,20 +4935,40 @@ const patternSchema = z.union([onePatternSchema, z.array(onePatternSchema).min(1
 * row carries its `app_id`, and the runtime compares that with the event's.
 * An `appId` here would be a second way to say it, and the way to leak.
 *
-* A segment trigger carries the predicate list, not a name: the push
-* materializes one segment row per journey that inlines a definition, owned
-* by the journey and named after its key, so the segment exists because the
-* journey exists and there is no order to get wrong (ADR 0016). The
-* definition is data — validated here, carried on the version, never
-* compiled and never executed.
+* A segment trigger says which audience in two ways (ADR 0016, ADR 0023).
+* Inline, carrying the predicate list itself: the push materializes one
+* segment row per journey that does, owned by the journey and named after
+* its key. Or by name, naming a `segments/<key>.ts` file of the same push:
+* the name resolves inside the tree at build time and the push writes that
+* file's row, so there is still no order to get wrong and no row outside the
+* repository a trigger can point at. Either way the definition is data —
+* validated here, carried on the version, never compiled and never executed.
+*
+* Every member is strict, so a journey holding the retired `source` or
+* `appId` key fails to build instead of silently triggering on every app or
+* on nothing. There is deliberately no pipe filter and no app filter: the
+* journey's own app is the only narrowing there is.
+*/
+const triggerSchema = z.union([
+	z.strictObject({ event: patternSchema }),
+	z.strictObject({ segment: segmentDefinitionSchema }),
+	z.strictObject({ segment: journeyKeySchema })
+]);
+/**
+* The name of the segment a trigger enrolls from, or null when it is an
+* event trigger. An inline definition materializes a row named after the
+* journey (ADR 0016); a named one is the segment file's own key (ADR 0023).
+* Segment names are unique per organization, so this one string is what
+* every reader — the live trigger, the enable-time enrollment job and the
+* journey page — resolves the row by.
 *
-* Both members are strict, so a journey holding the retired `source` or
-* `appId` key, or the retired `{ segment: "name" }` form, fails to build
-* instead of silently triggering on every app or on nothing. There is
-* deliberately no pipe filter and no app filter: the journey's own app is
-* the only narrowing there is.
+* Structural in its trigger parameter so `packages/db`'s mirror of the shape
+* passes without either package importing the other.
 */
-const triggerSchema = z.union([z.strictObject({ event: patternSchema }), z.strictObject({ segment: segmentDefinitionSchema })]);
+function triggerSegmentName(journeyKey, trigger) {
+	if (!("segment" in trigger)) return null;
+	return typeof trigger.segment === "string" ? trigger.segment : journeyKey;
+}
 /**
 * The address half of a from-header: a local part, an `@`, and a dotted
 * domain. Deliberately narrower than RFC 5322 (no quoted local parts, no
@@ -5068,6 +5123,40 @@ const manifestTemplateSchema = z.object({
 	propsSchema: z.record(z.string(), z.unknown()),
 	bundle: digestSchema
 });
+/**
+* One `segments/<key>.ts` file (ADR 0023): an audience several journeys of
+* one repository enroll from, written once instead of pasted into each
+* trigger. It carries no bundle and no digest, because it compiles to
+* nothing: a definition is a predicate list the evaluator folds, so there is
+* no code for an execution to pin and therefore no version of it.
+*
+* Plain rather than strict, for the same reason the other two entries are: a
+* stored manifest has to keep parsing after a field goes away (ADR 0011).
+*/
+const manifestSegmentSchema = z.object({
+	key: journeyKeySchema,
+	/** The author's labels, the way a journey and a template carry them. */
+	tags: tagsSchema,
+	/** The author's own sentence about who is in it; absent when unwritten. */
+	description: z.string().trim().max(500, `description must be at most ${500} characters`).optional(),
+	definition: segmentDefinitionSchema
+});
+/**
+* One event pattern the tree reacts to, read off the tree itself: a trigger,
+* a `waitForEvent`, or an event predicate in a segment. Nobody declares it —
+* a second source of truth would disagree with the code the first time an
+* author edited a trigger — so what a build could not read literally is
+* simply absent, which makes the list incomplete and never wrong.
+*
+* The pattern is stored as written: `order.*` is one entry, not an
+* expansion, because it is what the author asked for and what any reader
+* has to match against. `usedBy` names the journeys and segments that named
+* it, sorted, so a reader can say who is waiting.
+*/
+const manifestEventSchema = z.object({
+	pattern: onePatternSchema,
+	usedBy: z.array(z.string())
+});
 function uniqueKeys(items, ctx, path) {
 	const seen = /* @__PURE__ */ new Set();
 	for (const [index, item] of items.entries()) {
@@ -5103,6 +5192,19 @@ const manifestSchema = z.object({
 	journeys: z.array(manifestJourneySchema).max(PUSH_LIMITS.journeys),
 	templates: z.array(manifestTemplateSchema).max(PUSH_LIMITS.templates),
 	/**
+	* The `segments/` files this project pushes (ADR 0023). Defaulted rather
+	* than required: every manifest stored before segments were files carries
+	* none, and a project with no shared audience still writes the field.
+	*/
+	segments: z.array(manifestSegmentSchema).max(PUSH_LIMITS.segments).default([]),
+	/**
+	* The event patterns this tree reacts to, collected from the journeys
+	* and segments above rather than declared. Defaulted for the same reason
+	* `segments` is: every manifest stored before the collection existed
+	* carries none.
+	*/
+	events: z.array(manifestEventSchema).default([]),
+	/**
 	* The consent purposes this project declares, copied from `cow.json`.
 	* Optional rather than defaulted: a push made before purposes existed
 	* carries none, and its stored manifest still parses.
@@ -5113,7 +5215,22 @@ const manifestSchema = z.object({
 }).superRefine((manifest, ctx) => {
 	uniqueKeys(manifest.journeys, ctx, "journeys");
 	uniqueKeys(manifest.templates, ctx, "templates");
+	uniqueKeys(manifest.segments, ctx, "segments");
 	uniqueKeys(manifest.purposes ?? [], ctx, "purposes");
+	const segmentKeys = new Set(manifest.segments.map((segment) => segment.key));
+	for (const [index, journey] of manifest.journeys.entries()) {
+		const named = "segment" in journey.trigger && typeof journey.trigger.segment === "string" ? journey.trigger.segment : null;
+		if (named !== null && !segmentKeys.has(named)) ctx.addIssue({
+			code: "custom",
+			message: `journey "${journey.key}" enrolls from the segment "${named}", which this push does not carry. Push the segments/${named}.ts file with it, or write the predicate list in the trigger.`,
+			path: [
+				"journeys",
+				index,
+				"trigger",
+				"segment"
+			]
+		});
+	}
 	for (const [index, journey] of manifest.journeys.entries()) if (journey.enrollment && journey.purpose === "transactional") ctx.addIssue({
 		code: "custom",
 		message: `journey "${journey.key}": a transactional journey enrolls on every trigger, so it takes no enrollment cooldown`,
@@ -5387,6 +5504,34 @@ const eventNameStatsDtoSchema = z.object({
 		lastSeenAt: z.iso.datetime().nullable()
 	}))
 });
+/**
+* Has this app ever received these event names
+* (GET /v1/apps/{appId}/events/seen?name=a&name=b)? What `cow build` read
+* off the tree, asked against what the app actually sends.
+*
+* "Ever" rather than a window, deliberately: a window fires on anything
+* seasonal and puts a threshold in copy that would have to be defended. The
+* last-seen stamp travels beside the answer and the developer judges whether
+* eight months ago is a problem.
+*
+* A name may be a pattern, matched the way ingestion matches one (`*` only,
+* against the whole name), so `order.*` is seen once `order.paid` has
+* arrived.
+*
+* Repeated rather than comma-joined, because an event name may hold a comma.
+* One occurrence arrives as a string and several as an array, which is what
+* the union is for.
+*/
+const oneEventName = z.string().min(1).max(200);
+const eventsSeenQuerySchema = z.object({ name: z.union([oneEventName, z.array(oneEventName).max(200, "at most 200 names in one question")]).transform((value) => Array.isArray(value) ? value : [value]) });
+/**
+* One answer per name asked, in the order asked. `lastSeenAt` null is the
+* whole of "never": a name is only ever dated because a row carried it.
+*/
+const eventsSeenDtoSchema = z.object({ names: z.array(z.object({
+	name: z.string(),
+	lastSeenAt: z.iso.datetime().nullable()
+})) });
 
 //#endregion
 //#region ../../packages/shared/src/batch.ts
@@ -5964,9 +6109,18 @@ function matchesPattern(pattern, name) {
 	return (Array.isArray(pattern) ? pattern : [pattern]).some((one) => matchesOne(one, name));
 }
 function matchesOne(pattern, name) {
-	const literals = pattern.split("*");
-	if (name.startsWith("system.") && !(literals[0] ?? "").startsWith("system.")) return false;
-	return matchesLiterals(literals, name);
+	if (name.startsWith("system.") && !isSystemPattern(pattern)) return false;
+	return matchesLiterals(pattern.split("*"), name);
+}
+/**
+* Whether a pattern reaches into the system namespace: its literal prefix,
+* the text before its first `*`, is itself under SYSTEM_EVENT_PREFIX. The
+* system rule above asks it per name; `cow build` asks it per pattern, to
+* leave the events Cowliss writes itself out of the list of events a
+* developer is asked to send.
+*/
+function isSystemPattern(pattern) {
+	return (pattern.split("*")[0] ?? "").startsWith(SYSTEM_EVENT_PREFIX);
 }
 /**
 * Walk the `*`-separated literals left to right: the first anchors the start,
@@ -6409,7 +6563,23 @@ const createPushBodySchema = z.object({ data: z.object({
 	* lands silently whenever both orgs happen to hold an app of the same
 	* slug, which is exactly the shape `apps/platform-workspace` has.
 	*/
-	orgId: orgIdSchema
+	orgId: orgIdSchema,
+	/**
+	* Delete the `segments/` rows this app holds and this manifest does not
+	* carry (`cow push --prune`, ADR 0024). Off by default, which is what a
+	* push has always been: additive.
+	*
+	* Only segments, because only a push may write or unwrite one — the
+	* dashboard refuses to touch a pushed row and tells the reader to change
+	* the file and push again, which is this flag. Journeys and templates are
+	* not here: a journey has its own delete verb, which `cow push --prune`
+	* calls after the push, and a template's lifecycle belongs to the version
+	* prune sweep because a live execution pins the version it started on.
+	*
+	* `pushes.plan` takes the same body and ignores this: a plan writes
+	* nothing, and the drift it already reports is what a prune would act on.
+	*/
+	prune: z.boolean().default(false)
 }) });
 const listPushesQuerySchema = paginationQuerySchema.extend({ 
 /** One app's own pushes; absent lists the org's. */
@@ -6853,6 +7023,142 @@ const notificationPreferencesSchema = z.object({ purposes: z.array(notificationP
 */
 const updateNotificationPreferencesBodySchema = z.object({ data: z.object({ purposes: consentPatchSchema }) });
 
+//#endregion
+//#region ../../packages/shared/src/stable-json.ts
+/**
+* A key-sorted JSON rendering, for comparing or hashing two values a JSON
+* round trip may have reordered. `undefined` members are dropped the way
+* `JSON.stringify` drops them.
+*
+* Its own module with no imports at all, because both users need it and
+* they sit on opposite sides of a boundary: the release digest (which pulls
+* in node:crypto) and the compile workflow (which may not pull in anything).
+*/
+function stableJson(value) {
+	if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+	if (value !== null && typeof value === "object") return `{${Object.entries(value).filter(([, item]) => item !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(",")}}`;
+	return JSON.stringify(value) ?? "null";
+}
+
+//#endregion
+//#region ../../packages/shared/src/plan.ts
+/**
+* What a push would change, computed before anything is stored (ADR 0025).
+*
+* The server is the state: a checkout holds no record of what it last
+* pushed, so the baseline is the account itself — the latest version of
+* every key and the segment rows the repository writes. The comparison
+* below is the only one there is. `pushes.plan` runs it against those rows;
+* `cow status` runs it against the same entries read back through
+* `apps.status`, so the two can never disagree about what "changed" means.
+*/
+const PLAN_KINDS = [
+	"journey",
+	"segment",
+	"template"
+];
+const planKindSchema = z.enum(PLAN_KINDS);
+const planEntrySchema = z.object({
+	kind: planKindSchema,
+	key: z.string(),
+	change: z.enum([
+		"added",
+		"changed",
+		"unchanged"
+	]),
+	/**
+	* Which of the entry's fields differ from the one the account holds,
+	* sorted; empty unless `change` is `changed`. Named rather than counted,
+	* because "winback changed" and "winback's from changed" are answers to
+	* different questions.
+	*/
+	fields: z.array(z.string())
+});
+/**
+* Something the account holds that this push does not write. Reported and
+* never reconciled: the dashboard stays fully editable, and a push that
+* quietly undid what someone did there would be the worse surprise.
+*
+* `not-in-tree` is a key the repository no longer has (deleting it is its
+* own verb); `on-hold` is a journey someone put on hold, which a push
+* carrying new code for it still leaves on hold.
+*/
+const planDriftSchema = z.object({
+	kind: planKindSchema,
+	key: z.string(),
+	reason: z.enum(["not-in-tree", "on-hold"])
+});
+const pushPlanSchema = z.object({
+	appId: appIdSchema,
+	/** One per key the tree carries, in reading order: journeys, segments, templates. */
+	entries: z.array(planEntrySchema),
+	drift: z.array(planDriftSchema)
+});
+/**
+* `spine` never takes part: it is read off the same source the bundle is
+* built from, so it can only ever move together with `bundle`, and naming
+* both would say one thing twice.
+*/
+function entrySide(kind, entry) {
+	const { key, spine: _spine, ...fields } = entry;
+	return {
+		kind,
+		key,
+		fields
+	};
+}
+/** Every key the tree carries, as the plan compares them. */
+function manifestSides(manifest) {
+	return [
+		...manifest.journeys.map((journey) => entrySide("journey", journey)),
+		...manifest.segments.map((segment) => entrySide("segment", segment)),
+		...manifest.templates.map((template) => entrySide("template", template))
+	];
+}
+/** Journeys, then segments, then templates; alphabetical within each. */
+function order(one) {
+	return `${PLAN_KINDS.indexOf(one.kind)}${one.key}`;
+}
+function sameKey(a) {
+	return (b) => b.kind === a.kind && b.key === a.key;
+}
+/** The whole diff: what this tree would write, and what it leaves alone. */
+function pushPlan(appId, local, served) {
+	const entries = local.map((side) => {
+		const held = served.find(sameKey(side));
+		if (!held) return {
+			kind: side.kind,
+			key: side.key,
+			change: "added",
+			fields: []
+		};
+		const fields = [.../* @__PURE__ */ new Set([...Object.keys(side.fields), ...Object.keys(held.fields)])].filter((field) => stableJson(side.fields[field]) !== stableJson(held.fields[field])).sort();
+		return {
+			kind: side.kind,
+			key: side.key,
+			change: fields.length === 0 ? "unchanged" : "changed",
+			fields
+		};
+	});
+	const drift = served.map((side) => {
+		if (!local.some(sameKey(side))) return {
+			kind: side.kind,
+			key: side.key,
+			reason: "not-in-tree"
+		};
+		return side.onHold === true ? {
+			kind: side.kind,
+			key: side.key,
+			reason: "on-hold"
+		} : null;
+	});
+	return {
+		appId,
+		entries: entries.sort((a, b) => order(a).localeCompare(order(b))),
+		drift: drift.filter((one) => one !== null).sort((a, b) => order(a).localeCompare(order(b)))
+	};
+}
+
 //#endregion
 //#region ../../packages/shared/src/resend.ts
 /** Resend's own cap on one message's recipients, per list. */
@@ -7580,6 +7886,36 @@ const updateWebhookBodySchema = z.object({ data: z.object({
 /** `q` is a substring search over the webhook's name. */
 const listWebhooksQuerySchema = paginationQuerySchema.extend({ q: searchQuerySchema });
 
+//#endregion
+//#region ../../packages/shared/src/whoami.ts
+/**
+* What an ingestion key plus one source id write into. An org API key is
+* org-scoped and carries no app of its own (`ApiKeyClaims`), so any live
+* `src_` in the organization is accepted by the write path: a well-formed id
+* belonging to another app lands profiles there with a 200. The id the
+* caller is about to send is therefore the input, and this answers where it
+* goes before anything is written.
+*
+* Scoped to that one source's app on purpose: the key stays a write
+* credential, and a leaked one must not enumerate the org's other apps
+* (.scratch/24-onboarding-dx/spec.md).
+*/
+const whoamiQuerySchema = z.object({ sourceId: sourceIdSchema });
+const whoamiSchema = z.object({
+	orgId: z.string(),
+	app: z.object({
+		id: z.string(),
+		name: z.string()
+	}),
+	/** Every live pipe into that app, so "a Clerk source already feeds this" is visible. */
+	sources: z.array(sourceSchema.pick({
+		id: true,
+		kind: true,
+		configured: true,
+		lastReceivedAt: true
+	}))
+});
+
 //#endregion
 //#region ../../packages/api-client/src/client.ts
 var ApiError = class extends Error {
@@ -7604,7 +7940,7 @@ async function send(baseUrl, init) {
 			body: typeof init.body === "string" || init.body === null ? init.body : Uint8Array.from(init.body)
 		});
 	} catch {
-		throw new ApiError("network_error", `Could not reach the API at ${baseUrl}. Is apps/api running?`, 0);
+		throw new ApiError("network_error", `Could not reach the API at ${baseUrl}. Check the address, or set COW_API_URL to the one you meant.`, 0);
 	}
 	const requestId = response.headers.get("X-Request-Id") ?? void 0;
 	if (init.binary && response.ok) return {
@@ -7754,24 +8090,48 @@ function readCliPackage() {
 	return cached;
 }
 
+//#endregion
+//#region src/build/events.ts
+function collectEvents(tree) {
+	const named = /* @__PURE__ */ new Map();
+	const add = (key, pattern) => {
+		if (pattern.replaceAll("*", "") === "" || isSystemPattern(pattern)) return;
+		const keys = named.get(pattern) ?? /* @__PURE__ */ new Set();
+		keys.add(key);
+		named.set(pattern, keys);
+	};
+	const addDefinition = (key, definition) => {
+		for (const predicate of definition.predicates) if (predicate.kind === "event") add(key, predicate.name);
+	};
+	for (const journey of tree.journeys) {
+		if ("event" in journey.trigger) for (const pattern of [journey.trigger.event].flat()) add(journey.key, pattern);
+		else if (typeof journey.trigger.segment !== "string") addDefinition(journey.key, journey.trigger.segment);
+		for (const pattern of journey.waits ?? []) add(journey.key, pattern);
+	}
+	for (const segment of tree.segments ?? []) addDefinition(segment.key, segment.definition);
+	return [...named].map(([pattern, keys]) => ({
+		pattern,
+		usedBy: [...keys].sort(byCodePoint)
+	})).sort((a, b) => byCodePoint(a.pattern, b.pattern));
+}
+function byCodePoint(a, b) {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+
 //#endregion
 //#region src/build/spine.ts
 /**
-* The step spine, read off the source of `run` rather than recorded by
-* running it: a run against stub data follows one path and never sees an
-* `if` on a profile trait, which is the shape of half the journeys there
-* are. Reading the code sees every branch, labelled with its condition.
-*
-* What it reads: `await api.*` calls (in source order, with the literal
-* template, webhook, event, key, or duration when the author wrote one
-* inline), `if`/`else`, `switch`, loops, `try`/`catch`, `return`, `throw`, and
-* `api.restart()`. Calls behind a helper function in another file, and a
-* `run` that is not an inline function on the `defineJourney` object, are
-* not followed: the spine is display only, and its ceiling is the source in
-* front of it. The typecheck that ran first is TypeScript's; syntax it accepts
-* and this parser does not yields an empty spine, never a failed build.
-*/
-function readSpine(source) {
+* What one journey's source says: its spine, and every event pattern an
+* `api.waitForEvent` in it names literally, in source order and with a list
+* argument flattened.
+*
+* The patterns are read here rather than off the spine because the spine's
+* `detail` is a label: a non-literal argument shows as the source text the
+* author wrote, which reads fine and would collect `name` as an event name.
+* A caller that needs the data takes this; a caller that needs the display
+* takes `readSpine`.
+*/
+function readJourneySource(source) {
 	let program;
 	try {
 		program = parse(source, {
@@ -7780,22 +8140,37 @@ function readSpine(source) {
 			errorRecovery: true
 		}).program;
 	} catch {
-		return [];
+		return {
+			spine: [],
+			waits: []
+		};
 	}
 	const run = findRun(program);
-	if (!run) return [];
+	if (!run) return {
+		spine: [],
+		waits: []
+	};
 	const api = run.params[1];
-	if (api?.type !== "Identifier") return [];
+	if (api?.type !== "Identifier") return {
+		spine: [],
+		waits: []
+	};
 	const reader = new Reader(source, api.name);
-	if (run.body.type !== "BlockStatement") return [...reader.calls(run.body), {
-		name: "end",
-		detail: "returned"
-	}];
+	if (run.body.type !== "BlockStatement") return {
+		spine: [...reader.calls(run.body), {
+			name: "end",
+			detail: "returned"
+		}],
+		waits: reader.waitPatterns
+	};
 	const body = reader.block(run.body.body);
-	return body.ended ? body.entries : [...body.entries, {
-		name: "end",
-		detail: "returned"
-	}];
+	return {
+		spine: body.ended ? body.entries : [...body.entries, {
+			name: "end",
+			detail: "returned"
+		}],
+		waits: reader.waitPatterns
+	};
 }
 /** The `run` function on the object `export default defineJourney({...})` receives. */
 function findRun(program) {
@@ -7819,6 +8194,8 @@ var Reader = class {
 	api;
 	/** Variables holding a `waitForEvent` result, by name, to the event waited for. */
 	waits = /* @__PURE__ */ new Map();
+	/** Every pattern a `waitForEvent` named literally, in source order. */
+	waitPatterns = [];
 	constructor(source, api) {
 		this.source = source;
 		this.api = api;
@@ -7969,7 +8346,9 @@ var Reader = class {
 				detail(first ? this.literal(first) ?? this.text(first) : void 0);
 				break;
 			case "waitForEvent": {
-				detail(first ? this.literalPattern(first) ?? this.text(first) : void 0);
+				const patterns = this.literalPatterns(first);
+				if (patterns) this.waitPatterns.push(...patterns);
+				detail(patterns ? patternLabel(patterns) : first ? this.text(first) : void 0);
 				const timeout = this.property(args[1], "timeout");
 				if (timeout) entry.timeout = timeout;
 				break;
@@ -8015,12 +8394,22 @@ var Reader = class {
 	}
 	/** A literal pattern, one or a list, the way the trigger label shows it. */
 	literalPattern(node) {
+		const patterns = this.literalPatterns(node);
+		return patterns === void 0 ? void 0 : patternLabel(patterns);
+	}
+	/**
+	* The patterns a matcher argument names, or undefined when any of them is
+	* not a literal: a variable or a helper call is a pattern this read cannot
+	* know, and half a list is worse than none of it.
+	*/
+	literalPatterns(node) {
 		if (!node) return;
 		if (node.type === "ArrayExpression") {
 			const items = node.elements.map((item) => item ? this.literal(item) : void 0);
-			return items.every((item) => item !== void 0) ? patternLabel(items) : void 0;
+			return items.every((item) => item !== void 0) ? items : void 0;
 		}
-		return this.literal(node);
+		const one = this.literal(node);
+		return one === void 0 ? void 0 : [one];
 	}
 	/** The literal value of `key` in an inline object argument. */
 	property(node, key) {
@@ -8164,6 +8553,7 @@ const CONFIG_FILES = [
 const GUEST_ALIAS = {
 	"@cowliss/cli/journeys": guestFile("journeys"),
 	"@cowliss/cli/emails": guestFile("emails"),
+	"@cowliss/cli/segments": guestFile("segments"),
 	"@cowliss/cli/guest": guestFile("guest"),
 	"@cowliss/cli/guest-emails": guestFile("guest-emails"),
 	"@cowliss/cli/guest-wasi": guestFile("guest-wasi"),
@@ -8204,14 +8594,15 @@ async function projectSources(projectDir) {
 	return [
 		...(await Promise.all(CONFIG_FILES.map(async (file) => await stat(join(projectDir, file)).then(() => file, () => null)))).filter((file) => file !== null),
 		...(await listFiles(join(projectDir, "journeys"))).map((file) => `journeys/${file}`),
-		...(await listFiles(join(projectDir, "emails"))).map((file) => `emails/${file}`)
+		...(await listFiles(join(projectDir, "emails"))).map((file) => `emails/${file}`),
+		...(await listFiles(join(projectDir, "segments"))).map((file) => `segments/${file}`)
 	].sort();
 }
 async function discover(projectDir, kind, extension) {
 	const dir = join(projectDir, kind);
 	return (await listFiles(dir)).filter((file) => file.endsWith(extension) && !file.endsWith(".d.ts") && !basename(file).startsWith("_")).map((file) => {
 		const key = basename(file, extension);
-		if (!journeyKeySchema.safeParse(key).success) throw new Error(`${kind}/${file}: "${key}" is not a usable key. A journey or template file is named in kebab-case (a-z, 0-9, hyphens).`);
+		if (!journeyKeySchema.safeParse(key).success) throw new Error(`${kind}/${file}: "${key}" is not a usable key. A journey, template or segment file is named in kebab-case (a-z, 0-9, hyphens).`);
 		return {
 			key,
 			kind,
@@ -8235,6 +8626,20 @@ function assertUniqueKeys(files) {
 	}
 }
 /**
+* A trigger that names its segment resolves inside this one tree, or the
+* build stops here (ADR 0023). This is the whole reason the by-name form is
+* safe to have back: the name is a file in the repository the author is
+* looking at, never a row somebody renamed in the dashboard. Said with the
+* file in hand and the names that do exist, because the two ways out are
+* writing the missing file and fixing a typo.
+*/
+function assertSegmentResolves(relPath, trigger, segmentKeys) {
+	if (!("segment" in trigger) || typeof trigger.segment !== "string") return;
+	if (segmentKeys.has(trigger.segment)) return;
+	const available = segmentKeys.size === 0 ? "This project has no segments yet." : `This project's segments are ${[...segmentKeys].sort().map((key) => `"${key}"`).join(", ")}.`;
+	throw new Error(`${relPath}: this journey enrolls from the segment "${trigger.segment}", and there is no segments/${trigger.segment}.ts. ${available} Add that file, or write the predicate list in the trigger.`);
+}
+/**
 * `.cow/types.d.ts`: one `typeof import(...)` per template, merged into the
 * SDK's `CowTemplates`, which is what types `api.send.email`. Written before
 * the typecheck, because the typecheck is what it exists for.
@@ -8280,7 +8685,7 @@ async function typecheck(projectDir) {
 		});
 	} catch (error) {
 		const output = error;
-		const report = (output.stdout ?? "").trim() || (output.stderr ?? "").trim();
+		const report = (output.stdout ?? "").trim() || (output.stderr ?? "").trim() || String(error.message ?? "");
 		throw new Error(`Typecheck failed:\n${report}`);
 	}
 }
@@ -8372,12 +8777,16 @@ import { runGuest } from ${JSON.stringify(DRIVER[kind])};
 main(module, runGuest);
 `;
 }
-/** The local twin: the same graph, importable by Node for the manifest and `cow test`. */
+/**
+* The local twin: the same graph, importable by Node for the manifest and
+* `cow test`. A segment file gets the module and no driver: it compiles to
+* nothing the sandbox ever runs, so there is no guest protocol to speak.
+*/
 function nodeEntry(file, kind) {
+	const driver = kind === "segments" ? "" : `export { runGuest } from ${JSON.stringify(DRIVER[kind])};\n`;
 	return `import * as module from ${JSON.stringify(file)};
 export { module };
-export { runGuest } from ${JSON.stringify(DRIVER[kind])};
-`;
+${driver}`;
 }
 let messagePortsUnreffed = false;
 /**
@@ -8406,15 +8815,28 @@ function unrefMessagePorts() {
 * rebuilt bundle from being served out of Node's module cache.
 */
 async function loadNodeBundle(projectDir, key, kind = "journeys") {
-	unrefMessagePorts();
-	const path = join(projectDir, BUILD_DIR, "node", kind, `${key}.mjs`);
-	const { mtimeNs } = await stat(path, { bigint: true });
-	const loaded = await import(`${pathToFileURL(path).href}?v=${mtimeNs}`);
+	const loaded = await importNodeBundle(projectDir, key, kind);
 	return {
 		module: loaded.module,
 		runGuest: loaded.runGuest
 	};
 }
+async function importNodeBundle(projectDir, key, kind) {
+	unrefMessagePorts();
+	const path = join(projectDir, BUILD_DIR, "node", kind, `${key}.mjs`);
+	const { mtimeNs } = await stat(path, { bigint: true });
+	return await import(`${pathToFileURL(path).href}?v=${mtimeNs}`);
+}
+/**
+* A built segment file's own export. No driver and no guest protocol: the
+* definition is data `defineSegment` already validated at module load, so
+* reading it is an import and a shape check.
+*/
+async function loadSegment(projectDir, key) {
+	const { module } = await importNodeBundle(projectDir, key, "segments");
+	const segment = module.default;
+	return segment?.definition ? segment : void 0;
+}
 /**
 * A profile with nothing in it but the id and traits given: the base the
 * simulator answers `profile.get` with.
@@ -8442,6 +8864,7 @@ function emptyProfile(id = "", traits = {}, purposes = []) {
 function limitFailure(sizes) {
 	if (sizes.journeys > PUSH_LIMITS.journeys) return `This project has ${sizes.journeys} journeys; a push carries at most ${PUSH_LIMITS.journeys}.`;
 	if (sizes.templates > PUSH_LIMITS.templates) return `This project has ${sizes.templates} templates; a push carries at most ${PUSH_LIMITS.templates}.`;
+	if (sizes.segments > PUSH_LIMITS.segments) return `This project has ${sizes.segments} segments; a push carries at most ${PUSH_LIMITS.segments}.`;
 	for (const bundle of sizes.bundles) if (bundle.bytes > PUSH_LIMITS.bundleBytes) return `Bundle "${bundle.key}" is ${bundle.bytes} bytes; a bundle is at most ${PUSH_LIMITS.bundleBytes}.`;
 	if (sizes.sourceBytes > PUSH_LIMITS.sourceBytes) return `The source tarball is ${sizes.sourceBytes} bytes; a push carries at most ${PUSH_LIMITS.sourceBytes}.`;
 	return null;
@@ -8517,13 +8940,16 @@ async function buildProject(projectDir) {
 	const config = await assertCowConfig(projectDir);
 	const journeys = await discover(projectDir, "journeys", ".ts");
 	const templates = await discover(projectDir, "emails", ".tsx");
+	const segmentFiles = await discover(projectDir, "segments", ".ts");
 	assertUniqueKeys(journeys);
 	assertUniqueKeys(templates);
+	assertUniqueKeys(segmentFiles);
 	const outDir = join(projectDir, BUILD_DIR);
 	for (const kind of ["journeys", "emails"]) {
 		await mkdir(join(outDir, "bundles", kind), { recursive: true });
 		await mkdir(join(outDir, "node", kind), { recursive: true });
 	}
+	await mkdir(join(outDir, "node", "segments"), { recursive: true });
 	await writeFile(join(projectDir, TYPES_FILE), templateTypes(templates));
 	await typecheck(projectDir);
 	const files = [...journeys, ...templates];
@@ -8541,8 +8967,29 @@ async function buildProject(projectDir) {
 			bytes: wasi.code.byteLength
 		};
 	}));
+	const manifestSegments = await Promise.all(segmentFiles.map(async (source) => {
+		const nodeFile = join(outDir, "node", source.kind, `${source.key}.mjs`);
+		const node = await bundle(projectDir, nodeFile, nodeEntry(source.file, source.kind));
+		await writeFile(nodeFile, node.code);
+		await writeFile(`${nodeFile}.map`, node.map);
+		let segment;
+		try {
+			segment = await loadSegment(projectDir, source.key);
+		} catch (error) {
+			throw new Error(`${source.relPath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+		}
+		if (!segment) throw new Error(`${source.relPath} is not a segment: a segment file default-exports defineSegment({ predicates: [ ... ] }).`);
+		return {
+			key: source.key,
+			tags: segment.tags,
+			description: segment.description,
+			definition: segment.definition
+		};
+	}));
+	const segmentKeys = new Set(manifestSegments.map((segment) => segment.key));
 	const manifestJourneys = [];
 	const manifestTemplates = [];
+	const journeyWaits = /* @__PURE__ */ new Map();
 	for (const built of bundles) {
 		let report;
 		try {
@@ -8553,18 +9000,22 @@ async function buildProject(projectDir) {
 		}
 		const isJourney = built.source.kind === "journeys";
 		if (report?.kind !== (isJourney ? "journey" : "template")) throw new Error(`${built.source.relPath} is not a ${isJourney ? "journey" : "template"}: a journey default-exports defineJourney({ ... }), a template exports a component and a zod \`props\` schema.`);
-		if (report.kind === "journey") manifestJourneys.push({
-			key: built.source.key,
-			tags: report.tags,
-			trigger: report.trigger,
-			purpose: report.purpose,
-			enrollment: report.enrollment,
-			description: report.description,
-			from: report.from,
-			spine: readSpine(await readFile(built.source.file, "utf8")),
-			bundle: built.digest
-		});
-		else manifestTemplates.push({
+		if (report.kind === "journey") {
+			assertSegmentResolves(built.source.relPath, report.trigger, segmentKeys);
+			const { spine, waits } = readJourneySource(await readFile(built.source.file, "utf8"));
+			manifestJourneys.push({
+				key: built.source.key,
+				tags: report.tags,
+				trigger: report.trigger,
+				purpose: report.purpose,
+				enrollment: report.enrollment,
+				description: report.description,
+				from: report.from,
+				spine,
+				bundle: built.digest
+			});
+			journeyWaits.set(built.source.key, waits);
+		} else manifestTemplates.push({
 			key: built.source.key,
 			tags: report.tags,
 			sendClass: report.sendClass,
@@ -8579,6 +9030,7 @@ async function buildProject(projectDir) {
 	const failure = limitFailure({
 		journeys: journeys.length,
 		templates: templates.length,
+		segments: segmentFiles.length,
 		bundles: bundles.map((built) => ({
 			key: built.source.key,
 			bytes: built.bytes
@@ -8591,6 +9043,14 @@ async function buildProject(projectDir) {
 		sdk: (await readCliPackage()).version,
 		journeys: manifestJourneys,
 		templates: manifestTemplates,
+		segments: manifestSegments,
+		events: collectEvents({
+			journeys: manifestJourneys.map((journey) => ({
+				...journey,
+				waits: journeyWaits.get(journey.key)
+			})),
+			segments: manifestSegments
+		}),
 		purposes: config.purposes,
 		source: digestOf(await readFile(sourceFile))
 	});
@@ -8626,8 +9086,15 @@ async function buildIfStale(projectDir) {
 
 //#endregion
 //#region src/lib/config.ts
-const DEFAULT_API_URL = "http://localhost:3400";
-const DEFAULT_WEB_URL = "http://localhost:5273";
+/**
+* Where a `cow` that was told nothing talks to: the hosted service. A
+* developer running Cowliss itself points a checkout somewhere else with
+* `COW_API_URL` or `apiUrl` in `cow.json`, which both outrank this; the
+* default is the last resort, and the last resort of a published CLI cannot
+* be a port on the reader's own machine.
+*/
+const DEFAULT_API_URL = "https://api.cowliss.com";
+const DEFAULT_WEB_URL = "https://app.cowliss.com";
 function credentialsPath(env) {
 	return env.COW_CREDENTIALS_PATH ?? defaultCredentialsPath();
 }
@@ -8679,20 +9146,20 @@ function resolveCredential(env, credentials) {
 * The project's own `apiUrl` outranks the credentials file because it is the
 * more specific answer: `cow.json` says which API this project talks to, while the
 * credentials only remember where somebody last logged in. Without it a
-* checkout whose config names production silently fell through to
-* `DEFAULT_API_URL`, which is how a production deploy reaches localhost.
+* checkout whose config names one deployment silently fell through to
+* whatever the last `cow login` had saved.
 */
 function resolveApiUrl(env, credentials, flag, projectApiUrl) {
-	return flag ?? env.COW_API_URL ?? projectApiUrl ?? credentials?.apiUrl ?? "http://localhost:3400";
+	return flag ?? env.COW_API_URL ?? projectApiUrl ?? credentials?.apiUrl ?? "https://api.cowliss.com";
 }
 /**
 * The dashboard this project belongs to: the flag, the env var, the
 * project's own `cow.json`, then the default. Same precedence as the API URL
-* and for the same reason: a checkout pointed at production must not send
-* the developer (or a push's links) to localhost.
+* and for the same reason: a checkout pointed at one deployment must not
+* send the developer (or a push's links) to another.
 */
 function resolveWebUrl(env, projectWebUrl, flag) {
-	return flag ?? env.COW_WEB_URL ?? projectWebUrl ?? "http://localhost:5273";
+	return flag ?? env.COW_WEB_URL ?? projectWebUrl ?? "https://app.cowliss.com";
 }
 /**
 * Decode a JWT payload without verification. Display only: the API is the
@@ -8725,9 +9192,9 @@ function decodeSessionToken(token) {
 //#endregion
 //#region src/commands/add.ts
 /**
-* `cow add example <name>`: copy one of the gallery examples the package
+* `cow add blueprint <name>`: copy one of the gallery blueprints the package
 * ships into the project in the current directory. The same files back
-* `cow init --example` and the docs gallery, so what the docs render is
+* `cow init --blueprint` and the docs gallery, so what the docs render is
 * exactly what lands in a developer's repo.
 *
 * Resolved from the package's own manifest, the self-reference
@@ -8736,29 +9203,30 @@ function decodeSessionToken(token) {
 * bundled `dist/index.js`, and the published layout is the one nothing in
 * the monorepo exercises.
 */
-const EXAMPLES_DIR = fileURLToPath(new URL("examples/", import.meta.resolve("@cowliss/cli/package.json")));
-/** An example's copyable directories, in the order files are reported. */
+const BLUEPRINTS_DIR = fileURLToPath(new URL("blueprints/", import.meta.resolve("@cowliss/cli/package.json")));
+/** A blueprint's copyable directories, in the order files are reported. */
 const PARTS = [
 	"journeys",
 	"emails",
+	"segments",
 	"scenarios"
 ];
-async function exampleNames() {
-	return (await readdir(EXAMPLES_DIR, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+async function blueprintNames() {
+	return (await readdir(BLUEPRINTS_DIR, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
 }
 /**
-* Copy an example's files into `dir`, returning the project-relative paths
+* Copy a blueprint's files into `dir`, returning the project-relative paths
 * written. Collected and checked before anything is written, so a refusal on
 * the last file never leaves the first half copied.
 */
-async function copyExample(name, dir, force) {
-	const known = await exampleNames();
-	if (!known.includes(name)) throw new Error(`Unknown example "${name}". Known examples: ${known.join(", ")}`);
+async function copyBlueprint(name, dir, force) {
+	const known = await blueprintNames();
+	if (!known.includes(name)) throw new Error(`Unknown blueprint "${name}". Known blueprints: ${known.join(", ")}`);
 	const files = [];
 	for (const part of PARTS) {
 		let entries;
 		try {
-			entries = await readdir(join(EXAMPLES_DIR, name, part));
+			entries = await readdir(join(BLUEPRINTS_DIR, name, part));
 		} catch {
 			continue;
 		}
@@ -8768,244 +9236,80 @@ async function copyExample(name, dir, force) {
 	if (clashes.length > 0) throw new Error(`Already in this project: ${clashes.join(", ")}. Pass --force to overwrite.`);
 	for (const file of files) {
 		await mkdir(dirname(join(dir, file)), { recursive: true });
-		await copyFile(join(EXAMPLES_DIR, name, file), join(dir, file));
+		await copyFile(join(BLUEPRINTS_DIR, name, file), join(dir, file));
 	}
 	return files;
 }
 function registerAdd(program, io) {
-	program.command("add").description("add gallery example code to a cow repo").command("example <name>").description("copy an example's journeys, emails, and scenarios into this repo (local: no API call)").option("--force", "overwrite files that already exist").action(async (name, opts) => {
+	program.command("add").description("add gallery blueprint code to a cow repo").command("blueprint <name>").description("copy a blueprint's journeys, emails, segments, and scenarios into this repo (local: no API call)").option("--force", "overwrite files that already exist").action(async (name, opts) => {
 		const dir = process.cwd();
 		await assertCowConfig(dir);
-		const files = await copyExample(name, dir, opts.force === true);
+		const files = await copyBlueprint(name, dir, opts.force === true);
 		emit({ data: {
-			example: name,
+			blueprint: name,
 			dir,
 			files
 		} }, io, program.opts().json);
-		io.stderr(`Added the ${name} example:\n${files.map((file) => `  ${file}`).join("\n")}\n`);
+		io.stderr(`Added the ${name} blueprint:\n${files.map((file) => `  ${file}`).join("\n")}\n`);
 	});
 }
 
 //#endregion
-//#region src/lib/login.ts
-/**
-* Login via the dashboard's /cli-auth bridge: start a loopback server, open
-* the web app there, and the signed-in browser POSTs the Clerk session token
-* back. `--token <jwt>` bypasses the browser entirely (agents, CI).
-*/
-async function login(env, options) {
-	let token;
-	if (options.token !== void 0) {
-		token = options.token.trim();
-		if (decodeTokenPayload(token) === null) throw new Error("The provided --token value is not a JWT");
-	} else token = await collectTokenViaBrowser(resolveWebUrl(env, (await readCowConfig(process.cwd()))?.webUrl, options.webUrl), 3e5, options.noOpen === true);
-	const claims = decodeSessionToken(token);
-	if (claims === null) throw new Error("Token is not a decodable JWT");
-	if (claims.userId === null) throw new Error("Token has no subject claim. Is it a Clerk session token?");
-	const apiUrl = options.apiFlag ?? resolveApiUrl(env, null, void 0, (await readCowConfig(process.cwd()))?.apiUrl);
-	return {
-		credentialsPath: await writeCredentials(env, {
-			token,
-			apiUrl
-		}),
-		apiUrl,
-		userId: claims.userId,
-		orgId: claims.orgId,
-		role: claims.role,
-		hasOrg: claims.orgId !== null
-	};
-}
-/** Open the dashboard bridge and await one POST of { token }. */
-function collectTokenViaBrowser(webUrl, timeoutMs = 18e4, noOpen = false) {
-	return new Promise((resolve, reject) => {
-		let server = null;
-		const timer = setTimeout(() => {
-			server?.close();
-			reject(/* @__PURE__ */ new Error(`Timed out waiting for the browser to sign in (${Math.round(timeoutMs / 1e3)}s). Or paste a token: \`cow login --token <jwt>\`.`));
-		}, timeoutMs);
-		server = createServer((req, res) => {
-			res.setHeader("Access-Control-Allow-Origin", "*");
-			res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
-			res.setHeader("Access-Control-Allow-Headers", "Content-Type");
-			if (req.method === "OPTIONS") {
-				res.writeHead(204).end();
-				return;
-			}
-			if (req.method !== "POST") {
-				res.writeHead(405).end();
-				return;
-			}
-			const chunks = [];
-			req.on("data", (chunk) => chunks.push(chunk));
-			req.on("end", () => {
-				clearTimeout(timer);
-				try {
-					const body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
-					const field = (name) => typeof body === "object" && body !== null && name in body ? body[name] : void 0;
-					if (field("denied") === true) {
-						res.writeHead(200, { "Content-Type": "application/json" });
-						res.end(JSON.stringify({ ok: true }));
-						reject(/* @__PURE__ */ new Error("Sign-in was denied in the browser. No access was granted."));
-						return;
-					}
-					const token = field("token");
-					if (typeof token !== "string" || token.length === 0) {
-						res.writeHead(400, { "Content-Type": "application/json" });
-						res.end(JSON.stringify({ error: "missing token" }));
-						reject(/* @__PURE__ */ new Error("The browser bridge sent no token"));
-						return;
-					}
-					res.writeHead(200, { "Content-Type": "application/json" });
-					res.end(JSON.stringify({ ok: true }));
-					resolve(token);
-				} catch (error) {
-					reject(error instanceof Error ? error : new Error(String(error)));
-				} finally {
-					server?.close();
-				}
-			});
-		});
-		server.listen(0, "127.0.0.1", () => {
-			const address = server?.address();
-			if (address === null || typeof address !== "object") {
-				reject(/* @__PURE__ */ new Error("Could not bind a loopback port"));
-				return;
-			}
-			const callbackUrl = `http://127.0.0.1:${address.port}/cb`;
-			const target = `${webUrl}/cli-auth?cb=${encodeURIComponent(callbackUrl)}`;
-			if (!noOpen) openBrowser(target);
-			process.stderr.write(`Waiting for sign-in at:\n  ${target}\n`);
-		});
-		server.on("error", (error) => {
-			clearTimeout(timer);
-			reject(error);
-		});
-	});
-}
-function openBrowser(url) {
-	const cmd = process.platform === "darwin" ? "open" : process.platform === "linux" ? "xdg-open" : null;
-	if (cmd === null) return;
-	spawn(cmd, [url], {
-		stdio: "ignore",
-		detached: true
-	}).unref();
-}
-
-//#endregion
-//#region src/commands/auth.ts
-/** login/logout/whoami: session-token management, no contract route. */
-function registerAuth(program, env, io) {
-	program.command("login").description("authenticate via the dashboard browser flow (or --token) and cache the session token").option("--token <jwt>", "paste a session token instead of the browser flow").option("--web <url>", `dashboard URL; overrides COW_WEB_URL and webUrl in cow.json (default ${DEFAULT_WEB_URL})`).option("--no-open", "do not open the browser; print the URL and wait (headless/agent use)").action(async (opts) => {
-		const outcome = await login(env, {
-			token: opts.token,
-			webUrl: opts.web,
-			apiFlag: opts.api,
-			noOpen: opts.open === false
-		});
-		emit({ data: {
-			...outcome,
-			warnings: outcome.hasOrg ? void 0 : ["The token carries no active organization. Select one in the dashboard and log in again."]
-		} }, io, opts.json);
-	});
-	program.command("logout").description("delete the cached session token").action(async (opts) => {
-		const removed = await clearCredentials(env);
-		emit({ data: { removed } }, io, opts.json);
-	});
-	program.command("whoami").description("show which credential commands will use, and for a session its subject, org, role, and expiry").action(async (opts) => {
-		const credentials = await readCredentials(env);
-		const { kind } = resolveCredential(env, credentials);
-		if (kind === "none") throw new Error("Not logged in. Run `cow login` first, or set COW_PIPELINE_KEY.");
-		if (kind === "pipelineKey") {
-			emit({ data: {
-				credential: kind,
-				source: "COW_PIPELINE_KEY",
-				note: "A pipeline key may push, enable, disable, and read executions."
-			} }, io, opts.json);
-			return;
-		}
-		const claims = decodeSessionToken(credentials?.token ?? "");
-		if (!claims) throw new Error("Cached token is not decodable. Run `cow login` again.");
-		const projectApiUrl = (await readCowConfig(process.cwd()))?.apiUrl;
-		const apiUrl = resolveApiUrl(env, credentials, opts.api, projectApiUrl);
-		const mintedFor = credentials?.apiUrl;
-		emit({ data: {
-			credential: kind,
-			apiUrl,
-			mintedFor: mintedFor ?? null,
-			...mintedFor !== void 0 && mintedFor !== apiUrl ? { warning: `This token was minted for ${mintedFor}, but commands here talk to ${apiUrl}. Run \`cow login\` again from this directory.` } : {},
-			...claims
-		} }, io, opts.json);
-	});
-}
-
-//#endregion
-//#region src/commands/build.ts
-/**
-* `cow build`: typecheck, bundle, and write `.cow/build` for the project in
-* the current directory. Local only, no API call and no network.
-*/
-function registerBuild(program, io) {
-	program.command("build").description("typecheck and bundle the repo in the current directory, writing .cow/build (local: no API call)").action(async (opts) => {
-		emit({ data: await buildProject(process.cwd()) }, io, opts.json);
-	});
-}
-
-//#endregion
-//#region ../../node_modules/.pnpm/@asteasolutions+zod-to-openapi@9.1.0_zod@4.4.3/node_modules/@asteasolutions/zod-to-openapi/dist/index.cjs
-var require_dist = /* @__PURE__ */ __commonJSMin(((exports) => {
-	/******************************************************************************
-	Copyright (c) Microsoft Corporation.
-	
-	Permission to use, copy, modify, and/or distribute this software for any
-	purpose with or without fee is hereby granted.
-	
-	THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
-	REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
-	AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
-	INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
-	LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
-	OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-	PERFORMANCE OF THIS SOFTWARE.
-	***************************************************************************** */
-	function __rest(s, e) {
-		var t = {};
-		for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0) t[p] = s[p];
-		if (s != null && typeof Object.getOwnPropertySymbols === "function") {
-			for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i])) t[p[i]] = s[p[i]];
-		}
-		return t;
-	}
-	const ZodTypeKeys = {
-		ZodAny: "any",
-		ZodArray: "array",
-		ZodBigInt: "bigint",
-		ZodBoolean: "boolean",
-		ZodDefault: "default",
-		ZodPrefault: "prefault",
-		ZodTransform: "transform",
-		ZodEnum: "enum",
-		ZodIntersection: "intersection",
-		ZodLazy: "lazy",
-		ZodLiteral: "literal",
-		ZodNever: "never",
-		ZodNull: "null",
-		ZodNullable: "nullable",
-		ZodNumber: "number",
-		ZodNonOptional: "nonoptional",
-		ZodObject: "object",
-		ZodOptional: "optional",
-		ZodPipe: "pipe",
-		ZodReadonly: "readonly",
-		ZodRecord: "record",
-		ZodString: "string",
-		ZodTuple: "tuple",
-		ZodType: "type",
-		ZodUnion: "union",
-		ZodDiscriminatedUnion: "union",
-		ZodUnknown: "unknown",
-		ZodVoid: "void",
-		ZodDate: "date",
-		ZodTemplateLiteral: "template_literal"
+//#region ../../node_modules/.pnpm/@asteasolutions+zod-to-openapi@9.1.0_zod@4.4.3/node_modules/@asteasolutions/zod-to-openapi/dist/index.cjs
+var require_dist = /* @__PURE__ */ __commonJSMin(((exports) => {
+	/******************************************************************************
+	Copyright (c) Microsoft Corporation.
+	
+	Permission to use, copy, modify, and/or distribute this software for any
+	purpose with or without fee is hereby granted.
+	
+	THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+	REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+	AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+	INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+	LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+	OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+	PERFORMANCE OF THIS SOFTWARE.
+	***************************************************************************** */
+	function __rest(s, e) {
+		var t = {};
+		for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0) t[p] = s[p];
+		if (s != null && typeof Object.getOwnPropertySymbols === "function") {
+			for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i])) t[p[i]] = s[p[i]];
+		}
+		return t;
+	}
+	const ZodTypeKeys = {
+		ZodAny: "any",
+		ZodArray: "array",
+		ZodBigInt: "bigint",
+		ZodBoolean: "boolean",
+		ZodDefault: "default",
+		ZodPrefault: "prefault",
+		ZodTransform: "transform",
+		ZodEnum: "enum",
+		ZodIntersection: "intersection",
+		ZodLazy: "lazy",
+		ZodLiteral: "literal",
+		ZodNever: "never",
+		ZodNull: "null",
+		ZodNullable: "nullable",
+		ZodNumber: "number",
+		ZodNonOptional: "nonoptional",
+		ZodObject: "object",
+		ZodOptional: "optional",
+		ZodPipe: "pipe",
+		ZodReadonly: "readonly",
+		ZodRecord: "record",
+		ZodString: "string",
+		ZodTuple: "tuple",
+		ZodType: "type",
+		ZodUnion: "union",
+		ZodDiscriminatedUnion: "union",
+		ZodUnknown: "unknown",
+		ZodVoid: "void",
+		ZodDate: "date",
+		ZodTemplateLiteral: "template_literal"
 	};
 	function isZodType(schema, typeNames) {
 		return (Array.isArray(typeNames) ? typeNames : [typeNames]).some((typeName) => {
@@ -10050,6 +10354,23 @@ const events = defineModule(defineRoute({
 		...sessionErrors,
 		...errors("validation_failed")
 	}
+}), defineRoute({
+	method: "get",
+	path: "/v1/apps/{appId}/events/seen",
+	operationId: "apps.events.seen",
+	tags: ["events"],
+	summary: "Whether an app has ever received these event names",
+	security: PIPELINE_AUTH,
+	surfaces: { cli: false },
+	request: {
+		params: z.object({ appId: z.string() }),
+		query: eventsSeenQuerySchema
+	},
+	responses: {
+		200: envelope(eventsSeenDtoSchema),
+		...sessionErrors,
+		...errors("not_found", "validation_failed")
+	}
 }), defineRoute({
 	method: "get",
 	path: "/v1/events/{id}",
@@ -10217,6 +10538,19 @@ const ingestion = defineModule(defineRoute({
 		200: envelope(batchResultDtoSchema, "Per-item outcomes, positionally aligned"),
 		...ingestionErrors
 	}
+}), defineRoute({
+	method: "get",
+	path: "/v1/whoami",
+	operationId: "ingestion.whoami",
+	tags: ["ingestion"],
+	summary: "Which app a source id writes into",
+	security: API_KEY_AUTH,
+	surfaces: HIDDEN_FROM_TOOLS,
+	request: { query: whoamiQuerySchema },
+	responses: {
+		200: envelope(whoamiSchema, "The source's org, app, and sibling sources"),
+		...errors("invalid_key", "not_found", "validation_failed", "rate_limited")
+	}
 }));
 
 //#endregion
@@ -10442,12 +10776,26 @@ const params$6 = z.object({ id: z.string() });
 * push stores the source archive and its compile creates a version of every
 * key whose module changed; it turns nothing on (ADR 0011).
 *
-* `create` and `source` are hidden from the CLI and MCP surfaces because
-* both only make sense next to local files: the manifest `create` takes is
-* whatever `cow build` just wrote, and the tarball `source` returns is what
-* `cow pull` unpacks over a working tree.
+* `plan`, `create` and `source` are hidden from the CLI and MCP surfaces
+* because all three only make sense next to local files: the manifest the
+* first two take is whatever `cow build` just wrote, and the tarball
+* `source` returns is what `cow pull` unpacks over a working tree.
 */
 const pushes = defineModule(defineRoute({
+	method: "post",
+	path: "/v1/pushes/plan",
+	operationId: "pushes.plan",
+	tags: ["pushes"],
+	summary: "What a push of this tree would change",
+	security: PIPELINE_AUTH,
+	surfaces: HIDDEN_FROM_TOOLS,
+	request: { body: jsonBody(createPushBodySchema) },
+	responses: {
+		200: envelope(pushPlanSchema, "What this tree would write, and what it leaves alone"),
+		...sessionErrors,
+		...errors("validation_failed", "malformed_request")
+	}
+}), defineRoute({
 	method: "post",
 	path: "/v1/pushes",
 	operationId: "pushes.create",
@@ -11432,43 +11780,217 @@ const allRoutes = Object.values(contract).flatMap((module) => Object.values(modu
 const tags = [...new Set(allRoutes.flatMap((route) => route.tags ?? []))];
 
 //#endregion
-//#region ../../packages/shared/src/contract/surfaces.ts
-/** camelCase field name → kebab-case flag body (`sourceId` → `source-id`). */
-function kebabCase(name) {
-	return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
-}
+//#region src/lib/login.ts
 /**
-* Unwrap the wrapper types that only affect nullability/defaults
-* (ZodOptional/ZodNullable/ZodDefault) plus ZodPipe (`.transform()`, so CLI
-* users provide the pipe's input side). A field is optional when a
-* ZodOptional or ZodDefault appears anywhere in the chain.
+* Login via the dashboard's /cli-auth bridge: start a loopback server, open
+* the web app there, and the signed-in browser POSTs the Clerk session token
+* back. `--token <jwt>` bypasses the browser entirely (agents, CI).
 */
-function unwrapSchema(schema) {
-	let current = schema;
-	let required = true;
-	for (;;) if (current instanceof z.ZodOptional || current instanceof z.ZodDefault) {
-		required = false;
-		current = current.unwrap();
-	} else if (current instanceof z.ZodNullable) current = current.unwrap();
-	else if (current instanceof z.ZodPipe) current = current.def.in;
-	else return {
-		schema: current,
-		required
+async function login(env, options) {
+	let token;
+	if (options.token !== void 0) {
+		token = options.token.trim();
+		if (decodeTokenPayload(token) === null) throw new Error("The provided --token value is not a JWT");
+	} else token = await collectTokenViaBrowser(resolveWebUrl(env, (await readCowConfig(process.cwd()))?.webUrl, options.webUrl), 3e5, options.noOpen === true);
+	const claims = decodeSessionToken(token);
+	if (claims === null) throw new Error("Token is not a decodable JWT");
+	if (claims.userId === null) throw new Error("Token has no subject claim. Is it a Clerk session token?");
+	const apiUrl = options.apiFlag ?? resolveApiUrl(env, null, void 0, (await readCowConfig(process.cwd()))?.apiUrl);
+	return {
+		credentialsPath: await writeCredentials(env, {
+			token,
+			apiUrl
+		}),
+		apiUrl,
+		userId: claims.userId,
+		orgId: claims.orgId,
+		role: claims.role,
+		hasOrg: claims.orgId !== null
 	};
 }
-/**
-* The fixed string choices a schema offers, if it has any. An enum, a string
-* literal (zod holds a literal's values as a Set, since one can name
-* several), or a union of those: `violationStatusSchema.or(z.literal("all"))`
-* is the shape that makes the union arm worth walking. Anything else has no
-* closed set of values and belongs on a JSON flag.
-*/
-function stringChoices(schema) {
-	const inner = unwrapSchema(schema).schema;
-	if (inner instanceof z.ZodEnum) return [...inner.options].map(String);
-	if (inner instanceof z.ZodLiteral) {
-		const values = [...inner.values];
-		return values.every((value) => typeof value === "string") ? values : void 0;
+/** Open the dashboard bridge and await one POST of { token }. */
+function collectTokenViaBrowser(webUrl, timeoutMs = 18e4, noOpen = false) {
+	return new Promise((resolve, reject) => {
+		let server = null;
+		const timer = setTimeout(() => {
+			server?.close();
+			reject(/* @__PURE__ */ new Error(`Timed out waiting for the browser to sign in (${Math.round(timeoutMs / 1e3)}s). Or paste a token: \`cow login --token <jwt>\`.`));
+		}, timeoutMs);
+		server = createServer((req, res) => {
+			res.setHeader("Access-Control-Allow-Origin", "*");
+			res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+			res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+			if (req.method === "OPTIONS") {
+				res.writeHead(204).end();
+				return;
+			}
+			if (req.method !== "POST") {
+				res.writeHead(405).end();
+				return;
+			}
+			const chunks = [];
+			req.on("data", (chunk) => chunks.push(chunk));
+			req.on("end", () => {
+				clearTimeout(timer);
+				try {
+					const body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+					const field = (name) => typeof body === "object" && body !== null && name in body ? body[name] : void 0;
+					if (field("denied") === true) {
+						res.writeHead(200, { "Content-Type": "application/json" });
+						res.end(JSON.stringify({ ok: true }));
+						reject(/* @__PURE__ */ new Error("Sign-in was denied in the browser. No access was granted."));
+						return;
+					}
+					const token = field("token");
+					if (typeof token !== "string" || token.length === 0) {
+						res.writeHead(400, { "Content-Type": "application/json" });
+						res.end(JSON.stringify({ error: "missing token" }));
+						reject(/* @__PURE__ */ new Error("The browser bridge sent no token"));
+						return;
+					}
+					res.writeHead(200, { "Content-Type": "application/json" });
+					res.end(JSON.stringify({ ok: true }));
+					resolve(token);
+				} catch (error) {
+					reject(error instanceof Error ? error : new Error(String(error)));
+				} finally {
+					server?.close();
+				}
+			});
+		});
+		server.listen(0, "127.0.0.1", () => {
+			const address = server?.address();
+			if (address === null || typeof address !== "object") {
+				reject(/* @__PURE__ */ new Error("Could not bind a loopback port"));
+				return;
+			}
+			const callbackUrl = `http://127.0.0.1:${address.port}/cb`;
+			const target = `${webUrl}/cli-auth?cb=${encodeURIComponent(callbackUrl)}`;
+			if (!noOpen) openBrowser(target);
+			process.stderr.write(`Waiting for sign-in at:\n  ${target}\n`);
+		});
+		server.on("error", (error) => {
+			clearTimeout(timer);
+			reject(error);
+		});
+	});
+}
+function openBrowser(url) {
+	const cmd = process.platform === "darwin" ? "open" : process.platform === "linux" ? "xdg-open" : null;
+	if (cmd === null) return;
+	spawn(cmd, [url], {
+		stdio: "ignore",
+		detached: true
+	}).unref();
+}
+
+//#endregion
+//#region src/commands/auth.ts
+/** login/logout/whoami: session-token management, no contract route. */
+function registerAuth(program, env, io) {
+	program.command("login").description("authenticate via the dashboard browser flow (or --token) and cache the session token").option("--token <jwt>", "paste a session token instead of the browser flow").option("--web <url>", `dashboard URL; overrides COW_WEB_URL and webUrl in cow.json (default ${DEFAULT_WEB_URL})`).option("--no-open", "do not open the browser; print the URL and wait (headless/agent use)").action(async (opts) => {
+		const outcome = await login(env, {
+			token: opts.token,
+			webUrl: opts.web,
+			apiFlag: opts.api,
+			noOpen: opts.open === false
+		});
+		emit({ data: {
+			...outcome,
+			warnings: outcome.hasOrg ? void 0 : ["The token carries no active organization. Select one in the dashboard and log in again."]
+		} }, io, opts.json);
+	});
+	program.command("logout").description("delete the cached session token").action(async (opts) => {
+		const removed = await clearCredentials(env);
+		emit({ data: { removed } }, io, opts.json);
+	});
+	program.command("whoami").description("show which credential commands will use, and for a session its subject, org, role, and expiry").option("--key <ak_...>", "ask the API what an ingestion key writes into, instead of reading the cached session").option("--source <src_...>", "the source id that key is about to send to (required with --key)").action(async (opts) => {
+		if (opts.key) {
+			if (!opts.source) throw new Error("`--key` needs `--source <src_...>`: the id you are about to send to is what this checks.");
+			const client = createClient({
+				baseUrl: resolveApiUrl(env, await readCredentials(env), opts.api, (await readCowConfig(process.cwd()))?.apiUrl),
+				auth: () => opts.key ?? null,
+				headers: { [CLIENT_HEADER]: `@cowliss/cli/${(await readCliPackage()).version}` }
+			});
+			emit(await client.request(contract.ingestion["ingestion.whoami"], { query: { sourceId: opts.source } }), io, opts.json);
+			return;
+		}
+		const credentials = await readCredentials(env);
+		const { kind } = resolveCredential(env, credentials);
+		if (kind === "none") throw new Error("Not logged in. Run `cow login` first, or set COW_PIPELINE_KEY.");
+		if (kind === "pipelineKey") {
+			emit({ data: {
+				credential: kind,
+				source: "COW_PIPELINE_KEY",
+				note: "A pipeline key may push, enable, disable, and read executions."
+			} }, io, opts.json);
+			return;
+		}
+		const claims = decodeSessionToken(credentials?.token ?? "");
+		if (!claims) throw new Error("Cached token is not decodable. Run `cow login` again.");
+		const projectApiUrl = (await readCowConfig(process.cwd()))?.apiUrl;
+		const apiUrl = resolveApiUrl(env, credentials, opts.api, projectApiUrl);
+		const mintedFor = credentials?.apiUrl;
+		emit({ data: {
+			credential: kind,
+			apiUrl,
+			mintedFor: mintedFor ?? null,
+			...mintedFor !== void 0 && mintedFor !== apiUrl ? { warning: `This token was minted for ${mintedFor}, but commands here talk to ${apiUrl}. Run \`cow login\` again from this directory.` } : {},
+			...claims
+		} }, io, opts.json);
+	});
+}
+
+//#endregion
+//#region src/commands/build.ts
+/**
+* `cow build`: typecheck, bundle, and write `.cow/build` for the project in
+* the current directory. Local only, no API call and no network.
+*/
+function registerBuild(program, io) {
+	program.command("build").description("typecheck and bundle the repo in the current directory, writing .cow/build (local: no API call)").action(async (opts) => {
+		emit({ data: await buildProject(process.cwd()) }, io, opts.json);
+	});
+}
+
+//#endregion
+//#region ../../packages/shared/src/contract/surfaces.ts
+/** camelCase field name → kebab-case flag body (`sourceId` → `source-id`). */
+function kebabCase(name) {
+	return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+/**
+* Unwrap the wrapper types that only affect nullability/defaults
+* (ZodOptional/ZodNullable/ZodDefault) plus ZodPipe (`.transform()`, so CLI
+* users provide the pipe's input side). A field is optional when a
+* ZodOptional or ZodDefault appears anywhere in the chain.
+*/
+function unwrapSchema(schema) {
+	let current = schema;
+	let required = true;
+	for (;;) if (current instanceof z.ZodOptional || current instanceof z.ZodDefault) {
+		required = false;
+		current = current.unwrap();
+	} else if (current instanceof z.ZodNullable) current = current.unwrap();
+	else if (current instanceof z.ZodPipe) current = current.def.in;
+	else return {
+		schema: current,
+		required
+	};
+}
+/**
+* The fixed string choices a schema offers, if it has any. An enum, a string
+* literal (zod holds a literal's values as a Set, since one can name
+* several), or a union of those: `violationStatusSchema.or(z.literal("all"))`
+* is the shape that makes the union arm worth walking. Anything else has no
+* closed set of values and belongs on a JSON flag.
+*/
+function stringChoices(schema) {
+	const inner = unwrapSchema(schema).schema;
+	if (inner instanceof z.ZodEnum) return [...inner.options].map(String);
+	if (inner instanceof z.ZodLiteral) {
+		const values = [...inner.values];
+		return values.every((value) => typeof value === "string") ? values : void 0;
 	}
 	if (inner instanceof z.ZodUnion) {
 		const choices = [];
@@ -11790,6 +12312,51 @@ function registerContractCommands(program, run) {
 	}
 }
 
+//#endregion
+//#region src/commands/seen.ts
+function pad$1(text, width) {
+	return text.padEnd(width);
+}
+/**
+* The block, as lines, or nothing at all when every name has arrived at
+* least once. Leads with a blank line, the way the other sections of
+* `cow status` do, so a caller can splice it onto whatever it printed.
+*
+* Patterns are printed as the author wrote them (`order.*`, never an
+* expansion), each beside the journeys and segments that named it: those are
+* what stay quiet.
+*/
+function unseenLines(events, answers) {
+	const never = new Set(answers.filter((answer) => answer.lastSeenAt === null).map((answer) => answer.name));
+	const unseen = events.filter((event) => never.has(event.pattern));
+	if (unseen.length === 0) return [];
+	const width = Math.max(...unseen.map((event) => event.pattern.length));
+	return [
+		"",
+		"Nothing has sent these events yet, so what waits on them stays quiet:",
+		...unseen.map((event) => `  ${pad$1(event.pattern, width)}  ${event.usedBy.join(", ")}`)
+	];
+}
+/**
+* Ask the server about a tree's event names and render the answer. A tree
+* that names none skips the call.
+*
+* A failed call prints nothing rather than failing its command: this is a
+* warning beside work that has already happened, and a journey that was just
+* turned on is turned on whether or not the remark about it arrives.
+*/
+async function unseenReport(client, appId, events) {
+	if (events.length === 0) return [];
+	try {
+		return unseenLines(events, (await client.request(contract.events["apps.events.seen"], {
+			params: { appId },
+			query: { name: events.map((event) => event.pattern) }
+		})).data.names);
+	} catch {
+		return [];
+	}
+}
+
 //#endregion
 //#region src/commands/enable.ts
 /**
@@ -11845,6 +12412,31 @@ function flipSummary(journeys, status) {
 	if (journeys.length === 0) return `This app has no journeys to put ${STATE_WORD[status]}.`;
 	return journeys.map((journey) => [`${journey.key} is ${STATE_WORD[status]}.`, ...segmentLines(journey)].join("\n")).join("\n");
 }
+/**
+* What the journeys just turned on are waiting on and have never arrived.
+* Only on the way on: a journey going off or on hold is not about to miss
+* anything.
+*
+* Read off the tree in front of the developer, because that is where the
+* names come from; a directory that is not a project, or one that does not
+* build, names none and the remark is simply absent rather than wrong. A
+* journey enrolling from a `segments/` file waits through that file, so the
+* segment's own key joins the set the events are filtered by.
+*/
+async function unseenForKeys(client, keys) {
+	const dir = process.cwd();
+	const project = await assertCowConfig(dir).then(async (config) => ({
+		config,
+		built: await buildProject(dir)
+	})).catch(() => null);
+	if (!project) return [];
+	const waiting = new Set(keys);
+	for (const journey of project.built.manifest.journeys) {
+		const segment = waiting.has(journey.key) ? triggerSegmentName(journey.key, journey.trigger) : null;
+		if (segment) waiting.add(segment);
+	}
+	return unseenReport(client, project.config.appId, project.built.manifest.events.filter((event) => event.usedBy.some((key) => waiting.has(key))));
+}
 const DESCRIPTIONS = {
 	on: "turn journeys on",
 	off: "turn journeys off",
@@ -11859,12 +12451,14 @@ function register(program, clientFor, io, verb, status) {
 		if (merged.all === true && keys.length > 0) throw new Error(`Name the journeys or pass --all, not both: cow ${verb} welcome.`);
 		if (merged.all !== true && keys.length === 0) throw new Error(`Name at least one journey, or pass --all: cow ${verb} welcome.`);
 		const selector = merged.all === true ? { appId: (await assertCowConfig(process.cwd())).appId } : { keys };
-		const updated = await setStatus(await clientFor(merged), selector, status);
+		const client = await clientFor(merged);
+		const updated = await setStatus(client, selector, status);
 		if (merged.json === true) {
 			emit({ data: updated }, io, true);
 			return;
 		}
-		io.stdout(`${flipSummary(updated, status)}\n`);
+		const unseen = status === "on" ? await unseenForKeys(client, updated.map((journey) => journey.key)) : [];
+		io.stdout(`${[flipSummary(updated, status), ...unseen].join("\n")}\n`);
 	});
 }
 function registerEnable(program, clientFor, io) {
@@ -11956,7 +12550,7 @@ async function chooseApp(client, webUrl, flag, org, io, skipPrompts) {
 	return { appId: await ask("App id", only ?? "", io, false) };
 }
 function registerInit(program, clientFor, env, io) {
-	program.command("init").argument("[dir]", "directory to create the repo in (default: here)").description("create a cow repo: cow.json, journeys/, emails/, and the files to build them").option("--org <id>", "organization id (default: the logged-in org)").option("--app <id>", "app id this repository pushes to (default: ask, or the org's only one)").option("--yes", "accept the defaults instead of prompting").option("--example <name>", "start from a gallery example").action(async (dirArg, opts) => {
+	program.command("init").argument("[dir]", "directory to create the repo in (default: here)").description("create a cow repo: cow.json, journeys/, emails/, segments/, and the files to build them").option("--org <id>", "organization id (default: the logged-in org)").option("--app <id>", "app id this repository pushes to (default: ask, or the org's only one)").option("--yes", "accept the defaults instead of prompting").option("--blueprint <name>", "start from a gallery blueprint").action(async (dirArg, opts) => {
 		const merged = {
 			...program.opts(),
 			...opts
@@ -11966,7 +12560,7 @@ function registerInit(program, clientFor, env, io) {
 		const defaultName = basename(dirArg ? resolve(cwd, dirArg) : cwd);
 		const name = await ask("Repo name", defaultName, io, skipPrompts);
 		const dir = dirArg ? resolve(cwd, dirArg) : name === defaultName ? cwd : resolve(cwd, name);
-		if (existsSync(join(dir, "cow.json"))) throw new Error(`"${dir}" already holds a cow.json. Use \`cow add example\` to add code to it.`);
+		if (existsSync(join(dir, "cow.json"))) throw new Error(`"${dir}" already holds a cow.json. Use \`cow add blueprint\` to add code to it.`);
 		const credentials = await readCredentials(env);
 		const claimedOrg = credentials ? decodeSessionToken(credentials.token)?.orgId ?? null : null;
 		const orgId = typeof opts.org === "string" && opts.org !== "" ? opts.org : await ask("Organization id", claimedOrg ?? "", io, skipPrompts);
@@ -11994,19 +12588,21 @@ function registerInit(program, clientFor, env, io) {
 				include: [
 					"journeys",
 					"emails",
+					"segments",
 					".cow/types.d.ts"
 				]
 			}),
 			".gitignore": ".cow/\nnode_modules/\n",
 			"journeys/.gitkeep": "",
-			"emails/.gitkeep": ""
+			"emails/.gitkeep": "",
+			"segments/.gitkeep": ""
 		};
 		for (const [file, body] of Object.entries(contents)) {
 			await mkdir(dirname(join(dir, file)), { recursive: true });
 			await writeFile(join(dir, file), body, "utf8");
 		}
-		const example = typeof opts.example === "string" ? opts.example : void 0;
-		const files = [...Object.keys(contents), ...example ? await copyExample(example, dir, false) : []].sort();
+		const blueprint = typeof opts.blueprint === "string" ? opts.blueprint : void 0;
+		const files = [...Object.keys(contents), ...blueprint ? await copyBlueprint(blueprint, dir, false) : []].sort();
 		emit({ data: {
 			dir,
 			orgId,
@@ -12015,6 +12611,7 @@ function registerInit(program, clientFor, env, io) {
 		} }, io, merged.json);
 		const here = relative(cwd, dir) || ".";
 		const scenario = files.find((file) => file.startsWith("scenarios/")) ?? "scenarios/abandoned-checkout.timeout.json";
+		const journey = scenario.slice(10).split(".")[0] ?? "abandoned-checkout";
 		const appLine = app.appId === "" ? `No app named yet (${app.reason}). Put its id in cow.json's "appId"; you will find it on the app's page at ${webUrl}/apps.` : `Pushes to ${app.appId}`;
 		io.stderr([
 			`Created a cow repo in ${here}`,
@@ -12023,41 +12620,510 @@ function registerInit(program, clientFor, env, io) {
 			"Next steps:",
 			`  cd ${here}`,
 			"  npm install",
-			...example ? [] : ["  cow add example abandoned-checkout"],
+			...blueprint ? [] : ["  cow add blueprint abandoned-checkout"],
 			"  cow build",
-			`  cow test ${example ?? "abandoned-checkout"} --scenario ${scenario}`,
+			`  cow test ${journey} --scenario ${scenario}`,
 			""
 		].join("\n"));
 	});
 }
 
 //#endregion
-//#region src/commands/mcp/tools.ts
+//#region src/commands/status.ts
 /**
-* The fields of a request part. The container is unwrapped, its fields are
-* not: a field's `.optional()` and `.default()` wrappers are what the MCP
-* SDK parses tool arguments against.
+* `cow status`: what the server holds for every key of this app, and how far
+* the tree in front of the developer has moved from it. Hand-written rather
+* than derived from `apps.status`, because the drift is the half of the
+* answer no server read can know: it comes from building the repository
+* here and comparing the bundle digests with the versions the server has.
+*/
+/** Largest first: the first unit the gap fills is the one that reads best. */
+const UNITS = [
+	["year", 31536e6],
+	["month", 2592e6],
+	["week", 6048e5],
+	["day", 864e5],
+	["hour", 36e5],
+	["minute", 6e4],
+	["second", 1e3]
+];
+const relative$1 = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
+/** The gap between an instant and now, in words. */
+function ago(value, now) {
+	const gap = new Date(value).getTime() - now.getTime();
+	for (const [unit, ms] of UNITS) if (Math.abs(gap) >= ms) return relative$1.format(Math.round(gap / ms), unit);
+	return relative$1.format(0, "second");
+}
+/**
+* The drift, computed by the one comparison there is (`pushPlan`, ADR
+* 0025), so what `cow status` calls changed and what `cow push` calls
+* changed can never be two different things.
 *
-* Unwrapping the container is deliberate, and a change from the generated
-* table this replaced: `mcpToolFor` derives `paramsKeys`/`queryKeys` through
-* the same unwrap, so a wrapped container used to yield keys that `toInput`
-* would pick but that the tool never declared. No route wraps one today.
+* Segments are left out of both sides: `apps.status` reports the keys that
+* run, and a segment is a row rather than a version, so the server read
+* behind this command does not carry them. `cow push` plans over all three.
 */
-function shapeOf(schema) {
-	const inner = schema instanceof z.ZodType ? unwrapSchema(schema).schema : void 0;
-	return inner instanceof z.ZodObject ? inner.shape : {};
+function driftOf(status, manifest) {
+	const served = status.keys.map((entry) => ({
+		...entry.latestVersion ? entrySide(entry.kind, entry.latestVersion.manifest) : {
+			kind: entry.kind,
+			key: entry.key,
+			fields: {}
+		},
+		onHold: entry.status === "paused"
+	}));
+	return pushPlan(status.appId, manifestSides({
+		...manifest,
+		segments: []
+	}), served);
 }
-function pick(args, keys) {
-	const picked = {};
-	for (const key of keys) {
-		const value = args[key];
-		if (value !== void 0) picked[key] = value;
-	}
-	return picked;
+/**
+* The version's short name. The bundle digest rather than the compiled
+* module's, because a version is one bundle (a push that carries a bundle
+* the org already holds creates no second version) and the bundle is there
+* from the moment the push lands, while the module digest arrives only when
+* the compile finishes.
+*/
+function shortDigest(bundle) {
+	return bundle.replace("sha256:", "").slice(0, 8);
 }
-function defineTool(spec) {
-	const data = bodyDataSchema(spec.route);
-	const bodyShape = data === void 0 ? {} : data instanceof z.ZodObject ? data.shape : { data };
+function bundleOf(entry) {
+	const manifest = entry.latestVersion?.manifest;
+	return manifest ? manifest.bundle : null;
+}
+/** "version 3f2a1b9c, pushed 2 hours ago, still compiling" */
+function versionPhrase(entry, now) {
+	const version = entry.latestVersion;
+	if (!version) return "no version yet";
+	const state = version.status === "compiling" ? ", still compiling" : version.status === "failed" ? ", did not compile" : "";
+	const bundle = bundleOf(entry);
+	return `${bundle ? `version ${shortDigest(bundle)}` : "version"}, pushed ${ago(version.pushedAt, now)}${state}`;
+}
+function flagsPhrase(entry) {
+	return entry.status === null ? "" : entry.status === "paused" ? "on hold" : entry.status;
+}
+function livePhrase(entry) {
+	return entry.liveExecutions === 0 ? "" : `${entry.liveExecutions} running`;
+}
+function pad(text, width) {
+	return text.padEnd(width);
+}
+/**
+* The whole report, as lines. Pure so a test can read it: everything it
+* needs is the server's answer, the local build, and the clock.
+*
+* A null manifest is a tree that did not build. What the server runs is
+* still the answer to most of the question, so the report keeps it and drops
+* only the comparison.
+*/
+function statusLines(status, manifest, now) {
+	const journeys = status.keys.filter((entry) => entry.kind === "journey");
+	const templates = status.keys.filter((entry) => entry.kind === "template");
+	const lines = [`${status.appId}: ${journeys.length} ${journeys.length === 1 ? "journey" : "journeys"}, ${templates.length} ${templates.length === 1 ? "template" : "templates"} on the server.`];
+	const width = Math.max(0, ...status.keys.map((entry) => entry.key.length));
+	const section = (title, entries) => {
+		if (entries.length === 0) return;
+		const flagWidth = Math.max(0, ...entries.map((entry) => flagsPhrase(entry).length));
+		lines.push("", title);
+		for (const entry of entries) {
+			const flags = flagsPhrase(entry);
+			const live = livePhrase(entry);
+			const rest = [
+				...flags === "" ? [] : [pad(flags, flagWidth)],
+				versionPhrase(entry, now),
+				...live === "" ? [] : [live]
+			];
+			lines.push(`  ${pad(entry.key, width)}  ${rest.join("   ")}`.trimEnd());
+		}
+	};
+	section("Journeys", journeys);
+	section("Templates", templates);
+	if (!manifest) {
+		lines.push("", "This tree did not build, so nothing here is compared with it. Run cow build to see why.");
+		return lines;
+	}
+	const plan = driftOf(status, manifest);
+	const changed = plan.entries.filter((entry) => entry.change !== "unchanged");
+	const missing = plan.drift.filter((one) => one.reason === "not-in-tree");
+	if (changed.length > 0) lines.push("", `Changed here since the last push: ${changed.map((entry) => entry.key).join(", ")}. Run cow push.`);
+	if (missing.length > 0) {
+		lines.push("", "On the server and not in this tree:");
+		for (const entry of missing) lines.push(`  ${entry.key}, a ${entry.kind}. Delete it with cow ${entry.kind}s delete ${entry.key}.`);
+	}
+	if (status.warnings.length > 0) {
+		lines.push("", "Names this organization does not define yet:");
+		for (const warning of status.warnings) lines.push(`  ${warning}`);
+	}
+	return lines;
+}
+/** The app's status from the server, for this directory's `cow.json`. */
+async function readStatus(client, appId) {
+	return (await client.request(contract.apps["apps.status"], { params: { id: appId } })).data;
+}
+function registerStatus(program, clientFor, io) {
+	program.command("status").description("what this app's journeys and templates are doing, and what changed here since the last push").action(async (opts) => {
+		const merged = {
+			...program.opts(),
+			...opts
+		};
+		const config = await assertCowConfig(process.cwd());
+		const built = await buildProject(process.cwd()).catch(() => null);
+		const client = await clientFor(merged);
+		const status = await readStatus(client, config.appId);
+		if (merged.json === true) {
+			emit({ data: status }, io, true);
+			return;
+		}
+		const unseen = await unseenReport(client, config.appId, built?.manifest.events ?? []);
+		io.stdout(`${[...statusLines(status, built?.manifest ?? null, /* @__PURE__ */ new Date()), ...unseen].join("\n")}\n`);
+	});
+}
+
+//#endregion
+//#region src/commands/push.ts
+/** Does the org already hold these bytes? A 404 is the answer, not a failure. */
+async function held(client, digest) {
+	try {
+		await client.request(contract.artifacts["artifacts.head"], { params: { digest } });
+		return true;
+	} catch (error) {
+		if (error instanceof ApiError && error.status === 404) return false;
+		throw error;
+	}
+}
+/** Every artifact the manifest names, and the file `cow build` wrote it to. */
+function artifactFiles(projectDir, manifest) {
+	const out = join(projectDir, BUILD_DIR);
+	return [
+		...manifest.journeys.map((journey) => ({
+			digest: journey.bundle,
+			kind: "bundle",
+			file: join(out, "bundles", "journeys", `${journey.key}.js`)
+		})),
+		...manifest.templates.map((template) => ({
+			digest: template.bundle,
+			kind: "bundle",
+			file: join(out, "bundles", "emails", `${template.key}.js`)
+		})),
+		{
+			digest: manifest.source,
+			kind: "source",
+			file: join(out, "source.tgz")
+		}
+	];
+}
+/**
+* The body both `pushes.plan` and `pushes.create` take: the same manifest,
+* asked about and then stored.
+*
+* A stored manifest carries any protocol (a version outlives a bump), so
+* this is the one shape that pins it to the constant. `cow build` wrote
+* exactly that; restating it is what satisfies the literal.
+*/
+function pushBody({ manifest, config }, prune = false) {
+	return {
+		manifest: {
+			...manifest,
+			protocol: 3
+		},
+		prune,
+		appId: config.appId,
+		orgId: config.orgId
+	};
+}
+/**
+* What a push of this tree would change, having changed nothing. The build
+* comes back with it so the push that follows a confirmed plan uploads the
+* bundles that were planned rather than rebuilding and finding others.
+*/
+async function planProject({ client, projectDir }) {
+	const built = await buildProject(projectDir);
+	return {
+		plan: (await client.request(contract.pushes["pushes.plan"], { body: pushBody(built) })).data,
+		built
+	};
+}
+async function pushProject({ client, projectDir, built, prune }) {
+	const build = built ?? await buildProject(projectDir);
+	const { manifest } = build;
+	const uploaded = [];
+	for (const artifact of artifactFiles(projectDir, manifest)) {
+		if (await held(client, artifact.digest)) continue;
+		await client.request(contract.artifacts["artifacts.put"], {
+			params: { digest: artifact.digest },
+			query: { kind: artifact.kind },
+			body: await readFile(artifact.file)
+		});
+		uploaded.push(artifact.digest);
+	}
+	return {
+		push: (await client.request(contract.pushes["pushes.create"], { body: pushBody(build, prune) })).data,
+		uploaded
+	};
+}
+/**
+* The human report: what was stored, and one line per changed key with the
+* page that key now has on the dashboard. A key whose code did not change
+* gets no new version, so a push of an unchanged tree says exactly that.
+*/
+function pushSummary(outcome, webUrl) {
+	const { push } = outcome;
+	const uploaded = outcome.uploaded.length === 0 ? "nothing new to upload" : `${outcome.uploaded.length} artifact${outcome.uploaded.length === 1 ? "" : "s"} uploaded`;
+	const stored = `Push #${push.seq} stored (${uploaded}).`;
+	if (push.versions.length === 0) return `${stored} Nothing changed.`;
+	const width = Math.max(...push.versions.map((version) => version.key.length));
+	return [`${stored} Compiling ${push.versions.length} ${push.versions.length === 1 ? "key" : "keys"}:`, ...push.versions.map((version) => `  ${version.key.padEnd(width)}  ${webUrl}/${version.kind === "journey" ? "journeys" : "deliveries/templates"}/${version.key}`)].join("\n");
+}
+const MARK = {
+	added: "+",
+	changed: "~",
+	unchanged: " "
+};
+const DRIFT = {
+	"not-in-tree": "on the server, not in this tree",
+	"on-hold": "on hold; this leaves it that way"
+};
+/**
+* The plan as a developer reads it: one line per key, marked `+` for a key
+* the account does not have and `~` for one this tree moves, with the
+* fields that moved named beside it. Pure, so a test reads it and so `cow
+* plan` can print the same thing without pushing.
+*/
+function planLines(plan) {
+	const lines = [`Plan for ${plan.appId}:`, ""];
+	const width = Math.max(0, ...[...plan.entries, ...plan.drift].map((one) => one.key.length));
+	const row = (kind, key, mark, rest) => `${mark} ${kind.padEnd(8)}  ${key.padEnd(width)}  ${rest}`.trimEnd();
+	for (const entry of plan.entries) lines.push(row(entry.kind, entry.key, MARK[entry.change], entry.fields.join(", ")));
+	const count = (change) => plan.entries.filter((entry) => entry.change === change).length;
+	const [added, changed] = [count("added"), count("changed")];
+	lines.push("", added + changed === 0 ? "Nothing to change." : `${added} to add, ${changed} to change, ${count("unchanged")} unchanged.`);
+	if (plan.drift.length > 0) {
+		lines.push("", "Left alone:");
+		for (const one of plan.drift) lines.push(row(one.kind, one.key, " ", DRIFT[one.reason]));
+	}
+	return lines;
+}
+/**
+* What `--prune` acts on: drift this tree no longer carries. The other
+* drift reason (`on-hold`) is a journey the tree still has, and templates
+* are excluded outright — a live execution pins the template version it
+* started on, and the version prune sweep already owns their lifecycle.
+*/
+function prunable(plan) {
+	return plan.drift.filter((one) => one.reason === "not-in-tree" && one.kind !== "template");
+}
+/** The drift `--prune` would delete, with what the server says it costs. */
+function priced(drift, status) {
+	return drift.map((one) => {
+		const served = status.keys.find((entry) => entry.kind === "journey" && entry.key === one.key);
+		return {
+			kind: one.kind === "segment" ? "segment" : "journey",
+			key: one.key,
+			status: one.kind === "segment" ? null : served?.status ?? null,
+			liveExecutions: one.kind === "segment" ? 0 : served?.liveExecutions ?? 0
+		};
+	});
+}
+/** How many live runs the whole prune ends. */
+function liveTotal(doomed) {
+	return doomed.reduce((sum, one) => sum + one.liveExecutions, 0);
+}
+const runs = (count) => `${count} live run${count === 1 ? "" : "s"}`;
+/**
+* The bill, printed before the question and before anything is deleted:
+* one line per thing, with the journey's state and the runs it is carrying,
+* and the total underneath. Pure, so a test reads it.
+*/
+function pruneLines(doomed) {
+	const width = Math.max(...doomed.map((one) => one.key.length));
+	const total = liveTotal(doomed);
+	return [
+		"",
+		"No longer in this tree, so --prune deletes:",
+		"",
+		...doomed.map((one) => `- ${one.kind.padEnd(7)}  ${one.key.padEnd(width)}  ${one.kind === "segment" ? "" : `${one.status ?? "unknown"}  ${runs(one.liveExecutions)}`}`.trimEnd()),
+		"",
+		total === 0 ? "Nothing is running on any of them." : `${runs(total)} end the moment this is applied.`
+	];
+}
+/**
+* The refusal an unattended prune gets when the plan both adds and deletes,
+* which is what a renamed file looks like (ADR 0024). Not a heuristic: no
+* digest is compared and no pair is guessed, because two journeys may
+* legitimately share a bundle and a matching digest proves nothing. It is
+* the shape of the plan that is refused, and only when nobody is watching.
+*/
+function renameRefusal(added, doomed) {
+	const names = (ones) => ones.map((one) => `${one.kind} ${one.key}`).join(", ");
+	return [
+		"Nothing was pushed: this plan both adds and deletes, which is what renaming a file looks like,",
+		"and an unattended run is exactly where nobody reads the live-run count.",
+		`  adds:    ${names(added)}`,
+		`  deletes: ${names(doomed)}`,
+		`Confirm it yourself — run \`cow push --prune\` without --yes and answer the prompt — or split the`,
+		"rename into two pushes: push the new file, then prune once it is live."
+	].join("\n");
+}
+/**
+* Delete the journeys this tree dropped, through the two verbs that already
+* exist rather than a second destructive path: stop what is running, then
+* delete the journey. Both are a person's call and neither is on a pipeline
+* key's list, which is why the refusal says so in words.
+*
+* Sequential, and after the push: the tree that replaces them is stored
+* first, so a push that turns out to be invalid has destroyed nothing.
+*/
+async function pruneJourneys(client, doomed) {
+	for (const one of doomed) try {
+		if (one.liveExecutions > 0) await client.request(contract.executions["executions.cancel"], { body: { journey: one.key } });
+		await client.request(contract.journeys["journeys.delete"], { params: { key: one.key } });
+	} catch (error) {
+		if (error instanceof ApiError && (error.status === 401 || error.status === 403)) throw new Error(`The push landed, but "${one.key}" was not deleted: ending runs that are carrying real people takes a signed-in developer, not a deploy key. Run \`cow login\`, then \`cow push --prune\` again to finish it.`);
+		throw error;
+	}
+}
+/** One line for what went, after the push report. */
+function pruneSummary(doomed) {
+	return `Deleted ${doomed.map((one) => `${one.kind} ${one.key}`).join(", ")}.`;
+}
+/** Ask on the terminal. The question goes to stderr, like every other prompt. */
+async function confirm(question) {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stderr
+	});
+	try {
+		return /^y(es)?$/i.test((await rl.question(`${question} `)).trim());
+	} finally {
+		rl.close();
+	}
+}
+function registerPush(program, clientFor, env, io) {
+	program.command("push").description("show what this repository would change, then upload it once you agree").option("--yes", "apply without asking; what a pipeline passes").option("--prune", "also delete the journeys and segments this app has and this tree does not").action(async (opts) => {
+		const merged = {
+			...program.opts(),
+			...opts
+		};
+		const client = await clientFor(merged);
+		const projectDir = process.cwd();
+		const json = merged.json === true;
+		const { plan, built } = await planProject({
+			client,
+			projectDir
+		});
+		(json ? io.stderr : io.stdout)(`${planLines(plan).join("\n")}\n`);
+		const unseen = await unseenReport(client, plan.appId, built.manifest.events);
+		if (unseen.length > 0) (json ? io.stderr : io.stdout)(`${unseen.join("\n")}\n`);
+		const prune = merged.prune === true;
+		const drift = prune ? prunable(plan) : [];
+		const doomed = drift.length > 0 ? priced(drift, await readStatus(client, plan.appId)) : [];
+		if (doomed.length > 0) (json ? io.stderr : io.stdout)(`${pruneLines(doomed).join("\n")}\n`);
+		const added = plan.entries.filter((one) => one.change === "added");
+		if (merged.yes === true && doomed.length > 0 && added.length > 0) throw new Error(renameRefusal(added, doomed));
+		if ((plan.entries.some((one) => one.change !== "unchanged") || doomed.length > 0) && merged.yes !== true) {
+			if (!io.isTTY) throw new Error("Nothing was pushed: there is no terminal here to agree on. Re-run with --yes to push what this plan shows.");
+			if (!await confirm(doomed.length > 0 ? "Push this and delete those? [y/N]" : "Push this? [y/N]")) {
+				if (json) emit({ data: {
+					plan,
+					push: null,
+					pruned: []
+				} }, io, true);
+				else io.stdout("Nothing was pushed.\n");
+				return;
+			}
+		}
+		const outcome = await pushProject({
+			client,
+			projectDir,
+			built,
+			prune
+		});
+		await pruneJourneys(client, doomed.filter((one) => one.kind === "journey"));
+		if (json) {
+			emit({ data: {
+				plan,
+				push: outcome.push,
+				pruned: doomed.map((one) => ({
+					kind: one.kind,
+					key: one.key
+				}))
+			} }, io, true);
+			return;
+		}
+		const webUrl = resolveWebUrl(env, built.config.webUrl);
+		io.stdout(`${pushSummary(outcome, webUrl)}\n`);
+		if (doomed.length > 0) io.stdout(`${pruneSummary(doomed)}\n`);
+	});
+}
+
+//#endregion
+//#region src/commands/plan.ts
+/**
+* `cow plan` (ADR 0025): the read-only half of `cow push`. It builds, asks
+* the server what a push of this tree would change, prints it, and stops.
+* Nothing is uploaded and nothing is stored, so it is the one push verb that
+* costs an account nothing to run.
+*
+* Everything it prints is `cow push`'s: the comparison is the server's
+* (`pushes.plan`), the renderer is `planLines`, and the warning under it is
+* `unseenReport`. There is no second computation that could drift from the
+* one the push itself shows.
+*/
+/** The envelope `cow plan --json` prints, and what the MCP tool answers. */
+async function projectPlan(client) {
+	const { plan } = await planProject({
+		client,
+		projectDir: process.cwd()
+	});
+	return { data: plan };
+}
+function registerPlan(program, clientFor, io) {
+	program.command("plan").description("show what a push of this repository would change, and change nothing").action(async (opts) => {
+		const merged = {
+			...program.opts(),
+			...opts
+		};
+		const client = await clientFor(merged);
+		const { plan, built } = await planProject({
+			client,
+			projectDir: process.cwd()
+		});
+		if (merged.json === true) {
+			emit({ data: plan }, io, true);
+			return;
+		}
+		const unseen = await unseenReport(client, plan.appId, built.manifest.events);
+		io.stdout(`${[...planLines(plan), ...unseen].join("\n")}\n`);
+	});
+}
+
+//#endregion
+//#region src/commands/mcp/tools.ts
+/**
+* The fields of a request part. The container is unwrapped, its fields are
+* not: a field's `.optional()` and `.default()` wrappers are what the MCP
+* SDK parses tool arguments against.
+*
+* Unwrapping the container is deliberate, and a change from the generated
+* table this replaced: `mcpToolFor` derives `paramsKeys`/`queryKeys` through
+* the same unwrap, so a wrapped container used to yield keys that `toInput`
+* would pick but that the tool never declared. No route wraps one today.
+*/
+function shapeOf(schema) {
+	const inner = schema instanceof z.ZodType ? unwrapSchema(schema).schema : void 0;
+	return inner instanceof z.ZodObject ? inner.shape : {};
+}
+function pick(args, keys) {
+	const picked = {};
+	for (const key of keys) {
+		const value = args[key];
+		if (value !== void 0) picked[key] = value;
+	}
+	return picked;
+}
+function defineTool(spec) {
+	const data = bodyDataSchema(spec.route);
+	const bodyShape = data === void 0 ? {} : data instanceof z.ZodObject ? data.shape : { data };
 	return {
 		name: spec.name,
 		description: spec.description,
@@ -12084,11 +13150,23 @@ function planTools() {
 
 //#endregion
 //#region src/commands/mcp/server.ts
-/**
-* The cow MCP server: every admin/read capability of the dashboard API as
-* a native tool. The tool table (tools.ts) is planned from the shared route
-* contract at startup, so the surface cannot drift from the API.
-*/
+/** One tool call: the JSON it answered with, or the refusal it hit. */
+async function toolResult(run) {
+	try {
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(await run())
+		}] };
+	} catch (error) {
+		return {
+			content: [{
+				type: "text",
+				text: errorMessage$1(error)
+			}],
+			isError: true
+		};
+	}
+}
 async function createMcpServer({ client }) {
 	const { version } = await readCliPackage();
 	const server = new McpServer({
@@ -12099,23 +13177,11 @@ async function createMcpServer({ client }) {
 	for (const tool of planTools()) server.registerTool(tool.name, {
 		description: tool.description,
 		inputSchema: tool.inputSchema
-	}, async (args) => {
-		try {
-			const envelope = tool.route.request ? await request(tool.route, tool.toInput(args)) : await request(tool.route);
-			return { content: [{
-				type: "text",
-				text: JSON.stringify(envelope)
-			}] };
-		} catch (error) {
-			return {
-				content: [{
-					type: "text",
-					text: errorMessage$1(error)
-				}],
-				isError: true
-			};
-		}
-	});
+	}, async (args) => toolResult(() => tool.route.request ? request(tool.route, tool.toInput(args)) : request(tool.route)));
+	server.registerTool("pushes_plan", {
+		description: "What a push of the project in the current directory would change. Builds locally; uploads and stores nothing.",
+		inputSchema: {}
+	}, async () => toolResult(() => projectPlan(client)));
 	return server;
 }
 function errorMessage$1(error) {
@@ -12251,235 +13317,6 @@ function registerPull(program, clientFor, io) {
 	});
 }
 
-//#endregion
-//#region src/commands/push.ts
-/** Does the org already hold these bytes? A 404 is the answer, not a failure. */
-async function held(client, digest) {
-	try {
-		await client.request(contract.artifacts["artifacts.head"], { params: { digest } });
-		return true;
-	} catch (error) {
-		if (error instanceof ApiError && error.status === 404) return false;
-		throw error;
-	}
-}
-/** Every artifact the manifest names, and the file `cow build` wrote it to. */
-function artifactFiles(projectDir, manifest) {
-	const out = join(projectDir, BUILD_DIR);
-	return [
-		...manifest.journeys.map((journey) => ({
-			digest: journey.bundle,
-			kind: "bundle",
-			file: join(out, "bundles", "journeys", `${journey.key}.js`)
-		})),
-		...manifest.templates.map((template) => ({
-			digest: template.bundle,
-			kind: "bundle",
-			file: join(out, "bundles", "emails", `${template.key}.js`)
-		})),
-		{
-			digest: manifest.source,
-			kind: "source",
-			file: join(out, "source.tgz")
-		}
-	];
-}
-async function pushProject({ client, projectDir }) {
-	const { manifest, config } = await buildProject(projectDir);
-	const uploaded = [];
-	for (const artifact of artifactFiles(projectDir, manifest)) {
-		if (await held(client, artifact.digest)) continue;
-		await client.request(contract.artifacts["artifacts.put"], {
-			params: { digest: artifact.digest },
-			query: { kind: artifact.kind },
-			body: await readFile(artifact.file)
-		});
-		uploaded.push(artifact.digest);
-	}
-	return {
-		push: (await client.request(contract.pushes["pushes.create"], { body: {
-			manifest: {
-				...manifest,
-				protocol: 3
-			},
-			appId: config.appId,
-			orgId: config.orgId
-		} })).data,
-		uploaded
-	};
-}
-/**
-* The human report: what was stored, and one line per changed key with the
-* page that key now has on the dashboard. A key whose code did not change
-* gets no new version, so a push of an unchanged tree says exactly that.
-*/
-function pushSummary(outcome, webUrl) {
-	const { push } = outcome;
-	const uploaded = outcome.uploaded.length === 0 ? "nothing new to upload" : `${outcome.uploaded.length} artifact${outcome.uploaded.length === 1 ? "" : "s"} uploaded`;
-	const stored = `Push #${push.seq} stored (${uploaded}).`;
-	if (push.versions.length === 0) return `${stored} Nothing changed.`;
-	const width = Math.max(...push.versions.map((version) => version.key.length));
-	return [`${stored} Compiling ${push.versions.length} ${push.versions.length === 1 ? "key" : "keys"}:`, ...push.versions.map((version) => `  ${version.key.padEnd(width)}  ${webUrl}/${version.kind === "journey" ? "journeys" : "deliveries/templates"}/${version.key}`)].join("\n");
-}
-function registerPush(program, clientFor, env, io) {
-	program.command("push").description("build this repository and upload it; the server compiles what changed").action(async (opts) => {
-		const merged = {
-			...program.opts(),
-			...opts
-		};
-		const outcome = await pushProject({
-			client: await clientFor(merged),
-			projectDir: process.cwd()
-		});
-		if (merged.json === true) {
-			emit({ data: outcome.push }, io, true);
-			return;
-		}
-		const webUrl = resolveWebUrl(env, (await readCowConfig(process.cwd()))?.webUrl);
-		io.stdout(`${pushSummary(outcome, webUrl)}\n`);
-	});
-}
-
-//#endregion
-//#region src/commands/status.ts
-/**
-* `cow status`: what the server holds for every key of this app, and how far
-* the tree in front of the developer has moved from it. Hand-written rather
-* than derived from `apps.status`, because the drift is the half of the
-* answer no server read can know: it comes from building the repository
-* here and comparing the bundle digests with the versions the server has.
-*/
-/** Largest first: the first unit the gap fills is the one that reads best. */
-const UNITS = [
-	["year", 31536e6],
-	["month", 2592e6],
-	["week", 6048e5],
-	["day", 864e5],
-	["hour", 36e5],
-	["minute", 6e4],
-	["second", 1e3]
-];
-const relative$1 = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
-/** The gap between an instant and now, in words. */
-function ago(value, now) {
-	const gap = new Date(value).getTime() - now.getTime();
-	for (const [unit, ms] of UNITS) if (Math.abs(gap) >= ms) return relative$1.format(Math.round(gap / ms), unit);
-	return relative$1.format(0, "second");
-}
-function localKeys(manifest) {
-	return [...manifest.journeys.map((journey) => ({
-		kind: "journey",
-		key: journey.key,
-		bundle: journey.bundle
-	})), ...manifest.templates.map((template) => ({
-		kind: "template",
-		key: template.key,
-		bundle: template.bundle
-	}))];
-}
-/**
-* The version's short name. The bundle digest rather than the compiled
-* module's, because a version is one bundle (a push that carries a bundle
-* the org already holds creates no second version) and the bundle is there
-* from the moment the push lands, while the module digest arrives only when
-* the compile finishes.
-*/
-function shortDigest(bundle) {
-	return bundle.replace("sha256:", "").slice(0, 8);
-}
-function bundleOf(entry) {
-	const manifest = entry.latestVersion?.manifest;
-	return manifest ? manifest.bundle : null;
-}
-/** "version 3f2a1b9c, pushed 2 hours ago, still compiling" */
-function versionPhrase(entry, now) {
-	const version = entry.latestVersion;
-	if (!version) return "no version yet";
-	const state = version.status === "compiling" ? ", still compiling" : version.status === "failed" ? ", did not compile" : "";
-	const bundle = bundleOf(entry);
-	return `${bundle ? `version ${shortDigest(bundle)}` : "version"}, pushed ${ago(version.pushedAt, now)}${state}`;
-}
-function flagsPhrase(entry) {
-	return entry.status === null ? "" : entry.status === "paused" ? "on hold" : entry.status;
-}
-function livePhrase(entry) {
-	return entry.liveExecutions === 0 ? "" : `${entry.liveExecutions} running`;
-}
-function pad(text, width) {
-	return text.padEnd(width);
-}
-/**
-* The whole report, as lines. Pure so a test can read it: everything it
-* needs is the server's answer, the local build, and the clock.
-*
-* A null manifest is a tree that did not build. What the server runs is
-* still the answer to most of the question, so the report keeps it and drops
-* only the comparison.
-*/
-function statusLines(status, manifest, now) {
-	const local = manifest ? localKeys(manifest) : [];
-	const journeys = status.keys.filter((entry) => entry.kind === "journey");
-	const templates = status.keys.filter((entry) => entry.kind === "template");
-	const lines = [`${status.appId}: ${journeys.length} ${journeys.length === 1 ? "journey" : "journeys"}, ${templates.length} ${templates.length === 1 ? "template" : "templates"} on the server.`];
-	const width = Math.max(0, ...status.keys.map((entry) => entry.key.length));
-	const section = (title, entries) => {
-		if (entries.length === 0) return;
-		const flagWidth = Math.max(0, ...entries.map((entry) => flagsPhrase(entry).length));
-		lines.push("", title);
-		for (const entry of entries) {
-			const flags = flagsPhrase(entry);
-			const live = livePhrase(entry);
-			const rest = [
-				...flags === "" ? [] : [pad(flags, flagWidth)],
-				versionPhrase(entry, now),
-				...live === "" ? [] : [live]
-			];
-			lines.push(`  ${pad(entry.key, width)}  ${rest.join("   ")}`.trimEnd());
-		}
-	};
-	section("Journeys", journeys);
-	section("Templates", templates);
-	if (!manifest) {
-		lines.push("", "This tree did not build, so nothing here is compared with it. Run cow build to see why.");
-		return lines;
-	}
-	const changed = local.filter((entry) => {
-		const served = status.keys.find((one) => one.kind === entry.kind && one.key === entry.key);
-		return !served || bundleOf(served) !== entry.bundle;
-	});
-	const missing = status.keys.filter((entry) => !local.some((one) => one.kind === entry.kind && one.key === entry.key));
-	if (changed.length > 0) lines.push("", `Changed here since the last push: ${changed.map((entry) => entry.key).join(", ")}. Run cow push.`);
-	if (missing.length > 0) {
-		lines.push("", "On the server and not in this tree:");
-		for (const entry of missing) lines.push(`  ${entry.key}, a ${entry.kind}. Delete it with cow ${entry.kind}s delete ${entry.key}.`);
-	}
-	if (status.warnings.length > 0) {
-		lines.push("", "Names this organization does not define yet:");
-		for (const warning of status.warnings) lines.push(`  ${warning}`);
-	}
-	return lines;
-}
-/** The app's status from the server, for this directory's `cow.json`. */
-async function readStatus(client, appId) {
-	return (await client.request(contract.apps["apps.status"], { params: { id: appId } })).data;
-}
-function registerStatus(program, clientFor, io) {
-	program.command("status").description("what this app's journeys and templates are doing, and what changed here since the last push").action(async (opts) => {
-		const merged = {
-			...program.opts(),
-			...opts
-		};
-		const config = await assertCowConfig(process.cwd());
-		const built = await buildProject(process.cwd()).catch(() => null);
-		const status = await readStatus(await clientFor(merged), config.appId);
-		if (merged.json === true) {
-			emit({ data: status }, io, true);
-			return;
-		}
-		io.stdout(`${statusLines(status, built?.manifest ?? null, /* @__PURE__ */ new Date()).join("\n")}\n`);
-	});
-}
-
 //#endregion
 //#region src/build/simulate.ts
 /**
@@ -12765,6 +13602,7 @@ function buildProgram(env, io) {
 	registerInit(program, clientFor, env, io);
 	registerAdd(program, io);
 	registerBuild(program, io);
+	registerPlan(program, clientFor, io);
 	registerPush(program, clientFor, env, io);
 	registerStatus(program, clientFor, io);
 	registerEnable(program, clientFor, io);
@@ -12819,7 +13657,7 @@ function errorMessage(error) {
 			code: error.code,
 			message: error.message
 		} }, null, 2);
-		if (error.code === "invalid_key") return `${envelope}\n(hint: run \`cow login\` to refresh the session token)`;
+		if (error.code === "invalid_key" && !process.argv.includes("--key")) return `${envelope}\n(hint: run \`cow login\` to refresh the session token)`;
 		return envelope;
 	}
 	if (error instanceof Error) return `error: ${error.message}`;