primitive-admin 1.1.0-alpha.36 → 1.1.0-alpha.38

package/dist/src/commands/sync.js

@@ -11,7 +11,7 @@ import { resolveSyncDir, resolveSnapshotsRoot, isAutoResolvedSyncDir, checkLegac
 import { createSnapshot, listSnapshots, resolveSnapshot, restoreSnapshot, pruneSnapshots, } from "../lib/snapshots.js";
 import { validateWorkflowToml, formatWorkflowTomlErrors, } from "../lib/workflow-toml-validator.js";
 import { expandWorkflowTomlData } from "../lib/workflow-fragments.js";
-import { success, error, info, warn, keyValue, json, divider, } from "../lib/output.js";
+import { success, error, printApiError, info, warn, keyValue, json, divider, } from "../lib/output.js";
 import { confirmPrompt } from "../lib/confirm-prompt.js";
 import chalk from "chalk";
 function ensureDir(dirPath) {
@@ -131,6 +131,74 @@ export function shouldPushExpandedFile(parsed, storedHash) {
         return true;
     return computeExpandedContentHash(parsed) !== storedHash;
 }
+/**
+ * Model defaults for the *exact five* workflow-level fields that
+ * `serializeWorkflow` emits unconditionally (`sync.ts` workflow serializer:
+ * `perUserMaxRunning`, `perUserMaxQueued`, `dequeueOrder`,
+ * `requiresClientApply`, `syncCallable`). These mirror `models.yaml`
+ * (`WorkflowDefinition`): `perUserMaxRunning=4`, `perUserMaxQueued=100`,
+ * `dequeueOrder="fifo"`, `requiresClientApply=true`, `syncCallable=false`.
+ *
+ * This is deliberately NOT a generic models.yaml default importer — the model
+ * carries many defaults the serializer never writes (`perAppMax*`,
+ * `queueTtlSeconds`, …). Only the serializer-emitted surface matters for a
+ * content comparison, because the remote side is hashed via `serializeWorkflow`
+ * and therefore only ever contains these five.
+ */
+const WORKFLOW_SERIALIZER_DEFAULTS = {
+    perUserMaxRunning: 4,
+    perUserMaxQueued: 100,
+    dequeueOrder: "fifo",
+    requiresClientApply: true,
+    syncCallable: false,
+};
+/**
+ * Normalize a parsed workflow TOML object so that any of the five
+ * serializer-emitted fields the *local* file omits are filled in with the
+ * model default. Used by `diff` so a hand-authored workflow that omits e.g.
+ * `perUserMaxRunning` compares equal to a server that defaulted it to 4
+ * (the #1175 false-positive guard) — while a server value that was
+ * *explicitly set* to a non-default (e.g. 8) still shows as Modified.
+ *
+ * Returns a shallow clone with a normalized `workflow` table; the input is
+ * not mutated. Non-workflow TOML (no `workflow` table) is returned unchanged.
+ */
+export function normalizeWorkflowTomlDefaults(parsed) {
+    if (!parsed || typeof parsed !== "object" || !parsed.workflow) {
+        return parsed;
+    }
+    const workflow = { ...parsed.workflow };
+    for (const [field, defaultValue] of Object.entries(WORKFLOW_SERIALIZER_DEFAULTS)) {
+        if (workflow[field] === undefined || workflow[field] === null) {
+            workflow[field] = defaultValue;
+        }
+    }
+    return { ...parsed, workflow };
+}
+/**
+ * Canonical content hash of a workflow TOML for `diff`'s content comparison.
+ * Applies `normalizeWorkflowTomlDefaults` first so omitted-vs-defaulted fields
+ * don't spuriously diff, then runs the same `computeExpandedContentHash` that
+ * pull stores and push compares. Both the local file and the
+ * `serializeWorkflow`-produced remote form flow through this single function,
+ * so the two sides are normalized identically by construction.
+ */
+export function hashWorkflowTomlForDiff(parsed) {
+    return computeExpandedContentHash(normalizeWorkflowTomlDefaults(parsed));
+}
+/**
+ * Build the canonical content hash for a *server* workflow (as returned by
+ * `getWorkflow` + active `getWorkflowConfig`), mirroring exactly what a fresh
+ * `sync pull` would write to disk. Serializes via `serializeWorkflow`, parses
+ * the resulting TOML (remote serialized TOML never carries `include`s, so a
+ * plain `TOML.parse` is sufficient — no fragment path needed), then hashes
+ * through `hashWorkflowTomlForDiff` so it lines up with the local-file hash.
+ */
+export function hashRemoteWorkflowForDiff(workflow, draft, configs) {
+    const serialized = serializeWorkflow(workflow, draft, configs || []);
+    const parsed = TOML.parse(serialized);
+    return hashWorkflowTomlForDiff(parsed);
+}
 // TOML serialization helpers
 function serializeAppSettings(settings) {
     const data = {
@@ -703,17 +771,33 @@ export function parseTestCaseToml(tomlData) {
 /**
  * Pull server-side `Script` rows into `transforms/*.rhai` and record
  * each in the returned sync-state map. Issue #892 slice 7 + codex
- * follow-up on PR #893. Exported so the unit test can drive it
- * against a stubbed `client.listScripts`.
+ * follow-up on PR #893; body materialization fixed in issue #1196.
+ * Exported so the unit test can drive it against stubbed
+ * `client.listScripts` / `client.getScript`.
+ *
+ * Two-call contract: `listScripts` returns the `Script` HEADER only
+ * (no `body` — see `serializeScript` in `src/admin-api.ts`). The Rhai
+ * source lives on a versioned `ScriptConfig`. So for each listed
+ * script we fetch the full record with `getScript`, which returns the
+ * header plus serialized `configs` (each carrying its `body`), and
+ * write the ACTIVE config's body. Reading the body off the list shape
+ * (the old behavior) always produced 0-byte files.
  *
- * Idempotency: every call writes the body the server returned, so
- * re-running `sync pull` on an unchanged server overwrites with the
- * same bytes and produces the same `contentHash`. The result map
- * always reflects the current server state for the writes performed.
+ * Idempotency: every call writes the active-config body the server
+ * returned, so re-running `sync pull` on an unchanged server overwrites
+ * with the same bytes and produces the same `contentHash`. The result
+ * map always reflects the current server state for the writes performed.
+ *
+ * `count` is the number of files actually written, not the number of
+ * scripts listed: scripts with no active config and scripts whose
+ * config fetch fails are skipped (we never clobber a `.rhai` with an
+ * empty file).
  *
  * Older-server graceful path: if `listScripts` rejects (e.g. older
  * server without the route), the caller catches and treats it as
- * "no scripts to pull", leaving the directory empty.
+ * "no scripts to pull", leaving the directory empty. A per-script
+ * `getScript` failure is caught and that one script is skipped without
+ * aborting the rest of the pull.
  */
 export async function pullScripts(client, appId, configDir, logger = () => { }) {
     const transformsDir = join(configDir, "transforms");
@@ -727,22 +811,49 @@ export async function pullScripts(client, appId, configDir, logger = () => { })
     catch {
         return { scriptEntities, count: 0 };
     }
+    let written = 0;
     for (const script of items) {
         const name = script?.name;
         if (!name)
             continue;
+        // The body lives on the active `ScriptConfig`, not the header. Skip
+        // scripts with no active config rather than writing an empty file.
+        if (!script.activeConfigId) {
+            logger(`  Skipped transforms/${name}.rhai (no active config)`);
+            continue;
+        }
+        // Fetch the full script (header + serialized configs with bodies).
+        // Tolerate a per-script failure: skip this one, keep the rest.
+        let full;
+        try {
+            full = await client.getScript(appId, script.scriptId);
+        }
+        catch {
+            logger(`  Skipped transforms/${name}.rhai (could not fetch config)`);
+            continue;
+        }
+        const configs = Array.isArray(full?.configs) ? full.configs : [];
+        const activeConfigId = full?.activeConfigId ?? script.activeConfigId;
+        const activeConfig = configs.find((c) => c.configId === activeConfigId) ||
+            configs.find((c) => c.status === "active");
+        if (!activeConfig || typeof activeConfig.body !== "string") {
+            logger(`  Skipped transforms/${name}.rhai (no active config body)`);
+            continue;
+        }
         const filename = `${name}.rhai`;
         const filePath = join(transformsDir, filename);
-        const body = typeof script.body === "string" ? script.body : "";
-        writeFileSync(filePath, body);
+        writeFileSync(filePath, activeConfig.body);
         scriptEntities[name] = {
             id: script.scriptId,
             modifiedAt: script.modifiedAt || new Date().toISOString(),
+            // Recompute from the written file (not the server's contentHash) so
+            // it matches what `sync push`'s `shouldPushFile` gate recomputes.
             contentHash: computeFileHash(filePath),
         };
+        written += 1;
         logger(`  Wrote transforms/${filename}`);
     }
-    return { scriptEntities, count: items.length };
+    return { scriptEntities, count: written };
 }
 async function pullTestCasesForBlock(client, appId, blockType, blockId, blockKey, configDir, testCaseEntities, lookupMaps) {
     let testCases;
@@ -2683,6 +2794,109 @@ Directory Structure:
                         }
                         continue;
                     }
+                    // Shared update body for both the in-manifest update branch and the
+                    // adopt-by-key recovery branch (#1174). The body is large and
+                    // ordering-sensitive (metadata PATCH → config/draft steps →
+                    // deferred `syncCallable` PATCH); both call sites MUST run it
+                    // identically, so it lives here as a single closure rather than
+                    // being duplicated. `activeConfigId` is passed in explicitly: the
+                    // update branch reads it from sync state, while the adopt branch
+                    // seeds it from a fresh `getWorkflow` (sync state has none for an
+                    // out-of-manifest workflow).
+                    const applyWorkflowUpdate = async (workflowId, opts) => {
+                        const { expectedModifiedAt, activeConfigId } = opts;
+                        // Update workflow metadata and schemas.
+                        //
+                        // Sync-callable ordering (#807, codex review): the metadata
+                        // PATCH must NOT carry `syncCallable: true` here. The server
+                        // re-validates `syncCallable: true` against the workflow's
+                        // CURRENTLY-active server steps (`loadCurrentActiveSteps`),
+                        // not the steps being pushed in the same sync. So when a
+                        // single TOML edit both enables `syncCallable` and replaces
+                        // sync-incompatible active steps with compatible ones, a
+                        // combined metadata-first PATCH would be rejected against the
+                        // stale steps. Defer `syncCallable` to a second PATCH issued
+                        // AFTER the config/step update lands, so it validates against
+                        // the new (compatible) active steps. `requiresClientApply`
+                        // has no step-dependent validation, so it stays in the first
+                        // PATCH unchanged.
+                        const updated = await client.updateWorkflow(resolvedAppId, workflowId, {
+                            name: workflow.name,
+                            description: workflow.description,
+                            status: workflow.status,
+                            accessRule: workflow.accessRule !== undefined ? (workflow.accessRule || null) : undefined,
+                            // #1081 — workflow principal mode. Absent key → undefined
+                            // (server leaves it untouched); explicit value/empty is
+                            // forwarded so it round-trips.
+                            runAs: workflow.runAs !== undefined ? (workflow.runAs || null) : undefined,
+                            perUserMaxRunning: workflow.perUserMaxRunning,
+                            perUserMaxQueued: workflow.perUserMaxQueued,
+                            dequeueOrder: workflow.dequeueOrder,
+                            // Sync-callable flags (#807): pass through as-is. An absent
+                            // TOML key is `undefined` (dropped by JSON.stringify, so the
+                            // server's hasOwnProperty guard leaves the value untouched);
+                            // an explicit `false` is preserved as a meaningful value.
+                            requiresClientApply: workflow.requiresClientApply,
+                            inputSchema: workflow.inputSchema ? safeJsonParse(workflow.inputSchema) : null,
+                            outputSchema: workflow.outputSchema ? safeJsonParse(workflow.outputSchema) : null,
+                        }, expectedModifiedAt);
+                        // Track the latest workflow `modifiedAt` for the sync-state
+                        // write below. The first PATCH bumps it; the `syncCallable`
+                        // PATCH (if any) bumps it again. The config/step update does
+                        // NOT touch the workflow definition's `modifiedAt`.
+                        let latestModifiedAt = updated?.workflow?.modifiedAt;
+                        // Update active configuration steps (or draft for legacy).
+                        // Issue #687: name the slot we touched so the dev-loop
+                        // user can confirm before previewing.
+                        let updateSlotLabel = "active config";
+                        if (activeConfigId) {
+                            await client.updateWorkflowConfig(resolvedAppId, workflowId, activeConfigId, {
+                                steps,
+                            });
+                        }
+                        else {
+                            // Fallback to draft update for legacy workflows
+                            await client.updateWorkflowDraft(resolvedAppId, workflowId, {
+                                steps,
+                                inputSchema: workflow.inputSchema ? safeJsonParse(workflow.inputSchema) : null,
+                            });
+                            updateSlotLabel = "draft (legacy)";
+                        }
+                        // Second PATCH: apply `syncCallable` now that the new steps
+                        // are active (#807). Only sent when the TOML actually carries
+                        // the key — an absent key stays `undefined` and we skip the
+                        // call entirely, preserving the no-clobber discipline. Chain
+                        // `expectedModifiedAt` off the first PATCH's returned value so
+                        // optimistic concurrency stays intact (the step update above
+                        // doesn't change the workflow definition's `modifiedAt`).
+                        if (workflow.syncCallable !== undefined) {
+                            const syncCallableUpdated = await client.updateWorkflow(resolvedAppId, workflowId, { syncCallable: workflow.syncCallable }, 
+                            // Mirror the first PATCH's concurrency posture: `--force`
+                            // skips the check (undefined), otherwise reuse the fresh
+                            // `modifiedAt` from the first PATCH.
+                            options.force ? undefined : latestModifiedAt);
+                            if (syncCallableUpdated?.workflow?.modifiedAt) {
+                                latestModifiedAt = syncCallableUpdated.workflow.modifiedAt;
+                            }
+                        }
+                        info(`  Updated workflow: ${key} (${updateSlotLabel})`);
+                        // Update sync state with new modifiedAt. Store the *expanded*
+                        // content hash so future fragment-only edits are detected. The
+                        // adopt branch seeds the entity record before calling this, so
+                        // the entry exists for both call sites.
+                        if (syncState?.entities?.workflows?.[key] && latestModifiedAt) {
+                            syncState.entities.workflows[key].modifiedAt = latestModifiedAt;
+                            syncState.entities.workflows[key].contentHash = computeExpandedContentHash(tomlData);
+                        }
+                        // Fetch full workflow to get config name→ID mappings
+                        // (updateWorkflow response doesn't include configs)
+                        const fullWorkflow = await client.getWorkflow(resolvedAppId, workflowId);
+                        if (fullWorkflow?.configs) {
+                            for (const config of fullWorkflow.configs) {
+                                workflowConfigNameToId.set(`${key}#${config.configName}`, config.configId);
+                            }
+                        }
+                    };
                     if (existingId) {
                         // Update existing workflow
                         changes.push({ type: "workflow", action: "update", key });
@@ -2691,95 +2905,10 @@ Directory Structure:
                                 ? undefined
                                 : syncState?.entities?.workflows?.[key]?.modifiedAt;
                             try {
-                                // Update workflow metadata and schemas.
-                                //
-                                // Sync-callable ordering (#807, codex review): the metadata
-                                // PATCH must NOT carry `syncCallable: true` here. The server
-                                // re-validates `syncCallable: true` against the workflow's
-                                // CURRENTLY-active server steps (`loadCurrentActiveSteps`),
-                                // not the steps being pushed in the same sync. So when a
-                                // single TOML edit both enables `syncCallable` and replaces
-                                // sync-incompatible active steps with compatible ones, a
-                                // combined metadata-first PATCH would be rejected against the
-                                // stale steps. Defer `syncCallable` to a second PATCH issued
-                                // AFTER the config/step update lands, so it validates against
-                                // the new (compatible) active steps. `requiresClientApply`
-                                // has no step-dependent validation, so it stays in the first
-                                // PATCH unchanged.
-                                const updated = await client.updateWorkflow(resolvedAppId, existingId, {
-                                    name: workflow.name,
-                                    description: workflow.description,
-                                    status: workflow.status,
-                                    accessRule: workflow.accessRule !== undefined ? (workflow.accessRule || null) : undefined,
-                                    // #1081 — workflow principal mode. Absent key → undefined
-                                    // (server leaves it untouched); explicit value/empty is
-                                    // forwarded so it round-trips.
-                                    runAs: workflow.runAs !== undefined ? (workflow.runAs || null) : undefined,
-                                    perUserMaxRunning: workflow.perUserMaxRunning,
-                                    perUserMaxQueued: workflow.perUserMaxQueued,
-                                    dequeueOrder: workflow.dequeueOrder,
-                                    // Sync-callable flags (#807): pass through as-is. An absent
-                                    // TOML key is `undefined` (dropped by JSON.stringify, so the
-                                    // server's hasOwnProperty guard leaves the value untouched);
-                                    // an explicit `false` is preserved as a meaningful value.
-                                    requiresClientApply: workflow.requiresClientApply,
-                                    inputSchema: workflow.inputSchema ? safeJsonParse(workflow.inputSchema) : null,
-                                    outputSchema: workflow.outputSchema ? safeJsonParse(workflow.outputSchema) : null,
-                                }, expectedModifiedAt);
-                                // Track the latest workflow `modifiedAt` for the sync-state
-                                // write below. The first PATCH bumps it; the `syncCallable`
-                                // PATCH (if any) bumps it again. The config/step update does
-                                // NOT touch the workflow definition's `modifiedAt`.
-                                let latestModifiedAt = updated?.workflow?.modifiedAt;
-                                // Update active configuration steps (or draft for legacy).
-                                // Issue #687: name the slot we touched so the dev-loop
-                                // user can confirm before previewing.
-                                let updateSlotLabel = "active config";
-                                if (existingActiveConfigId) {
-                                    await client.updateWorkflowConfig(resolvedAppId, existingId, existingActiveConfigId, {
-                                        steps,
-                                    });
-                                }
-                                else {
-                                    // Fallback to draft update for legacy workflows
-                                    await client.updateWorkflowDraft(resolvedAppId, existingId, {
-                                        steps,
-                                        inputSchema: workflow.inputSchema ? safeJsonParse(workflow.inputSchema) : null,
-                                    });
-                                    updateSlotLabel = "draft (legacy)";
-                                }
-                                // Second PATCH: apply `syncCallable` now that the new steps
-                                // are active (#807). Only sent when the TOML actually carries
-                                // the key — an absent key stays `undefined` and we skip the
-                                // call entirely, preserving the no-clobber discipline. Chain
-                                // `expectedModifiedAt` off the first PATCH's returned value so
-                                // optimistic concurrency stays intact (the step update above
-                                // doesn't change the workflow definition's `modifiedAt`).
-                                if (workflow.syncCallable !== undefined) {
-                                    const syncCallableUpdated = await client.updateWorkflow(resolvedAppId, existingId, { syncCallable: workflow.syncCallable }, 
-                                    // Mirror the first PATCH's concurrency posture: `--force`
-                                    // skips the check (undefined), otherwise reuse the fresh
-                                    // `modifiedAt` from the first PATCH.
-                                    options.force ? undefined : latestModifiedAt);
-                                    if (syncCallableUpdated?.workflow?.modifiedAt) {
-                                        latestModifiedAt = syncCallableUpdated.workflow.modifiedAt;
-                                    }
-                                }
-                                info(`  Updated workflow: ${key} (${updateSlotLabel})`);
-                                // Update sync state with new modifiedAt. Store the *expanded*
-                                // content hash so future fragment-only edits are detected.
-                                if (syncState?.entities?.workflows?.[key] && latestModifiedAt) {
-                                    syncState.entities.workflows[key].modifiedAt = latestModifiedAt;
-                                    syncState.entities.workflows[key].contentHash = computeExpandedContentHash(tomlData);
-                                }
-                                // Fetch full workflow to get config name→ID mappings
-                                // (updateWorkflow response doesn't include configs)
-                                const fullWorkflow = await client.getWorkflow(resolvedAppId, existingId);
-                                if (fullWorkflow?.configs) {
-                                    for (const config of fullWorkflow.configs) {
-                                        workflowConfigNameToId.set(`${key}#${config.configName}`, config.configId);
-                                    }
-                                }
+                                await applyWorkflowUpdate(existingId, {
+                                    expectedModifiedAt,
+                                    activeConfigId: existingActiveConfigId,
+                                });
                             }
                             catch (err) {
                                 if (err instanceof ConflictError) {
@@ -2868,7 +2997,116 @@ Directory Structure:
                                 }
                             }
                             catch (err) {
-                                throw wrapEntityError(err, "create", "workflow", key);
+                                // Issue #1174: idempotent create — adopt-by-key on conflict.
+                                // A workflow can exist on the server but be absent from local
+                                // sync state — e.g. created out-of-band via the admin API
+                                // (#971), or orphaned by a prior push that aborted before
+                                // recording it. On retry this CREATE path hits the
+                                // `workflowKeyPerApp` unique constraint and the server
+                                // returns "workflowKey already exists" (HTTP 400; cron uses
+                                // 409). Rather than abort the whole push, look up the
+                                // existing workflow by key (the list endpoint is app-scoped,
+                                // so every item is owned by this app), verify the SAME key,
+                                // adopt its id into sync state, and re-issue as an UPDATE so
+                                // the push converges. Mirrors the cron-trigger recovery at
+                                // ~sync.ts:2627. Unexpected errors still surface via
+                                // `wrapEntityError`, matching the db-type precedent.
+                                const msg = String(err?.message || err);
+                                const isConflict = err?.statusCode === 409 || msg.includes("already exists");
+                                if (!isConflict) {
+                                    throw wrapEntityError(err, "create", "workflow", key);
+                                }
+                                info(`  Workflow already exists on server, adopting by key: ${key}`);
+                                let adoptedId;
+                                try {
+                                    // Use fetchAll — listWorkflows is paginated, so a single
+                                    // page could miss the by-key match on a large app.
+                                    const items = await fetchAll((p) => client.listWorkflows(resolvedAppId, p));
+                                    // Verify same key + app ownership: the list endpoint only
+                                    // returns workflows for `resolvedAppId`, so a workflowKey
+                                    // match is also an ownership match. Never overwrite an
+                                    // unrelated resource — require exact key equality.
+                                    const existing = (items || []).find((w) => w?.workflowKey === key);
+                                    if (existing?.workflowId) {
+                                        adoptedId = existing.workflowId;
+                                    }
+                                }
+                                catch (lookupErr) {
+                                    throw wrapEntityError(new Error(`workflow "${key}" already exists but could not be adopted (lookup failed: ${String(lookupErr?.message || lookupErr)})`), "create", "workflow", key);
+                                }
+                                if (!adoptedId) {
+                                    // "already exists" but no matching key found on the server —
+                                    // surface the original error rather than silently
+                                    // overwriting an unrelated workflow.
+                                    throw wrapEntityError(err, "create", "workflow", key);
+                                }
+                                // Out-of-manifest adopt: warn (info-level), matching the cron
+                                // adopt line, and seed the sync-state entity record so the
+                                // shared update body can write modifiedAt/contentHash into it.
+                                if (syncState) {
+                                    if (!syncState.entities.workflows) {
+                                        syncState.entities.workflows = {};
+                                    }
+                                    if (!syncState.entities.workflows[key]) {
+                                        syncState.entities.workflows[key] = {
+                                            id: adoptedId,
+                                        };
+                                    }
+                                    else {
+                                        syncState.entities.workflows[key].id = adoptedId;
+                                    }
+                                }
+                                // Seed the real activeConfigId from the server before the
+                                // shared update body runs. Sync state has none for an
+                                // out-of-manifest workflow, so without this the shared body
+                                // would wrongly fall back to `updateWorkflowDraft`.
+                                let adoptedActiveConfigId;
+                                try {
+                                    const fullWorkflow = await client.getWorkflow(resolvedAppId, adoptedId);
+                                    adoptedActiveConfigId =
+                                        fullWorkflow?.workflow?.activeConfigId;
+                                }
+                                catch (getErr) {
+                                    throw wrapEntityError(new Error(`workflow "${key}" was adopted but could not be loaded (getWorkflow failed: ${String(getErr?.message || getErr)})`), "update", "workflow", key);
+                                }
+                                // Persist the fetched activeConfigId into the seeded
+                                // sync-state record so it round-trips identically to the
+                                // CREATE path (~sync.ts:3387). Without this the *next*
+                                // content-changing push reads `existingActiveConfigId ===
+                                // undefined` (sync.ts:3187) and wrongly falls back to the
+                                // legacy `updateWorkflowDraft` instead of
+                                // `updateWorkflowConfig` — a persisted-state divergence from
+                                // a normally-created workflow.
+                                if (syncState?.entities?.workflows?.[key] &&
+                                    adoptedActiveConfigId) {
+                                    syncState.entities.workflows[key].activeConfigId =
+                                        adoptedActiveConfigId;
+                                }
+                                // Switch to UPDATE on the adopted workflow. First adopt has no
+                                // stored modifiedAt → omit expectedModifiedAt (force the
+                                // PATCH), matching the cron adopt + the --force path. An
+                                // unexpected ConflictError here is still adoptable resilience
+                                // scope, so collect it; any other error surfaces.
+                                try {
+                                    await applyWorkflowUpdate(adoptedId, {
+                                        expectedModifiedAt: undefined,
+                                        activeConfigId: adoptedActiveConfigId,
+                                    });
+                                    info(`  Adopted + updated workflow: ${key}`);
+                                }
+                                catch (updErr) {
+                                    if (updErr instanceof ConflictError) {
+                                        conflicts.push({
+                                            type: "workflow",
+                                            key,
+                                            serverModifiedAt: updErr.serverModifiedAt,
+                                            localModifiedAt: "unknown",
+                                        });
+                                    }
+                                    else {
+                                        throw wrapEntityError(updErr, "update", "workflow", key);
+                                    }
+                                }
                             }
                         }
                     }
@@ -4112,13 +4350,9 @@ Directory Structure:
                     // Don't mask the original error
                 }
             }
-            error(err.message);
-            // Print structured server-side validation details (issue #684).
-            if (err instanceof ApiError && Array.isArray(err.details) && err.details.length > 0) {
-                for (const detail of err.details) {
-                    console.error(`    - ${typeof detail === "string" ? detail : JSON.stringify(detail)}`);
-                }
-            }
+            // Print message + structured server-side validation details
+            // (issue #684; now via the shared #1173 helper).
+            printApiError(err);
             process.exit(1);
         }
     });
@@ -4220,12 +4454,17 @@ Directory Structure:
                     localPrompts.add(key);
                 }
             }
+            // #1175: capture the parsed (fragment-expanded) local workflow TOML
+            // per key so the content-aware comparison below can hash it without a
+            // second read.
+            const localWorkflowParsed = new Map();
             const workflowsDir = join(configDir, "workflows");
             if (existsSync(workflowsDir)) {
                 for (const file of readdirSync(workflowsDir).filter((f) => f.endsWith(".toml"))) {
                     const tomlData = parseTomlFile(join(workflowsDir, file));
                     const key = tomlData.workflow?.key || basename(file, ".toml");
                     localWorkflows.add(key);
+                    localWorkflowParsed.set(key, tomlData);
                 }
             }
             const emailTemplatesDirPath = join(configDir, "email-templates");
@@ -4236,6 +4475,30 @@ Directory Structure:
                     localEmailTemplates.add(emailType);
                 }
             }
+            // Transforms (Rhai scripts) — issue #1196. Before this, `sync diff`
+            // ignored scripts entirely, so a body that drifted between the local
+            // `.rhai` and the server's active config silently read as Synced. We
+            // list the server scripts (header only) and read the local file
+            // contents so the comparison below can hash both sides.
+            let scriptItemsDiff = [];
+            try {
+                const scriptsResult = await client.listScripts(resolvedAppId);
+                scriptItemsDiff = scriptsResult.items || [];
+            }
+            catch {
+                // Older server without the scripts route — treat as no scripts.
+            }
+            const remoteScripts = new Map(scriptItemsDiff
+                .filter((s) => s?.name)
+                .map((s) => [s.name, s]));
+            const localScripts = new Map();
+            const transformsDirPath = join(configDir, "transforms");
+            if (existsSync(transformsDirPath)) {
+                for (const file of readdirSync(transformsDirPath).filter((f) => f.endsWith(".rhai"))) {
+                    const name = basename(file, ".rhai");
+                    localScripts.set(name, readFileSync(join(transformsDirPath, file), "utf-8"));
+                }
+            }
             // Compare
             const differences = [];
             // Integrations
@@ -4308,14 +4571,69 @@ Directory Structure:
                     differences.push({ type: "prompt", key, status: "remote only" });
                 }
             }
-            // Workflows
+            // Workflows — #1175: content-aware comparison.
+            //
+            // For workflows present on BOTH sides we no longer stop at key
+            // existence. We fetch the full remote workflow (mirroring `sync pull`:
+            // `getWorkflow` + active `getWorkflowConfig` for steps), serialize it
+            // through the SAME `serializeWorkflow` pull writes to disk, and hash
+            // both sides through the canonical pull/push hash. A difference is
+            // reported as `modified`, which `diff` frames as a preview of
+            // `sync pull` (pull would rewrite the local file to match running
+            // state). It is NOT framed as "push would send": push *preserves*
+            // omitted remote values (sync.ts updateWorkflow), so a remote
+            // non-default vs a local omission shows Modified even though push
+            // wouldn't change it.
+            //
+            // Default-normalization (see `hashWorkflowTomlForDiff`) means a local
+            // file that omits perUserMaxRunning/Queued etc. reads as Synced when
+            // the server holds the model defaults (4/100/…), and only an
+            // explicitly-set non-default server value reads as Modified.
+            const remoteWorkflowIds = new Map(workflowItems.map((w) => [w.workflowKey, w.workflowId]));
             for (const key of localWorkflows) {
                 if (!remoteWorkflows.has(key)) {
                     differences.push({ type: "workflow", key, status: "local only" });
+                    continue;
                 }
-                else {
-                    differences.push({ type: "workflow", key, status: "exists" });
+                // Present on both sides → compare content.
+                const workflowId = remoteWorkflowIds.get(key);
+                const localParsed = localWorkflowParsed.get(key);
+                let status = "exists";
+                let hint;
+                try {
+                    if (!workflowId || !localParsed) {
+                        throw new Error("missing workflow id or local parse");
+                    }
+                    const remoteData = await client.getWorkflow(resolvedAppId, workflowId);
+                    // Fetch active config steps (mirrors pull at the workflows hydrate
+                    // block). Failure here is non-fatal — we degrade to key-only.
+                    const activeConfigId = remoteData.workflow?.activeConfigId;
+                    if (activeConfigId && Array.isArray(remoteData.configs)) {
+                        try {
+                            const activeConfig = await client.getWorkflowConfig(resolvedAppId, workflowId, activeConfigId);
+                            const idx = remoteData.configs.findIndex((c) => c.configId === activeConfigId);
+                            if (idx >= 0 && activeConfig) {
+                                remoteData.configs[idx] = activeConfig;
+                            }
+                        }
+                        catch {
+                            // Ignore — fall back to whatever steps the workflow GET carried.
+                        }
+                    }
+                    const remoteHash = hashRemoteWorkflowForDiff(remoteData.workflow, remoteData.draft, remoteData.configs || []);
+                    const localHash = hashWorkflowTomlForDiff(localParsed);
+                    if (remoteHash !== localHash) {
+                        status = "modified";
+                        hint = "run `sync pull` to rewrite the local TOML to match running state";
+                    }
+                }
+                catch {
+                    // Per-workflow fetch failure must not abort the whole diff. Degrade
+                    // gracefully to a key-only "Synced (content not compared)" caveat.
+                    status = "exists";
+                    hint = "content not compared (fetch failed)";
                 }
+                differences.push({ type: "workflow", key, status, hint });
             }
             for (const key of remoteWorkflows) {
                 if (!localWorkflows.has(key)) {
@@ -4336,6 +4654,55 @@ Directory Structure:
                     differences.push({ type: "email-template", key, status: "remote only" });
                 }
             }
+            // Transforms (Rhai scripts) — issue #1196. Content-aware, mirroring
+            // the workflow block: for scripts present on both sides we fetch the
+            // server's active-config body (via `getScript`, the same call pull
+            // uses) and compare it to the local `.rhai` contents. A difference is
+            // reported as `modified`, framed as a preview of `sync pull`. A
+            // per-script fetch failure degrades to key-only (Synced, not compared)
+            // rather than aborting the whole diff.
+            for (const [name, localBody] of localScripts) {
+                const remote = remoteScripts.get(name);
+                if (!remote) {
+                    differences.push({ type: "transform", key: name, status: "local only" });
+                    continue;
+                }
+                let status = "exists";
+                let hint;
+                try {
+                    if (!remote.activeConfigId) {
+                        // No active config server-side — nothing to compare against.
+                        status = "exists";
+                        hint = "content not compared (no active config)";
+                    }
+                    else {
+                        const full = await client.getScript(resolvedAppId, remote.scriptId);
+                        const configs = Array.isArray(full?.configs) ? full.configs : [];
+                        const activeConfigId = full?.activeConfigId ?? remote.activeConfigId;
+                        const activeConfig = configs.find((c) => c.configId === activeConfigId) ||
+                            configs.find((c) => c.status === "active");
+                        if (!activeConfig || typeof activeConfig.body !== "string") {
+                            status = "exists";
+                            hint = "content not compared (no active config body)";
+                        }
+                        else if (activeConfig.body !== localBody) {
+                            status = "modified";
+                            hint = "run `sync pull` to rewrite the local .rhai to match running state";
+                        }
+                    }
+                }
+                catch {
+                    // Per-script fetch failure must not abort the whole diff.
+                    status = "exists";
+                    hint = "content not compared (fetch failed)";
+                }
+                differences.push({ type: "transform", key: name, status, hint });
+            }
+            for (const name of remoteScripts.keys()) {
+                if (!localScripts.has(name)) {
+                    differences.push({ type: "transform", key: name, status: "remote only" });
+                }
+            }
             // Compare test cases for synced prompts and workflows
             const testCaseDiffs = [];
             // Helper to compare test cases for a block
@@ -4386,6 +4753,7 @@ Directory Structure:
             divider();
             const localOnly = differences.filter((d) => d.status === "local only");
             const remoteOnly = differences.filter((d) => d.status === "remote only");
+            const modified = differences.filter((d) => d.status === "modified");
             const existing = differences.filter((d) => d.status === "exists");
             if (localOnly.length > 0) {
                 info("Local only (will be created on push):");
@@ -4401,10 +4769,22 @@ Directory Structure:
                 }
                 console.log();
             }
+            // #1175: workflows whose deployed content differs from the local TOML.
+            // Framed as a preview of `sync pull` — pull would rewrite these files
+            // to match what's actually running (NOT "push would send").
+            if (modified.length > 0) {
+                warn("Modified — `sync pull` would rewrite these to match running state:");
+                for (const d of modified) {
+                    const hint = d.hint ? ` ${chalk.dim(`(${d.hint})`)}` : "";
+                    console.log(`  ${chalk.yellow("~")} ${d.type}: ${d.key}${hint}`);
+                }
+                console.log();
+            }
             if (existing.length > 0) {
                 info("Synced:");
                 for (const d of existing) {
-                    console.log(`  ${chalk.dim("=")} ${d.type}: ${d.key}`);
+                    const hint = d.hint ? ` ${chalk.dim(`(${d.hint})`)}` : "";
+                    console.log(`  ${chalk.dim("=")} ${d.type}: ${d.key}${hint}`);
                 }
             }
             // Show test case differences
@@ -4427,6 +4807,7 @@ Directory Structure:
             divider();
             keyValue("Local only", localOnly.length);
             keyValue("Remote only", remoteOnly.length);
+            keyValue("Modified", modified.length);
             keyValue("Synced", existing.length);
             if (testCaseDiffs.length > 0) {
                 keyValue("Test Cases (local only)", tcLocalOnly.length);