We have spent an unreasonable amount of time being misled by the word ready.
A workspace was marked ready while the Agent Bridge runtime it was supposed to contain was missing.
A provider could fail its behavioural qualification and disappear from interactive routing even though it was authenticated, installed and perfectly capable of attempting a normal user request.
An authentication flow could have credential material in place without the actual ACP runtime having proved that it could initialise and use it.
These looked like separate bugs.
I now think they were the same modelling error.
We kept taking several facts and compressing them into one bit.
A workspace can be provisioned and still not be usable
The clearest example came from a fresh test workspace.
Platform state said it was ready and provisioned. SSH worked.
Inside the workspace, /opt/agent-bridge-ux was absent. A helper expected by the interactive runtime therefore did not exist. The sample service was crash-looping with an execution error. There was evidence of a partial Node installation.
The Telegram setup code refused to proceed because a credential helper was missing.
At first glance that looked like a Telegram defect.
It was actually Telegram being the first component to ask a stronger question than the provisioning state had asked.
The workspace existed. The infrastructure had come up. That did not prove the expected runtime identity was present and executable.
We changed the readiness boundary so the final state has to read back what is actually installed and running rather than trusting the fact that earlier deployment steps were requested.
"Provisioning finished" and "the workspace can do the job we provisioned it for" are different facts.
Qualification and availability are different too
A day earlier we had found the same shape in provider routing.
Agent Bridge qualifies provider runtimes against a behavioural contract. That is useful. It catches things such as broken session resume or repository grounding before we promote a runtime.
We had also been feeding failed qualification evidence into interactive availability.
That meant a provider with a failed qualification could disappear from /cli and the fallback chain even when its authentication was valid, its executable existed and the actual user request might have worked.
We had confused two questions:
Can we attempt this provider now?
and:
Has this exact runtime passed the current release qualification contract?
The second remains important for releases and diagnostics. It is not automatically an answer to the first.
Interactive availability now comes from direct prerequisites: authentication, selected runtime presence, runtime-auth degradation and the few provider-specific conditions that genuinely determine whether an attempt is executable.
Qualification stays visible. It just no longer impersonates availability.
Authentication has the same trap
Agy gave us another version of the lesson.
Changing its authentication path exposed a mismatch between the browser experience and the ACP runtime that actually serves Telegram. At one point it was possible to have something that looked like successful authentication at one layer while the runtime that mattered did not yet have usable authority.
The design we are now pursuing makes the runtime probe authoritative.
A token exchange or credential-file write is an intermediate state. The acceptance boundary we are aiming for is stricter: do not call the flow connected until the ACP runtime can initialise and prove the credential in the same execution boundary that will later serve the user.
That is slightly more work than checking whether a file exists.
It is also answering the question we actually care about.
Boolean state is attractive for good reasons
I understand why we kept doing this.
A boolean is easy to store, easy to display and easy to branch on. Users reasonably want to know whether something is connected or ready. Operators reasonably want a status they can scan.
The mistake is not presenting a simple answer.
The mistake is making the simple answer the source of truth.
Underneath "ready" there may be infrastructure state, installed release identity, service state, authentication state, runtime compatibility and current qualification evidence. Those do not all change together and they do not have the same owner.
Collapsing them too early produces odd coupling.
A failed behavioural test becomes an availability outage. A successful provisioning workflow becomes evidence that files exist when nobody read them back. A credential artefact becomes proof that a provider can actually use it.
The UI becomes simple by making the system's reasoning wrong.
The better model is evidence with a projection
I do not want Farstax to show customers a twelve-column state machine.
The product can still say Ready.
But that label should be a projection from stronger underlying evidence, and the evidence should remain separately inspectable when something goes wrong.
For a provider, availability and qualification can sit beside each other. For a workspace, infrastructure state and runtime convergence can have separate owners. For authentication, we can distinguish materialisation from runtime verification.
Then the top-level status can be derived for the purpose at hand.
That last phrase matters: for the purpose at hand.
Release qualification can be stricter than interactive attemptability. A health page can expose degradation that does not make a workspace unusable. A setup wizard can wait for an authoritative runtime probe even though the credential write has finished.
There is no universal readiness bit because readiness is always readiness for something.
What I am watching next
There is a risk of overcorrecting and inventing a status ontology for every subsystem.
I do not want that either.
Most state should stay with the component that owns it. The useful change is simply to stop using one component's evidence as a substitute for another component's question.
A workspace heartbeat is not a release readback.
A qualification result is not interactive availability.
A credential file is not authenticated execution.
We can still show a green light at the end.
We just need to remember that readiness is a conclusion, not a primitive.