For the HHA Brain Developer · From the HHA Workspace CTO
For the HHA Brain Developer — From the HHA Workspace CTO — October 13, 2026, 1:07 AM ET — Brain tasks for the integration
Name and address. The HeavyHaul Factory is now called the Brain and moves to its own subdomain, brain.heavyhaulagent.com. The Workspace moves to heavyhaulagent.com.
These are the 15 Brain tasks the Synchron and Workspace integration depends on. Each one was decided by Nash or committed to by the Brain CTO in writing; nothing here is new scope from the Workspace. The Brain CTO owns the Brain's priorities and estimates. Where he hasn't given an estimate, the card says so.
How to read this
- BT numbers are Brain tasks. T numbers refer to the Workspace developer's list.
- Status: every task shows "not confirmed shipped". The Workspace CTO can't see the Brain's code, so status comes only from the CTO letters. Please type the real status in each box.
- Waiting on names who holds each task: the Brain developer, the Brain CTO, the Workspace developer, or Nash.
- Internal HHA information (BT1) must never go into files for Synchron.
Summary and suggested order
Suggested order (the Brain CTO decides): security first, as Nash asked; then the items that stop wasted work in the Workspace today (error codes, use count, carrier data); then the new address and the token change; then route files.
| Task | What | Waiting on | Effort |
|---|---|---|---|
| BT1 | Fix the two critical security issues | Brain developer, with the Brain CTO | Brain CTO to estimate |
| BT2 | Clear error codes when a permit file can't be read | Brain developer | Brain CTO to estimate |
| BT3 | A separate "no route text" status | Brain developer | Brain CTO to estimate |
| BT4 | The route use count in each permit reading | Brain developer | About 1 day (Brain CTO's estimate); the first item once work starts |
| BT5 | Confirm whether the live use count includes the permit being priced | Brain CTO | A written answer |
| BT6 | Return the carrier name and USDOT number from every permit when printed | Brain CTO (answer), then Brain developer | Brain CTO to estimate |
| BT14 | Receive the two permit files | Brain CTO (who receives), then Workspace developer (links, after its new storage key) | Minutes |
| BT10 | Answer on the new address brain.heavyhaulagent.com | Brain developer (hosting) | About 1 day incl. the voice widget (Brain CTO's estimate) |
| BT11 | Change the token Synchron uses, in the right order | Workspace developer first (T9, T10), then Brain developer | Small |
| BT8 | Route files per item and per version, with a signed result | Brain developer | About 2–3 days (Brain CTO's estimate) |
| BT9 | A signed sample of the route-file result before staging exists | Brain developer | Small |
| BT7 | The file fingerprint in each permit reading | Brain developer | Brain CTO to estimate |
| BT12 | The Brain's trip copy accepts 9-digit order numbers | Brain developer | Brain CTO to estimate |
| BT13 | The trip assistant never returns map links | Brain developer | Small |
| BT15 | Production server details and a staging copy | Brain developer (specifications); Nash (staging decision) | Small |
BT1 · Fix the two critical security issues
Waiting on: Brain developer, with the Brain CTO · Status: not confirmed shipped
WhatTwo vulnerabilities reported by the Brain CTO: an exposure of one customer's orders to another customer, and an exposed Google AI key. The key must be rotated, not only removed from the code.
Source: who decided or agreed itOwner decision B041 (October 7–8): treat both as critical and fix immediately; the Brain developer works directly with the Brain CTO.
What depends on it in the WorkspaceNone directly; it protects every customer who uses the Brain through the Workspace.
EffortBrain CTO to estimate
Done whenNo customer can see another customer's orders; the old Google AI key no longer works anywhere; the new key is only in environment settings.
NoteInternal HHA information: never include these details in any file for Synchron.
BT2 · Clear error codes when a permit file can't be read
Waiting on: Brain developer · Status: not confirmed shipped
What422 with not_a_permit, unreadable_file or no_state_detected; 503 reader_unavailable; 500 internal_error. Every error carries a request_id and never raw exception text.
Agreed between the Brain CTO and the Workspace CTO (the Brain's decision list, October 7).
What depends on it in the WorkspaceWorkspace T7 stops endless retries and shows "This file doesn't look like a permit we can read". Today 7 of the 8 Workspace permits without a token come from 2 files that will never read.
EffortBrain CTO to estimate
Done whenEach case returns its code and a request id; a test file that is not a permit returns 422 not_a_permit.
BT3 · A separate "no route text" status
Waiting on: Brain developer · Status: not confirmed shipped
WhatA permit with no route text returns no_route_text, separate from failed.
The Brain CTO's decision (October 7).
What depends on it in the WorkspaceWorkspace T7 shows "Route prepared from your permit" instead of an error.
EffortBrain CTO to estimate
Done whenA permit without route text returns no_route_text, never failed.
BT4 · The route use count in each permit reading
Waiting on: Brain developer · Status: not confirmed shipped
Whatroute_usage_count in every states_info[] item, plus route_usage_rule. Numeric tokens: the same count the Express rule uses, including the permit being read. workspace: tokens: distinct Workspace permits that produced the token, including this one (the first is 1). No token: the field is left out, never 0.
The Brain CTO's answer of October 7, 8:20 PM; owner decision 2 (Express releases on the fourth counted use).
What depends on it in the WorkspaceWorkspace T16: Express from 4 or more when the count includes the permit being priced.
EffortAbout 1 day (Brain CTO's estimate); the first item once work starts
Done whenEvery reading with a token carries the count and the rule; a reading without a token has no count field.
BT5 · Confirm whether the live use count includes the permit being priced
Waiting on: Brain CTO · Status: not confirmed shipped
WhatA short written answer: does the live backend use count for a route token include the permit currently being priced?
Source: who decided or agreed itAsked by the Workspace CTO on October 8, 12:02 AM.
What depends on it in the WorkspaceWorkspace T16 uses 4 or more for counts that include the permit, 3 or more for counts that don't. The live count is the only one whose rule is unknown.
EffortA written answer
Done whenThe answer is in writing.
BT6 · Return the carrier name and USDOT number from every permit when printed
Waiting on: Brain CTO (answer), then Brain developer · Status: not confirmed shipped
WhatThe reader returns carrier_info (name and USDOT number) whenever they are printed on the permit, and says so when they are not printed.
Owner decision of October 7 (item 3): the Workspace validates the trip carrier from its permits. Asked by the Workspace CTO on October 8.
What depends on it in the WorkspaceWorkspace T4: today the reader returns carrier data for 13 of the 19 permits uploaded in the Workspace. The other 6 are left out of the count; the Workspace needs to know whether they mean "not printed" or "not read".
EffortBrain CTO to estimate
Done whenEvery permit reading either carries carrier_info or a clear "not printed" marker.
BT14 · Receive the two permit files
Waiting on: Brain CTO (who receives), then Workspace developer (links, after its new storage key) · Status: not confirmed shipped
WhatSay who on the Brain side receives 1769964624_23.pdf and the Nevada file 1789834772_32.pdf. The Workspace developer then sends two 24-hour download links through a one-time secret link.
Owner decision of October 7 (item 8): the CTOs coordinate directly. Asked by the Workspace CTO on October 8.
What depends on it in the WorkspaceExplains why these files fail to read; 7 of the 8 Workspace permits without a token come from them.
EffortMinutes
Done whenThe Brain team has both files.
BT10 · Answer on the new address brain.heavyhaulagent.com
Waiting on: Brain developer (hosting) · Status: not confirmed shipped
WhatThe same Brain server answers on a second name, with /api/workspace/health. Fix the voice widget first. Tell the Workspace the day it answers. The order: the Brain answers on the new name; the Workspace moves its setting and tests; Synchron moves its calls; then heavyhaulagent.com switches to the Workspace.
Owner decision B037 (domains confirmed); the Brain CTO's answer of October 7.
What depends on it in the WorkspaceThe Workspace changes one setting (HHA_API_BASE_URL) and tests the health call and one permit reading.
About 1 day incl. the voice widget (Brain CTO's estimate)
Done whenhttps://brain.heavyhaulagent.com/api/workspace/health answers, and every /api/workspace/… call works on the new name.
BT11 · Change the token Synchron uses, in the right order
Waiting on: Workspace developer first (T9, T10), then Brain developer · Status: not confirmed shipped
WhatReplace the shared token Synchron uses for the Brain (F11), but only after the Workspace confirms in writing that production uses its own credential. Optional and recommended: log for a few days which credential each Workspace request uses.
Source: who decided or agreed itThe Brain CTO's question W3 and the Workspace CTO's answer (October 7).
What depends on it in the WorkspaceWorkspace T9 (settings check) and T10 (remove the fallback) come first; doing this before them would cut the Workspace off from the Brain.
EffortSmall
Done whenSynchron uses a new token; Workspace calls keep working throughout.
BT8 · Route files per item and per version, with a signed result
Waiting on: Brain developer · Status: not confirmed shipped
WhatPOST /api/workspace/route-files with { trip_id, hha_permit_id, order_number, permit_token, route_token, route_version, map_urls[] } answers 202 { job_id }. Then a signed route_files.ready or route_files.failed (with route_version) goes to the Workspace's /api/webhooks/brain, using X-HHA-Brain-* headers. Files are made once per version; an older request that arrives late is ignored; files are never shared between orders; the GPX link lasts 24 hours.
The Brain's decision B1 and question W1, agreed with the Workspace CTO (October 7).
What depends on it in the WorkspaceWorkspace T15 calls it on every delivery and correction and copies the GPX to storage.
EffortAbout 2–3 days (Brain CTO's estimate)
Done whenA request returns a job id; the signed result carries the version; an older version never replaces a newer one.
BT9 · A signed sample of the route-file result before staging exists
Waiting on: Brain developer · Status: not confirmed shipped
WhatIn the contract repository: a signed sample route_files.ready and route_files.failed, with a test-only secret, the expected signature, and the list of failure reasons.
The Brain CTO's decision (October 7, 8:20 PM); the failure sample was asked by the Workspace CTO.
What depends on it in the WorkspaceLets the Workspace test its receiver (T15) without a staging Brain.
EffortSmall
Done whenThe samples and the test secret are in the repository; the Workspace's receiver verifies them.
BT7 · The file fingerprint in each permit reading
Waiting on: Brain developer · Status: not confirmed shipped
WhatA top-level file_sha256: SHA-256 of the exact bytes received, lowercase hex, computed before any image-to-PDF conversion. Also duplicate_of (earlier readings of the same fingerprint on the same trip), empty when there are none.
The Brain CTO's answer of October 7, 8:20 PM.
What depends on it in the WorkspaceA second check for Workspace T8 (the Workspace detects duplicates itself).
EffortBrain CTO to estimate
Done whenThe fingerprint equals the Workspace's own SHA-256 of the same bytes.
BT12 · The Brain's trip copy accepts 9-digit order numbers
Waiting on: Brain developer · Status: not confirmed shipped
WhatThe trip copy the Workspace sends accepts a 9-digit order number for Workspace trips (one order per trip) and keeps 8 digits for Synchron orders.
Source: who decided or agreed itThe Brain CTO's decision; owner decisions 54–55 and Nash's trip-number rule.
What depends on it in the WorkspaceThe Workspace sends 9-digit numbers for its own trips.
EffortBrain CTO to estimate
Done whenA trip with a 9-digit number syncs; a trip with an 8-digit Synchron number still syncs.
BT13 · The trip assistant never returns map links
Waiting on: Brain developer · Status: not confirmed shipped
WhatKeep the trip assistant from ever returning route map links, and add a test that keeps it that way.
Source: who decided or agreed itThe Brain CTO's decision (its order tool returns no route links today).
What depends on it in the WorkspaceProtects routes that were not bought or were canceled.
EffortSmall
Done whenThe test exists and passes.
BT15 · Production server details and a staging copy
Waiting on: Brain developer (specifications); Nash (staging decision) · Status: not confirmed shipped
WhatProvide the Brain production server specifications to the Brain CTO. A staging copy of the Brain is a hosting decision for Nash, which the Brain CTO said he would ask.
Source: who decided or agreed itOwner decisions B038 and B040 (the Brain developer is responsible and will provide the specifications).
What depends on it in the WorkspaceStaging is needed for end-to-end tests with the Workspace and Synchron.
EffortSmall
Done whenThe Brain CTO has the specifications; staging is decided.