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.

TaskWhatWaiting onEffort
BT1Fix the two critical security issuesBrain developer, with the Brain CTOBrain CTO to estimate
BT2Clear error codes when a permit file can't be readBrain developerBrain CTO to estimate
BT3A separate "no route text" statusBrain developerBrain CTO to estimate
BT4The route use count in each permit readingBrain developerAbout 1 day (Brain CTO's estimate); the first item once work starts
BT5Confirm whether the live use count includes the permit being pricedBrain CTOA written answer
BT6Return the carrier name and USDOT number from every permit when printedBrain CTO (answer), then Brain developerBrain CTO to estimate
BT14Receive the two permit filesBrain CTO (who receives), then Workspace developer (links, after its new storage key)Minutes
BT10Answer on the new address brain.heavyhaulagent.comBrain developer (hosting)About 1 day incl. the voice widget (Brain CTO's estimate)
BT11Change the token Synchron uses, in the right orderWorkspace developer first (T9, T10), then Brain developerSmall
BT8Route files per item and per version, with a signed resultBrain developerAbout 2–3 days (Brain CTO's estimate)
BT9A signed sample of the route-file result before staging existsBrain developerSmall
BT7The file fingerprint in each permit readingBrain developerBrain CTO to estimate
BT12The Brain's trip copy accepts 9-digit order numbersBrain developerBrain CTO to estimate
BT13The trip assistant never returns map linksBrain developerSmall
BT15Production server details and a staging copyBrain 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

What

Two 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 it

Owner 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 Workspace

None directly; it protects every customer who uses the Brain through the Workspace.

Effort

Brain CTO to estimate

Done when

No customer can see another customer's orders; the old Google AI key no longer works anywhere; the new key is only in environment settings.

Note

Internal HHA information: never include these details in any file for Synchron.

Brain developer — status or questions on BT1

BT2 · Clear error codes when a permit file can't be read

Waiting on: Brain developer · Status: not confirmed shipped

What

422 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.

Source: who decided or agreed it

Agreed between the Brain CTO and the Workspace CTO (the Brain's decision list, October 7).

What depends on it in the Workspace

Workspace 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.

Effort

Brain CTO to estimate

Done when

Each case returns its code and a request id; a test file that is not a permit returns 422 not_a_permit.

Brain developer — status or questions on BT2

BT3 · A separate "no route text" status

Waiting on: Brain developer · Status: not confirmed shipped

What

A permit with no route text returns no_route_text, separate from failed.

Source: who decided or agreed it

The Brain CTO's decision (October 7).

What depends on it in the Workspace

Workspace T7 shows "Route prepared from your permit" instead of an error.

Effort

Brain CTO to estimate

Done when

A permit without route text returns no_route_text, never failed.

Brain developer — status or questions on BT3

BT4 · The route use count in each permit reading

Waiting on: Brain developer · Status: not confirmed shipped

What

route_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.

Source: who decided or agreed it

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 Workspace

Workspace T16: Express from 4 or more when the count includes the permit being priced.

Effort

About 1 day (Brain CTO's estimate); the first item once work starts

Done when

Every reading with a token carries the count and the rule; a reading without a token has no count field.

Brain developer — status or questions on BT4

BT5 · Confirm whether the live use count includes the permit being priced

Waiting on: Brain CTO · Status: not confirmed shipped

What

A short written answer: does the live backend use count for a route token include the permit currently being priced?

Source: who decided or agreed it

Asked by the Workspace CTO on October 8, 12:02 AM.

What depends on it in the Workspace

Workspace 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.

Effort

A written answer

Done when

The answer is in writing.

Brain developer — status or questions on BT5

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

What

The reader returns carrier_info (name and USDOT number) whenever they are printed on the permit, and says so when they are not printed.

Source: who decided or agreed it

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 Workspace

Workspace 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".

Effort

Brain CTO to estimate

Done when

Every permit reading either carries carrier_info or a clear "not printed" marker.

Brain developer — status or questions on BT6

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

What

Say 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.

Source: who decided or agreed it

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 Workspace

Explains why these files fail to read; 7 of the 8 Workspace permits without a token come from them.

Effort

Minutes

Done when

The Brain team has both files.

Brain developer — status or questions on BT14

BT10 · Answer on the new address brain.heavyhaulagent.com

Waiting on: Brain developer (hosting) · Status: not confirmed shipped

What

The 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.

Source: who decided or agreed it

Owner decision B037 (domains confirmed); the Brain CTO's answer of October 7.

What depends on it in the Workspace

The Workspace changes one setting (HHA_API_BASE_URL) and tests the health call and one permit reading.

Effort

About 1 day incl. the voice widget (Brain CTO's estimate)

Done when

https://brain.heavyhaulagent.com/api/workspace/health answers, and every /api/workspace/… call works on the new name.

Brain developer — status or questions on BT10

BT11 · Change the token Synchron uses, in the right order

Waiting on: Workspace developer first (T9, T10), then Brain developer · Status: not confirmed shipped

What

Replace 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 it

The Brain CTO's question W3 and the Workspace CTO's answer (October 7).

What depends on it in the Workspace

Workspace T9 (settings check) and T10 (remove the fallback) come first; doing this before them would cut the Workspace off from the Brain.

Effort

Small

Done when

Synchron uses a new token; Workspace calls keep working throughout.

Brain developer — status or questions on BT11

BT8 · Route files per item and per version, with a signed result

Waiting on: Brain developer · Status: not confirmed shipped

What

POST /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.

Source: who decided or agreed it

The Brain's decision B1 and question W1, agreed with the Workspace CTO (October 7).

What depends on it in the Workspace

Workspace T15 calls it on every delivery and correction and copies the GPX to storage.

Effort

About 2–3 days (Brain CTO's estimate)

Done when

A request returns a job id; the signed result carries the version; an older version never replaces a newer one.

Brain developer — status or questions on BT8

BT9 · A signed sample of the route-file result before staging exists

Waiting on: Brain developer · Status: not confirmed shipped

What

In 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.

Source: who decided or agreed it

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 Workspace

Lets the Workspace test its receiver (T15) without a staging Brain.

Effort

Small

Done when

The samples and the test secret are in the repository; the Workspace's receiver verifies them.

Brain developer — status or questions on BT9

BT7 · The file fingerprint in each permit reading

Waiting on: Brain developer · Status: not confirmed shipped

What

A 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.

Source: who decided or agreed it

The Brain CTO's answer of October 7, 8:20 PM.

What depends on it in the Workspace

A second check for Workspace T8 (the Workspace detects duplicates itself).

Effort

Brain CTO to estimate

Done when

The fingerprint equals the Workspace's own SHA-256 of the same bytes.

Brain developer — status or questions on BT7

BT12 · The Brain's trip copy accepts 9-digit order numbers

Waiting on: Brain developer · Status: not confirmed shipped

What

The 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 it

The Brain CTO's decision; owner decisions 54–55 and Nash's trip-number rule.

What depends on it in the Workspace

The Workspace sends 9-digit numbers for its own trips.

Effort

Brain CTO to estimate

Done when

A trip with a 9-digit number syncs; a trip with an 8-digit Synchron number still syncs.

Brain developer — status or questions on BT12

BT13 · The trip assistant never returns map links

Waiting on: Brain developer · Status: not confirmed shipped

What

Keep the trip assistant from ever returning route map links, and add a test that keeps it that way.

Source: who decided or agreed it

The Brain CTO's decision (its order tool returns no route links today).

What depends on it in the Workspace

Protects routes that were not bought or were canceled.

Effort

Small

Done when

The test exists and passes.

Brain developer — status or questions on BT13

BT15 · Production server details and a staging copy

Waiting on: Brain developer (specifications); Nash (staging decision) · Status: not confirmed shipped

What

Provide 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 it

Owner decisions B038 and B040 (the Brain developer is responsible and will provide the specifications).

What depends on it in the Workspace

Staging is needed for end-to-end tests with the Workspace and Synchron.

Effort

Small

Done when

The Brain CTO has the specifications; staging is decided.

Brain developer — status or questions on BT15