When a Job-Search CLI Times Out, It Says "Result Unknown" and Never Re-Sends: recruitment-cli's Failure Model
Any system that triggers remote side effects — a send, a payment, an API call — faces the same ambiguity between "didn't happen" and "happened but unconfirmed." recruitment-cli's conservative recovery pattern, treating unknown as a distinct state and refusing to auto-replay, is a practical template for keeping those systems honest.
recruitment-cli exposes a unified workflow for job seekers and recruiters: you scope a platform, account, role, and filters; it builds a target list with activity evidence; you create a communication plan; then it executes and saves platform receipts. The same abilities run from a CLI, a local AI demo, or an SDK that can be plugged into any agent. All entry points converge on a shared RecruitmentClient, so deduplication and recovery rules live in one place.
The hard part is the timeout window. If a greeting is sent, the platform completes it, but local code only sees a timeout, the state could be either "not sent" or "sent but unconfirmed". Rather than guess, the tool writes a `pending` record before invoking the remote call, and on exception marks the operation `indeterminate`. A later run converts any leftover `pending` to `indeterminate` and skips that target; only a business receipt that matches the target's API path and parameters is allowed to upgrade state to `sent`. The AI entry point enforces this by requiring an `allowContact` policy that the model cannot set via its own arguments.
The design explicitly trades away auto-recovery for traceability: if the process dies after `pending` is written but before the remote call, the next run will not re-send, even though nothing may have been sent. It reduces duplicate greetings at the cost of occasional manual verification. Current limits include local-only records (no cross-device dedup), no server-side idempotency key, and platform-adapters that must track page and protocol changes.
Persisting pending before the remote call turns an ambiguous crash into a known indeterminate state, buying a guarantee against duplicate sends at the cost of possibly asking the user to manually verify a contact that never happened.
The tool treats 'skipped' as two different things depending on whether it happened before or after entering the send phase; the same display label hides different recovery semantics, which is a reminder that state names alone don't carry behavior.
By putting business rules in a shared client rather than in the CLI layer, recruitment-cli ensures that any AI agent using the SDK can't accidentally bypass deduplication; the design enforces that 'may send' and 'may send again' are separate checks.
The explicit limitation that no server-side idempotency key exists is refreshing: the tool documents what it does not guarantee, which is more useful than overclaiming exactly-once delivery capability.