fix: auto-start workers in context manager; warn on RUNNING+failed tasks

[nthmost-orkes]

Summary

• TaskHandler context manager auto-starts workers (__enter__ now calls start_processes()), so with TaskHandler(...) as h: works correctly without a separate h.start_processes() call. start_processes() gains an idempotency guard (_processes_started flag) so existing code that calls it explicitly inside the with block is unaffected. Fixes Python SDK: TaskHandler context manager silently starts 0 workers if start_processes() is not called explicitly getting-started#42.

• WorkflowExecutor.execute() warns when workflow is RUNNING but a task has already failed — when execute() returns a RUNNING run after the wait timeout expires, it now does a follow-up get_workflow() call, finds any FAILED/FAILED_WITH_TERMINAL_ERROR tasks, and logs a WARNING with the task reference name and reason_for_incompletion. This surfaces failure details that would otherwise be invisible (workflow stays RUNNING while the failed task awaits retries). Fixes Python SDK: worker exception causes silent stuck RUNNING workflow — execute() returns RUNNING with no error getting-started#41.

Test plan

• TestTaskHandlerContextManager::test_context_manager_enter — verifies with handler as h: h is handler
• TestTaskHandlerContextManager::test_context_manager_exit — verifies stop_processes() is called on exit (updated to patch Process since __enter__ now starts workers)
• Full unit suite: python3 -m pytest tests/unit/ — 440 passed

🤖 Generated with Claude Code

[v1r3n]

what are the implications of auto starting the process?

[nthmost-orkes]

Good question -- mostly pros in my reckoning but i'll take a second look.

1. Fixes the context manager contract. with-as-no-op is a Python anti-pattern. File handles, locks, threads, subprocess all acquire on enter. TaskHandler was the odd one.
2. Fixes a real user bug — Python SDK: TaskHandler context manager silently starts 0 workers if start_processes() is not called explicitly getting-started#42. Users wrote with TaskHandler(...) as h: expecting it to run and got silence.
3. Idempotency guard preserves every existing caller. Anyone doing with h: h.start_processes() is unaffected — second call is a no-op.
4. stop_processes() resets the flag, so stop → restart works. (Onboard repo to PyPI (Python Package Index) #3 from last turn is handled.)

I'll go look at some things that come to mind... will update

[nthmost-orkes]

Changes prompted by this review:

Thinking through the implications surfaced two edge cases worth hardening, both now pushed as follow-up commits:

• Partial-failure cleanup in __enter__ — Python skips __exit__ when __enter__ raises, so if start_processes() bailed mid-spawn, any already-started workers would leak. __enter__ now calls stop_processes() before re-raising.
• Flag-set ordering — _processes_started = True now runs after a successful start rather than before, so a failed start remains retryable instead of silently no-op'ing on the next attempt.

For the main behavior change itself:

• Backward compat is preserved — the idempotency guard means existing code that calls start_processes() explicitly inside a with block is unaffected.
• stop_processes() resets the flag, so stop → restart cycles still work.