Backport #2914: Add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var to local world#2921

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pranaygp merged 2 commits into from
Aug 24, 2026
Merged

Backport #2914: Add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var to local world #2921

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5b2f4ab
feat(world-local): add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var (#2…
github-actions[bot] Jul 14, 2026
48011fd
Fix: Destructuring a non-existent `clearCache` property from `createS…
vercel[bot] Jul 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/brave-eyes-shake.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@workflow/world-local': minor
---

Add `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var as a fallback for the `recoverActiveRuns` option, so re-enqueueing of pending/running runs on startup can be disabled without a custom world module.
5 changes: 5 additions & 0 deletions docs/content/docs/deploying/world/local-world.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -58,6 +58,10 @@ Port resolution priority: `baseUrl` > `port` > `PORT` > auto-detected

Maximum number of concurrent queue workers. Default: `100`

### `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS`

Whether pending and running runs found in the data directory are re-enqueued when the world starts. Set to `0` or `false` to skip recovery and leave stale runs untouched. Default: `true`

### Programmatic configuration

{/* @skip-typecheck: incomplete code sample */}
Expand All@@ -69,6 +73,7 @@ const world = createLocalWorld({
port: 5173,
// baseUrl overrides port if set
baseUrl: "https://local.example.com:3000",
recoverActiveRuns: true, // overrides WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS
});
```

Expand Down
56 changes: 55 additions & 1 deletion packages/world-local/src/config.test.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import { setWorkflowBasePath } from '@workflow/utils';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { resolveBaseUrl } from './config';
import { resolveBaseUrl, resolveRecoverActiveRuns } from './config';

// Mock the getWorkflowPort function from @workflow/utils/get-port
vi.mock('@workflow/utils/get-port', () => ({
Expand DownExpand Up@@ -303,3 +303,57 @@ describe('resolveBaseUrl', () => {
});
});
});

describe('resolveRecoverActiveRuns', () => {
let originalEnv: NodeJS.ProcessEnv;

beforeEach(() => {
originalEnv = { ...process.env };
delete process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS;
});

afterEach(() => {
process.env = originalEnv;
});

it('defaults to true when neither config nor env is set', () => {
expect(resolveRecoverActiveRuns({})).toBe(true);
});

it('prioritizes explicit config over the env var', () => {
process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = '1';
expect(resolveRecoverActiveRuns({ recoverActiveRuns: false })).toBe(false);

process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = '0';
expect(resolveRecoverActiveRuns({ recoverActiveRuns: true })).toBe(true);
});

it.each([
'0',
'false',
'FALSE',
'False',
])('disables recovery for env value %j', (value) => {
process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
expect(resolveRecoverActiveRuns({})).toBe(false);
});

it.each([
'1',
'true',
'TRUE',
])('enables recovery for env value %j', (value) => {
process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
expect(resolveRecoverActiveRuns({})).toBe(true);
});

it.each([
'',
'yes',
'off',
'nonsense',
])('falls back to the default for unrecognized env value %j', (value) => {
process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
expect(resolveRecoverActiveRuns({})).toBe(true);
});
});
27 changes: 25 additions & 2 deletions packages/world-local/src/config.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -21,8 +21,10 @@ export type Config = {
baseUrl?: string;
/**
* Whether start() should re-enqueue pending/running runs from storage.
* Defaults to true. Test harnesses that always start from a clean slate can
* disable recovery to avoid replaying stale runs.
* Defaults to true; the `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var is
* used as a fallback when this option is unset. Test harnesses that always
* start from a clean slate can disable recovery to avoid replaying stale
* runs.
*/
recoverActiveRuns?: boolean;
/**
Expand All@@ -46,6 +48,27 @@ export const config = once<Config>(() => {
return { dataDir, baseUrl };
});

/**
* Resolves whether start() should re-enqueue pending/running runs from
* storage, following the priority order:
* 1. config.recoverActiveRuns (explicit factory option)
* 2. WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var (`0`/`false` disables,
* `1`/`true` enables; read lazily to handle late env var setting)
* 3. Default: true
*
* An unrecognized env value falls through to the default — the env var is an
* escape hatch, not a hard requirement.
*/
export function resolveRecoverActiveRuns(config: Partial<Config>): boolean {
if (config.recoverActiveRuns !== undefined) {
return config.recoverActiveRuns;
}
const raw = process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS?.toLowerCase();
if (raw === '0' || raw === 'false') return false;
if (raw === '1' || raw === 'true') return true;
return true;
}

export function resolveDirectBaseUrl(config: Partial<Config>): string {
return (
config.baseUrl ??
Expand Down
6 changes: 3 additions & 3 deletions packages/world-local/src/index.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import path from 'node:path';
import type { QueuePrefix, World } from '@workflow/world';
import { reenqueueActiveRuns, SPEC_VERSION_CURRENT } from '@workflow/world';
import type { Config } from './config.js';
import { config } from './config.js';
import { config, resolveRecoverActiveRuns } from './config.js';
import {
clearCreatedFilesCache,
deleteJSON,
Expand DownExpand Up@@ -47,7 +47,7 @@ export type LocalWorld = World & {
* @param args.dataDir - Directory for storing workflow data (default: `.workflow-data/`)
* @param args.port - Port override for queue transport (default: auto-detected)
* @param args.baseUrl - Full base URL override for queue transport (default: `http://localhost:{port}`)
* @param args.recoverActiveRuns - Whether `start()` should re-enqueue pending/running runs from storage (default: `true`)
* @param args.recoverActiveRuns - Whether `start()` should re-enqueue pending/running runs from storage (default: `true`; falls back to the `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var when unset)
* @param args.tag - Optional tag to scope files (e.g., `vitest-0`). When set, files are written
* as `{id}.{tag}.json` and `clear()` only deletes files matching this tag.
* @throws {DataDirAccessError} If the data directory cannot be created or accessed
Expand All@@ -63,7 +63,7 @@ export function createLocalWorld(args?: Partial<Config>): LocalWorld {
const tag = mergedConfig.tag;
const queue = createQueue(mergedConfig);
const storage = createStorage(mergedConfig.dataDir, tag);
const recoverActiveRuns = mergedConfig.recoverActiveRuns ?? true;
const recoverActiveRuns = resolveRecoverActiveRuns(mergedConfig);
return {
specVersion: SPEC_VERSION_CURRENT,
...queue,
Expand Down
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
Backport #2914: Add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var to local world#2921

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

pranaygp
merged 2 commits into

from

Aug 24, 2026
 Merged


Backport #2914: Add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var to local world
#2921
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
5b2f4ab

feat(world-local): add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var (#2…


github-actions[bot] Jul 14, 2026
48011fd

Fix: Destructuring a non-existent `clearCache` property from `createS…


vercel[bot] Jul 14, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/brave-eyes-shake.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@workflow/world-local': minor
---

Add `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var as a fallback for the `recoverActiveRuns` option, so re-enqueueing of pending/running runs on startup can be disabled without a custom world module.

5 changes: 5 additions & 0 deletions
docs/content/docs/deploying/world/local-world.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -58,6 +58,10 @@ Port resolution priority: `baseUrl` > `port` > `PORT` > auto-detected

Maximum number of concurrent queue workers. Default: `100`

### `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS`

Whether pending and running runs found in the data directory are re-enqueued when the world starts. Set to `0` or `false` to skip recovery and leave stale runs untouched. Default: `true`

### Programmatic configuration

{/* @skip-typecheck: incomplete code sample */}
Expand All@@ -69,6 +73,7 @@ const world = createLocalWorld({
 port: 5173,
 // baseUrl overrides port if set
 baseUrl: "https://local.example.com:3000",
 recoverActiveRuns: true, // overrides WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS
});
```

Expand Down

56 changes: 55 additions & 1 deletion
packages/world-local/src/config.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import { setWorkflowBasePath } from '@workflow/utils';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { resolveBaseUrl } from './config';
import { resolveBaseUrl, resolveRecoverActiveRuns } from './config';

// Mock the getWorkflowPort function from @workflow/utils/get-port
vi.mock('@workflow/utils/get-port', () => ({
Expand DownExpand Up@@ -303,3 +303,57 @@ describe('resolveBaseUrl', () => {
 });
 });
});

describe('resolveRecoverActiveRuns', () => {
 let originalEnv: NodeJS.ProcessEnv;

 beforeEach(() => {
 originalEnv = { ...process.env };
 delete process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS;
 });

 afterEach(() => {
 process.env = originalEnv;
 });

 it('defaults to true when neither config nor env is set', () => {
 expect(resolveRecoverActiveRuns({})).toBe(true);
 });

 it('prioritizes explicit config over the env var', () => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = '1';
 expect(resolveRecoverActiveRuns({ recoverActiveRuns: false })).toBe(false);

 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = '0';
 expect(resolveRecoverActiveRuns({ recoverActiveRuns: true })).toBe(true);
 });

 it.each([
 '0',
 'false',
 'FALSE',
 'False',
 ])('disables recovery for env value %j', (value) => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
 expect(resolveRecoverActiveRuns({})).toBe(false);
 });

 it.each([
 '1',
 'true',
 'TRUE',
 ])('enables recovery for env value %j', (value) => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
 expect(resolveRecoverActiveRuns({})).toBe(true);
 });

 it.each([
 '',
 'yes',
 'off',
 'nonsense',
 ])('falls back to the default for unrecognized env value %j', (value) => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
 expect(resolveRecoverActiveRuns({})).toBe(true);
 });
});

27 changes: 25 additions & 2 deletions
packages/world-local/src/config.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -21,8 +21,10 @@ export type Config = {
 baseUrl?: string;
 /**
 * Whether start() should re-enqueue pending/running runs from storage.
 * Defaults to true. Test harnesses that always start from a clean slate can
 * disable recovery to avoid replaying stale runs.
 * Defaults to true; the `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var is
 * used as a fallback when this option is unset. Test harnesses that always
 * start from a clean slate can disable recovery to avoid replaying stale
 * runs.
 */
 recoverActiveRuns?: boolean;
 /**
Expand All@@ -46,6 +48,27 @@ export const config = once<Config>(() => {
 return { dataDir, baseUrl };
});

/**
 * Resolves whether start() should re-enqueue pending/running runs from
 * storage, following the priority order:
 * 1. config.recoverActiveRuns (explicit factory option)
 * 2. WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var (`0`/`false` disables,
 * `1`/`true` enables; read lazily to handle late env var setting)
 * 3. Default: true
 *
 * An unrecognized env value falls through to the default — the env var is an
 * escape hatch, not a hard requirement.
 */
export function resolveRecoverActiveRuns(config: Partial<Config>): boolean {
 if (config.recoverActiveRuns !== undefined) {
 return config.recoverActiveRuns;
 }
 const raw = process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS?.toLowerCase();
 if (raw === '0' || raw === 'false') return false;
 if (raw === '1' || raw === 'true') return true;
 return true;
}

export function resolveDirectBaseUrl(config: Partial<Config>): string {
 return (
 config.baseUrl ??
Expand Down

6 changes: 3 additions & 3 deletions
packages/world-local/src/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import path from 'node:path';
import type { QueuePrefix, World } from '@workflow/world';
import { reenqueueActiveRuns, SPEC_VERSION_CURRENT } from '@workflow/world';
import type { Config } from './config.js';
import { config } from './config.js';
import { config, resolveRecoverActiveRuns } from './config.js';
import {
 clearCreatedFilesCache,
 deleteJSON,
Expand DownExpand Up@@ -47,7 +47,7 @@ export type LocalWorld = World & {
 * @param args.dataDir - Directory for storing workflow data (default: `.workflow-data/`)
 * @param args.port - Port override for queue transport (default: auto-detected)
 * @param args.baseUrl - Full base URL override for queue transport (default: `http://localhost:{port}`)
 * @param args.recoverActiveRuns - Whether `start()` should re-enqueue pending/running runs from storage (default: `true`)
 * @param args.recoverActiveRuns - Whether `start()` should re-enqueue pending/running runs from storage (default: `true`; falls back to the `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var when unset)
 * @param args.tag - Optional tag to scope files (e.g., `vitest-0`). When set, files are written
 * as `{id}.{tag}.json` and `clear()` only deletes files matching this tag.
 * @throws {DataDirAccessError} If the data directory cannot be created or accessed
Expand All@@ -63,7 +63,7 @@ export function createLocalWorld(args?: Partial<Config>): LocalWorld {
 const tag = mergedConfig.tag;
 const queue = createQueue(mergedConfig);
 const storage = createStorage(mergedConfig.dataDir, tag);
 const recoverActiveRuns = mergedConfig.recoverActiveRuns ?? true;
 const recoverActiveRuns = resolveRecoverActiveRuns(mergedConfig);
 return {
 specVersion: SPEC_VERSION_CURRENT,
 ...queue,
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Backport #2914: Add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var to local world#2921

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

pranaygp
merged 2 commits into

from

Aug 24, 2026
 Merged


Backport #2914: Add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var to local world
#2921
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
5b2f4ab

feat(world-local): add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var (#2…


github-actions[bot] Jul 14, 2026
48011fd

Fix: Destructuring a non-existent `clearCache` property from `createS…


vercel[bot] Jul 14, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/brave-eyes-shake.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@workflow/world-local': minor
---

Add `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var as a fallback for the `recoverActiveRuns` option, so re-enqueueing of pending/running runs on startup can be disabled without a custom world module.

5 changes: 5 additions & 0 deletions
docs/content/docs/deploying/world/local-world.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -58,6 +58,10 @@ Port resolution priority: `baseUrl` > `port` > `PORT` > auto-detected

Maximum number of concurrent queue workers. Default: `100`

### `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS`

Whether pending and running runs found in the data directory are re-enqueued when the world starts. Set to `0` or `false` to skip recovery and leave stale runs untouched. Default: `true`

### Programmatic configuration

{/* @skip-typecheck: incomplete code sample */}
Expand All@@ -69,6 +73,7 @@ const world = createLocalWorld({
 port: 5173,
 // baseUrl overrides port if set
 baseUrl: "https://local.example.com:3000",
 recoverActiveRuns: true, // overrides WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS
});
```

Expand Down

56 changes: 55 additions & 1 deletion
packages/world-local/src/config.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import { setWorkflowBasePath } from '@workflow/utils';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { resolveBaseUrl } from './config';
import { resolveBaseUrl, resolveRecoverActiveRuns } from './config';

// Mock the getWorkflowPort function from @workflow/utils/get-port
vi.mock('@workflow/utils/get-port', () => ({
Expand DownExpand Up@@ -303,3 +303,57 @@ describe('resolveBaseUrl', () => {
 });
 });
});

describe('resolveRecoverActiveRuns', () => {
 let originalEnv: NodeJS.ProcessEnv;

 beforeEach(() => {
 originalEnv = { ...process.env };
 delete process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS;
 });

 afterEach(() => {
 process.env = originalEnv;
 });

 it('defaults to true when neither config nor env is set', () => {
 expect(resolveRecoverActiveRuns({})).toBe(true);
 });

 it('prioritizes explicit config over the env var', () => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = '1';
 expect(resolveRecoverActiveRuns({ recoverActiveRuns: false })).toBe(false);

 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = '0';
 expect(resolveRecoverActiveRuns({ recoverActiveRuns: true })).toBe(true);
 });

 it.each([
 '0',
 'false',
 'FALSE',
 'False',
 ])('disables recovery for env value %j', (value) => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
 expect(resolveRecoverActiveRuns({})).toBe(false);
 });

 it.each([
 '1',
 'true',
 'TRUE',
 ])('enables recovery for env value %j', (value) => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
 expect(resolveRecoverActiveRuns({})).toBe(true);
 });

 it.each([
 '',
 'yes',
 'off',
 'nonsense',
 ])('falls back to the default for unrecognized env value %j', (value) => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
 expect(resolveRecoverActiveRuns({})).toBe(true);
 });
});

27 changes: 25 additions & 2 deletions
packages/world-local/src/config.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -21,8 +21,10 @@ export type Config = {
 baseUrl?: string;
 /**
 * Whether start() should re-enqueue pending/running runs from storage.
 * Defaults to true. Test harnesses that always start from a clean slate can
 * disable recovery to avoid replaying stale runs.
 * Defaults to true; the `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var is
 * used as a fallback when this option is unset. Test harnesses that always
 * start from a clean slate can disable recovery to avoid replaying stale
 * runs.
 */
 recoverActiveRuns?: boolean;
 /**
Expand All@@ -46,6 +48,27 @@ export const config = once<Config>(() => {
 return { dataDir, baseUrl };
});

/**
 * Resolves whether start() should re-enqueue pending/running runs from
 * storage, following the priority order:
 * 1. config.recoverActiveRuns (explicit factory option)
 * 2. WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var (`0`/`false` disables,
 * `1`/`true` enables; read lazily to handle late env var setting)
 * 3. Default: true
 *
 * An unrecognized env value falls through to the default — the env var is an
 * escape hatch, not a hard requirement.
 */
export function resolveRecoverActiveRuns(config: Partial<Config>): boolean {
 if (config.recoverActiveRuns !== undefined) {
 return config.recoverActiveRuns;
 }
 const raw = process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS?.toLowerCase();
 if (raw === '0' || raw === 'false') return false;
 if (raw === '1' || raw === 'true') return true;
 return true;
}

export function resolveDirectBaseUrl(config: Partial<Config>): string {
 return (
 config.baseUrl ??
Expand Down

6 changes: 3 additions & 3 deletions
packages/world-local/src/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import path from 'node:path';
import type { QueuePrefix, World } from '@workflow/world';
import { reenqueueActiveRuns, SPEC_VERSION_CURRENT } from '@workflow/world';
import type { Config } from './config.js';
import { config } from './config.js';
import { config, resolveRecoverActiveRuns } from './config.js';
import {
 clearCreatedFilesCache,
 deleteJSON,
Expand DownExpand Up@@ -47,7 +47,7 @@ export type LocalWorld = World & {
 * @param args.dataDir - Directory for storing workflow data (default: `.workflow-data/`)
 * @param args.port - Port override for queue transport (default: auto-detected)
 * @param args.baseUrl - Full base URL override for queue transport (default: `http://localhost:{port}`)
 * @param args.recoverActiveRuns - Whether `start()` should re-enqueue pending/running runs from storage (default: `true`)
 * @param args.recoverActiveRuns - Whether `start()` should re-enqueue pending/running runs from storage (default: `true`; falls back to the `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var when unset)
 * @param args.tag - Optional tag to scope files (e.g., `vitest-0`). When set, files are written
 * as `{id}.{tag}.json` and `clear()` only deletes files matching this tag.
 * @throws {DataDirAccessError} If the data directory cannot be created or accessed
Expand All@@ -63,7 +63,7 @@ export function createLocalWorld(args?: Partial<Config>): LocalWorld {
 const tag = mergedConfig.tag;
 const queue = createQueue(mergedConfig);
 const storage = createStorage(mergedConfig.dataDir, tag);
 const recoverActiveRuns = mergedConfig.recoverActiveRuns ?? true;
 const recoverActiveRuns = resolveRecoverActiveRuns(mergedConfig);
 return {
 specVersion: SPEC_VERSION_CURRENT,
 ...queue,
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Backport #2914: Add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var to local world#2921

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

pranaygp
merged 2 commits into

from

Aug 24, 2026
 Merged


Backport #2914: Add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var to local world
#2921
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
5b2f4ab

feat(world-local): add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var (#2…


github-actions[bot] Jul 14, 2026
48011fd

Fix: Destructuring a non-existent `clearCache` property from `createS…


vercel[bot] Jul 14, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/brave-eyes-shake.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@workflow/world-local': minor
---

Add `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var as a fallback for the `recoverActiveRuns` option, so re-enqueueing of pending/running runs on startup can be disabled without a custom world module.

5 changes: 5 additions & 0 deletions
docs/content/docs/deploying/world/local-world.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -58,6 +58,10 @@ Port resolution priority: `baseUrl` > `port` > `PORT` > auto-detected

Maximum number of concurrent queue workers. Default: `100`

### `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS`

Whether pending and running runs found in the data directory are re-enqueued when the world starts. Set to `0` or `false` to skip recovery and leave stale runs untouched. Default: `true`

### Programmatic configuration

{/* @skip-typecheck: incomplete code sample */}
Expand All@@ -69,6 +73,7 @@ const world = createLocalWorld({
 port: 5173,
 // baseUrl overrides port if set
 baseUrl: "https://local.example.com:3000",
 recoverActiveRuns: true, // overrides WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS
});
```

Expand Down

56 changes: 55 additions & 1 deletion
packages/world-local/src/config.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import { setWorkflowBasePath } from '@workflow/utils';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { resolveBaseUrl } from './config';
import { resolveBaseUrl, resolveRecoverActiveRuns } from './config';

// Mock the getWorkflowPort function from @workflow/utils/get-port
vi.mock('@workflow/utils/get-port', () => ({
Expand DownExpand Up@@ -303,3 +303,57 @@ describe('resolveBaseUrl', () => {
 });
 });
});

describe('resolveRecoverActiveRuns', () => {
 let originalEnv: NodeJS.ProcessEnv;

 beforeEach(() => {
 originalEnv = { ...process.env };
 delete process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS;
 });

 afterEach(() => {
 process.env = originalEnv;
 });

 it('defaults to true when neither config nor env is set', () => {
 expect(resolveRecoverActiveRuns({})).toBe(true);
 });

 it('prioritizes explicit config over the env var', () => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = '1';
 expect(resolveRecoverActiveRuns({ recoverActiveRuns: false })).toBe(false);

 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = '0';
 expect(resolveRecoverActiveRuns({ recoverActiveRuns: true })).toBe(true);
 });

 it.each([
 '0',
 'false',
 'FALSE',
 'False',
 ])('disables recovery for env value %j', (value) => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
 expect(resolveRecoverActiveRuns({})).toBe(false);
 });

 it.each([
 '1',
 'true',
 'TRUE',
 ])('enables recovery for env value %j', (value) => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
 expect(resolveRecoverActiveRuns({})).toBe(true);
 });

 it.each([
 '',
 'yes',
 'off',
 'nonsense',
 ])('falls back to the default for unrecognized env value %j', (value) => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
 expect(resolveRecoverActiveRuns({})).toBe(true);
 });
});

27 changes: 25 additions & 2 deletions
packages/world-local/src/config.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -21,8 +21,10 @@ export type Config = {
 baseUrl?: string;
 /**
 * Whether start() should re-enqueue pending/running runs from storage.
 * Defaults to true. Test harnesses that always start from a clean slate can
 * disable recovery to avoid replaying stale runs.
 * Defaults to true; the `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var is
 * used as a fallback when this option is unset. Test harnesses that always
 * start from a clean slate can disable recovery to avoid replaying stale
 * runs.
 */
 recoverActiveRuns?: boolean;
 /**
Expand All@@ -46,6 +48,27 @@ export const config = once<Config>(() => {
 return { dataDir, baseUrl };
});

/**
 * Resolves whether start() should re-enqueue pending/running runs from
 * storage, following the priority order:
 * 1. config.recoverActiveRuns (explicit factory option)
 * 2. WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var (`0`/`false` disables,
 * `1`/`true` enables; read lazily to handle late env var setting)
 * 3. Default: true
 *
 * An unrecognized env value falls through to the default — the env var is an
 * escape hatch, not a hard requirement.
 */
export function resolveRecoverActiveRuns(config: Partial<Config>): boolean {
 if (config.recoverActiveRuns !== undefined) {
 return config.recoverActiveRuns;
 }
 const raw = process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS?.toLowerCase();
 if (raw === '0' || raw === 'false') return false;
 if (raw === '1' || raw === 'true') return true;
 return true;
}

export function resolveDirectBaseUrl(config: Partial<Config>): string {
 return (
 config.baseUrl ??
Expand Down

6 changes: 3 additions & 3 deletions
packages/world-local/src/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import path from 'node:path';
import type { QueuePrefix, World } from '@workflow/world';
import { reenqueueActiveRuns, SPEC_VERSION_CURRENT } from '@workflow/world';
import type { Config } from './config.js';
import { config } from './config.js';
import { config, resolveRecoverActiveRuns } from './config.js';
import {
 clearCreatedFilesCache,
 deleteJSON,
Expand DownExpand Up@@ -47,7 +47,7 @@ export type LocalWorld = World & {
 * @param args.dataDir - Directory for storing workflow data (default: `.workflow-data/`)
 * @param args.port - Port override for queue transport (default: auto-detected)
 * @param args.baseUrl - Full base URL override for queue transport (default: `http://localhost:{port}`)
 * @param args.recoverActiveRuns - Whether `start()` should re-enqueue pending/running runs from storage (default: `true`)
 * @param args.recoverActiveRuns - Whether `start()` should re-enqueue pending/running runs from storage (default: `true`; falls back to the `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var when unset)
 * @param args.tag - Optional tag to scope files (e.g., `vitest-0`). When set, files are written
 * as `{id}.{tag}.json` and `clear()` only deletes files matching this tag.
 * @throws {DataDirAccessError} If the data directory cannot be created or accessed
Expand All@@ -63,7 +63,7 @@ export function createLocalWorld(args?: Partial<Config>): LocalWorld {
 const tag = mergedConfig.tag;
 const queue = createQueue(mergedConfig);
 const storage = createStorage(mergedConfig.dataDir, tag);
 const recoverActiveRuns = mergedConfig.recoverActiveRuns ?? true;
 const recoverActiveRuns = resolveRecoverActiveRuns(mergedConfig);
 return {
 specVersion: SPEC_VERSION_CURRENT,
 ...queue,
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
Backport #2914: Add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var to local world#2921

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

pranaygp
merged 2 commits into

from

Aug 24, 2026
 Merged


Backport #2914: Add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var to local world
#2921
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
5b2f4ab

feat(world-local): add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var (#2…


github-actions[bot] Jul 14, 2026
48011fd

Fix: Destructuring a non-existent `clearCache` property from `createS…


vercel[bot] Jul 14, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/brave-eyes-shake.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@workflow/world-local': minor
---

Add `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var as a fallback for the `recoverActiveRuns` option, so re-enqueueing of pending/running runs on startup can be disabled without a custom world module.

5 changes: 5 additions & 0 deletions
docs/content/docs/deploying/world/local-world.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -58,6 +58,10 @@ Port resolution priority: `baseUrl` > `port` > `PORT` > auto-detected

Maximum number of concurrent queue workers. Default: `100`

### `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS`

Whether pending and running runs found in the data directory are re-enqueued when the world starts. Set to `0` or `false` to skip recovery and leave stale runs untouched. Default: `true`

### Programmatic configuration

{/* @skip-typecheck: incomplete code sample */}
Expand All@@ -69,6 +73,7 @@ const world = createLocalWorld({
 port: 5173,
 // baseUrl overrides port if set
 baseUrl: "https://local.example.com:3000",
 recoverActiveRuns: true, // overrides WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS
});
```

Expand Down

56 changes: 55 additions & 1 deletion
packages/world-local/src/config.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import { setWorkflowBasePath } from '@workflow/utils';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { resolveBaseUrl } from './config';
import { resolveBaseUrl, resolveRecoverActiveRuns } from './config';

// Mock the getWorkflowPort function from @workflow/utils/get-port
vi.mock('@workflow/utils/get-port', () => ({
Expand DownExpand Up@@ -303,3 +303,57 @@ describe('resolveBaseUrl', () => {
 });
 });
});

describe('resolveRecoverActiveRuns', () => {
 let originalEnv: NodeJS.ProcessEnv;

 beforeEach(() => {
 originalEnv = { ...process.env };
 delete process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS;
 });

 afterEach(() => {
 process.env = originalEnv;
 });

 it('defaults to true when neither config nor env is set', () => {
 expect(resolveRecoverActiveRuns({})).toBe(true);
 });

 it('prioritizes explicit config over the env var', () => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = '1';
 expect(resolveRecoverActiveRuns({ recoverActiveRuns: false })).toBe(false);

 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = '0';
 expect(resolveRecoverActiveRuns({ recoverActiveRuns: true })).toBe(true);
 });

 it.each([
 '0',
 'false',
 'FALSE',
 'False',
 ])('disables recovery for env value %j', (value) => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
 expect(resolveRecoverActiveRuns({})).toBe(false);
 });

 it.each([
 '1',
 'true',
 'TRUE',
 ])('enables recovery for env value %j', (value) => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
 expect(resolveRecoverActiveRuns({})).toBe(true);
 });

 it.each([
 '',
 'yes',
 'off',
 'nonsense',
 ])('falls back to the default for unrecognized env value %j', (value) => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
 expect(resolveRecoverActiveRuns({})).toBe(true);
 });
});

27 changes: 25 additions & 2 deletions
packages/world-local/src/config.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -21,8 +21,10 @@ export type Config = {
 baseUrl?: string;
 /**
 * Whether start() should re-enqueue pending/running runs from storage.
 * Defaults to true. Test harnesses that always start from a clean slate can
 * disable recovery to avoid replaying stale runs.
 * Defaults to true; the `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var is
 * used as a fallback when this option is unset. Test harnesses that always
 * start from a clean slate can disable recovery to avoid replaying stale
 * runs.
 */
 recoverActiveRuns?: boolean;
 /**
Expand All@@ -46,6 +48,27 @@ export const config = once<Config>(() => {
 return { dataDir, baseUrl };
});

/**
 * Resolves whether start() should re-enqueue pending/running runs from
 * storage, following the priority order:
 * 1. config.recoverActiveRuns (explicit factory option)
 * 2. WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var (`0`/`false` disables,
 * `1`/`true` enables; read lazily to handle late env var setting)
 * 3. Default: true
 *
 * An unrecognized env value falls through to the default — the env var is an
 * escape hatch, not a hard requirement.
 */
export function resolveRecoverActiveRuns(config: Partial<Config>): boolean {
 if (config.recoverActiveRuns !== undefined) {
 return config.recoverActiveRuns;
 }
 const raw = process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS?.toLowerCase();
 if (raw === '0' || raw === 'false') return false;
 if (raw === '1' || raw === 'true') return true;
 return true;
}

export function resolveDirectBaseUrl(config: Partial<Config>): string {
 return (
 config.baseUrl ??
Expand Down

6 changes: 3 additions & 3 deletions
packages/world-local/src/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import path from 'node:path';
import type { QueuePrefix, World } from '@workflow/world';
import { reenqueueActiveRuns, SPEC_VERSION_CURRENT } from '@workflow/world';
import type { Config } from './config.js';
import { config } from './config.js';
import { config, resolveRecoverActiveRuns } from './config.js';
import {
 clearCreatedFilesCache,
 deleteJSON,
Expand DownExpand Up@@ -47,7 +47,7 @@ export type LocalWorld = World & {
 * @param args.dataDir - Directory for storing workflow data (default: `.workflow-data/`)
 * @param args.port - Port override for queue transport (default: auto-detected)
 * @param args.baseUrl - Full base URL override for queue transport (default: `http://localhost:{port}`)
 * @param args.recoverActiveRuns - Whether `start()` should re-enqueue pending/running runs from storage (default: `true`)
 * @param args.recoverActiveRuns - Whether `start()` should re-enqueue pending/running runs from storage (default: `true`; falls back to the `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var when unset)
 * @param args.tag - Optional tag to scope files (e.g., `vitest-0`). When set, files are written
 * as `{id}.{tag}.json` and `clear()` only deletes files matching this tag.
 * @throws {DataDirAccessError} If the data directory cannot be created or accessed
Expand All@@ -63,7 +63,7 @@ export function createLocalWorld(args?: Partial<Config>): LocalWorld {
 const tag = mergedConfig.tag;
 const queue = createQueue(mergedConfig);
 const storage = createStorage(mergedConfig.dataDir, tag);
 const recoverActiveRuns = mergedConfig.recoverActiveRuns ?? true;
 const recoverActiveRuns = resolveRecoverActiveRuns(mergedConfig);
 return {
 specVersion: SPEC_VERSION_CURRENT,
 ...queue,
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Backport #2914: Add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var to local world#2921

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

pranaygp
merged 2 commits into

from

Aug 24, 2026
 Merged


Backport #2914: Add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var to local world
#2921
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
5b2f4ab

feat(world-local): add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var (#2…


github-actions[bot] Jul 14, 2026
48011fd

Fix: Destructuring a non-existent `clearCache` property from `createS…


vercel[bot] Jul 14, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/brave-eyes-shake.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@workflow/world-local': minor
---

Add `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var as a fallback for the `recoverActiveRuns` option, so re-enqueueing of pending/running runs on startup can be disabled without a custom world module.

5 changes: 5 additions & 0 deletions
docs/content/docs/deploying/world/local-world.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -58,6 +58,10 @@ Port resolution priority: `baseUrl` > `port` > `PORT` > auto-detected

Maximum number of concurrent queue workers. Default: `100`

### `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS`

Whether pending and running runs found in the data directory are re-enqueued when the world starts. Set to `0` or `false` to skip recovery and leave stale runs untouched. Default: `true`

### Programmatic configuration

{/* @skip-typecheck: incomplete code sample */}
Expand All@@ -69,6 +73,7 @@ const world = createLocalWorld({
 port: 5173,
 // baseUrl overrides port if set
 baseUrl: "https://local.example.com:3000",
 recoverActiveRuns: true, // overrides WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS
});
```

Expand Down

56 changes: 55 additions & 1 deletion
packages/world-local/src/config.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import { setWorkflowBasePath } from '@workflow/utils';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { resolveBaseUrl } from './config';
import { resolveBaseUrl, resolveRecoverActiveRuns } from './config';

// Mock the getWorkflowPort function from @workflow/utils/get-port
vi.mock('@workflow/utils/get-port', () => ({
Expand DownExpand Up@@ -303,3 +303,57 @@ describe('resolveBaseUrl', () => {
 });
 });
});

describe('resolveRecoverActiveRuns', () => {
 let originalEnv: NodeJS.ProcessEnv;

 beforeEach(() => {
 originalEnv = { ...process.env };
 delete process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS;
 });

 afterEach(() => {
 process.env = originalEnv;
 });

 it('defaults to true when neither config nor env is set', () => {
 expect(resolveRecoverActiveRuns({})).toBe(true);
 });

 it('prioritizes explicit config over the env var', () => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = '1';
 expect(resolveRecoverActiveRuns({ recoverActiveRuns: false })).toBe(false);

 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = '0';
 expect(resolveRecoverActiveRuns({ recoverActiveRuns: true })).toBe(true);
 });

 it.each([
 '0',
 'false',
 'FALSE',
 'False',
 ])('disables recovery for env value %j', (value) => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
 expect(resolveRecoverActiveRuns({})).toBe(false);
 });

 it.each([
 '1',
 'true',
 'TRUE',
 ])('enables recovery for env value %j', (value) => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
 expect(resolveRecoverActiveRuns({})).toBe(true);
 });

 it.each([
 '',
 'yes',
 'off',
 'nonsense',
 ])('falls back to the default for unrecognized env value %j', (value) => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
 expect(resolveRecoverActiveRuns({})).toBe(true);
 });
});

27 changes: 25 additions & 2 deletions
packages/world-local/src/config.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -21,8 +21,10 @@ export type Config = {
 baseUrl?: string;
 /**
 * Whether start() should re-enqueue pending/running runs from storage.
 * Defaults to true. Test harnesses that always start from a clean slate can
 * disable recovery to avoid replaying stale runs.
 * Defaults to true; the `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var is
 * used as a fallback when this option is unset. Test harnesses that always
 * start from a clean slate can disable recovery to avoid replaying stale
 * runs.
 */
 recoverActiveRuns?: boolean;
 /**
Expand All@@ -46,6 +48,27 @@ export const config = once<Config>(() => {
 return { dataDir, baseUrl };
});

/**
 * Resolves whether start() should re-enqueue pending/running runs from
 * storage, following the priority order:
 * 1. config.recoverActiveRuns (explicit factory option)
 * 2. WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var (`0`/`false` disables,
 * `1`/`true` enables; read lazily to handle late env var setting)
 * 3. Default: true
 *
 * An unrecognized env value falls through to the default — the env var is an
 * escape hatch, not a hard requirement.
 */
export function resolveRecoverActiveRuns(config: Partial<Config>): boolean {
 if (config.recoverActiveRuns !== undefined) {
 return config.recoverActiveRuns;
 }
 const raw = process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS?.toLowerCase();
 if (raw === '0' || raw === 'false') return false;
 if (raw === '1' || raw === 'true') return true;
 return true;
}

export function resolveDirectBaseUrl(config: Partial<Config>): string {
 return (
 config.baseUrl ??
Expand Down

6 changes: 3 additions & 3 deletions
packages/world-local/src/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import path from 'node:path';
import type { QueuePrefix, World } from '@workflow/world';
import { reenqueueActiveRuns, SPEC_VERSION_CURRENT } from '@workflow/world';
import type { Config } from './config.js';
import { config } from './config.js';
import { config, resolveRecoverActiveRuns } from './config.js';
import {
 clearCreatedFilesCache,
 deleteJSON,
Expand DownExpand Up@@ -47,7 +47,7 @@ export type LocalWorld = World & {
 * @param args.dataDir - Directory for storing workflow data (default: `.workflow-data/`)
 * @param args.port - Port override for queue transport (default: auto-detected)
 * @param args.baseUrl - Full base URL override for queue transport (default: `http://localhost:{port}`)
 * @param args.recoverActiveRuns - Whether `start()` should re-enqueue pending/running runs from storage (default: `true`)
 * @param args.recoverActiveRuns - Whether `start()` should re-enqueue pending/running runs from storage (default: `true`; falls back to the `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var when unset)
 * @param args.tag - Optional tag to scope files (e.g., `vitest-0`). When set, files are written
 * as `{id}.{tag}.json` and `clear()` only deletes files matching this tag.
 * @throws {DataDirAccessError} If the data directory cannot be created or accessed
Expand All@@ -63,7 +63,7 @@ export function createLocalWorld(args?: Partial<Config>): LocalWorld {
 const tag = mergedConfig.tag;
 const queue = createQueue(mergedConfig);
 const storage = createStorage(mergedConfig.dataDir, tag);
 const recoverActiveRuns = mergedConfig.recoverActiveRuns ?? true;
 const recoverActiveRuns = resolveRecoverActiveRuns(mergedConfig);
 return {
 specVersion: SPEC_VERSION_CURRENT,
 ...queue,
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Backport #2914: Add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var to local world#2921

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

pranaygp
merged 2 commits into

from

Aug 24, 2026
 Merged


Backport #2914: Add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var to local world
#2921
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
5b2f4ab

feat(world-local): add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var (#2…


github-actions[bot] Jul 14, 2026
48011fd

Fix: Destructuring a non-existent `clearCache` property from `createS…


vercel[bot] Jul 14, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/brave-eyes-shake.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@workflow/world-local': minor
---

Add `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var as a fallback for the `recoverActiveRuns` option, so re-enqueueing of pending/running runs on startup can be disabled without a custom world module.

5 changes: 5 additions & 0 deletions
docs/content/docs/deploying/world/local-world.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -58,6 +58,10 @@ Port resolution priority: `baseUrl` > `port` > `PORT` > auto-detected

Maximum number of concurrent queue workers. Default: `100`

### `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS`

Whether pending and running runs found in the data directory are re-enqueued when the world starts. Set to `0` or `false` to skip recovery and leave stale runs untouched. Default: `true`

### Programmatic configuration

{/* @skip-typecheck: incomplete code sample */}
Expand All@@ -69,6 +73,7 @@ const world = createLocalWorld({
 port: 5173,
 // baseUrl overrides port if set
 baseUrl: "https://local.example.com:3000",
 recoverActiveRuns: true, // overrides WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS
});
```

Expand Down

56 changes: 55 additions & 1 deletion
packages/world-local/src/config.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import { setWorkflowBasePath } from '@workflow/utils';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { resolveBaseUrl } from './config';
import { resolveBaseUrl, resolveRecoverActiveRuns } from './config';

// Mock the getWorkflowPort function from @workflow/utils/get-port
vi.mock('@workflow/utils/get-port', () => ({
Expand DownExpand Up@@ -303,3 +303,57 @@ describe('resolveBaseUrl', () => {
 });
 });
});

describe('resolveRecoverActiveRuns', () => {
 let originalEnv: NodeJS.ProcessEnv;

 beforeEach(() => {
 originalEnv = { ...process.env };
 delete process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS;
 });

 afterEach(() => {
 process.env = originalEnv;
 });

 it('defaults to true when neither config nor env is set', () => {
 expect(resolveRecoverActiveRuns({})).toBe(true);
 });

 it('prioritizes explicit config over the env var', () => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = '1';
 expect(resolveRecoverActiveRuns({ recoverActiveRuns: false })).toBe(false);

 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = '0';
 expect(resolveRecoverActiveRuns({ recoverActiveRuns: true })).toBe(true);
 });

 it.each([
 '0',
 'false',
 'FALSE',
 'False',
 ])('disables recovery for env value %j', (value) => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
 expect(resolveRecoverActiveRuns({})).toBe(false);
 });

 it.each([
 '1',
 'true',
 'TRUE',
 ])('enables recovery for env value %j', (value) => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
 expect(resolveRecoverActiveRuns({})).toBe(true);
 });

 it.each([
 '',
 'yes',
 'off',
 'nonsense',
 ])('falls back to the default for unrecognized env value %j', (value) => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
 expect(resolveRecoverActiveRuns({})).toBe(true);
 });
});

27 changes: 25 additions & 2 deletions
packages/world-local/src/config.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -21,8 +21,10 @@ export type Config = {
 baseUrl?: string;
 /**
 * Whether start() should re-enqueue pending/running runs from storage.
 * Defaults to true. Test harnesses that always start from a clean slate can
 * disable recovery to avoid replaying stale runs.
 * Defaults to true; the `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var is
 * used as a fallback when this option is unset. Test harnesses that always
 * start from a clean slate can disable recovery to avoid replaying stale
 * runs.
 */
 recoverActiveRuns?: boolean;
 /**
Expand All@@ -46,6 +48,27 @@ export const config = once<Config>(() => {
 return { dataDir, baseUrl };
});

/**
 * Resolves whether start() should re-enqueue pending/running runs from
 * storage, following the priority order:
 * 1. config.recoverActiveRuns (explicit factory option)
 * 2. WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var (`0`/`false` disables,
 * `1`/`true` enables; read lazily to handle late env var setting)
 * 3. Default: true
 *
 * An unrecognized env value falls through to the default — the env var is an
 * escape hatch, not a hard requirement.
 */
export function resolveRecoverActiveRuns(config: Partial<Config>): boolean {
 if (config.recoverActiveRuns !== undefined) {
 return config.recoverActiveRuns;
 }
 const raw = process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS?.toLowerCase();
 if (raw === '0' || raw === 'false') return false;
 if (raw === '1' || raw === 'true') return true;
 return true;
}

export function resolveDirectBaseUrl(config: Partial<Config>): string {
 return (
 config.baseUrl ??
Expand Down

6 changes: 3 additions & 3 deletions
packages/world-local/src/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import path from 'node:path';
import type { QueuePrefix, World } from '@workflow/world';
import { reenqueueActiveRuns, SPEC_VERSION_CURRENT } from '@workflow/world';
import type { Config } from './config.js';
import { config } from './config.js';
import { config, resolveRecoverActiveRuns } from './config.js';
import {
 clearCreatedFilesCache,
 deleteJSON,
Expand DownExpand Up@@ -47,7 +47,7 @@ export type LocalWorld = World & {
 * @param args.dataDir - Directory for storing workflow data (default: `.workflow-data/`)
 * @param args.port - Port override for queue transport (default: auto-detected)
 * @param args.baseUrl - Full base URL override for queue transport (default: `http://localhost:{port}`)
 * @param args.recoverActiveRuns - Whether `start()` should re-enqueue pending/running runs from storage (default: `true`)
 * @param args.recoverActiveRuns - Whether `start()` should re-enqueue pending/running runs from storage (default: `true`; falls back to the `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var when unset)
 * @param args.tag - Optional tag to scope files (e.g., `vitest-0`). When set, files are written
 * as `{id}.{tag}.json` and `clear()` only deletes files matching this tag.
 * @throws {DataDirAccessError} If the data directory cannot be created or accessed
Expand All@@ -63,7 +63,7 @@ export function createLocalWorld(args?: Partial<Config>): LocalWorld {
 const tag = mergedConfig.tag;
 const queue = createQueue(mergedConfig);
 const storage = createStorage(mergedConfig.dataDir, tag);
 const recoverActiveRuns = mergedConfig.recoverActiveRuns ?? true;
 const recoverActiveRuns = resolveRecoverActiveRuns(mergedConfig);
 return {
 specVersion: SPEC_VERSION_CURRENT,
 ...queue,
Expand Down
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
Backport #2914: Add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var to local world#2921

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

pranaygp
merged 2 commits into

from

Aug 24, 2026
 Merged


Backport #2914: Add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var to local world
#2921
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


2 commits


Select commit
Hold shift + click to select a range
5b2f4ab

feat(world-local): add WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var (#2…


github-actions[bot] Jul 14, 2026
48011fd

Fix: Destructuring a non-existent `clearCache` property from `createS…


vercel[bot] Jul 14, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


5 changes: 5 additions & 0 deletions
.changeset/brave-eyes-shake.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
---
'@workflow/world-local': minor
---

Add `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var as a fallback for the `recoverActiveRuns` option, so re-enqueueing of pending/running runs on startup can be disabled without a custom world module.

5 changes: 5 additions & 0 deletions
docs/content/docs/deploying/world/local-world.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -58,6 +58,10 @@ Port resolution priority: `baseUrl` > `port` > `PORT` > auto-detected

Maximum number of concurrent queue workers. Default: `100`

### `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS`

Whether pending and running runs found in the data directory are re-enqueued when the world starts. Set to `0` or `false` to skip recovery and leave stale runs untouched. Default: `true`

### Programmatic configuration

{/* @skip-typecheck: incomplete code sample */}
Expand All@@ -69,6 +73,7 @@ const world = createLocalWorld({
 port: 5173,
 // baseUrl overrides port if set
 baseUrl: "https://local.example.com:3000",
 recoverActiveRuns: true, // overrides WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS
});
```

Expand Down

56 changes: 55 additions & 1 deletion
packages/world-local/src/config.test.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
import { setWorkflowBasePath } from '@workflow/utils';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { resolveBaseUrl } from './config';
import { resolveBaseUrl, resolveRecoverActiveRuns } from './config';

// Mock the getWorkflowPort function from @workflow/utils/get-port
vi.mock('@workflow/utils/get-port', () => ({
Expand DownExpand Up@@ -303,3 +303,57 @@ describe('resolveBaseUrl', () => {
 });
 });
});

describe('resolveRecoverActiveRuns', () => {
 let originalEnv: NodeJS.ProcessEnv;

 beforeEach(() => {
 originalEnv = { ...process.env };
 delete process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS;
 });

 afterEach(() => {
 process.env = originalEnv;
 });

 it('defaults to true when neither config nor env is set', () => {
 expect(resolveRecoverActiveRuns({})).toBe(true);
 });

 it('prioritizes explicit config over the env var', () => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = '1';
 expect(resolveRecoverActiveRuns({ recoverActiveRuns: false })).toBe(false);

 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = '0';
 expect(resolveRecoverActiveRuns({ recoverActiveRuns: true })).toBe(true);
 });

 it.each([
 '0',
 'false',
 'FALSE',
 'False',
 ])('disables recovery for env value %j', (value) => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
 expect(resolveRecoverActiveRuns({})).toBe(false);
 });

 it.each([
 '1',
 'true',
 'TRUE',
 ])('enables recovery for env value %j', (value) => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
 expect(resolveRecoverActiveRuns({})).toBe(true);
 });

 it.each([
 '',
 'yes',
 'off',
 'nonsense',
 ])('falls back to the default for unrecognized env value %j', (value) => {
 process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS = value;
 expect(resolveRecoverActiveRuns({})).toBe(true);
 });
});

27 changes: 25 additions & 2 deletions
packages/world-local/src/config.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -21,8 +21,10 @@ export type Config = {
 baseUrl?: string;
 /**
 * Whether start() should re-enqueue pending/running runs from storage.
 * Defaults to true. Test harnesses that always start from a clean slate can
 * disable recovery to avoid replaying stale runs.
 * Defaults to true; the `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var is
 * used as a fallback when this option is unset. Test harnesses that always
 * start from a clean slate can disable recovery to avoid replaying stale
 * runs.
 */
 recoverActiveRuns?: boolean;
 /**
Expand All@@ -46,6 +48,27 @@ export const config = once<Config>(() => {
 return { dataDir, baseUrl };
});

/**
 * Resolves whether start() should re-enqueue pending/running runs from
 * storage, following the priority order:
 * 1. config.recoverActiveRuns (explicit factory option)
 * 2. WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS env var (`0`/`false` disables,
 * `1`/`true` enables; read lazily to handle late env var setting)
 * 3. Default: true
 *
 * An unrecognized env value falls through to the default — the env var is an
 * escape hatch, not a hard requirement.
 */
export function resolveRecoverActiveRuns(config: Partial<Config>): boolean {
 if (config.recoverActiveRuns !== undefined) {
 return config.recoverActiveRuns;
 }
 const raw = process.env.WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS?.toLowerCase();
 if (raw === '0' || raw === 'false') return false;
 if (raw === '1' || raw === 'true') return true;
 return true;
}

export function resolveDirectBaseUrl(config: Partial<Config>): string {
 return (
 config.baseUrl ??
Expand Down

6 changes: 3 additions & 3 deletions
packages/world-local/src/index.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import path from 'node:path';
import type { QueuePrefix, World } from '@workflow/world';
import { reenqueueActiveRuns, SPEC_VERSION_CURRENT } from '@workflow/world';
import type { Config } from './config.js';
import { config } from './config.js';
import { config, resolveRecoverActiveRuns } from './config.js';
import {
 clearCreatedFilesCache,
 deleteJSON,
Expand DownExpand Up@@ -47,7 +47,7 @@ export type LocalWorld = World & {
 * @param args.dataDir - Directory for storing workflow data (default: `.workflow-data/`)
 * @param args.port - Port override for queue transport (default: auto-detected)
 * @param args.baseUrl - Full base URL override for queue transport (default: `http://localhost:{port}`)
 * @param args.recoverActiveRuns - Whether `start()` should re-enqueue pending/running runs from storage (default: `true`)
 * @param args.recoverActiveRuns - Whether `start()` should re-enqueue pending/running runs from storage (default: `true`; falls back to the `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` env var when unset)
 * @param args.tag - Optional tag to scope files (e.g., `vitest-0`). When set, files are written
 * as `{id}.{tag}.json` and `clear()` only deletes files matching this tag.
 * @throws {DataDirAccessError} If the data directory cannot be created or accessed
Expand All@@ -63,7 +63,7 @@ export function createLocalWorld(args?: Partial<Config>): LocalWorld {
 const tag = mergedConfig.tag;
 const queue = createQueue(mergedConfig);
 const storage = createStorage(mergedConfig.dataDir, tag);
 const recoverActiveRuns = mergedConfig.recoverActiveRuns ?? true;
 const recoverActiveRuns = resolveRecoverActiveRuns(mergedConfig);
 return {
 specVersion: SPEC_VERSION_CURRENT,
 ...queue,
Expand Down
Loading