post-merge-setup

name	post-merge-setup
description	Maintain the post-merge setup script that runs automatically after task merges.

Post-Merge Setup

After a task is merged, two things run automatically:

1. Setup script -- installs dependencies, runs migrations, rebuilds.
2. Workflow reconciliation -- stops workflows removed from .replit and restarts already running workflows.

If either step fails, the agent will be alerted about the issue, and should fix it immediately.

What Runs Automatically

The system runs the configured post-merge script from the project root with bash. Stdin is closed (/dev/null), so commands that prompt for input will get EOF and fail immediately. The full Nix environment is available on PATH.

If the script does not exist, setup fails and you are asked to create it.

The script has a configurable timeout. If the script takes longer, it is killed and setup fails with a timeout error.

After the script, workflow reconciliation syncs running workflows with the current .replit config.

Available Commands

Get the post-merge config

const config = await getPostMergeConfig();
console.log(config);
// { scriptPath: "...", timeoutMs: ... }

Returns the configured script path and timeout from .replit. If not yet configured, both fields will be null.

Set post-merge config

await setPostMergeConfig({ scriptPath: "scripts/post-merge.sh", timeoutMs: 180000 });

Sets the post-merge script path and/or timeout. Both parameters are optional -- only provided values are updated. Note: scriptPath must be set (either already configured or provided in the same call) before setting timeoutMs alone, because .replit requires path in the [postMerge] section. Use timeoutMs when:

• The script timed out -- if the script naturally takes a long time (large npm install, slow migrations), increase the timeout so it succeeds on the next merge. Estimate a reasonable value from the script's expected runtime and add a buffer (e.g. if npm install takes 3s, set timeout to 5000 ms).
• The script hangs -- if the script hangs due to a bug (e.g. waiting for input), fix the script first, then consider lowering the timeout to catch future hangs early.

Run post-merge setup

const result = await runPostMergeSetup();
console.log(result);

Runs the post-merge script and workflow reconciliation. Returns { success, setupError, reconciliationError, scriptPath, stdoutPath, stderrPath, durationMs, timeoutMs }.

• success: true only when both setup and reconciliation succeeded
• setupError / reconciliationError: what failed (empty string when that step succeeded)
• scriptPath: path to the post-merge script that was executed
• stdoutPath / stderrPath: full log file paths
• durationMs / timeoutMs: how long it ran and the configured timeout

All parameters are optional: pass timeoutMs to override the configured script timeout for this run, and taskId / taskRef to surface the run in the task feed.

The tail of the stdout/stderr log files (last 10 lines with line numbers) is automatically opened into your context after the call.

Fixing Failures

When setup fails:

1. Check the log files opened into your context after the call (last 10 lines of stdout/stderr with line numbers). The scriptPath in the result tells you which script was executed.
2. Fix the script -- create it if missing, update it if broken.
3. If it timed out, increase the timeout with setPostMergeConfig({ timeoutMs: ... }) based on how long the script actually needs.
4. Retry with runPostMergeSetup() to confirm the fix works.

If workflow reconciliation fails, use the workflows skill to check and restart affected workflows.

Common failure causes:

• Missing script -> use the scriptPath from the result (or call getPostMergeConfig()) to find the expected path, then create the script there.
• Script timed out -> increase timeout with setPostMergeConfig({ timeoutMs: ... }), or optimize the script.
• A command prompts for input (stdin is closed, so it gets EOF and fails) -> use non-interactive flags (--yes, --force, -y, etc.).
• A dependency or migration command fails -> fix the command or the underlying config.

Writing the Post-Merge Script

Use the scriptPath from the last runPostMergeSetup() result if available. Otherwise, call getPostMergeConfig() to find the script location.

Example:

#!/bin/bash
set -e

pnpm install
pnpm --filter @workspace/db run push-force

Guidelines:

• Idempotent. Safe to run multiple times.
• Non-interactive. Stdin is closed. Use --yes / --force flags.
• Fail fast. Use set -e.
• Keep it fast. Runs while the user waits. If it takes more than 2 minutes, consider optimizing or increasing the timeout.