Skip to content

[FD-6368] feat: an agent's clock is opt-in: clock/v1 use_env_time, called only when sync_env_clock's agent_clock is on - #832

Open
williamloo-scale wants to merge 7 commits into
mainfrom
wlo/agent-clock-opt-in
Open

williamloo-scale wants to merge 7 commits into
mainfrom
wlo/agent-clock-opt-in

Conversation

@williamloo-scale

@williamloo-scale williamloo-scale commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Why

Since #726, sync_env_clock has every agent registered with the env follow the env's clock, and deploy_agent does the same for an agent it deploys while the clock is armed. So any task that sets the clock puts its agents on virtual time. An agent on the env's clock reads a date that its files' modification times don't share, so CLIs break:

  • FD-6368: Claude Code's transcript cleanup deletes the live conversation once the env's date is more than 30 days ahead.
  • Gemini: the CLI's lock on ~/.gemini/projects.json took its own fresh lock for a stale one ([FD-5916] feat(agents): the Gemini CLI image follows the env's clock #770's validation).
  • Every agent's TLS goes through the egress proxy while its clock is armed (codex/rustls, MCP certificates).

The agent's clock should be something a task asks for and the agent opts into.

What

libfaketime stays preloaded (/etc/ld.so.preload). It already reads real time from an unarmed clock page, and every issue above needs an armed one, so the toggle is whether the agent's page is armed.

Follower (utils/faketime_clock/clock-follower, shared with computers):

  • Takes env_time from its config.
  • false: it follows and acknowledges the gateway's versions, so clock writes can wait for it, while the page stays real time.
  • Missing, as every computer's config is: it arms as before.
  • Its status reports env_time.

Agent (AgentEnvAgent, agentenv_protocol.a2a_agent.clock):

  • sync_time writes the follower's config with env_time: false, keeping true for the same gateway and name.
  • New clock/v1 method use_env_time (POST /ext/clock/use-env-time, no fields) is the agent's opt-in. It turns env_time on and answers {"env_time": true, "follower": ...} once the follower shows that config. It is refused before sync_time.
  • use_env_time is an optional feature (env_time) of clock/v1. The SDK turns it on for every agent whose clock/v1 operations are the SDK's, whether the SDK adds clock/v1 or the agent declares it.
  • An agent that serves a clock/v1 operation of its own keeps its declaration as is, and still starts without use_env_time.

Task (sync_env_clock, a2a_agent/clock.py):

  • New field agent_clock, default false.
  • Only when it's on does the step have agents follow: sync_time, then use_env_time where the card serves it.
  • require_agent_clock implies it.
  • The armed clock's configuration records it, so a late agent follows only a clock armed with it.
  • A use_env_time that fails fails the step and retires the follower, as a failed sync_time does.

Compatibility

  • New protocol + an image with today's follower: that follower ignores env_time and arms from sync_time, as now. But the framework only calls sync_time when a task opts in, so the default is still real time.
  • An image rebuilt with this follower + the old protocol: the config has no env_time, so the follower arms as today.
  • Images need no Dockerfile change. A rebuild picks up the follower and the protocol.

Tests

  • Follower: a config with env_time: false acknowledges versions with the page on real time, then follows once it's true. 16 passed.
  • Protocol (2015 passed):
    • the card serves both methods;
    • an agent with its own sync_time starts;
    • an agent that declares clock/v1 with the SDK's handlers serves use_env_time;
    • sync_time alone keeps real time;
    • use_env_time arms and answers;
    • re-sync keeps env_time for the same gateway and name, not another;
    • use_env_time is refused before sync_time and takes no fields.
  • Framework:
    • by default no agent follows, at arm time or later;
    • use_env_time is called after sync_time with the control token where served;
    • a failing use_env_time fails the step and retires the follower;
    • the flag round-trips.
  • tst/unit/task_step + a2a_agent + agents + env/envs: 6474 passed. 5 fail on main locally too: 4 in computer_exec_test and 1 in test_disk_recipe.

Rollout

  1. This PR and its release. From then on, the framework keeps agents on real time by default.
  2. Merging this rebuilds every image that takes clock, because the new follower changes its build context: Claude Code, opencode and the clocked computer bases. A follow-up raises Claude Code's and opencode's protocol floor to this release, so their images certainly carry use_env_time. The five agent PRs ([FD-5916] feat(agents): the Codex image follows the env's clock #765, [FD-5916] feat(agents): the Hermes image follows the env's clock #768–[FD-5916] feat(agents): the pi image follows the env's clock #771) merge main and take the same floor.
  3. Tasks that want agents on virtual time, such as PSI Bench's, add "agent_clock": true to sync_env_clock.

Complements #831, which keeps Claude Code's transcripts on tasks that opt in.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

The latest commit appears safe to merge; no new blocking issues were found.

Summary

The latest commit enables use_env_time for agents that explicitly declare CLOCK_V1 and use the SDK's clock handlers, while leaving custom clock handlers unchanged.

  • Agent virtual time now needs a task-level opt-in.
  • Agents can join env time only after use_env_time opts them in.

The earlier findings are addressed. No new actionable issues found.

Reviews (9) · Last reviewed commit: "fix(protocol): an agent that declares cl..." · Reviewed by Greptile

…nc_env_clock opts in (agent_clock)

sync_env_clock had every agent registered with the env follow its clock,
and deploy_agent every agent it deployed while the clock was armed. An
agent on the env's clock reads a date its files' modification times don't
share, and a CLI that judges a file's age by them breaks: Claude Code's
transcript cleanup deletes the live conversation once the env's date is
more than 30 days ahead (FD-6368).

agent_clock, off by default, now decides it; require_agent_clock implies
it. The armed clock's configuration records it, so an agent deployed
later follows only a clock armed with it, and a clock a run armed before
this change has none follow. Images are unchanged: an agent that isn't
asked to follow keeps real time.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@williamloo-scale
williamloo-scale requested a review from a team as a code owner November 20, 2026 00:27
@earakely-scale

Copy link
Copy Markdown
Collaborator

🤖 Automated Claude routine — Env Pod PR Context Review. This is a bot, not Edgar Arakelyan; not a human review.

Context from outside this diff: #831 was opened three minutes before this PR and addresses the same transcript-cleanup failure a different way. Neither PR links the other, so flagging it in case the overlap isn't known.

  • Here, src/agent_env/task_step/task_steps/sync_env_clock.py — self.agent_clock = agent_clock or require_agent_clock — makes following opt-in, so the default path no longer reaches the cleanup.
  • fix(agents): Claude Code keeps its transcripts on an env clock set ahead of real time #831 changes the image instead: src/agent_env/agents/agents/claude-code/claude_bridge.py, CLI_SETTINGS = {"cleanupPeriodDays": 36500} on every CLI run, with a measured repro (clock frozen ahead: turn 4 sent the model turn 4 only; with the setting, turns 1–4).

They read as complementary rather than alternative. Anything that opts in lands back in the state #831 measured: the tasks your Rollout section says will add "agent_clock": true, and also anything setting require_agent_clock, which this PR has imply agent_clock — per the description, the validator and the local clock e2e both do. So this narrows who is exposed, but the opted-in path still needs #831's fix.

Might be worth agreeing merge order, and whether both land, rather than either one closing the issue alone.


Generated by Claude Code

…e sync_time opts it in

An agent image preloaded agent-env's libfaketime into every process of
the agent's user from boot (/etc/ld.so.preload), whether or not a task
used the clock. AgentEnvAgent's clock/v1 sync_time is now the opt-in: an
image that names its clock libraries (AGENTENV_CLOCK_PRELOAD) loads them
into nothing, and once the follower takes sync_time's config the server
puts them in LD_PRELOAD for every program it starts from then on, and
drops the real-time marker it was started with. A server restarted
mid-run loads them again, as it takes back the task's zone. An image that
names none, as every one before this, is unchanged.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@williamloo-scale williamloo-scale changed the title [FD-6368] feat(task_step): agents follow the env's clock only when sync_env_clock opts in (agent_clock) [FD-6368] feat: an agent's clock is opt-in: AgentEnvAgent loads libfaketime only once sync_env_clock's agent_clock calls sync_time Nov 20, 2026
Comment thread src/agent_env/agents/README.md Resolved
…ries; Claude Code's and OpenCode's still preload for every process

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@williamloo-scale

Copy link
Copy Markdown
Contributor Author

Thanks for the pointer to #831. They're complementary. This PR narrows who runs on the env's clock: no task does unless it opts in, and libfaketime isn't loaded until then. #831's cleanupPeriodDays keeps Claude Code's transcripts for tasks that do opt in, including those using require_agent_clock, the validator and the clock e2e. Both should land, in either order.

…in; sync_time only configures the follower

AgentEnvAgent serves a second clock/v1 method, use_env_time: it loads the
image's clock libraries (AGENTENV_CLOCK_PRELOAD) into LD_PRELOAD for what
the server starts, and is refused before sync_time has configured the
follower. sync_time no longer loads anything. A server restarted mid-run
loads them again only once use_env_time was called. Core calls
use_env_time right after sync_time where an agent's card serves it,
which it does only for a task whose sync_env_clock sets agent_clock; a
use_env_time that fails fails the step and retires the follower, as a
failed sync_time does.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@williamloo-scale williamloo-scale changed the title [FD-6368] feat: an agent's clock is opt-in: AgentEnvAgent loads libfaketime only once sync_env_clock's agent_clock calls sync_time [FD-6368] feat: an agent's clock is opt-in: clock/v1 use_env_time, called only when sync_env_clock's agent_clock is on Nov 20, 2026
…ent with its own sync_time still starts

As a core operation, use_env_time left an agent that overrides
CLOCK_V1.sync_time only partly overriding clock/v1's SDK operations, and
build_registry refused it. It is now the optional feature env_time,
which the SDK's own clock turns on; an agent that declares clock/v1
itself serves sync_time alone, as before.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@williamloo-scale

Copy link
Copy Markdown
Contributor Author

@greptileai review

…tays preloaded and reads real time until then

Keeping /etc/ld.so.preload and toggling what it reads is smaller and
complete: libfaketime already reads real time from an unarmed page, and
every issue so far (FD-6368, gemini's lock, the proxy's TLS) needs an
armed one. The follower takes env_time from its config: false, it follows
and acknowledges the gateway's versions while the page stays real time;
missing, as a computer's config is, it arms as before. An agent's
sync_time writes env_time false (true kept for the same gateway and
name); use_env_time turns it on and answers once the follower shows it.
The LD_PRELOAD opt-in, AGENTENV_CLOCK_PRELOAD and the restart marker are
gone, and images need no change beyond the follower they copy.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@williamloo-scale

Copy link
Copy Markdown
Contributor Author

@greptileai review

…DK serves use_env_time too

_with_clock added the env_time feature only for agents that don't
declare clock/v1, so one declaring it with the SDK's handlers served
sync_time alone: the SDK's sync_time keeps real time until use_env_time,
which core then never called, and the agent stayed on real time with
require_agent_clock. Its declaration now gets env_time too; an agent
that serves a clock/v1 operation of its own keeps its declaration.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@williamloo-scale

Copy link
Copy Markdown
Contributor Author

@greptileai review

@williamloo-scale

Copy link
Copy Markdown
Contributor Author

@greptileai please review the latest commit (7496597)

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants