Skip to content

The agent that grows with you

fix(unbroker): review round - nameless-email gate, dnc consent scope, defunct exclusion

SHL0MSde406259c545
diff --git a/optional-skills/security/unbroker/README.md b/optional-skills/security/unbroker/README.md
index 3a3b6980492..f5e027ed5e2 100644
--- a/optional-skills/security/unbroker/README.md
+++ b/optional-skills/security/unbroker/README.md
@@ -121,10 +121,10 @@ The underlying CLI (run via `terminal`, as `python3 scripts/pdd.py <cmd>`):
a single verified request deletes their data from **every registered broker at once**, and
`pdd.py next` surfaces it as the highest-leverage action.
- **Spam-call lane.** A run can be entered from the phone number ("my number keeps getting spam
- calls"): the number is scanned across the reverse-phone people-search sites (18 of the 22
- curated records), opted out, and re-checked on the same schedule - and `pdd.py dnc` registers it
- on the FTC's National Do Not Call Registry (surfaced by `next` for US personal numbers until
- filed).
+ calls"): the number is scanned across the reverse-phone people-search sites (14 of the live
+ curated records; five curated brokers are defunct and excluded from planning), opted out, and
+ re-checked on the same schedule - and `pdd.py dnc` registers it on the FTC's National Do Not
+ Call Registry (surfaced by `next` for phone-led US runs until filed or declined).
- **Ledger, audit, and re-scan.** Every case is a validated state machine, every PII disclosure is
logged (field names only), and confirmed removals are re-scanned on a schedule so a re-listing is
caught and re-filed. Ledger writes are file-locked for safe concurrent runs.
@@ -133,7 +133,7 @@ The underlying CLI (run via `terminal`, as `python3 scripts/pdd.py <cmd>`):
## Tests
-34 hermetic tests (no network, browser, or email; SMTP and IMAP are exercised through injected
+42 hermetic tests (no network, browser, or email; SMTP and IMAP are exercised through injected
fakes):
```bash
@@ -158,7 +158,7 @@ python3 tests/skills/test_unbroker_skill.py # dependency-
**v1.0.** The deterministic engine, the autonomous loop, the verified cluster-parent deletion lanes,
and full broker-registry coverage (the CA Data Broker Registry plus the DROP one-shot) are built and
-covered by 34 hermetic tests. The skill ships placeholder data only. Live agent-driven submission
+covered by 42 hermetic tests. The skill ships placeholder data only. Live agent-driven submission
against broker sites is the active field-testing frontier.
## Credits and license
diff --git a/optional-skills/security/unbroker/SKILL.md b/optional-skills/security/unbroker/SKILL.md
index 74361404a38..ea8d998edb4 100644
--- a/optional-skills/security/unbroker/SKILL.md
+++ b/optional-skills/security/unbroker/SKILL.md
@@ -123,7 +123,7 @@ breaks reading the dossier).
| `$PDD drop <subject> [--filed]` | **The one-shot legal lever**: one CA DROP request deletes from ALL registered brokers; `--filed` records it |
| `$PDD dnc <subject> [--filed]` | **The spam-call lever**: register the subject's US personal numbers on the FTC National Do Not Call Registry (sales calls stop within 31 days, never expires); `--filed` records it |
| `$PDD plan <subject> [--priority crucial]` | Per-broker tier + method + `search_vectors` + the exact fields to disclose |
-| `$PDD plan <subject> --batch` | **Reduce view**: overlays ledger state, groups brokers by next action (unscanned/found/indirect/blocked/in_progress/done), collapses ownership clusters, **orders `found` cluster-parents-first + emits a tailored `parent_playbook`**, prints `next_actions` |
+| `$PDD plan <subject> --batch` | **Reduce view**: overlays ledger state, groups brokers by next action (unscanned/unsearchable/found/indirect/blocked/in_progress/human/done/not_found; defunct brokers are excluded and listed under `defunct`), collapses ownership clusters, **orders `found` cluster-parents-first + emits a tailored `parent_playbook`**, prints `next_actions` |
| `$PDD fanout <subject> [--priority crucial] [--size 5]` | Batch brokers into parallel `delegate_task` subagents (auto for large runs; batches of 5 - 8+ time out) |
| `$PDD record <subject> <broker> <state> [--found true] [--evidence JSON] [--disclosed F --channel C] [--reason "..."]` | Update the ledger (validated state machine); **auto-stamps `next_recheck_at`** |
| `$PDD show <subject> <broker>` | Read back a case's recorded state + evidence + disclosure log (so the parent re-verifies a subagent's `found` without re-deriving the listing URL) |
@@ -287,13 +287,17 @@ is where lead buyers get it. The same engine, entered from the number:
but collect the full name + contact email at intake anyway: every opt-out form and legal request
needs them.
2. **The loop is unchanged.** `$PDD next <subject>` drives the same crawl / opt-out / re-check
- queue; the reverse-phone sites (18 of the 22 curated people-search records declare `by: phone`)
- are scanned with the phone vector, and the re-check schedule watches for the number re-listing
+ queue; the reverse-phone sites (14 of the live curated records declare `by: phone`; five curated
+ brokers are defunct - dead domains, excluded from planning) are scanned with the phone vector, and the re-check schedule watches for the number re-listing
(per the subject's `rescan_interval_days`).
3. **DNC one-shot.** For a US personal number, `next` also surfaces `dnc_register` once: the FTC
National Do Not Call Registry (free, never expires, sales calls stop within 31 days; up to 3
numbers per pass, one confirmation email per number - open each link within 72 hours). `$PDD
- dnc <subject>` prints the steps; `$PDD dnc <subject> --filed` records it. DNC stops lawful
+ dnc <subject>` prints the steps; `$PDD dnc <subject> --filed` records it and
+ `$PDD dnc <subject> --declined` opts the subject out without recording a filing that never
+ happened. Surfaced only for phone-led runs (`--focus-phone`) and only for NANP numbers,
+ always with `confirm_first` - intake consent covers broker removal, not a new registry
+ disclosure. DNC stops lawful
telemarketers, not scammers - broker removal is what cuts the lead lists, so do both.
## Pitfalls
diff --git a/optional-skills/security/unbroker/references/brokers/clustrmaps.json b/optional-skills/security/unbroker/references/brokers/clustrmaps.json
index 9999b7ecfdd..40cd20de208 100644
--- a/optional-skills/security/unbroker/references/brokers/clustrmaps.json
+++ b/optional-skills/security/unbroker/references/brokers/clustrmaps.json
@@ -18,9 +18,6 @@
"name",
"phone",
"address"
- ],
- "url_format_quirks": [
- "DEFUNCT: the domain's public DNS returns 127.0.0.1 - a deliberate kill-switch, not a tool block (confirmed via 1.1.1.1, verified live 2026-10-26). Scan/opt-out moot; record not_found citing this. NOTE: an earlier quirk advised taking this domain to the browser rung past the SSRF guard - superseded; the domain is dead, not guarded."
]
},
"optout": {
@@ -40,17 +37,20 @@
"contact_email",
"profile_url"
],
- "notes": "Address/resident aggregator. Opt-out at /bl/opt-out: submit the profile URL + email, confirm the link. DEFUNCT: the domain's public DNS returns 127.0.0.1 - a deliberate kill-switch, not a tool block (confirmed via 1.1.1.1, verified live 2026-10-26). Scan/opt-out moot; record not_found citing this. NOTE: an earlier quirk advised taking this domain to the browser rung past the SSRF guard - superseded; the domain is dead, not guarded.",
+ "notes": "Address/resident aggregator. Opt-out at /bl/opt-out: submit the profile URL + email, confirm the link. DEFUNCT since 2026-10-26: deliberate kill-switch: public DNS answers 127.0.0.1 (checked via 1.1.1.1). Excluded from all planning/scanning/re-checks; close any open case as not_found citing this record.",
"quirks": [
"Opt-out URL is the documented public endpoint; datacenter IPs get 403 (anti-bot), so confirm the live flow via the operator's residential browser before the first submission, then set last_verified.",
"Needs the confirmed profile_url (the address/person page).",
- "Email verification required.",
- "DEFUNCT: the domain's public DNS returns 127.0.0.1 - a deliberate kill-switch, not a tool block (confirmed via 1.1.1.1, verified live 2026-10-26). Scan/opt-out moot; record not_found citing this. NOTE: an earlier quirk advised taking this domain to the browser rung past the SSRF guard - superseded; the domain is dead, not guarded."
+ "Email verification required."
],
"est_processing_days": 3,
"reappearance_risk": "medium"
},
"last_verified": "2026-10-26",
"source": "curated",
- "confidence": "documented"
+ "confidence": "documented",
+ "defunct": {
+ "since": "2026-10-26",
+ "evidence": "deliberate kill-switch: public DNS answers 127.0.0.1 (checked via 1.1.1.1)"
+ }
}
diff --git a/optional-skills/security/unbroker/references/brokers/cyberbackgroundchecks.json b/optional-skills/security/unbroker/references/brokers/cyberbackgroundchecks.json
index 2f2097c2d85..03459e4083e 100644
--- a/optional-skills/security/unbroker/references/brokers/cyberbackgroundchecks.json
+++ b/optional-skills/security/unbroker/references/brokers/cyberbackgroundchecks.json
@@ -46,10 +46,10 @@
],
"notes": "Free people-search. Opt-out at /removal: find the record, submit email, confirm link.",
"quirks": [
+ "ACCESS (verified live 2026-10-26): /removal sits behind a Cloudflare interstitial ('Just a moment...') that did NOT auto-clear for the automation browser (stuck >1 min), while their static phone pages fetch fine via web_extract. Present the removal as a manual step for the operator's everyday browser; the owner card also carries the in-flow 'This is me...Remove My Record' control.",
"Opt-out URL is the documented public endpoint; datacenter IPs get 403 (anti-bot), so confirm the live flow via the operator's residential browser before the first submission, then set last_verified.",
"Needs the confirmed profile_url.",
- "Email verification required.",
- "ACCESS (verified live 2026-10-26): /removal sits behind a Cloudflare interstitial ('Just a moment...') that did NOT auto-clear for the automation browser (stuck >1 min), while their static phone pages fetch fine via web_extract. Present the removal as a manual step for the operator's everyday browser; the owner card also carries the in-flow 'This is me...Remove My Record' control."
+ "Email verification required."
],
"est_processing_days": 3,
"reappearance_risk": "medium"
diff --git a/optional-skills/security/unbroker/references/brokers/intelius.json b/optional-skills/security/unbroker/references/brokers/intelius.json
index a9088be0014..071cee9ef15 100644
--- a/optional-skills/security/unbroker/references/brokers/intelius.json
+++ b/optional-skills/security/unbroker/references/brokers/intelius.json
@@ -3,7 +3,9 @@
"name": "Intelius",
"category": "people_search",
"priority": "crucial",
- "jurisdictions": ["US"],
+ "jurisdictions": [
+ "US"
+ ],
"parent": "peopleconnect",
"owns": [
"truthfinder",
@@ -22,7 +24,11 @@
"url": "https://www.intelius.com/",
"fetch": "web_extract",
"match_signal": "result",
- "by": ["name", "phone", "address"],
+ "by": [
+ "name",
+ "phone",
+ "address"
+ ],
"url_patterns": {
"name": "https://www.intelius.com/people-search/{First}-{Last}/",
"name_state": "https://www.intelius.com/people-search/{first}-{last}/{state-name}/",
@@ -52,7 +58,11 @@
"payment": false,
"dob": true
},
- "inputs": ["contact_email", "full_name", "date_of_birth"],
+ "inputs": [
+ "contact_email",
+ "full_name",
+ "date_of_birth"
+ ],
"deletion": {
"via": "in_flow",
"prefer": false,
diff --git a/optional-skills/security/unbroker/references/brokers/nuwber.json b/optional-skills/security/unbroker/references/brokers/nuwber.json
index e80c2a57c25..6dac1408997 100644
--- a/optional-skills/security/unbroker/references/brokers/nuwber.json
+++ b/optional-skills/security/unbroker/references/brokers/nuwber.json
@@ -18,9 +18,6 @@
"name",
"phone",
"address"
- ],
- "url_format_quirks": [
- "DEFUNCT: the domain no longer resolves (NXDOMAIN; NS records remain at Cloudflare but no A record - confirmed via 1.1.1.1, verified live 2026-10-26). Scan/opt-out moot; record not_found citing this. NOTE: an earlier quirk blamed the Hermes web_extract SSRF guard for unreachable scans - that was this same DNS state misread; the guard was correct to refuse."
]
},
"optout": {
@@ -40,17 +37,20 @@
"contact_email",
"profile_url"
],
- "notes": "People-search. Opt-out: submit the profile URL + email at /removal/link, confirm via the emailed link. DEFUNCT: the domain no longer resolves (NXDOMAIN; NS records remain at Cloudflare but no A record - confirmed via 1.1.1.1, verified live 2026-10-26). Scan/opt-out moot; record not_found citing this. NOTE: an earlier quirk blamed the Hermes web_extract SSRF guard for unreachable scans - that was this same DNS state misread; the guard was correct to refuse.",
+ "notes": "People-search. Opt-out: submit the profile URL + email at /removal/link, confirm via the emailed link. DEFUNCT since 2026-10-26: NXDOMAIN; NS remain parked at Cloudflare with no A record (checked via 1.1.1.1). Excluded from all planning/scanning/re-checks; close any open case as not_found citing this record.",
"quirks": [
"Opt-out URL is the documented public endpoint; datacenter IPs get 403 (anti-bot), so confirm the live flow via the operator's residential browser before the first submission, then set last_verified.",
"Needs the confirmed profile_url (paste the listing URL you recorded).",
- "Email verification required.",
- "DEFUNCT: the domain no longer resolves (NXDOMAIN; NS records remain at Cloudflare but no A record - confirmed via 1.1.1.1, verified live 2026-10-26). Scan/opt-out moot; record not_found citing this. NOTE: an earlier quirk blamed the Hermes web_extract SSRF guard for unreachable scans - that was this same DNS state misread; the guard was correct to refuse."
+ "Email verification required."
],
"est_processing_days": 3,
"reappearance_risk": "medium"
},
"last_verified": "2026-10-26",
"source": "curated",
- "confidence": "documented"
+ "confidence": "documented",
+ "defunct": {
+ "since": "2026-10-26",
+ "evidence": "NXDOMAIN; NS remain parked at Cloudflare with no A record (checked via 1.1.1.1)"
+ }
}
diff --git a/optional-skills/security/unbroker/references/brokers/peekyou.json b/optional-skills/security/unbroker/references/brokers/peekyou.json
index 2079bcff2bc..38bcb3b9b69 100644
--- a/optional-skills/security/unbroker/references/brokers/peekyou.json
+++ b/optional-skills/security/unbroker/references/brokers/peekyou.json
@@ -3,7 +3,9 @@
"name": "PeekYou",
"category": "people_search",
"priority": "high",
- "jurisdictions": ["US"],
+ "jurisdictions": [
+ "US"
+ ],
"parent": "peekyou",
"owns": [],
"search": {
@@ -12,9 +14,10 @@
"fetch": "browser",
"match_signal": "result",
"antibot": "cloudflare",
- "by": ["name", "phone", "address"],
- "url_format_quirks": [
- "DEFUNCT: domain now controlled by Atlas Data Privacy Corp (Atlas v. PeekYou LLC settlement under Daniel's Law; site serves the Atlas notice - verified live 2026-10-26). Scan/opt-out moot; record not_found citing this."
+ "by": [
+ "name",
+ "phone",
+ "address"
]
},
"optout": {
@@ -30,18 +33,25 @@
"phone_callback": false,
"payment": false
},
- "inputs": ["full_name", "contact_email", "profile_url"],
- "notes": "Aggregates social/web profiles. Opt-out: paste your PeekYou profile URL(s), pick a reason, provide email, confirm the link. DEFUNCT: domain now controlled by Atlas Data Privacy Corp (Atlas v. PeekYou LLC settlement under Daniel's Law; site serves the Atlas notice - verified live 2026-10-26). Scan/opt-out moot; record not_found citing this.",
+ "inputs": [
+ "full_name",
+ "contact_email",
+ "profile_url"
+ ],
+ "notes": "Aggregates social/web profiles. Opt-out: paste your PeekYou profile URL(s), pick a reason, provide email, confirm the link. DEFUNCT since 2026-10-26: public DNS dead after the Atlas Data Privacy Corp settlement (verified 2026-10-26). Excluded from all planning/scanning/re-checks; close any open case as not_found citing this record.",
"quirks": [
"Opt-out URL is the documented public endpoint; datacenter IPs get 403 (anti-bot), so confirm the live flow via the operator's residential browser before the first submission, then set last_verified.",
"Needs the confirmed PeekYou profile_url.",
- "Email verification required.",
- "DEFUNCT: domain now controlled by Atlas Data Privacy Corp (Atlas v. PeekYou LLC settlement under Daniel's Law; site serves the Atlas notice - verified live 2026-10-26). Scan/opt-out moot; record not_found citing this."
+ "Email verification required."
],
"est_processing_days": 7,
"reappearance_risk": "medium"
},
"last_verified": "2026-10-26",
"source": "curated",
- "confidence": "documented"
+ "confidence": "documented",
+ "defunct": {
+ "since": "2026-10-26",
+ "evidence": "public DNS dead after the Atlas Data Privacy Corp settlement (verified 2026-10-26)"
+ }
}
diff --git a/optional-skills/security/unbroker/references/brokers/peoplefinders.json b/optional-skills/security/unbroker/references/brokers/peoplefinders.json
index 07cd576f95e..6b7a574e721 100644
--- a/optional-skills/security/unbroker/references/brokers/peoplefinders.json
+++ b/optional-skills/security/unbroker/references/brokers/peoplefinders.json
@@ -46,10 +46,10 @@
],
"notes": "Standalone people-search (Confi-Chek family). Opt-out: find the listing, submit with a contact email, confirm via the emailed link.",
"quirks": [
+ "RECORD SUPPRESSION FORM (verified live 2026-10-26): at /opt-out it hard-requires street + city + state alongside first/last, email, phone, DOB (month is a numeric select: 10, not Oct), and a consent checkbox; a Cloudflare Turnstile is present and auto-clears on a residential automation browser. Their public people-search may hold NO record for the subject - check it first; a record-less subject cannot honestly complete this form (treat as indirect exposure and lean on the SearchPeopleFree sister flow).",
"Opt-out URL is the documented public endpoint; datacenter IPs get 403 (anti-bot), so confirm the live flow via the operator's residential browser before the first submission, then set last_verified.",
"Needs the confirmed profile_url from evidence.",
- "Email verification: poll-verification picks up the link; open it in the agent browser.",
- "RECORD SUPPRESSION FORM (verified live 2026-10-26): at /opt-out it hard-requires street + city + state alongside first/last, email, phone, DOB (month is a numeric select: 10, not Oct), and a consent checkbox; a Cloudflare Turnstile is present and auto-clears on a residential automation browser. Their public people-search may hold NO record for the subject - check it first; a record-less subject cannot honestly complete this form (treat as indirect exposure and lean on the SearchPeopleFree sister flow)."
+ "Email verification: poll-verification picks up the link; open it in the agent browser."
],
"est_processing_days": 7,
"reappearance_risk": "medium"
diff --git a/optional-skills/security/unbroker/references/brokers/radaris.json b/optional-skills/security/unbroker/references/brokers/radaris.json
index d1abda49439..b3d99db6530 100644
--- a/optional-skills/security/unbroker/references/brokers/radaris.json
+++ b/optional-skills/security/unbroker/references/brokers/radaris.json
@@ -3,21 +3,26 @@
"name": "Radaris",
"category": "people_search",
"priority": "crucial",
- "jurisdictions": ["US"],
+ "jurisdictions": [
+ "US"
+ ],
"search": {
"method": "url_pattern",
"url": "https://radaris.com/",
"fetch": "web_extract",
"match_signal": "View Profile",
- "by": ["name", "phone", "address"],
+ "by": [
+ "name",
+ "phone",
+ "address"
+ ],
"url_patterns": {
"name": "https://radaris.com/p/{First}/{Last}/"
},
"url_format_quirks": [
"Name profile page: /p/{First}/{Last}/ with First/Last Capitalized and a TRAILING slash, e.g. /p/Jane/Public/ . Readable via web_extract (no hard bot gate as of 2026-06-30).",
"The page aggregates: a 'phone numbers & home addresses' table (the DIRECT hit for the subject), a relatives/namesakes carousel ('Review the potential relatives'), and resume/CV records. The subject's removable row is in the address table; the carousel entries are OTHER people - disambiguate by address/age before acting.",
- "Page is noisy with testimonials/reviews boilerplate; the signal blocks are 'phone numbers & home addresses N' and 'resumes & CV records N'.",
- "DEFUNCT: domain transferred by court order to Atlas Data Privacy Corp (Atlas Data Privacy v. Radaris.com, NJ Superior Court final judgment 2026-08-27, Daniel's Law; site now serves the court notice - verified live 2026-10-26). Scan/opt-out moot; record not_found citing this."
+ "Page is noisy with testimonials/reviews boilerplate; the signal blocks are 'phone numbers & home addresses N' and 'resumes & CV records N'."
]
},
"optout": {
@@ -33,19 +38,25 @@
"phone_callback": false,
"payment": false
},
- "inputs": ["profile_url", "contact_email"],
- "notes": "Multi-step control-privacy wizard: step 1 NEXT -> step 2 'identify your personal page' (paste the NUMBERED profile URL into the 'Or Enter URL of your page' field; typing reveals a NEXT submit button) -> then user_email + Google reCAPTCHA -> emailed verification link. If there is no View Profile button for the subject, email [email protected] and reply to the auto-response until removed. DEFUNCT: domain transferred by court order to Atlas Data Privacy Corp (Atlas Data Privacy v. Radaris.com, NJ Superior Court final judgment 2026-08-27, Daniel's Law; site now serves the court notice - verified live 2026-10-26). Scan/opt-out moot; record not_found citing this.",
+ "inputs": [
+ "profile_url",
+ "contact_email"
+ ],
+ "notes": "Multi-step control-privacy wizard: step 1 NEXT -> step 2 'identify your personal page' (paste the NUMBERED profile URL into the 'Or Enter URL of your page' field; typing reveals a NEXT submit button) -> then user_email + Google reCAPTCHA -> emailed verification link. If there is no View Profile button for the subject, email [email protected] and reply to the auto-response until removed. DEFUNCT since 2026-08-27: domain seized via Atlas Data Privacy Corp (NJ Daniel's Law, final judgment 2026-08-27). Excluded from all planning/scanning/re-checks; close any open case as not_found citing this record.",
"email": "[email protected]",
"quirks": [
"CAPTCHA: the form carries a Google reCAPTCHA (hidden field g-recaptcha-response) plus anti-bot fingerprint tokens (jfp, token). Tier is T2 without a captcha-clearing browser backend (T1 with Browserbase). (Record previously mis-declared captcha:false.)",
"The /control-privacy form REQUIRES the per-person NUMBERED profile URL. Pasting the aggregate /p/{First}/{Last}/ URL is rejected with the validation error: 'The URL must include unique number at the end'. The real removable URL looks like https://{region}.radaris.com/person/~First-Last/1234567890 (see the field placeholder).",
"The subject's own record may appear ONLY as a static row in the 'phone numbers & home addresses' table with NO 'View Profile' link, so no numbered profile URL is exposed for them (the /p/{First}/{Last}/ page deep-links only to relatives/namesakes via JS onclick, not static hrefs). When that happens the /control-privacy form cannot be used -- do NOT fabricate or submit a relative's or namesake's profile URL. Fall back to email: write [email protected] with the subject's own listed details and request removal, replying to the auto-response until confirmed.",
- "Pressing Enter in the URL field reloads the wizard to step 1 (does not submit); type into the field and click the revealed NEXT button instead.",
- "DEFUNCT: domain transferred by court order to Atlas Data Privacy Corp (Atlas Data Privacy v. Radaris.com, NJ Superior Court final judgment 2026-08-27, Daniel's Law; site now serves the court notice - verified live 2026-10-26). Scan/opt-out moot; record not_found citing this."
+ "Pressing Enter in the URL field reloads the wizard to step 1 (does not submit); type into the field and click the revealed NEXT button instead."
],
"est_processing_days": 14,
"reappearance_risk": "high"
},
"last_verified": "2026-10-26",
- "source": "BADBOOL"
+ "source": "BADBOOL",
+ "defunct": {
+ "since": "2026-08-27",
+ "evidence": "domain seized via Atlas Data Privacy Corp (NJ Daniel's Law, final judgment 2026-08-27)"
+ }
}
diff --git a/optional-skills/security/unbroker/references/brokers/rehold.json b/optional-skills/security/unbroker/references/brokers/rehold.json
index 830196df628..e23c8c2a44a 100644
--- a/optional-skills/security/unbroker/references/brokers/rehold.json
+++ b/optional-skills/security/unbroker/references/brokers/rehold.json
@@ -3,7 +3,9 @@
"name": "Rehold",
"category": "property_records",
"priority": "long_tail",
- "jurisdictions": ["US"],
+ "jurisdictions": [
+ "US"
+ ],
"search": {
"method": "url_pattern",
"url": "https://rehold.com/",
@@ -11,9 +13,8 @@
"match_signal": "result",
"match_signal_notes": "PROPERTY-RECORD, NOT PII. An address match here shows only PUBLIC PROPERTY RECORDS (build year, beds/baths, last sale price, incident history). Resident/owner NAMES sit behind 'View full report', which leads to a paywall/signup, so no personal PII is publicly exposed. Public property records are NOT removable. Record `found` ONLY if a resident NAME matching the subject is publicly displayed on the free page; an address-only match is `not_found` (nothing to opt out of).",
"access": "paywall",
- "by": ["address"],
- "url_format_quirks": [
- "DEFUNCT: rehold.com named in the same Atlas v. Radaris final judgment (2026-08-27); domain serves the court notice (verified live 2026-10-26). Scan/opt-out moot; record not_found citing this."
+ "by": [
+ "address"
]
},
"optout": {
@@ -29,18 +30,23 @@
"phone_callback": false,
"payment": false
},
- "inputs": ["profile_url"],
- "notes": "Address-anchored property/reverse-address site. Only pursue an opt-out if the scan found a publicly displayed resident NAME for the subject (see match_signal_notes); a bare public property record is not personal PII and is not removable. If the subject's personal profile IS shown, submit the profile URL to the opt-out endpoint and confirm the live flow in a residential browser before the first submission, then set last_verified. DEFUNCT: rehold.com named in the same Atlas v. Radaris final judgment (2026-08-27); domain serves the court notice (verified live 2026-10-26). Scan/opt-out moot; record not_found citing this.",
+ "inputs": [
+ "profile_url"
+ ],
+ "notes": "Address-anchored property/reverse-address site. Only pursue an opt-out if the scan found a publicly displayed resident NAME for the subject (see match_signal_notes); a bare public property record is not personal PII and is not removable. If the subject's personal profile IS shown, submit the profile URL to the opt-out endpoint and confirm the live flow in a residential browser before the first submission, then set last_verified. DEFUNCT since 2026-08-27: domain dead per the same NJ Daniel's Law final judgment (Atlas Data Privacy Corp, 2026-08-27). Excluded from all planning/scanning/re-checks; close any open case as not_found citing this record.",
"quirks": [
"Distinguish 'address exists in a public property DB' (non-removable) from 'the subject's personal profile is displayed' (removable). Only the latter is an actionable exposure.",
"'View full report' is a paywall/signup, not proof of a public listing.",
- "Opt-out endpoint UNVERIFIED: confirm the live flow before the first submission.",
- "DEFUNCT: rehold.com named in the same Atlas v. Radaris final judgment (2026-08-27); domain serves the court notice (verified live 2026-10-26). Scan/opt-out moot; record not_found citing this."
+ "Opt-out endpoint UNVERIFIED: confirm the live flow before the first submission."
],
"est_processing_days": 3,
"reappearance_risk": "low"
},
"last_verified": "2026-10-26",
"source": "curated",
- "confidence": "documented"
+ "confidence": "documented",
+ "defunct": {
+ "since": "2026-08-27",
+ "evidence": "domain dead per the same NJ Daniel's Law final judgment (Atlas Data Privacy Corp, 2026-08-27)"
+ }
}
diff --git a/optional-skills/security/unbroker/references/brokers/searchpeoplefree.json b/optional-skills/security/unbroker/references/brokers/searchpeoplefree.json
index 076b37b2c83..810dad3b021 100644
--- a/optional-skills/security/unbroker/references/brokers/searchpeoplefree.json
+++ b/optional-skills/security/unbroker/references/brokers/searchpeoplefree.json
@@ -46,10 +46,10 @@
],
"notes": "Free people-search. Opt-out: find the listing, submit with an email, confirm the link.",
"quirks": [
+ "ENTRY GATE (verified live 2026-10-26): /opt-out takes first/last/email + a terms checkbox + Cloudflare Turnstile, then 'Begin removal process' emails a verify button (24h TTL) leading to the removal form; ~3 days processing. The Turnstile AUTO-CLEARED as normal operation on a residential automation browser (token observed) - stays automated, unlike reCAPTCHA checkboxes.",
"Opt-out URL is the documented public endpoint; datacenter IPs get 403 (anti-bot), so confirm the live flow via the operator's residential browser before the first submission, then set last_verified.",
"Needs the confirmed profile_url.",
- "Email verification required.",
- "ENTRY GATE (verified live 2026-10-26): /opt-out takes first/last/email + a terms checkbox + Cloudflare Turnstile, then 'Begin removal process' emails a verify button (24h TTL) leading to the removal form; ~3 days processing. The Turnstile AUTO-CLEARED as normal operation on a residential automation browser (token observed) - stays automated, unlike reCAPTCHA checkboxes."
+ "Email verification required."
],
"est_processing_days": 3,
"reappearance_risk": "medium"
diff --git a/optional-skills/security/unbroker/references/brokers/spokeo.json b/optional-skills/security/unbroker/references/brokers/spokeo.json
index debc88b9319..7d721e1aa80 100644
--- a/optional-skills/security/unbroker/references/brokers/spokeo.json
+++ b/optional-skills/security/unbroker/references/brokers/spokeo.json
@@ -3,24 +3,15 @@
"name": "Spokeo",
"category": "people_search",
"priority": "crucial",
- "jurisdictions": [
- "US"
- ],
+ "jurisdictions": ["US"],
"parent": "spokeo",
- "owns": [
- "freepeopledirectory"
- ],
+ "owns": ["freepeopledirectory"],
"search": {
"method": "url_pattern",
"url": "https://www.spokeo.com/search",
"fetch": "browser",
"match_signal": "profile",
- "by": [
- "name",
- "phone",
- "email",
- "address"
- ],
+ "by": ["name", "phone", "email", "address"],
"url_patterns": {
"phone": "https://www.spokeo.com/{areacode}-{prefix}-{line}"
},
@@ -42,17 +33,11 @@
"phone_callback": false,
"payment": false
},
- "inputs": [
- "profile_url",
- "contact_email"
- ],
+ "inputs": ["profile_url", "contact_email"],
"deletion": {
"via": "email_followup",
"email": "[email protected]",
- "kinds": [
- "ccpa",
- "generic"
- ],
+ "kinds": ["ccpa", "generic"],
"notes": "[email protected] is the documented direct privacy contact (verified live on /optout 2026-07-01). Use for full CCPA deletion beyond listing opt-out, for listings the form rejects, and when more listings keep surfacing."
},
"playbook": [
@@ -64,11 +49,12 @@
],
"notes": "Form + [email protected] verified live 2026-07-01. Their page: opting out does not remove data from original sources and listings may reappear as new public records arrive -- keep the reappearance re-scan scheduled.",
"quirks": [
+ "OPT-OUT FORM NOW CAPTCHA-GATED (verified live 2026-10-26; previously captcha-free): a reCAPTCHA v2 checkbox must be checked for the form to submit ('Please complete the captcha to submit your opt out request'). Clears on a real residential browser; synthetic CDP clicks on a debug-profile Chrome did NOT toggle it - if it will not clear, fall back to the [email protected] deletion email naming the listing URL(s).",
"Profile URL formats the form accepts: listing URL like spokeo.com/{First}-{Last}/{City}/{ST}/p{id} or a purchase URL spokeo.com/purchase?q=... (examples shown on /optout).",
"Multiple listings per person are NORMAL (one per name x location x record cluster); each unique URL must be opted out individually -- feed every found listing URL through the form.",
"Processing is 24-48h ('depending on the nature of your request and the amount of data').",
"Paid accounts may retain data even when hidden from free search - verify actual removal, don't mark confirmed_removed off the free-search view alone.",
- "OPT-OUT FORM NOW CAPTCHA-GATED (verified live 2026-10-26; previously captcha-free): a reCAPTCHA v2 checkbox must be checked for the form to submit ('Please complete the captcha to submit your opt out request'). Clears on a real residential browser; synthetic CDP clicks on a debug-profile Chrome did NOT toggle it - if it will not clear, fall back to the [email protected] deletion email naming the listing URL(s)."
+ "CAPTCHA REALITY (2026-10-26): the form's reCAPTCHA v2 checkbox refused synthetic automation clicks - no token, no challenge, no error - so this is T2 without a captcha-clearing browser backend. One clean attempt, then queue the manual step; [email protected] (deletion email naming the listing URLs) is the no-captcha lane."
],
"est_processing_days": 2,
"reappearance_risk": "medium"
diff --git a/optional-skills/security/unbroker/references/brokers/usphonebook.json b/optional-skills/security/unbroker/references/brokers/usphonebook.json
index 0086b3b1720..4cc70d87ca7 100644
--- a/optional-skills/security/unbroker/references/brokers/usphonebook.json
+++ b/optional-skills/security/unbroker/references/brokers/usphonebook.json
@@ -46,10 +46,10 @@
],
"notes": "Reverse-phone + people-search. Opt-out: paste the listing URL, provide an email, confirm via the emailed link.",
"quirks": [
+ "ENTRY GATE (verified live 2026-10-26): /opt-out lands on /removal asking first/last/email + a reCAPTCHA ENTERPRISE checkbox; on submit it emails a verify link (24h TTL) to the record-selection form, ~3 days processing. The checkbox refused synthetic automation clicks (see methods.md CAPTCHA policy) - T2 unless the operator's everyday browser clears it.",
"Opt-out URL is the documented public endpoint; datacenter IPs get 403 (anti-bot), so confirm the live flow via the operator's residential browser before the first submission, then set last_verified.",
"Needs the confirmed profile_url.",
- "Email verification required.",
- "ENTRY GATE (verified live 2026-10-26): /opt-out lands on /removal asking first/last/email + a reCAPTCHA ENTERPRISE checkbox; on submit it emails a verify link (24h TTL) to the record-selection form, ~3 days processing. The checkbox refused synthetic automation clicks (see methods.md CAPTCHA policy) - T2 unless the operator's everyday browser clears it."
+ "Email verification required."
],
"est_processing_days": 3,
"reappearance_risk": "medium"
diff --git a/optional-skills/security/unbroker/references/methods.md b/optional-skills/security/unbroker/references/methods.md
index 288133832b3..dbaa066bbd4 100644
--- a/optional-skills/security/unbroker/references/methods.md
+++ b/optional-skills/security/unbroker/references/methods.md
@@ -281,8 +281,8 @@ T2 and become human tasks. **Never use a third-party CAPTCHA-defeating service.*
A phone-led run ("my number keeps getting spam calls") is the same loop entered from the number:
`intake --phone ... --focus-phone ...` (the focus number is what phone-asking opt-out forms
disclose), then `next` as usual. `search_vectors` already emits one `by: phone` vector per dossier
-phone on every broker that declares phone search (18 of the 22 curated records). Two
-phone-specific notes:
+phone on every broker that declares phone search (14 of the live records; five curated
+brokers are defunct - dead domains excluded from planning). Three phone-specific notes:
- **Reverse-phone pages SEO-echo the number too.** The title/H1 templating trap applies: a real
result is a card naming the subscriber (name / age / city), not the query echo. Corroborate
diff --git a/optional-skills/security/unbroker/scripts/autopilot.py b/optional-skills/security/unbroker/scripts/autopilot.py
index 363785a90f0..dfefa6b5353 100644
--- a/optional-skills/security/unbroker/scripts/autopilot.py
+++ b/optional-skills/security/unbroker/scripts/autopilot.py
@@ -24,6 +24,7 @@ import os
from pathlib import Path
import brokers as brokers_mod
+import dossier as dossier_mod
import emailer
import ledger as ledger_mod
import paths
@@ -113,6 +114,34 @@ def _email_lane(row: dict) -> tuple[str | None, str]:
return None, ""
+def _email_identity_ready(dossier: dict) -> bool:
+ """One predicate shared by every email lane: the subject has a full name AND a contact
+ email, so a request can self-identify and carry a confirm-to address."""
+ return bool(((dossier.get("identity") or {}).get("full_name") or "").strip()
+ and dossier_mod.contact_email(dossier))
+
+
+def _defunct_closeout_digest(ledger: dict, defunct_ids: set, by_id: dict, subject_id: str) -> list[dict]:
+ """One-time digest entries closing the OPEN cases of defunct brokers as not_found.
+
+ The plan and batch views exclude dead domains (never scanned, opted-out, or re-checked),
+ so this is the only place they surface -- and not_found from an in-flight state is legal
+ only with the defunct evidence cited (see ledger.TRANSITIONS).
+ """
+ out = []
+ for bid, case in sorted(ledger.items()):
+ if bid not in defunct_ids or case.get("state") not in {
+ "found", "action_selected", "submitted", "verification_pending",
+ "awaiting_processing", "human_task_queued"}:
+ continue
+ out.append(_digest(
+ {"broker_id": bid, "broker_name": (by_id.get(bid) or {}).get("name") or bid},
+ "broker is defunct (domain dead/seized) - close the case",
+ [f"python3 scripts/pdd.py record {subject_id} {bid} not_found "
+ f"--reason 'broker defunct: see its broker record'"]))
+ return out
+
+
def _optout_action(row: dict, playbook: dict[str, dict], subject_id: str, dossier: dict,
email_mode: str, smtp_ok: bool, confirm_first: bool) -> tuple[dict | None, dict | None]:
"""Map one actionable `found` row to (agent_action, human_digest_entry).
@@ -134,6 +163,16 @@ def _optout_action(row: dict, playbook: dict[str, dict], subject_id: str, dossie
can_email = (email_mode in ("programmatic", "alias") and smtp_ok) or email_mode == "browser"
if email_addr and can_email:
kind = request_kind(dossier, deletion.get("kinds"))
+ # Phase 2 identity gate: a legal email must self-identify. Intake only WARNS when
+ # the name/contact email is missing (scans don't need them); enforce it HERE so a
+ # nameless subject routes to the digest instead of auto-sending a request signed
+ # "None" (or carrying an unfilled {full_name} placeholder).
+ if not _email_identity_ready(dossier):
+ return None, _digest(row, "email lane ready, but the subject's full name / contact email is missing",
+ ["Collect them (intake --full-name / --contact-email, or a dossier edit), "
+ "then re-run `next` -- the email action will surface",
+ f"Then: python3 scripts/pdd.py send-email {subject_id} {bid} --kind {kind} "
+ f"--to {email_addr} --listing <confirmed-url>"])
via = "browser" if email_mode == "browser" else "smtp"
then = ("send-email records it + returns a recipient-locked payload; compose and send it in "
"the operator's webmail via browser_exec, then `verify-link` on the reply and open the link"
@@ -197,10 +236,56 @@ def _optout_action(row: dict, playbook: dict[str, dict], subject_id: str, dossie
"deleting undoes it and does not stop re-listing")
if req.get("captcha"):
action["note"] = ("CAPTCHA-gated: attempt with the configured browser backend once; if it "
- "does not clear, record blocked (do NOT retry-loop or bypass)")
+ "does not clear, record human_task_queued with the reason. Do NOT retry-loop "
+ "or bypass -- and do NOT record blocked either: a blocked case re-scans, "
+ "re-finds the listing and re-queues this opt-out forever, while the digest "
+ "hands it to the operator exactly once")
return action, None
+def _indirect_case(row: dict, dossier: dict, email_mode: str, smtp_ok: bool,
+ subject_id: str, confirm_first: bool) -> tuple[dict | None, dict | None]:
+ """Map one `indirect_exposure` row to (agent_action, human_digest_entry).
+
+ The subject's PII sits on a THIRD PARTY's record: drive the opt-out form with only the
+ subject's own identifiers, or send the targeted delete-my-PII email -- which must
+ self-identify, so a nameless/contact-less subject routes to the digest instead.
+ """
+ bid = row["broker_id"]
+ has_email = bool(row.get("optout_email") or (row.get("deletion") or {}).get("email"))
+ if not has_email and row.get("optout_url"):
+ # No email lane (e.g. ThatsThem is web-form-only): drive the opt-out FORM, submitting
+ # ONLY the subject's own identifiers to scrub from the third party's record.
+ return {
+ "type": "indirect_web_form",
+ "broker_id": bid, "confirm_first": confirm_first,
+ "optout_url": row.get("optout_url"),
+ "steps": [f"browser_exec: new_tab({row.get('optout_url')!r}) + wait_for_load()",
+ "submit ONLY the subject's own identifiers (the fields the form requires) to "
+ "remove them from the third party's record; disclose nothing extra",
+ "confirm the success state, screenshot into evidence/"],
+ "after": f"python3 scripts/pdd.py record {subject_id} {bid} submitted --channel web_form",
+ }, None
+ if (email_mode in ("programmatic", "alias") and smtp_ok) or email_mode == "browser":
+ # Same identity gate as the email lane: a delete-my-PII request must self-identify.
+ if not _email_identity_ready(dossier):
+ return None, _digest(row, "indirect-exposure request needs the subject's name + contact email first",
+ ["Collect them (intake --full-name / --contact-email), then re-run `next`"])
+ return {
+ "type": "indirect_email_send",
+ "broker_id": bid, "confirm_first": confirm_first,
+ "send_via": "browser" if email_mode == "browser" else "smtp",
+ "command": f"python3 scripts/pdd.py send-email {subject_id} {bid} --kind ccpa_indirect "
+ f"--listing <third-party-listing-url>",
+ }, None
+ return None, _digest(row, "indirect-exposure request (draft mode: a human must hit send)",
+ ["Send the rendered ccpa_indirect draft",
+ f"Then: python3 scripts/pdd.py record {subject_id} {bid} submitted "
+ f"--disclosed contact_email --channel email"],
+ prep=[f"python3 scripts/pdd.py render-email {subject_id} {bid} "
+ f"--kind ccpa_indirect --listing <url>"])
+
+
def _registry_one_shots(dossier: dict, registry_recs: list, residency: str,
subject_id: str, confirm_first: bool) -> list[dict]:
"""One-shot registrations beyond the per-broker casework, each surfaced once per subject
@@ -221,13 +306,20 @@ def _registry_one_shots(dossier: dict, registry_recs: list, residency: str,
"data brokers at once (superset of what commercial services cover).",
"after": f"python3 scripts/pdd.py drop {subject_id} --filed",
})
- phones = list((dossier.get("identity") or {}).get("phones") or [])
- if residency.startswith("US") and phones and not prefs.get("dnc_filed_at"):
+ # DNC: surfaced ONLY for phone-led runs (focus_phone set). A name-led subject's `next`
+ # must reach done_for_now instead of offering an unrelated registry signup; `dnc` stays
+ # available manually for any subject. confirm_first is ALWAYS true -- intake consent
+ # authorizes broker removal, and a new registry submission is a separate disclosure
+ # the operator confirms even in full autonomy. --declined clears it without recording
+ # a filing that never happened.
+ eligible = registry.dnc_eligible(dossier)
+ if (residency.startswith("US") and prefs.get("focus_phone") and eligible
+ and not prefs.get("dnc_filed_at") and not prefs.get("dnc_declined_at")):
actions.append({
"type": "dnc_register",
"one_shot": True,
"url": registry.DNC_URL,
- "confirm_first": confirm_first,
+ "confirm_first": True,
"command": f"python3 scripts/pdd.py dnc {subject_id}",
"why": "US personal number(s) not yet on the National Do Not Call Registry: lawful "
"telemarketers must stop within 31 days; registration never expires.",
@@ -237,6 +329,7 @@ def _registry_one_shots(dossier: dict, registry_recs: list, residency: str,
"configured browser, present it as a manual step in the end-of-run digest "
"instead of fighting it.",
"after": f"python3 scripts/pdd.py dnc {subject_id} --filed",
+ "declined": f"python3 scripts/pdd.py dnc {subject_id} --declined",
})
return actions
@@ -258,6 +351,7 @@ def next_actions(dossier: dict, brokers_list: list[dict], cfg: dict,
groups = batch["groups"]
playbook = {p["broker_id"]: p for p in batch.get("parent_playbook") or []}
by_id = {b.get("id"): b for b in brokers_list}
+ defunct_ids = {b.get("id") for b in brokers_list if b.get("defunct")}
actions: list[dict] = []
digest: list[dict] = []
@@ -302,8 +396,8 @@ def next_actions(dossier: dict, brokers_list: list[dict], cfg: dict,
# 2) in-flight email verifications: poll the inbox (or hand to the human in draft mode)
for st in ("submitted", "verification_pending"):
for bid, case in sorted(ledger.items()):
- if case.get("state") != st:
- continue
+ if case.get("state") != st or bid in defunct_ids:
+ continue # defunct: a dead domain never verifies anything
broker = by_id.get(bid) or {}
if not ((broker.get("optout") or {}).get("requires") or {}).get("email_verification"):
continue
@@ -334,6 +428,8 @@ def next_actions(dossier: dict, brokers_list: list[dict], cfg: dict,
for case in ledger_mod.due(subject_id, at=at, ledger=ledger):
bid = case.get("broker_id")
st = case.get("state")
+ if bid in defunct_ids:
+ continue # dead domain: nothing can reappear; the case rests where it is
if st in ("awaiting_processing", "confirmed_removed"):
actions.append({
"type": "verify_removal",
@@ -345,6 +441,9 @@ def next_actions(dossier: dict, brokers_list: list[dict], cfg: dict,
elif st in ("submitted", "verification_pending") and not mail["imap"]:
pass # already covered by the digest entry above
+ # 3b) defunct brokers: close their open cases honestly (see _defunct_closeout_digest).
+ digest.extend(_defunct_closeout_digest(ledger, defunct_ids, by_id, subject_id))
+
# 4) Phase 2 opt-outs: parents first (batch_plan already ordered them)
for row in groups.get("found") or []:
action, task = _optout_action(row, playbook, subject_id, dossier,
@@ -356,36 +455,11 @@ def next_actions(dossier: dict, brokers_list: list[dict], cfg: dict,
# 5) indirect exposure: targeted delete-my-PII requests
for row in groups.get("indirect_exposure") or []:
- bid = row["broker_id"]
- has_email = bool(row.get("optout_email") or (row.get("deletion") or {}).get("email"))
- if not has_email and row.get("optout_url"):
- # No email lane (e.g. ThatsThem is web-form-only): drive the opt-out FORM, submitting
- # ONLY the subject's own identifiers to scrub from the third party's record.
- actions.append({
- "type": "indirect_web_form",
- "broker_id": bid, "confirm_first": confirm_first,
- "optout_url": row.get("optout_url"),
- "steps": [f"browser_exec: new_tab({row.get('optout_url')!r}) + wait_for_load()",
- "submit ONLY the subject's own identifiers (the fields the form requires) to "
- "remove them from the third party's record; disclose nothing extra",
- "confirm the success state, screenshot into evidence/"],
- "after": f"python3 scripts/pdd.py record {subject_id} {bid} submitted --channel web_form",
- })
- elif (email_mode in ("programmatic", "alias") and mail["smtp"]) or email_mode == "browser":
- actions.append({
- "type": "indirect_email_send",
- "broker_id": bid, "confirm_first": confirm_first,
- "send_via": "browser" if email_mode == "browser" else "smtp",
- "command": f"python3 scripts/pdd.py send-email {subject_id} {bid} --kind ccpa_indirect "
- f"--listing <third-party-listing-url>",
- })
- else:
- digest.append(_digest(row, "indirect-exposure request (draft mode: a human must hit send)",
- ["Send the rendered ccpa_indirect draft",
- f"Then: python3 scripts/pdd.py record {subject_id} {bid} submitted "
- f"--disclosed contact_email --channel email"],
- prep=[f"python3 scripts/pdd.py render-email {subject_id} {bid} "
- f"--kind ccpa_indirect --listing <url>"]))
+ action, task = _indirect_case(row, dossier, email_mode, mail["smtp"], subject_id, confirm_first)
+ if action:
+ actions.append(action)
+ if task:
+ digest.append(task)
# 6) blocked sites: stealth pass if we have one, else the operator-browser path
blocked = groups.get("blocked") or []
diff --git a/optional-skills/security/unbroker/scripts/ledger.py b/optional-skills/security/unbroker/scripts/ledger.py
index b4f8122b88d..337bccc39ed 100644
--- a/optional-skills/security/unbroker/scripts/ledger.py
+++ b/optional-skills/security/unbroker/scripts/ledger.py
@@ -30,18 +30,24 @@ TRANSITIONS: dict[str, set[str]] = {
# request (-> submitted) or a human task. Re-scan can clear it (-> not_found) or upgrade it to a
# direct listing (-> found).
"indirect_exposure": {"submitted", "human_task_queued", "not_found", "found", "blocked"},
- "action_selected": {"submitted", "human_task_queued", "blocked"},
- "submitted": {"verification_pending", "awaiting_processing", "human_task_queued", "blocked"},
+ "action_selected": {"submitted", "human_task_queued", "blocked", "not_found"},
+ # not_found from the in-flight states exists for ONE reason: the broker died (domain
+ # seized by court order / NXDOMAIN). A dead site cannot hold the listing, so the honest
+ # close-out is not_found citing the defunct record -- never used for a LIVE broker's
+ # in-flight request, which waits out its processing window instead.
+ "submitted": {"verification_pending", "awaiting_processing", "human_task_queued", "blocked",
+ "not_found"},
# verification_pending -> awaiting_processing: the verify link was opened/acknowledged and the
# broker is now processing the removal (their stated window). confirmed_removed still requires a
# verifying re-scan, never the submission flow's own say-so.
- "verification_pending": {"awaiting_processing", "confirmed_removed", "human_task_queued", "blocked"},
- "awaiting_processing": {"confirmed_removed", "human_task_queued", "blocked"},
+ "verification_pending": {"awaiting_processing", "confirmed_removed", "human_task_queued",
+ "blocked", "not_found"},
+ "awaiting_processing": {"confirmed_removed", "human_task_queued", "blocked", "not_found"},
"confirmed_removed": {"reappeared", "confirmed_removed"},
"reappeared": {"found", "indirect_exposure"},
"human_task_queued": {
"found", "indirect_exposure", "action_selected", "submitted", "verification_pending",
- "awaiting_processing", "confirmed_removed", "blocked",
+ "awaiting_processing", "confirmed_removed", "blocked", "not_found",
},
# blocked: automated tools (web_extract/proxyless browser) couldn't read the site. A later pass
# -- a stealth/cloud browser OR guiding the operator's own (residential) browser -- can resolve it
diff --git a/optional-skills/security/unbroker/scripts/pdd.py b/optional-skills/security/unbroker/scripts/pdd.py
index 37d7a93a782..a0d2f17e476 100644
--- a/optional-skills/security/unbroker/scripts/pdd.py
+++ b/optional-skills/security/unbroker/scripts/pdd.py
@@ -306,13 +306,20 @@ def cmd_intake(args) -> None:
identity = data["identity"]
consent = data.get("consent", {})
residency = data.get("residency_jurisdiction", "US")
- prefs = data.get("preferences")
+ prefs = data.get("preferences") or {}
+ if getattr(args, "focus_phone", None):
+ # --focus-phone applies to --json intake too (it was silently ignored before):
+ # same normalized-digits dedupe as the CLI path, same preferences marker.
+ if registry.phone_digits(args.focus_phone) not in {
+ registry.phone_digits(p) for p in identity.get("phones") or []}:
+ identity.setdefault("phones", []).append(args.focus_phone)
+ prefs["focus_phone"] = args.focus_phone
else:
# Phone-led intake: a spam-call run starts from the number. At least ONE identifier
# is required (name, phone, or email). The full name is not required to SCAN
# (phone/email/address vectors run; name-only brokers group as `unsearchable`), but
# every opt-out form and legal request needs it -- warned below, not refused.
- if not (args.full_name or args.phone or args.email):
+ if not (args.full_name or args.phone or args.email or getattr(args, "focus_phone", None)):
sys.exit("error: intake needs at least one identifier: --full-name, --phone, or --email")
identity = {"full_name": args.full_name, "emails": args.email or [], "phones": args.phone or []}
if args.alias:
@@ -348,7 +355,10 @@ def cmd_intake(args) -> None:
if getattr(args, "focus_phone", None):
# Phone-led (spam-call) run: the number being scrubbed. Add it to the dossier
# phones so search vectors cover it even when it was not listed separately.
- if args.focus_phone not in identity["phones"]:
+ # Compare on normalized digits: "--phone 555-123-4567 --focus-phone 5551234567"
+ # is ONE number, and a duplicate would double the phone vectors and the DNC list.
+ if registry.phone_digits(args.focus_phone) not in {
+ registry.phone_digits(p) for p in identity["phones"]}:
identity["phones"].append(args.focus_phone)
prefs["focus_phone"] = args.focus_phone
d = dossier_mod.create(identity, consent, residency, prefs)
@@ -422,6 +432,15 @@ def cmd_registry(args) -> None:
_out(out)
+def _mark_one_shot(d: dict, subject: str, key: str, label: str) -> dict:
+ """Record a registry one-shot marker (drop_filed_at / dnc_filed_at / dnc_declined_at)."""
+ prefs = d.setdefault("preferences", {})
+ prefs[key] = dossier_mod.now()
+ dossier_mod.save(d)
+ return {"subject": subject, key: prefs[key],
+ "note": f"recorded; `next` will stop surfacing the {label} one-shot"}
+
+
def cmd_drop(args) -> None:
"""The one-shot legal lever: CA DROP deletes from ALL registered brokers at once."""
d = _require_subject(args.subject)
@@ -430,11 +449,7 @@ def cmd_drop(args) -> None:
res = (d.get("residency_jurisdiction") or "US").upper()
eligible = res.startswith("US-CA")
if args.filed:
- prefs = d.setdefault("preferences", {})
- prefs["drop_filed_at"] = dossier_mod.now()
- dossier_mod.save(d)
- _out({"subject": args.subject, "drop_filed_at": prefs["drop_filed_at"],
- "note": "recorded; `next` will stop surfacing the DROP one-shot"})
+ _out(_mark_one_shot(d, args.subject, "drop_filed_at", "DROP"))
return
_out({
"subject": args.subject,
@@ -467,33 +482,32 @@ def cmd_dnc(args) -> None:
d = _require_subject(args.subject)
dossier_mod.require_authorized(d)
res = (d.get("residency_jurisdiction") or "US").upper()
- phones = list((d.get("identity") or {}).get("phones") or [])
- eligible = res.startswith("US") and bool(phones)
+ numbers = registry.dnc_eligible(d)
+ eligible = res.startswith("US") and bool(numbers)
if args.filed:
- prefs = d.setdefault("preferences", {})
- prefs["dnc_filed_at"] = dossier_mod.now()
- dossier_mod.save(d)
- _out({"subject": args.subject, "dnc_filed_at": prefs["dnc_filed_at"],
- "note": "recorded; `next` will stop surfacing the DNC one-shot"})
+ _out(_mark_one_shot(d, args.subject, "dnc_filed_at", "DNC"))
+ return
+ if getattr(args, "declined", False):
+ _out(_mark_one_shot(d, args.subject, "dnc_declined_at", "DNC (declined)"))
return
_out({
"subject": args.subject,
"eligible": eligible,
"residency": res,
- "numbers": phones,
+ "numbers": numbers,
"dnc_url": registry.DNC_URL,
"steps": ([
f"Open {registry.DNC_URL} and enter the subject's personal number(s) -- up to "
- f"three per pass ({len(phones)} on file here) -- with the subject's contact email.",
+ f"three per pass ({len(numbers)} eligible here) -- with the subject's contact email.",
"The FTC sends a confirmation email PER NUMBER; open each link within 72 hours "
"or that number is not registered.",
"Sales calls stop within 31 days; registration never expires (personal numbers "
"only -- business/fax lines are not covered).",
f"After submitting, run `dnc {args.subject} --filed` so the loop stops "
- "re-surfacing it.",
+ "re-surfacing it (or `dnc {args.subject} --declined` if the subject opts out).",
] if eligible else [
- "The National Do Not Call Registry covers US personal numbers only; this subject "
- "has no US residency or no phone on file.",
+ "The National Do Not Call Registry covers US (NANP) personal numbers only; this "
+ "subject has no US residency or no eligible US number on file.",
"The broker-removal lane (`next`) is what cuts the lead lists scammers buy, in "
"any jurisdiction.",
]),
@@ -591,6 +605,11 @@ def _email_request(d: dict, b: dict, kind: str, listings, identifiers) -> tuple[
ident = d.get("identity", {})
if ident.get("full_name"):
fields.setdefault("full_name", ident["full_name"])
+ else:
+ # Never render the literal None. Generic drafts are operator-edited, so an explicit
+ # placeholder is the honest stand-in; the legal kinds are refused upstream when the
+ # subject is nameless (see _require_email_identity).
+ fields.setdefault("full_name", "[your full name]")
fields.setdefault("contact_email", dossier_mod.contact_email(d) or "")
if listings:
fields["listing_urls"] = listings
@@ -602,7 +621,10 @@ def _email_request(d: dict, b: dict, kind: str, listings, identifiers) -> tuple[
ids = list(identifiers or [])
if not ids:
ids = [contact for contact in [dossier_mod.contact_email(d)] if contact]
- ids.append(f'the name "{ident.get("full_name")}" where it appears as a relative/associated person')
+ # Only when a name exists -- a nameless subject must never emit the literal
+ # None into a legal email.
+ if ident.get("full_name"):
+ ids.append(f'the name "{ident["full_name"]}" where it appears as a relative/associated person')
fields = {
"full_name": fields.get("full_name"),
"contact_email": fields.get("contact_email"),
@@ -613,6 +635,26 @@ def _email_request(d: dict, b: dict, kind: str, listings, identifiers) -> tuple[
return fields, sorted(fields.keys())
+def _require_email_identity(d: dict, kind: str, sending: bool) -> None:
+ """Enforce the intake warning at the send boundary: a removal request must self-identify.
+
+ Intake only WARNS when the name/contact email is missing (scans run fine without them);
+ this is where it turns fatal. `generic` drafts are operator-edited ([your name]), so
+ rendering one without a name is allowed -- but SENDING any request without a name is
+ not, and the contact email (the confirm-to address) is required in every mode.
+ """
+ missing = []
+ if (sending or kind != "generic") and not ((d.get("identity") or {}).get("full_name") or "").strip():
+ missing.append("full name")
+ if not dossier_mod.contact_email(d):
+ missing.append("contact email")
+ if missing:
+ sys.exit("error: a removal request must self-identify, and the subject's "
+ + " and ".join(missing) + " is missing. Collect it first "
+ "(intake --full-name / --contact-email, or a dossier edit), then re-run; "
+ "scans do not need it, sending does.")
+
+
def cmd_render_email(args) -> None:
d = _require_subject(args.subject)
dossier_mod.require_authorized(d)
@@ -620,6 +662,7 @@ def cmd_render_email(args) -> None:
if not b:
sys.exit(f"error: unknown broker {args.broker!r}")
kind = getattr(args, "kind", "generic") or "generic"
+ _require_email_identity(d, kind, sending=False)
fields, disclosed = _email_request(d, b, kind, args.listing, getattr(args, "identifier", None))
if kind == "generic":
draft = email_modes.render_draft(b, fields)
@@ -658,6 +701,7 @@ def cmd_send_email(args) -> None:
"note": "already submitted; not re-sending (idempotent). Use --force to re-send."})
return
kind = getattr(args, "kind", "generic") or "generic"
+ _require_email_identity(d, kind, sending=True)
fields, disclosed = _email_request(d, b, kind, args.listing, getattr(args, "identifier", None))
body = legal.render_optout_email(b, fields) if kind == "generic" else legal.render_request(kind, b, fields)
@@ -881,6 +925,9 @@ def build_parser() -> argparse.ArgumentParser:
s.add_argument("subject")
s.add_argument("--filed", action="store_true",
help="mark the DNC registration as filed (stops `next` surfacing it)")
+ s.add_argument("--declined", action="store_true",
+ help="record that the subject declines DNC registration (stops `next` "
+ "surfacing it WITHOUT recording a filing that never happened)")
s.set_defaults(func=cmd_dnc)
s = sub.add_parser("plan", help="compute per-broker tier + next action for a subject")
diff --git a/optional-skills/security/unbroker/scripts/registry.py b/optional-skills/security/unbroker/scripts/registry.py
index 2a501f87b96..4f245757cc1 100644
--- a/optional-skills/security/unbroker/scripts/registry.py
+++ b/optional-skills/security/unbroker/scripts/registry.py
@@ -37,6 +37,33 @@ DEFAULT_URL = _CA_CSV.format(year=_CA_FLOOR_YEAR)
DROP_URL = "https://privacy.ca.gov/drop"
# National Do Not Call Registry (FTC): the US-wide personal-number list for spam-call runs.
DNC_URL = "https://www.donotcall.gov/register.html"
+
+
+def phone_digits(phone: str) -> str:
+ """Best-effort NANP normalization: keep digits, strip a leading country-code 1."""
+ d = re.sub(r"\D", "", str(phone or ""))
+ return d[1:] if len(d) == 11 and d.startswith("1") else d
+
+
+_NANP = re.compile(r"^[2-9]\d{2}[2-9]\d{6}$")
+
+
+def dnc_eligible(dossier: dict) -> list:
+ """The subject's numbers eligible for the National Do Not Call Registry: NANP only.
+
+ A US-residency subject can still carry a non-NANP number (or a Canadian NANP one -- the
+ residency check lives with the caller), and the FTC form rejects non-US numbers, so the
+ surfaced list is digits-normalized and deduped: "555-123-4567" and "5551234567" are ONE
+ number, never two registrations.
+ """
+ out: list = []
+ seen: set = set()
+ for p in (dossier.get("identity") or {}).get("phones") or []:
+ d = phone_digits(p)
+ if _NANP.match(d) and d not in seen:
+ seen.add(d)
+ out.append(d)
+ return out
USER_AGENT = "Mozilla/5.0 (compatible; unbroker/1.0; data opt-out)"
diff --git a/optional-skills/security/unbroker/scripts/tiers.py b/optional-skills/security/unbroker/scripts/tiers.py
index 6395de1ea8d..f08950b6288 100644
--- a/optional-skills/security/unbroker/scripts/tiers.py
+++ b/optional-skills/security/unbroker/scripts/tiers.py
@@ -43,6 +43,11 @@ def plan(subject_dossier: dict, brokers_list: list[dict], cfg: dict,
or cfg.get("email_mode", "draft_only")
actions: list[dict] = []
for b in brokers_list:
+ if b.get("defunct"):
+ # Dead domain (seized/NXDOMAIN): excluded from every scan/act surface so it
+ # never wedges a crawl, queues an opt-out against a corpse, or re-checks one.
+ # batch_plan surfaces the ids so the run book can say why they are absent.
+ continue
opt = b.get("optout") or {}
search = b.get("search") or {}
# Defensive shape coercion: a subagent may have written a malformed record (requires as a
@@ -96,7 +101,7 @@ def fanout(brokers_list: list[dict], batch_size: int = 5) -> dict:
Scanning many brokers serially is slow and burns context; above `batch_size`
the agent is expected to spawn one subagent per batch (see SKILL.md).
"""
- ids = [b.get("id") for b in brokers_list if b.get("id")]
+ ids = [b.get("id") for b in brokers_list if b.get("id") and not b.get("defunct")]
batches = [ids[i:i + batch_size] for i in range(0, len(ids), batch_size)]
return {
"broker_count": len(ids),
@@ -116,6 +121,8 @@ def runnable_for(subject_dossier: dict, brokers_list: list[dict]) -> tuple[list[
runnable: list[dict] = []
unsearchable: list[dict] = []
for b in brokers_list:
+ if b.get("defunct"):
+ continue # dead domains are neither runnable nor unsearchable: they are absent
(runnable if vectors_mod.search_vectors(subject_dossier, b) else unsearchable).append(b)
return runnable, unsearchable
@@ -137,8 +144,9 @@ def batch_plan(subject_dossier: dict, brokers_list: list[dict], cfg: dict,
children is ONE action, not N. Read-only: computes, never mutates the ledger.
"""
ledger = ledger or {}
+ defunct = [b.get("id") for b in brokers_list if b.get("defunct")]
actions = plan(subject_dossier, brokers_list, cfg, browser_clears_captcha)
- vcount = {a["broker_id"]: a.get("search_vectors_count", 1) for a in actions}
+ vcount = {a["broker_id"]: a["search_vectors_count"] for a in actions}
# child id -> parent id (only for parents present in this plan set)
child_to_parent: dict[str, str] = {}
@@ -194,7 +202,7 @@ def batch_plan(subject_dossier: dict, brokers_list: list[dict], cfg: dict,
elif st in groups:
groups[st].append(row)
elif st not in _SCANNED_STATES:
- if not vcount.get(bid, 1):
+ if not vcount.get(bid):
groups["unsearchable"].append(row)
else:
groups["unscanned"].append(row)
@@ -211,6 +219,7 @@ def batch_plan(subject_dossier: dict, brokers_list: list[dict], cfg: dict,
return {
"subject": subject_dossier.get("subject_id"),
"phase": "discover" if groups["unscanned"] else "delete",
+ "defunct": defunct,
"counts": {k: len(v) for k, v in groups.items()},
"groups": groups,
"cluster_savings": {p: kids for p, kids in covered_by_parent.items()},
@@ -244,8 +253,12 @@ def synthesize_steps(r: dict) -> list[str]:
+ " -- prefer deletion over suppression.")
if r.get("notes"):
steps.append(str(r["notes"]))
- for q in (r.get("optout_quirks") or [])[:3]:
+ quirks = r.get("optout_quirks") or []
+ for q in quirks[:4]:
steps.append(str(q))
+ if len(quirks) > 4:
+ steps.append(f"(+{len(quirks) - 4} more quirks in this broker's record -- read them "
+ "before filing; the record is the source of truth)")
return steps
diff --git a/tests/skills/test_unbroker_skill.py b/tests/skills/test_unbroker_skill.py
index 295bc803962..98fca73a83d 100644
--- a/tests/skills/test_unbroker_skill.py
+++ b/tests/skills/test_unbroker_skill.py
@@ -693,8 +693,8 @@ def test_phone_led_intake_without_name():
# intake with no identifier at all is refused
try:
_run(["intake", "--consent"])
- except SystemExit:
- pass
+ except SystemExit as e:
+ assert "at least one identifier" in str(e) # not just any argparse exit
else:
raise AssertionError("intake without any identifier must be refused")
@@ -716,7 +716,8 @@ def test_focus_phone_drives_disclosure_and_vectors():
def test_dnc_one_shot_surfaced_once_then_filed():
with temp_env():
sid = _run(["intake", "--full-name", "Jane Q. Public", "--email", "[email protected]",
- "--phone", "+1-415-555-0137", "--consent"])["subject_id"]
+ "--phone", "+1-415-555-0137", "--focus-phone", "+1-415-555-0137",
+ "--consent"])["subject_id"]
d = dossier.load(sid)
d["residency_jurisdiction"] = "US-CA"
dossier.save(d)
@@ -725,7 +726,9 @@ def test_dnc_one_shot_surfaced_once_then_filed():
assert out["dnc_url"] == "https://www.donotcall.gov/register.html"
assert "72 hours" in " ".join(out["steps"])
q = autopilot.next_actions(dossier.load(sid), [], _auto_cfg(), {}, env={})
- assert any(a["type"] == "dnc_register" for a in q["actions"])
+ act = next(a for a in q["actions"] if a["type"] == "dnc_register")
+ assert act["confirm_first"] is True # a new registry disclosure always asks
+ assert act["declined"]
filed = _run(["dnc", sid, "--filed"])
assert "dnc_filed_at" in filed
q2 = autopilot.next_actions(dossier.load(sid), [], _auto_cfg(), {}, env={})
@@ -757,11 +760,167 @@ def test_unsearchable_group_and_fanout_skip_for_nameless_subject():
# fanout batches only brokers this subject can actually be searched on
fan = _run(["fanout", sid])
ids = [b for batch in fan["batches"] for b in batch["brokers"]]
- assert fan["skipped_unsearchable"] >= 1
+ assert fan["skipped_unsearchable"] == 3 # 22 curated - 5 defunct - 14 live phone-capable
for bid in ids:
assert "phone" in (brokers.get(bid).get("search") or {}).get("by", ["name"])
+
+# --- review fixes: nameless emails, dnc scope/decline, defunct brokers, focus-phone edges ---
+
+def test_email_requests_refuse_nameless_subject():
+ """A nameless subject must never render/send a legal email that says 'None'."""
+ with temp_env():
+ sid = _run(["intake", "--phone", "+1-415-555-0137", "--email", "[email protected]",
+ "--consent"])["subject_id"]
+ try:
+ _run(["render-email", sid, "spokeo", "--kind", "ccpa_indirect",
+ "--listing", "https://www.spokeo.com/x"])
+ except SystemExit as e:
+ assert "full name" in str(e)
+ else:
+ raise AssertionError("render-email must refuse a nameless legal request")
+ # send-email needs a real email mode to reach the identity gate (not draft_only)
+ config.save_config({**config.DEFAULT_CONFIG, "email_mode": "browser"})
+ try:
+ _run(["send-email", sid, "spokeo", "--kind", "generic",
+ "--listing", "https://www.spokeo.com/x"])
+ except SystemExit as e:
+ assert "full name" in str(e) # sending needs the name even for generic
+ else:
+ raise AssertionError("send-email must refuse a nameless subject")
+ # generic drafts stay renderable (operator-edited signature) and never say "None"
+ out = _run(["render-email", sid, "spokeo", "--kind", "generic",
+ "--listing", "https://www.spokeo.com/x"])
+ draft_text = Path(out["draft"]).read_text(encoding="utf-8")
+ assert "None" not in draft_text and "[your full name]" in draft_text
+
+
+def test_email_request_omits_name_identifier_when_nameless():
+ with temp_env():
+ sid = _run(["intake", "--phone", "+1-415-555-0137", "--consent"])["subject_id"]
+ d = dossier.load(sid)
+ fields, _disclosed = pdd._email_request(d, brokers.get("spokeo"), "ccpa_indirect",
+ ["https://www.spokeo.com/x"], None)
+ assert "None" not in " ".join(fields["my_identifiers"])
+
+
+def test_optout_email_lane_requires_identity_in_next():
+ """The autonomous email lane digests (never queues) for a nameless subject."""
+ with temp_env():
+ mailer = _mini_broker("mailer")
+ mailer["optout"] = {**mailer["optout"], "method": "email", "email": "[email protected]"}
+ led = {"mailer": {"state": "found"}}
+ sid = _run(["intake", "--phone", "+1-415-555-0137", "--consent"])["subject_id"]
+ q = autopilot.next_actions(dossier.load(sid), [mailer], _auto_cfg(email_mode="browser"),
+ led, env={})
+ assert not any(a["type"] == "optout_email_send" for a in q["actions"])
+ assert "full name" in _json.dumps(q["human_digest"])
+ sid2 = _run(["intake", "--full-name", "Jane Q. Public", "--email", "[email protected]",
+ "--consent"])["subject_id"]
+ q2 = autopilot.next_actions(dossier.load(sid2), [mailer], _auto_cfg(email_mode="browser"),
+ led, env={})
+ assert any(a["type"] == "optout_email_send" for a in q2["actions"])
+
+
+def test_dnc_register_needs_phone_led_run_and_can_be_declined():
+ with temp_env():
+ # name-led subject: no dnc action, and `next` must terminate
+ sid = _run(["intake", "--full-name", "Jane Q. Public", "--email", "[email protected]",
+ "--consent"])["subject_id"]
+ _age = autopilot.cache_age_days
+ autopilot.cache_age_days = lambda: 0.0 # fresh broker cache: no refresh action
+ try:
+ q = autopilot.next_actions(dossier.load(sid), [], _auto_cfg(), {}, env={})
+ finally:
+ autopilot.cache_age_days = _age
+ assert not any(a["type"] == "dnc_register" for a in q["actions"])
+ assert q["done_for_now"] is True # a name-led run must terminate, not wedge on DNC
+ # phone-led subject: surfaced once with confirm_first, then --declined clears it
+ sid2 = _run(["intake", "--phone", "+1-415-555-0137", "--focus-phone", "+1-415-555-0137",
+ "--consent"])["subject_id"]
+ q2 = autopilot.next_actions(dossier.load(sid2), [], _auto_cfg(), {}, env={})
+ assert next(a for a in q2["actions"] if a["type"] == "dnc_register")["confirm_first"] is True
+ dec = _run(["dnc", sid2, "--declined"])
+ assert "dnc_declined_at" in dec
+ q3 = autopilot.next_actions(dossier.load(sid2), [], _auto_cfg(), {}, env={})
+ assert not any(a["type"] == "dnc_register" for a in q3["actions"])
+ # a non-NANP number is not registrable even on a phone-led run
+ sid3 = _run(["intake", "--phone", "+44 20 7946 0958", "--focus-phone", "+44 20 7946 0958",
+ "--consent"])["subject_id"]
+ q4 = autopilot.next_actions(dossier.load(sid3), [], _auto_cfg(), {}, env={})
+ assert not any(a["type"] == "dnc_register" for a in q4["actions"])
+ assert _run(["dnc", sid3])["eligible"] is False
+
+
+def test_defunct_brokers_excluded_from_all_planning():
+ with temp_env():
+ d = _consenting()
+ dead = _mini_broker("deadbroker")
+ dead["defunct"] = {"since": "2026-08-27", "evidence": "domain seized"}
+ deadrest = _mini_broker("deadrest")
+ deadrest["defunct"] = {"since": "2026-08-27", "evidence": "NXDOMAIN"}
+ live = _mini_broker("livebroker")
+ bl = [dead, deadrest, live]
+ assert [a["broker_id"] for a in tiers.plan(d, bl, config.DEFAULT_CONFIG)] == ["livebroker"]
+ bp = tiers.batch_plan(d, bl, config.DEFAULT_CONFIG, {})
+ assert bp["defunct"] == ["deadbroker", "deadrest"]
+ assert not any(r["broker_id"].startswith("dead") for g in bp["groups"].values() for r in g)
+ runnable, unsearchable = tiers.runnable_for(d, bl)
+ assert [b["id"] for b in runnable + unsearchable] == ["livebroker"]
+ assert all("deadbroker" not in batch and "deadrest" not in batch
+ for batch in tiers.fanout(bl)["batches"])
+ # open cases of dead brokers: no re-checks, one close-out digest entry instead
+ led = {"deadbroker": {"broker_id": "deadbroker", "state": "submitted"},
+ "deadrest": {"broker_id": "deadrest", "state": "confirmed_removed",
+ "next_recheck_at": "2020-01-01T00:00:00Z"},
+ "livebroker": {"broker_id": "livebroker", "state": "confirmed_removed",
+ "next_recheck_at": "2020-01-01T00:00:00Z"}}
+ q = autopilot.next_actions(d, bl, _auto_cfg(), led, env={})
+ kinds = [(a["type"], a.get("broker_id")) for a in q["actions"]]
+ assert ("verify_removal", "deadrest") not in kinds # never re-scan a corpse
+ assert ("verify_removal", "livebroker") in kinds # live brokers still recheck
+ close = [t for t in q["human_digest"] if "deadbroker" in _json.dumps(t)]
+ assert close and "not_found" in _json.dumps(close)
+
+
+def test_ledger_allows_not_found_close_out_for_dead_brokers():
+ for st in ("found", "action_selected", "submitted", "verification_pending",
+ "awaiting_processing", "human_task_queued"):
+ assert "not_found" in ledger.TRANSITIONS[st], st
+
+
+def test_focus_phone_edge_cases():
+ with temp_env():
+ # focus-phone alone satisfies the identifier requirement
+ out = _run(["intake", "--focus-phone", "+1-415-555-0137", "--consent"])
+ assert out["phones"] == 1 and out["focus_phone"] == "+1-415-555-0137"
+ # a differently-formatted duplicate is ONE number, not two vectors
+ out2 = _run(["intake", "--phone", "555-123-4567", "--focus-phone", "5551234567",
+ "--consent"])
+ assert out2["phones"] == 1
+ # --json intake honors --focus-phone too (was silently ignored)
+ import tempfile as _tf
+ with _tf.NamedTemporaryFile("w", suffix=".json", delete=False) as f:
+ _json.dump({"identity": {"full_name": "Json Subject", "emails": ["[email protected]"]},
+ "consent": {"authorized": True, "method": "self"},
+ "residency_jurisdiction": "US"}, f)
+ jpath = f.name
+ out3 = _run(["intake", "--json", jpath, "--focus-phone", "+1-510-555-0199"])
+ assert out3["focus_phone"] == "+1-510-555-0199"
+ d = dossier.load(out3["subject_id"])
+ assert d["preferences"]["focus_phone"] == "+1-510-555-0199"
+ assert "+1-510-555-0199" in d["identity"]["phones"]
+
+
+def test_synthesize_steps_keep_gate_quirks_within_cap():
+ r = {"optout_url": "https://x.example/optout",
+ "optout_quirks": ["q1", "q2", "q3", "q4 GATE", "q5"]}
+ steps = tiers.synthesize_steps(r)
+ assert any("q4 GATE" in s for s in steps) # the 4th quirk (a gate finding) survives
+ assert any("+1 more quirk" in s for s in steps) # truncation is disclosed, never silent
+
+
if __name__ == "__main__":
failures = []
tests = [(n, f) for n, f in sorted(globals().items()) if n.startswith("test_") and callable(f)]
diff --git a/website/docs/user-guide/skills/optional/security/security-unbroker.md b/website/docs/user-guide/skills/optional/security/security-unbroker.md
index b28feeea4a4..9bf94eef4c7 100644
--- a/website/docs/user-guide/skills/optional/security/security-unbroker.md
+++ b/website/docs/user-guide/skills/optional/security/security-unbroker.md
@@ -137,7 +137,7 @@ breaks reading the dossier).
| `$PDD drop <subject> [--filed]` | **The one-shot legal lever**: one CA DROP request deletes from ALL registered brokers; `--filed` records it |
| `$PDD dnc <subject> [--filed]` | **The spam-call lever**: register the subject's US personal numbers on the FTC National Do Not Call Registry (sales calls stop within 31 days, never expires); `--filed` records it |
| `$PDD plan <subject> [--priority crucial]` | Per-broker tier + method + `search_vectors` + the exact fields to disclose |
-| `$PDD plan <subject> --batch` | **Reduce view**: overlays ledger state, groups brokers by next action (unscanned/found/indirect/blocked/in_progress/done), collapses ownership clusters, **orders `found` cluster-parents-first + emits a tailored `parent_playbook`**, prints `next_actions` |
+| `$PDD plan <subject> --batch` | **Reduce view**: overlays ledger state, groups brokers by next action (unscanned/unsearchable/found/indirect/blocked/in_progress/human/done/not_found; defunct brokers are excluded and listed under `defunct`), collapses ownership clusters, **orders `found` cluster-parents-first + emits a tailored `parent_playbook`**, prints `next_actions` |
| `$PDD fanout <subject> [--priority crucial] [--size 5]` | Batch brokers into parallel `delegate_task` subagents (auto for large runs; batches of 5 - 8+ time out) |
| `$PDD record <subject> <broker> <state> [--found true] [--evidence JSON] [--disclosed F --channel C] [--reason "..."]` | Update the ledger (validated state machine); **auto-stamps `next_recheck_at`** |
| `$PDD show <subject> <broker>` | Read back a case's recorded state + evidence + disclosure log (so the parent re-verifies a subagent's `found` without re-deriving the listing URL) |
@@ -301,13 +301,17 @@ is where lead buyers get it. The same engine, entered from the number:
but collect the full name + contact email at intake anyway: every opt-out form and legal request
needs them.
2. **The loop is unchanged.** `$PDD next <subject>` drives the same crawl / opt-out / re-check
- queue; the reverse-phone sites (18 of the 22 curated people-search records declare `by: phone`)
- are scanned with the phone vector, and the re-check schedule watches for the number re-listing
+ queue; the reverse-phone sites (14 of the live curated records declare `by: phone`; five curated
+ brokers are defunct - dead domains, excluded from planning) are scanned with the phone vector, and the re-check schedule watches for the number re-listing
(per the subject's `rescan_interval_days`).
3. **DNC one-shot.** For a US personal number, `next` also surfaces `dnc_register` once: the FTC
National Do Not Call Registry (free, never expires, sales calls stop within 31 days; up to 3
numbers per pass, one confirmation email per number - open each link within 72 hours). `$PDD
- dnc <subject>` prints the steps; `$PDD dnc <subject> --filed` records it. DNC stops lawful
+ dnc <subject>` prints the steps; `$PDD dnc <subject> --filed` records it and
+ `$PDD dnc <subject> --declined` opts the subject out without recording a filing that never
+ happened. Surfaced only for phone-led runs (`--focus-phone`) and only for NANP numbers,
+ always with `confirm_first` - intake consent covers broker removal, not a new registry
+ disclosure. DNC stops lawful
telemarketers, not scammers - broker removal is what cuts the lead lists, so do both.
## Pitfalls