Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

feat: add a per-task Stall nudge toggle to scheduled tasks, off by default for do-release

[._.]/ Adam Eivyea6440cbccbf
diff --git a/client/src/components/cos/constants.js b/client/src/components/cos/constants.js
index 0f5e57ea5a..17d0ad71df 100644
--- a/client/src/components/cos/constants.js
+++ b/client/src/components/cos/constants.js
@@ -439,6 +439,14 @@ export const RELEASE_OPTIONS = [
{ field: 'autoDecide', label: 'Make decisions', description: 'Make routine design and preference decisions and list them for your review, instead of stopping to ask' },
];
+// The idle stall nudge (taskMetadata.stallNudge), ON unless explicitly false.
+// Shown for every scheduled task; do-release ships with it off because its
+// long quiet stretch is waiting on its own release PR's CI.
+export const STALL_NUDGE_OPTION = {
+ label: 'Stall nudge',
+ description: 'After 10 quiet minutes, paste a reminder into the agent session to keep working. Turn off for tasks that wait a long time on work they started, such as CI on a release PR.',
+};
+
// better-dependency-freedom's removal bar — the slashdo `/do:depfree` modes.
// Values mirror DEPFREE_MODES in server/lib/cosValidation.js; the server drops
// anything else, and an absent key means the default bar.
diff --git a/client/src/components/cos/tabs/schedule/GlobalConfigControls.jsx b/client/src/components/cos/tabs/schedule/GlobalConfigControls.jsx
index cc4c2b1f27..fbc442fc46 100644
--- a/client/src/components/cos/tabs/schedule/GlobalConfigControls.jsx
+++ b/client/src/components/cos/tabs/schedule/GlobalConfigControls.jsx
@@ -2,7 +2,7 @@ import { useState, useEffect, useMemo } from 'react';
import useFieldDraft from '../../../../hooks/useFieldDraft';
import { RotateCcw, AlertCircle } from 'lucide-react';
import CronInput from '../../../CronInput';
-import { AGENT_OPTIONS, BRANCHES_PER_AGENT_DEFAULT, BRANCHES_PER_AGENT_OPTIONS, BRANCHES_PER_AGENT_TASK_TYPES, DEFAULT_REVIEW_STOP_MODE, DEPFREE_MODE_DEFAULT, DEPFREE_MODE_OPTIONS, DEPFREE_MODE_TASK_TYPES, depfreeModeOption, REVIEWER_OVERRIDE_KEYS as REVIEW_CONFIG_KEYS, IMPLICIT_PR_COMPLETION, PR_AUTHOR_FILTER_OPTIONS, PR_COMPLETION_OPTIONS, pinnedPrCompletion, prCompletionOption, RELEASE_OPTIONS, RELEASE_OPTIONS_TASK_TYPES, ISSUE_AUTHOR_FILTER_OPTIONS, ISSUE_AUTHOR_FILTER_TASK_TYPES, SWARM_COUNT_OPTIONS, SWARM_TASK_TYPES } from '../../constants';
+import { AGENT_OPTIONS, BRANCHES_PER_AGENT_DEFAULT, BRANCHES_PER_AGENT_OPTIONS, BRANCHES_PER_AGENT_TASK_TYPES, DEFAULT_REVIEW_STOP_MODE, DEPFREE_MODE_DEFAULT, DEPFREE_MODE_OPTIONS, DEPFREE_MODE_TASK_TYPES, depfreeModeOption, REVIEWER_OVERRIDE_KEYS as REVIEW_CONFIG_KEYS, IMPLICIT_PR_COMPLETION, PR_AUTHOR_FILTER_OPTIONS, PR_COMPLETION_OPTIONS, pinnedPrCompletion, prCompletionOption, RELEASE_OPTIONS, RELEASE_OPTIONS_TASK_TYPES, STALL_NUDGE_OPTION, ISSUE_AUTHOR_FILTER_OPTIONS, ISSUE_AUTHOR_FILTER_TASK_TYPES, SWARM_COUNT_OPTIONS, SWARM_TASK_TYPES } from '../../constants';
import ReviewerPicker from '../../ReviewerPicker';
import Banner from '../../../ui/Banner';
import InfoTooltip from '../../../ui/InfoTooltip';
@@ -205,6 +205,20 @@ export default function GlobalConfigControls({ taskType, config, onUpdate, onTri
// Release options are ON unless explicitly false, so the toggle writes an
// explicit boolean either way.
+ // ON unless explicitly false, like the release options — so it reads from
+ // the same rule the server's nudge gate applies (sessionController.js).
+ const stallNudgeEnabled = config.taskMetadata?.stallNudge !== false;
+ const handleStallNudgeToggle = async () => {
+ setUpdating(true);
+ try {
+ await onUpdate(taskType, {
+ taskMetadata: { ...(config.taskMetadata || {}), stallNudge: !stallNudgeEnabled }
+ });
+ } finally {
+ setUpdating(false);
+ }
+ };
+
const handleReleaseOptionToggle = async (field) => {
setUpdating(true);
try {
@@ -797,6 +811,20 @@ export default function GlobalConfigControls({ taskType, config, onUpdate, onTri
</button>
);
})}
+ <button
+ type="button"
+ disabled={updating}
+ aria-pressed={stallNudgeEnabled}
+ aria-label={`${stallNudgeEnabled ? 'Disable' : 'Enable'} ${STALL_NUDGE_OPTION.label.toLowerCase()}`}
+ className={`w-full flex items-center justify-between gap-3 min-h-[44px] rounded px-2 -mx-2 text-left ${updating ? 'opacity-60 cursor-not-allowed' : 'cursor-pointer hover:bg-port-card/30 active:bg-port-card/50'}`}
+ onClick={handleStallNudgeToggle}
+ >
+ <div className="min-w-0 flex-1">
+ <span className="text-sm text-white">{STALL_NUDGE_OPTION.label}</span>
+ <p className="text-xs text-gray-500">{STALL_NUDGE_OPTION.description}</p>
+ </div>
+ <ToggleSwitch enabled={stallNudgeEnabled} disabled={updating} decorative />
+ </button>
</div>
{(config.taskMetadata?.openPR || claimFlow) && (
<FormField label="After opening PR" className="mt-3" labelClassName="text-sm text-gray-400 block mb-2">
diff --git a/client/src/components/cos/tabs/schedule/GlobalConfigControls.test.jsx b/client/src/components/cos/tabs/schedule/GlobalConfigControls.test.jsx
index b724997ca0..e0f6b96fb0 100644
--- a/client/src/components/cos/tabs/schedule/GlobalConfigControls.test.jsx
+++ b/client/src/components/cos/tabs/schedule/GlobalConfigControls.test.jsx
@@ -300,6 +300,22 @@ describe('GlobalConfigControls — release options', () => {
});
});
+describe('GlobalConfigControls — stall nudge', () => {
+ it('shows the nudge ON for a task that never set it and writes an explicit false when turned off', () => {
+ const onUpdate = renderControls({ taskMetadata: { useWorktree: true } });
+ expect(screen.getByRole('button', { name: 'Disable stall nudge' })).toHaveAttribute('aria-pressed', 'true');
+ fireEvent.click(screen.getByRole('button', { name: 'Disable stall nudge' }));
+ expect(onUpdate).toHaveBeenCalledWith('feature-ideas', { taskMetadata: { useWorktree: true, stallNudge: false } });
+ });
+
+ it('shows do-release with the nudge off and turns it back on', () => {
+ const onUpdate = renderControls({ taskType: 'do-release', taskMetadata: { slashdoCommand: 'release', stallNudge: false } });
+ expect(screen.getByRole('button', { name: 'Enable stall nudge' })).toHaveAttribute('aria-pressed', 'false');
+ fireEvent.click(screen.getByRole('button', { name: 'Enable stall nudge' }));
+ expect(onUpdate).toHaveBeenCalledWith('do-release', { taskMetadata: { slashdoCommand: 'release', stallNudge: true } });
+ });
+});
+
describe('GlobalConfigControls — file issues only', () => {
it('is hidden for non-audit tasks', () => {
renderControls();
diff --git a/server/lib/cosValidation.js b/server/lib/cosValidation.js
index 0fa0b29bf8..82567028e5 100644
--- a/server/lib/cosValidation.js
+++ b/server/lib/cosValidation.js
@@ -997,7 +997,13 @@ const ALLOWED_TASK_METADATA_KEYS = [
// `universe-bible-images`: hold canon entries that have no description yet
// out of the render batch, so image quota isn't spent on a name with nothing
// behind it. See services/scheduledHandlers/universeBibleImages.js.
- 'requireDescribed'
+ 'requireDescribed',
+ // Whether PortOS pastes its stall nudge into a TUI session that has sat quiet
+ // for STALL_NUDGE_IDLE_MS (lib/tuiHandshake.js). ON unless explicitly `false`.
+ // A task that legitimately waits a long time on work it started — do-release
+ // parking on its release PR's CI watch — turns it off, because the nudge lands
+ // mid-wait and reads as "wrap up now".
+ 'stallNudge'
];
// The params bag for the PROGRAMMATIC scheduled handlers
diff --git a/server/lib/validation.test.js b/server/lib/validation.test.js
index 6460e5f8f4..1442353717 100644
--- a/server/lib/validation.test.js
+++ b/server/lib/validation.test.js
@@ -975,6 +975,11 @@ describe('validation.js', () => {
});
describe('sanitizeTaskMetadata', () => {
+ it('keeps the stall-nudge toggle only as a boolean', () => {
+ expect(sanitizeTaskMetadata({ stallNudge: false })).toEqual({ stallNudge: false });
+ expect(sanitizeTaskMetadata({ stallNudge: 'off' })).toBeNull();
+ });
+
it('should return null for null/undefined/non-object input', () => {
expect(sanitizeTaskMetadata(null)).toBeNull();
expect(sanitizeTaskMetadata(undefined)).toBeNull();
diff --git a/server/services/agentTuiSpawning.test.js b/server/services/agentTuiSpawning.test.js
index b1fe1c86d4..de2989b436 100644
--- a/server/services/agentTuiSpawning.test.js
+++ b/server/services/agentTuiSpawning.test.js
@@ -2249,6 +2249,38 @@ describe('spawnTuiAgent runtime', () => {
expect(agentLifecycle.finalizeAgent).toHaveBeenCalledOnce();
});
+ // A schedule can turn the stall nudge off (taskMetadata.stallNudge: false) for a
+ // task whose long quiet stretch is a wait it owns. do-release ships that way:
+ // agent-0f4189d3 parked on its release PR's background CI watch, took the nudge
+ // as "wrap up" and wrote INCOMPLETE with the PR still open.
+ it.each([
+ { stallNudge: false, nudges: false },
+ { stallNudge: 'false', nudges: false },
+ { stallNudge: true, nudges: true },
+ { stallNudge: undefined, nudges: true },
+ ])('honors taskMetadata.stallNudge=$stallNudge once the prompt has started a turn', async ({ stallNudge, nudges }) => {
+ runSpawn({ task: { id: 'task-1', description: 'do the thing', metadata: stallNudge === undefined ? {} : { stallNudge } } });
+ await flushMicrotasks();
+ await capturedOnData(Buffer.from('Codex booting...\n' + CODEX_COMPOSER));
+ await vi.advanceTimersByTimeAsync(2000);
+ expect(pasteCount()).toBe(1);
+ await capturedOnData(Buffer.from('do the thing\n'));
+ await vi.advanceTimersByTimeAsync(4000);
+ // Output well after the submit is the run's own work, not an echo — the
+ // prompt has started a turn, which is when the opt-out takes over.
+ await vi.advanceTimersByTimeAsync(PROMPT_WORK_EVIDENCE_MS);
+ await capturedOnData(Buffer.from('Opened the release PR; waiting on its CI in the background.\n'));
+ vi.mocked(shellService.pasteToSession).mockClear();
+ await vi.advanceTimersByTimeAsync(nudges ? STALL_NUDGE_IDLE_MS + SIGNAL_POLL_MS : 2 * 60 * 60 * 1000);
+ if (nudges) {
+ expect(shellService.pasteToSession).toHaveBeenCalledWith(SESSION_ID, STALL_NUDGE_TEXT, expect.anything());
+ } else {
+ expect(shellService.pasteToSession).not.toHaveBeenCalled();
+ expect(cosAgentLifecycle.updateAgent).not.toHaveBeenCalledWith('agent-1', { metadata: { phase: 'stalled' } });
+ }
+ expect(agentLifecycle.finalizeAgent).not.toHaveBeenCalled();
+ });
+
// ── Stalled session: the turn just ended, with the task unfinished ─────────
// agent-bb3061af (2026-09-17): the run finished its /simplify pass, printed
// "Next: /do:pr", ended its turn and sat at an idle composer. Nothing was on
diff --git a/server/services/agentTuiSpawning/sessionController.js b/server/services/agentTuiSpawning/sessionController.js
index 7594aef00a..e1b5009895 100644
--- a/server/services/agentTuiSpawning/sessionController.js
+++ b/server/services/agentTuiSpawning/sessionController.js
@@ -41,6 +41,7 @@ import { createContentRefusalDetector, createClaudeSessionLimitBannerDetector, c
import { isAntigravityCommand } from '../../lib/antigravity.js';
import { isCodexCommand } from '../../lib/codex.js';
import { isClaudeCommand, isOpencodeCommand } from '../../lib/providerModels.js';
+import { isFalsyMeta } from '../../lib/metadataFlags.js';
import { createCodexModelRejectionGate } from './codexModelRejection.js';
import {
READY_POLL_INTERVAL_MS,
@@ -1962,6 +1963,13 @@ export function createTuiSessionController({
// validation/fix work. Silence alone must not inject another turn or badge
// it as stalled. Explicit provider failures and terminal signals above stay active.
if (sessionPhase !== 'running' || !promptSubmittedAt || securityScanGrant?.timeLimitSeconds === 'unlimited') return;
+ // The task's schedule turned the nudge off (taskMetadata.stallNudge). Its
+ // quiet stretches are waits it owns — do-release parks on its release PR's
+ // CI — so silence there is not a stall to interrupt. Only once the prompt
+ // has started a turn: before that, these nudges are what detects a prompt
+ // that never ran and fails it (prompt-not-submitted) instead of holding
+ // its lane forever.
+ if (promptGate.worked && isFalsyMeta(task?.metadata?.stallNudge)) return;
const stalled = stallNudgeGate.takeNudge(now, lastOutputAt);
if (!stalled) return;
// Read the sentinel here rather than on every tick: its watcher polls on its
diff --git a/server/services/taskSchedule.test.js b/server/services/taskSchedule.test.js
index 0351f609c7..e46bed43ba 100644
--- a/server/services/taskSchedule.test.js
+++ b/server/services/taskSchedule.test.js
@@ -608,6 +608,18 @@ describe('taskSchedule', () => {
expect(schedule.executions['task:do-release']).toMatchObject({ count: 2 })
})
+ it('turns the stall nudge off for a stored do-release schedule that never set it, and keeps an explicit choice', async () => {
+ mockSchedule({
+ tasks: { 'do-release': { type: 'on-demand', enabled: true, taskMetadata: { slashdoCommand: 'release', finishInFlight: true } } }
+ })
+ expect((await loadSchedule()).tasks['do-release'].taskMetadata).toMatchObject({ stallNudge: false, finishInFlight: true })
+
+ mockSchedule({
+ tasks: { 'do-release': { type: 'on-demand', enabled: true, taskMetadata: { slashdoCommand: 'release', stallNudge: true } } }
+ })
+ expect((await loadSchedule()).tasks['do-release'].taskMetadata.stallNudge).toBe(true)
+ })
+
it('should load and return existing v2 schedule', async () => {
mockSchedule({
tasks: { 'security': { type: 'weekly', enabled: true, providerId: 'p1', model: 'm1', prompt: null } }
diff --git a/server/services/taskScheduleRegistry.js b/server/services/taskScheduleRegistry.js
index 53489abf8a..965d41030a 100644
--- a/server/services/taskScheduleRegistry.js
+++ b/server/services/taskScheduleRegistry.js
@@ -58,10 +58,15 @@ const NON_COMMITTING_COORDINATOR_METADATA = { useWorktree: false, openPR: false,
// release options (RELEASE_OPTION_KEYS — finish in-flight work, merge dependency
// updates, resolve blockers, make routine decisions) are seeded ON and stay
// operator-editable, globally and per app; each is ON unless explicitly false.
+// `stallNudge: false` because a release run's longest quiet stretch is waiting
+// on its own release PR's CI, and a nudge there made agent runs quit INCOMPLETE
+// with the PR still open. loadSchedule's default deep-merge carries it into
+// existing installs that never set the key.
const DO_RELEASE_METADATA = {
...NON_COMMITTING_COORDINATOR_METADATA,
slashdoCommand: 'release',
...Object.fromEntries(RELEASE_OPTION_KEYS.map((key) => [key, true])),
+ stallNudge: false,
};
// Migration 274 removes branch-cleanup from new schedules, but a partially
// upgraded install may still load its stored task before the migration runs.