feat(config): add workflow.subagent_timeout to replace hardcoded 5-minute limit

The map-codebase workflow had a hardcoded 300000ms (5 minute) timeout
for parallel subagent tasks. On large codebases or with slower models
(e.g. GPT via Codex), subagents can need 10-20+ minutes, causing the
parent to kill still-working agents and fall back to sequential mode.

Changes:
- Add workflow.subagent_timeout config key (default: 300000ms)
- Register in VALID_CONFIG_KEYS (config.cjs)
- Add to loadConfig() defaults and return object (core.cjs)
- Emit in map-codebase init context (init.cjs)
- Update map-codebase.md to use config value instead of hardcoded 300000
- Document in planning-config.md reference

Users can now increase the timeout via:
  /gsd:settings workflow.subagent_timeout 900000

Closes #1472

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

get-shit-done/bin/lib/config.cjs

@@ -25,6 +25,7 @@ const VALID_CONFIG_KEYS = new Set([
   'workflow.use_worktrees',
   'git.branching_strategy', 'git.phase_branch_template', 'git.milestone_branch_template', 'git.quick_branch_template',
   'planning.commit_docs', 'planning.search_gitignored',
+  'workflow.subagent_timeout',
   'hooks.context_warnings',
   'project_code', 'phase_naming',
 ]);

get-shit-done/bin/lib/core.cjs

@@ -218,6 +218,7 @@ function loadConfig(cwd) {
     context_window: 200000, // default 200k; set to 1000000 for Opus/Sonnet 4.6 1M models
     phase_naming: 'sequential', // 'sequential' (default, auto-increment) or 'custom' (arbitrary string IDs)
     project_code: null, // optional short prefix for phase dirs (e.g., 'CK' → 'CK-01-foundation')
+    subagent_timeout: 300000, // 5 min default; increase for large codebases or slower models (ms)
   };
 
   try {
@@ -310,6 +311,7 @@ function loadConfig(cwd) {
       context_window: get('context_window') ?? defaults.context_window,
       phase_naming: get('phase_naming') ?? defaults.phase_naming,
       project_code: get('project_code') ?? defaults.project_code,
+      subagent_timeout: get('subagent_timeout', { section: 'workflow', field: 'subagent_timeout' }) ?? defaults.subagent_timeout,
       model_overrides: parsed.model_overrides || null,
       agent_skills: parsed.agent_skills || {},
     };

get-shit-done/bin/lib/init.cjs

@@ -780,6 +780,7 @@ function cmdInitMapCodebase(cwd, raw) {
     commit_docs: config.commit_docs,
     search_gitignored: config.search_gitignored,
     parallelization: config.parallelization,
+    subagent_timeout: config.subagent_timeout,
 
     // Paths
     codebase_dir: '.planning/codebase',

get-shit-done/references/planning-config.md

@@ -25,6 +25,7 @@ Configuration options for `.planning/` directory behavior.
 | `git.milestone_branch_template` | `"gsd/{milestone}-{slug}"` | Branch template for milestone strategy |
 | `git.quick_branch_template` | `null` | Optional branch template for quick-task runs |
 | `workflow.use_worktrees` | `true` | Whether executor agents run in isolated git worktrees. Set to `false` to disable worktrees — agents execute sequentially on the main working tree instead. Recommended for solo developers or when worktree merges cause issues. |
+| `workflow.subagent_timeout` | `300000` | Timeout in milliseconds for parallel subagent tasks (e.g. codebase mapping). Increase for large codebases or slower models. Default: 300000 (5 minutes). |
 </config_schema>
 
 <commit_docs_behavior>

get-shit-done/workflows/map-codebase.md

@@ -36,7 +36,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 AGENT_SKILLS_MAPPER=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" agent-skills gsd-codebase-mapper 2>/dev/null)
 ```
 
-Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`.
+Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`, `subagent_timeout`.
 </step>
 
 <step name="check_existing">
@@ -199,9 +199,11 @@ Wait for all 4 agents to complete using TaskOutput tool.
 TaskOutput tool:
   task_id: "{task_id from Agent result}"
   block: true
-  timeout: 300000
+  timeout: {subagent_timeout from init context, default 300000}
 ```
 
+> The timeout is configurable via `workflow.subagent_timeout` in `.planning/config.json` (milliseconds). Default: 300000 (5 minutes). Increase for large codebases or slower models.
+
 Call TaskOutput for all 4 agents in parallel (single message with 4 TaskOutput calls).
 
 Once all TaskOutput calls return, read each agent's output file to collect confirmations.

tests/subagent-timeout.test.cjs

@@ -0,0 +1,125 @@
+/**
+ * GSD Tools Tests - subagent timeout configuration
+ *
+ * Validates that workflow.subagent_timeout is properly registered,
+ * loaded from config, and emitted in init context.
+ *
+ * Closes: #1472
+ */
+
+const { test, describe, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+const { runGsdTools, createTempProject, cleanup } = require('./helpers.cjs');
+
+// ─── config key registration ─────────────────────────────────────────────────
+
+describe('workflow.subagent_timeout config key (#1472)', () => {
+  let tmpDir;
+
+  beforeEach(() => {
+    tmpDir = createTempProject();
+  });
+
+  afterEach(() => {
+    cleanup(tmpDir);
+  });
+
+  test('subagent_timeout has correct default value (300000ms)', () => {
+    // Write a minimal config.json
+    const configPath = path.join(tmpDir, '.planning', 'config.json');
+    fs.writeFileSync(configPath, JSON.stringify({ model_profile: 'balanced' }, null, 2));
+
+    // Load config via init and check the value propagates
+    // Use config-get to verify the field is recognized
+    const result = runGsdTools(['config-set', 'workflow.subagent_timeout', '600000'], tmpDir);
+    assert.ok(result.success, `config-set should accept workflow.subagent_timeout: ${result.error}`);
+
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    assert.strictEqual(config.workflow.subagent_timeout, 600000);
+  });
+
+  test('config-set rejects invalid config keys but accepts subagent_timeout', () => {
+    const configPath = path.join(tmpDir, '.planning', 'config.json');
+    fs.writeFileSync(configPath, JSON.stringify({}, null, 2));
+
+    // Valid key should succeed
+    const valid = runGsdTools(['config-set', 'workflow.subagent_timeout', '900000'], tmpDir);
+    assert.ok(valid.success, `workflow.subagent_timeout should be a valid key: ${valid.error}`);
+
+    // Invalid key should fail
+    const invalid = runGsdTools(['config-set', 'workflow.nonexistent_key', 'true'], tmpDir);
+    assert.ok(!invalid.success, 'nonexistent key should be rejected');
+  });
+
+  test('subagent_timeout appears in map-codebase init context', () => {
+    const configPath = path.join(tmpDir, '.planning', 'config.json');
+    fs.writeFileSync(configPath, JSON.stringify({
+      workflow: { subagent_timeout: 600000 }
+    }, null, 2));
+
+    const result = runGsdTools('init map-codebase', tmpDir, { HOME: tmpDir });
+    assert.ok(result.success, `init map-codebase should succeed: ${result.error}`);
+
+    const parsed = JSON.parse(result.output);
+    assert.strictEqual(parsed.subagent_timeout, 600000, 'init context should include configured timeout');
+  });
+
+  test('subagent_timeout defaults to 300000 when not configured', () => {
+    const configPath = path.join(tmpDir, '.planning', 'config.json');
+    fs.writeFileSync(configPath, JSON.stringify({}, null, 2));
+
+    const result = runGsdTools('init map-codebase', tmpDir, { HOME: tmpDir });
+    assert.ok(result.success, `init map-codebase should succeed: ${result.error}`);
+
+    const parsed = JSON.parse(result.output);
+    assert.strictEqual(parsed.subagent_timeout, 300000, 'default should be 300000ms (5 minutes)');
+  });
+});
+
+describe('map-codebase workflow references configurable timeout (#1472)', () => {
+  test('workflow file references subagent_timeout from init context', () => {
+    const workflowPath = path.join(__dirname, '..', 'get-shit-done', 'workflows', 'map-codebase.md');
+    const content = fs.readFileSync(workflowPath, 'utf8');
+
+    assert.ok(
+      content.includes('subagent_timeout'),
+      'map-codebase.md should reference subagent_timeout from init context'
+    );
+    assert.ok(
+      content.includes('workflow.subagent_timeout'),
+      'map-codebase.md should document the config key'
+    );
+  });
+
+  test('workflow file no longer has hardcoded 300000 timeout', () => {
+    const workflowPath = path.join(__dirname, '..', 'get-shit-done', 'workflows', 'map-codebase.md');
+    const content = fs.readFileSync(workflowPath, 'utf8');
+
+    // The timeout line should reference the config variable, not a hardcoded value
+    const timeoutLines = content.split('\n').filter(l => l.includes('timeout:'));
+    for (const line of timeoutLines) {
+      assert.ok(
+        !line.match(/timeout:\s*300000\s*$/),
+        `found hardcoded timeout: "${line.trim()}". Should reference subagent_timeout from init context.`
+      );
+    }
+  });
+});
+
+describe('planning-config.md documents subagent_timeout (#1472)', () => {
+  test('reference doc includes subagent_timeout entry', () => {
+    const refPath = path.join(__dirname, '..', 'get-shit-done', 'references', 'planning-config.md');
+    const content = fs.readFileSync(refPath, 'utf8');
+
+    assert.ok(
+      content.includes('workflow.subagent_timeout'),
+      'planning-config.md should document workflow.subagent_timeout'
+    );
+    assert.ok(
+      content.includes('300000'),
+      'planning-config.md should document the default value (300000)'
+    );
+  });
+});