fix: auto-start workers in TaskHandler context manager

[nthmost-orkes]

Summary

TaskHandler.__enter__ now calls start_processes() automatically, so with TaskHandler(...) as th: works correctly without a separate th.start_processes() call inside the block.

Changes:

• __enter__ calls start_processes() on entry; if it raises, calls stop_processes() before propagating (since Python skips __exit__ when __enter__ raises)
• start_processes() gains an idempotency guard (_processes_started flag) so existing code that calls it explicitly inside the with block is unaffected
• stop_processes() resets the flag so stop → restart cycles work correctly
• Flag is set after a successful start so a failed start remains retryable

Fixes conductor-oss/getting-started#42.

User impact

First-time users following the quickstart who used with TaskHandler(...) as th: without calling th.start_processes() would see their workflow hang in RUNNING indefinitely — 0 workers were ever started. Now the context manager behaves like standard Python: setup happens in __enter__, teardown in __exit__.

Test plan

• test_context_manager_enter — verifies with handler as h: h is handler
• test_context_manager_exit — verifies stop_processes() is called on exit
• 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.