Hard-stop agent workflows when shell spawn returns exit_code -1 #258

New Issue

2026-07-06T12:09:24-05:00

jcwalker3 commented

2026-07-06 12:09:24 -05:00

Problem

When the Cursor/Grok shell executor fails to spawn (exit_code: -1, no stdout/stderr), agents currently retry indefinitely. In session 019f382e this caused 100+ tool calls and multi-minute stalls on a trivial encode+commit task.

Proposal

After the first spawn failure on a trivial probe (echo, pwd), mark shell unavailable for the session.
After N consecutive spawn failures (e.g. 2), hard-stop further Shell tool use and return a recovery report.
Recovery report should mention: restart session, kill hung background terminals, use MCP-native paths.

Acceptance

Documented operator/agent behavior when shell spawn is broken.
Tests or harness guardrails prevent retry spirals.

Context

Blocked #152 doc commit on 2026-07-06; hung pytest in terminal 5 (pid 23337) suspected contributor.

## Problem When the Cursor/Grok shell executor fails to spawn (`exit_code: -1`, no stdout/stderr), agents currently retry indefinitely. In session `019f382e` this caused 100+ tool calls and multi-minute stalls on a trivial encode+commit task. ## Proposal - After the first spawn failure on a trivial probe (`echo`, `pwd`), mark shell unavailable for the session. - After N consecutive spawn failures (e.g. 2), hard-stop further Shell tool use and return a recovery report. - Recovery report should mention: restart session, kill hung background terminals, use MCP-native paths. ## Acceptance - Documented operator/agent behavior when shell spawn is broken. - Tests or harness guardrails prevent retry spirals. ## Context Blocked #152 doc commit on 2026-07-06; hung pytest in terminal 5 (`pid 23337`) suspected contributor.

jcwalker3 referenced this issue

2026-07-06 12:21:31 -05:00

Map gitea_commit_files in the task capability resolver #262

jcwalker3 referenced this issue

2026-07-06 12:21:33 -05:00

Provide native MCP-safe commit payload preparation without shell #263

jcwalker3 added the status:in-progress label 2026-07-06 13:44:52 -05:00

jcwalker3 commented

2026-07-06 13:45:23 -05:00

Claimed. Branch: docs/issue-258-shell-spawn-hard-stop. Worktree: branches/docs-issue-258-shell-spawn-hard-stop. Lock taken via gitea_lock_issue (fail-closed check passed).

Scope for this slice (per acceptance criteria):

Documented operator/agent behavior for shell-spawn failure (exit_code: -1, empty stdout/stderr): probe once, mark shell unavailable, hard-stop after 2 consecutive spawn failures, emit recovery report (restart session, kill hung background terminals, prefer MCP-native paths)
Rule text in docs/llm-workflow-runbooks.md and the portable skill doc
Doc-contract tests so the guardrail text cannot silently regress

Claimed. Branch: `docs/issue-258-shell-spawn-hard-stop`. Worktree: `branches/docs-issue-258-shell-spawn-hard-stop`. Lock taken via `gitea_lock_issue` (fail-closed check passed). Scope for this slice (per acceptance criteria): - Documented operator/agent behavior for shell-spawn failure (`exit_code: -1`, empty stdout/stderr): probe once, mark shell unavailable, hard-stop after 2 consecutive spawn failures, emit recovery report (restart session, kill hung background terminals, prefer MCP-native paths) - Rule text in `docs/llm-workflow-runbooks.md` and the portable skill doc - Doc-contract tests so the guardrail text cannot silently regress

jcwalker3 referenced this issue from a commit

2026-07-06 13:52:26 -05:00

docs: add Shell Spawn Hard-Stop Rule for agent workflows (#258)

jcwalker3 referenced a pull request that will close this issue

2026-07-06 13:53:23 -05:00

docs: add Shell Spawn Hard-Stop Rule for agent workflows (Closes #258) #281

sysadmin closed this issue

2026-07-07 01:18:51 -05:00

sysadmin referenced this issue from a commit

2026-07-07 01:18:52 -05:00

Merge pull request 'docs: add Shell Spawn Hard-Stop Rule for agent workflows (Closes #258)' (#281) from docs/issue-258-shell-spawn-hard-stop into master

sysadmin removed the status:in-progress label 2026-07-07 01:18:52 -05:00