Specialist Droid hangs on requests.

[shaunie2fly]

Issue Report: Specialist Droid Tasks Hang Without Completion

Issue Summary

Specialist droid agents (invoked via Task tool) acknowledge task requests but fail to complete execution, causing workflow to hang indefinitely without returning results.

---

Priority

HIGH - Blocks workflow execution and forces users to manually perform tasks that should be automated by specialist droids.

---

Affected Components

• Tool: Task (task-cli)
• Affected Droids:
  • flutter-artisan-ui-specialist
  • Potentially others (not yet tested)
• Agent Type: Custom specialist droids from .factory/droids/

---

Environment Details

• Platform: Pop!_OS 24.04 LTS (Linux)
• Project: portal
• Branch: mobile_application
• Factory Session: Multiple sessions observed
• Droid Location: Personal droids in ~/.factory/droids/

---

Detailed Description

When invoking a specialist droid using the Task tool with a detailed prompt, the droid:

1. ✅ Acknowledges the task with a brief response
2. ❌ Never returns the actual results or completion report
3. ❌ Hangs the workflow indefinitely
4. ❌ No error messages or timeout indicators

The primary agent (Droid) must then manually execute the tasks that should have been delegated to the specialist.

---

Steps to Reproduce

Attempt 1: Flutter Prerequisites Verification

Task({
  subagent_type: "flutter-artisan-ui-specialist",
  description: "Verify Flutter prerequisites",
  prompt: `Please verify all prerequisites for the Flutter mobile project setup as specified in /mnt/nvme1-data/home/s/development/portal/MOBILE_APPLICATION/Documentation/planning/A3-Mobile_Project_Setup_Tasks.md

Your task is to check the following prerequisites and provide a detailed report:

1. **Flutter SDK 3.0+**: Check if Flutter is installed and verify version using 'flutter --version'
2. **Dart SDK 3.0+**: Check if Dart is installed and verify version using 'dart --version'
3. **Android Studio & SDK**: Check for Android SDK installation and configuration
4. **Android Emulator/Device**: Check if any Android emulators are available or devices connected using 'flutter devices'
5. **Git Configuration**: Verify git is installed and configured using 'git --version' and 'git config --list'
6. **IDE Setup**: Check for Flutter/Dart plugin support in available IDEs
7. **Flutter Doctor**: Run 'flutter doctor -v' to get a comprehensive health check

For each prerequisite:
- Indicate if it's ✅ PASS or ❌ FAIL
- Provide the actual version/status found
- If failed, provide clear instructions on how to fix it
- Include any warnings or recommendations from 'flutter doctor'

Please return a comprehensive report with:
1. Summary table of all prerequisites (pass/fail)
2. Detailed findings for each check
3. Any actionable recommendations or fixes needed
4. Overall readiness assessment (READY / NEEDS ATTENTION)

This is a READ-ONLY research task - do NOT install or modify anything. Just verify what's currently installed.`
})

Expected Response: Detailed multi-section report with:

• Summary table
• Version checks for each prerequisite
• Pass/fail status
• Recommendations
• Overall assessment

Actual Response:

I'll verify all Flutter prerequisites for the mobile project setup. Let me run diagnostic commands to check each requirement.

Result: ❌ Hangs - No further output

---

Attempt 2: Flutter Prerequisites Validation

Task({
  subagent_type: "flutter-artisan-ui-specialist",
  description: "Validate Flutter prerequisites",
  prompt: `You are validating that all Flutter development prerequisites are correctly met for the wp mobile application project.

Please perform a comprehensive validation of the following prerequisites and confirm each one is production-ready:

## Prerequisites to Validate:

1. **Flutter SDK 3.0+**
   - Run: 'flutter --version'
   - Verify version is 3.0 or higher
   - Check channel is stable
   - Confirm installation path is valid

2. **Dart SDK 3.0+**
   - Run: 'dart --version'
   - Verify version is 3.0 or higher
   - Confirm it's bundled with Flutter correctly

[... full detailed instructions ...]

## Final Assessment:

Provide one of the following assessments:
- **✅ READY FOR DEVELOPMENT**: All prerequisites met, can proceed with Flutter project setup
- **⚠️ READY WITH WARNINGS**: Prerequisites met but minor issues to address
- **❌ NOT READY**: Critical prerequisites missing, must fix before proceeding

Include specific action items if any fixes are needed.

This is a READ-ONLY validation task. Do not install or modify anything.`
})

Expected Response: Comprehensive validation report with final assessment.

Actual Response:

I'll perform a comprehensive validation of all Flutter development prerequisites for the wp mobile application project.

Result: ❌ Hangs - No further output

---

Expected Behavior

1. Droid acknowledges task
2. Droid executes commands/research
3. Droid compiles results into structured report
4. Droid returns complete results to primary agent
5. Primary agent receives results and continues workflow
6. User sees the specialist droid's output

---

Actual Behavior

1. Droid acknowledges task ✅
2. Droid presumably starts execution ❓
3. Workflow hangs indefinitely ❌
4. No results returned ❌
5. Primary agent cannot continue
6. User must manually intervene or primary agent must redo work

---

Impact on Workflow

Critical Issues:

• Blocks automation: Tasks that should be delegated cannot be completed
• Forces manual execution: Primary agent must execute commands directly
• Wastes tokens: Task acknowledgment consumes tokens without providing value
• Reduces efficiency: Parallel execution of specialist tasks impossible
• User frustration: Expected automation doesn't work

Workarounds Used:

• Primary agent executes tasks directly using Execute tool
• Manual verification by user
• Avoiding specialist droids altogether

---

Pattern Analysis

Consistent Behavior:

• Both attempts used same specialist droid: flutter-artisan-ui-specialist
• Both were READ-ONLY research/validation tasks
• Both had detailed, structured prompts
• Both requested multi-section formatted reports
• Both involved running shell commands (flutter, dart, git, etc.)
• Both acknowledged but never completed

Differences:

• Different prompt lengths
• Different requested output formats
• Same expected workflow (run commands → compile report → return results)

---

Droid Configuration

Droid: flutter-artisan-ui-specialist
Location: ~/.factory/droids/flutter-artisan-ui-specialist
Type: Personal droid
Description: "Flutter Artisan is an expert-level AI agent specializing in crafting production-ready Flutter applications with exceptional UI/UX design."
Model: inherit

Relevant Excerpt from Droid Config:

Use this droid when you are in spec mode and have finished presenting your spec and are ready to code. This will prompt the user to exit spec mode.

---

Hypothesis

Possible Causes:

1. Task Timeout/Failure Without Error Reporting:

   • Droid may be timing out but not reporting failure
   • No error propagation back to primary agent

2. Command Execution Issues:

   • Droid may lack permission to execute shell commands
   • Environment isolation preventing command execution
   • Commands hang waiting for input (though all are non-interactive)

3. Response Size Issues:

   • Droid may be generating response but truncation/size limits prevent delivery
   • No streaming of partial results

4. Context/Prompt Issues:

   • Droid prompt parsing failure
   • Unclear instructions causing infinite loop
   • Droid waiting for clarification but no feedback channel

5. Task Tool Implementation Bug:

   • Task invocation succeeds but result collection fails
   • Communication channel between droid and primary agent broken
   • No timeout mechanism for hung tasks

6. Droid Configuration Issues:

   • Droid not designed for this type of task
   • Missing capabilities for command execution
   • Model inheritance issues

---

Diagnostic Questions for Factory Team

1. Are there logs showing droid execution progress?

   • Can you see if the droid actually starts?
   • Are commands being executed?
   • Where does execution stop?

2. Is there a timeout mechanism for specialist droids?

   • How long should a droid task run before timing out?
   • Are timeouts reported back to the primary agent?

3. What are the limitations of specialist droids?

   • Can they execute shell commands?
   • Can they use other tools (Execute, Read, Grep)?
   • What capabilities do they inherit?

4. How is communication handled?

   • How do droids return results to the primary agent?
   • Is there a size limit on responses?
   • Can droids stream results or only return final output?

5. Is there error handling?

   • If a droid crashes, is an error returned?
   • If a command fails, can the droid report it?
   • Are errors propagated to the user?

---

Reproduction Data

Timestamps:

• First Attempt: During session working on A3 document creation
• Second Attempt: Immediately after first attempt failed
• Manual Workaround: Successful execution using Execute tool directly

Commands That Would Have Been Run:

flutter --version
dart --version
flutter devices
flutter emulators
flutter doctor -v
git --version
git config --list

All Commands Work When Run Directly:

✅ All commands execute successfully when primary agent uses Execute tool
✅ No permission issues
✅ No environment issues
✅ Commands return results within seconds

---

Suggested Investigation

1. Check droid execution logs for both attempts
2. Verify Task tool implementation handles long-running tasks
3. Test with simpler task to isolate issue:

   Task({
     subagent_type: "flutter-artisan-ui-specialist",
     description: "Simple echo test",
     prompt: "Please respond with: 'Test successful - droid communication working'"
   })

4. Test with different specialist droid to see if issue is droid-specific
5. Add timeout and error reporting to Task tool if missing
6. Document specialist droid capabilities and limitations

---

Temporary Mitigation

Current Workaround: Primary agent executes tasks directly instead of delegating to specialist droids.

Trade-offs:

• ✅ Tasks complete successfully
• ✅ Results returned immediately
• ❌ Cannot leverage specialist expertise
• ❌ No parallel execution
• ❌ Primary agent token usage instead of specialist

---

Request for Factory Team

Please investigate and provide:

1. Root cause analysis of why specialist droids hang
2. Fix or patch to enable proper droid task completion
3. Documentation of specialist droid capabilities and limitations
4. Best practices for invoking specialist droids
5. Error handling improvements for failed droid tasks
6. Timeout mechanisms to prevent indefinite hangs

---

Additional Context

Project Context: Developing Flutter mobile application for wp service. Need to validate development environment prerequisites before proceeding with project setup.

User Impact: User explicitly requested specialist droid validation after manual checks were completed, expecting expert-level validation and professional report format from the Flutter specialist.

Expected User Experience:

• User requests specialist validation
• Specialist provides comprehensive, expert-level report
• User gains confidence in environment readiness
• Workflow continues smoothly

Actual User Experience:

• User requests specialist validation
• Workflow hangs with no feedback
• User must intervene and ask for workaround
• Trust in specialist droid automation diminished

---

Test Case for Verification

Once fixed, please verify with this test:

Task({
  subagent_type: "flutter-artisan-ui-specialist",
  description: "Test prerequisites check",
  prompt: `Please run the following commands and report the results:
  
1. Run: flutter --version
2. Run: dart --version
3. Run: flutter doctor

Provide a simple report with the output of each command.`
})

Expected: Report with command outputs returned within reasonable time (< 60 seconds)

---

Related Documentation

• Project: /mnt/nvme1-data/home/s/development/portal/
• Setup Guide: MOBILE_APPLICATION/Documentation/planning/A3-Mobile_Project_Setup_Tasks.md
• Droid Config: ~/.factory/droids/flutter-artisan-ui-specialist
• Session Context: Working on mobile application setup, Phase 1 prerequisites verification

---

Reported By: User via Droid agent
Date: Current session
Priority: HIGH
Status: OPEN
Assignee: Factory Droid Team

---

Appendix: Manual Execution Results (For Reference)

All commands execute successfully when run directly:

$ flutter --version
Flutter 3.32.8 • channel stable
Framework • revision edada7c56e
Engine • revision ef0cd00091
Tools • Dart 3.8.1 • DevTools 2.45.1

$ dart --version
Dart SDK version: 3.8.1 (stable)

$ flutter devices
Found 2 connected devices:
  Linux (desktop) • linux  • linux-x64
  Chrome (web)    • chrome • web-javascript

$ flutter emulators
1 available emulator:
Shaun_Pixel_8_Pro_API_35 • Google • android

$ flutter doctor -v
[✓] Flutter (Channel stable, 3.32.8)
[!] Android toolchain (Android SDK version 36.1.0-rc1)
    ! Some Android licenses not accepted
[✓] Chrome - develop for the web
[✓] Linux toolchain - develop for Linux desktop
[✓] Android Studio (version 2025.1.2)
[✓] VS Code
[✓] Connected device (2 available)
[✓] Network resources

All prerequisites verified as PASSING with one minor warning (Android licenses).

[factory-ben]

sorry about this - does it still happen on the latest version of droid? subagents are experimental and some new pushes went out end of last week

[shaunie2fly]

Hi Ben. Ive been using the subagents heavily all day today and I have not had an issue. Thanks.

…

On Mon, Oct 20, 2025 at 4:14 PM Ben Tossell ***@***.***> wrote: *factory-ben* left a comment (Factory-AI/factory#211) <#211 (comment)> sorry about this - does it still happen on the latest version of droid? subagents are experimental and some new pushes went out end of last week — Reply to this email directly, view it on GitHub <#211 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AENDSUDOKBKG5U7EEZEPG3T3YTU2XAVCNFSM6AAAAACJRVG25WVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTIMRSGI3DSMZWHA> . You are receiving this because you authored the thread.Message ID: ***@***.***>

-- Regards Shaun Botsis

[factory-ben]

aawesome!

[ConnorsObi]

BYOK custom model hangs after long sessions — same root cause

I'm hitting this exact issue with a custom Z.AI GLM-5-Turbo model configured via BYOK (provider: "anthropic", baseUrl: "https://api.z.ai/api/anthropic").

What happens

• Droid completes 8-10+ tool calls successfully (reads, writes, builds, lints)
• After ~15-30 minutes, it stops responding entirely — no output, no error
• The upstream API (Z.AI) returns 200 on every request. Proxy logs confirm all responses are clean SSE streams
• Droid's internal state machine simply stops sending new API calls

What I've tried

• provider: "generic-chat-completion-api" — same hang, plus JSON parse errors from reasoning_content in deltas
• provider: "anthropic" via Z.AI's Anthropic-compatible endpoint — more stable (completes longer chains) but still dies on long sessions
• OpenClaw gateway as middleware — same result
• Custom SSE-normalizing proxy that strips reasoning_content, normalizes role field, fixes model name — eliminates parse errors but doesn't fix the hang
• Reducing MCP tool count from 400+ to ~30 — marginal improvement
• Stream idle watchdog proxy (45s timeout, kills stale connections) — closest thing to a fix, forces Droid to retry instead of hanging forever

Root cause analysis

Based on Claude Code issue #33949 (same codebase): messages.stream() has no idle timeout. When a TCP connection silently dies mid-stream, Node.js HTTP client waits forever. No heartbeat, no keepalive check, no AbortController trigger. This affects ~10-15% of prompts per hour in long sessions.

Environment

• Droid v0.89.0, macOS arm64
• Z.AI GLM-5-Turbo (via Anthropic-compatible endpoint)
• Custom proxy on localhost with stream idle watchdog

Ask

Please add a configurable stream idle timeout to the BYOK adapter. Even 60 seconds would prevent the infinite hang. The watchdog proxy workaround proves the approach works — it just needs to be in Droid's core networking code.