跪拜 Guibai
← All articles
TypeScript · Node.js · Architecture

When a Job-Search CLI Times Out, It Says "Result Unknown" and Never Re-Sends: recruitment-cli's Failure Model

By 浪遏 ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

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.

Summary

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.

Takeaways
— recruitment-cli provides four workflow stages: define scope, organize targets, prepare communication, and execute with receipts; each stage produces a result for the next step.
— A stable bindingId is computed from platformId + accountId, so multiple aliases for the same account share locks and operation records.
— The send-record key is platformId + accountId + role + targetId, deliberately excluding planId so the same target in two plans is still one business contact.
— Account locks handle concurrency within a local data directory; operation records handle recovery after a process restart; neither shares across machines.
— The execution order is: write a pending operation to disk first, then invoke the remote send; the remote call's definite receipt sets state to sent or skipped, and any exception sets it to indeterminate.
— On a later run, a leftover pending record is converted to indeterminate and the target is skipped, not retried, because local state can't know whether the send actually happened.
— A skipped outcome from the pre-check is not persisted so a new plan can reconsider that target; a definite skip after contacting the platform is persisted.
— The BOSS adapter generates a send receipt only when the response's API path and target parameters match, and the business result is successful; opening a window or returning from a click is not evidence.
— AI tools separate read, local-write, and remote-write; recruit_run_plan requires an allowContact policy passed by the caller, which the model cannot grant itself in its arguments.
— Version 0.1.2 requires Node.js ≥ 22.16 and Chrome/Chromium; the author verified the release with 13 offline tests using fictional data.
— Current boundaries: no shared dedup across devices, no server-side idempotency key, and platform adapters need ongoing maintenance for page and protocol changes.
Conclusions

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.

Concepts & terms
Indeterminate outcome
A third result state beyond success and failure, used when a remote operation may have completed but the client cannot confirm it. Instead of retrying or declaring success, the system records that the outcome is unknown and stops, so the user can verify manually.
Business receipt
Platform evidence that a specific business action (like sending a greeting) actually succeeded, verified by matching the API request path and target parameters against the response. Only such a receipt can upgrade an operation from pending to sent.
Binding ID
A stable identifier computed from platformId plus accountId, independent of any alias the user picks. Aliases are just pointers to this identity, allowing account locks and operation records to be shared across all aliases that reference the same real account.
Source: juejin.cn ↗ Google Translate ↗ Backup ↗