[Change]: Let agents create and update conversation-bound cron jobs

[dennisonbertram]

Parent epic: #1000
Depends on: #1001.

Work type

Shippable feature slice: complete conversational CREATE, READ, UPDATE, and DELETE for cron jobs.

Problem

The tool catalog exposes create/read/delete-oriented cron operations, but current GitHub main does not provide a complete conversational update path. Creation also needs a hard guarantee that a job is bound to the current run's tenant, agent, and conversation so later fires advance the same chat safely.

Independent review of PR #1057 confirmed three release blockers: SQLite reserves job names globally instead of within the immutable ownership scope; the assembled scoped lifecycle is proven only for embedded cron and not the remote HTTP client path; and persistence-first scheduler reconciliation can diverge from the stored job after a registration failure or overlapping update/delete.

Protected user path

A user can say: “Every five minutes check whether the website is deployed,” then ask the agent to inspect, change, pause/resume, or delete that job. The agent must perform each operation and return transcript-readable state. Independent tenant/conversation/agent scopes may reuse a conventional name without collision.

How to fix

1. Bind cron_create to RunMetadata at the harness boundary. Persist conversation ID, tenant ID, and agent ID from the current run; do not accept ownership overrides from tool arguments.
2. Add a cron_update model-facing tool and service operation. It may update schedule, prompt, timeout/config, tags, and enabled/paused state, but never job ID or ownership.
3. Keep explicit read operations for list/status/history and explicit delete/pause/resume operations. Return stable structured payloads containing job ID, schedule, state, next run, last result/run link when available, and scope-safe display metadata.
4. Register the new operation in builtin catalogs, permission declarations, schemas, and tool documentation.
5. Use optimistic versioning or an equivalent conflict check so concurrent updates do not silently overwrite one another.
6. Emit lifecycle events/results suitable for the chat transcript.
7. Replace SQLite's global name constraint with active-name uniqueness on (tenant_id, conversation_id, agent_id, name). Preserve legacy empty-scope rows and every execution during an atomic, idempotent table-rebuild migration. Model tools remain ID-only; operator name lookup must return a typed ambiguity error rather than choosing an arbitrary scoped row.
8. Exercise the assembled remote model-tool path through cron.Server -> cron.Client -> cronClientAdapter -> scoped client -> model tools, including owned history and cross-scope not-found behavior. Raw cronsd authentication remains [Bug]: Execute harness jobs through remote cronsd instead of the shell executor #1003.
9. Serialize mutations per job across persistence and scheduler reconciliation. Scheduler replacement must register the replacement before removing the old entry, avoid re-registering non-schedule edits, compensate/reload after post-CAS reconciliation failure, and prevent overlapping update/delete from rearming stale or deleted state. Failed create registration must not leave an active stored orphan.

Acceptance criteria

• CREATE binds a job to the active conversation scope.
• CREATE supports explicit conversational/harness prompts while preserving legacy shell commands; shell commands and harness prompts are non-empty and type-distinct.
• Active names are unique only within exact tenant + conversation + agent ownership; independent scopes may use the same name.
• Existing databases migrate atomically and idempotently without losing jobs, executions, timestamps, or legacy empty-scope values.
• READ lists only jobs visible to the current scope and returns one job's current status/history.
• Model-facing CRUD/history remains ID-only. Operator name lookup either returns one unambiguous job or a typed ambiguity error.
• The complete scoped model-tool lifecycle is proven over both embedded and remote HTTP client adapters; an out-of-scope job is not found, not mutated, and leaks no history.
• UPDATE changes the next invocation's schedule/prompt/config and rejects stale/conflicting writes; model-facing updates require the version returned by cron_get.
• Persistence and live scheduler remain aligned after registration failure, overlapping updates, and update/delete races.
• Prompt/config/timeout/tag-only edits do not replace the live schedule entry.
• PAUSE and RESUME preserve the job and visibly change its next-run state.
• DELETE removes/cancels the job and a subsequent read reports not found.
• Ownership fields cannot be mutated.
• Invalid schedules, incomplete execution configs, and explicitly supplied non-positive timeouts produce actionable errors; omitted create timeouts retain the documented default.
• Existing shell-target cron jobs remain compatible.
• An assembled stateful model-tool lifecycle reaches the in-process harness starter with the originating conversation and typed run correlation metadata.

Test-first plan

Add failing tests for:

• full create -> list/get/history -> update -> pause -> resume -> delete lifecycle in embedded and remote-client modes;
• updated prompt and schedule used by the next invocation;
• tenant/agent/conversation isolation and same-name reuse across independent scopes;
• atomic/idempotent migration preserving legacy jobs and executions;
• ambiguous operator name lookup;
• forbidden ownership mutation;
• stale update conflict;
• scheduler registration failure compensation, concurrent update ordering, and update/delete serialization;
• non-schedule edits preserving the live entry;
• invalid schedule, execution-config, and timeout validation;
• tool registration, schemas, and permission/catalog coverage;
• transcript-safe result serialization.

Run:

• go test ./internal/cron ./internal/harness/tools/deferred ./internal/harness/tools ./cmd/harnessd -count=1
• go test -race ./internal/cron ./internal/harness/tools/deferred ./internal/harness/tools ./cmd/harnessd -count=1
• ./scripts/test-regression.sh

Scope boundaries

In scope: conversational cron CRUD, immutable scope binding, scoped-name schema/migration, unambiguous lookup, embedded and remote model-client lifecycle coverage, persistence/scheduler reconciliation, registrations/schemas, result shape, tests, and docs.

Out of scope: raw remote cronsd authentication and harness dispatch (#1003), overlap control and terminal linkage (#1004), callback changes, and macOS task controls.

Rollout / rollback

Ship additively after a stopped-process SQLite backup. On startup, both embedded harnessd and standalone cronsd run the idempotent migration before scheduler registration. Validate row counts, execution references, scoped-name index shape, and SQLite integrity before accepting traffic.

Existing shell jobs and legacy empty-scope rows must remain readable. Rollback should use a compatibility-capable binary while retaining the migrated schema. A schema downgrade to global name uniqueness is permitted only after a global duplicate-name preflight succeeds; if cross-scope duplicates exist, abort rather than dropping, merging, or silently renaming data.

Definition of done

One PR closes this issue, uses the repository's full change form requirements, includes an impact map and test-first evidence, updates tool/reference docs and indexes, passes focused normal/race and full repository verification, is rebased after dependency gates #1070/#1055 land, and proves persistence/live-scheduler convergence plus multi-turn same-chat CRUD in both embedded and remote-client modes.

[dennisonbertram]

Cheap-agent exact-head audit of PR #1057 at 9e20e53 found a P1 ownership defect before promotion.

SQLite currently declares cron job name as globally UNIQUE. Two independent tenants or conversations therefore cannot both create a conventional job name such as check-deployment, even though every model-facing operation is otherwise scoped by immutable run metadata. Conversational CRUD requires names to be unique only within the intended ownership scope, with a migration and duplicate-name regressions across two tenant/conversation scopes. Global reservation is not an acceptable user-facing policy.

Additional required evidence:

• exercise the remote HTTP cron client through scoped list/get/history/update/pause/resume/delete, proving an out-of-scope job is not found, not mutated, and leaks no history;
• prove persisted compare-and-swap state and the live scheduler remain reconciled if scheduler re-registration fails after persistence;
• rebase after the prerequisite chain and preserve the cmd/harnessd test additions plus all current logs/index entries.

PR #1057 remains unapproved and intentionally unmerged until the schema policy, migration, remote scope tests, scheduler failure behavior, full regression, and multi-turn same-chat CRUD proof are green.

[dennisonbertram]

2026-08-01 acceptance audit supplement

The current repair candidate is not promotion-ready. Independent full-diff review found these blocking P1s:

1. Cross-scope cron access and mutation. Scope is propagated only through cron_create. List/get/update/delete/history remain global through the agent tool interface, HTTP client/server, and SQLite predicates. Scope B can observe or mutate scope A by ID/name, and same-name lookup is nondeterministic.
2. Duplicate scheduler entry on active-to-active status update. Scheduler.AddJob replaces only the map value and leaves the prior robfig entry installed. cron_resume on an already-active job can therefore create two firing schedules while HasEntry reports one.
3. Store/scheduler divergence on failure. Update/resume persists the new schedule/status before replacing or adding the live entry. A scheduler error can leave persisted active state with no matching dispatcher entry or the wrong live schedule.

Additional P2: migration detection recognizes only an exact inline NAME TEXT NOT NULL UNIQUE form, not equivalent table/named constraints.

Required red-first sequence

1. Assembled remote harnessd -> cron.Client -> cronsd -> SQLite -> scheduler create/list/get/update/history/delete lifecycle, retaining tenant + agent + conversation and harness execution.
2. Two scopes using the same name; list/get/history/update/delete from A cannot observe or affect B, by both ID and name.
3. Legacy global-name migration preserves jobs and executions/history, allows same name across scopes, rejects duplicates within one scope, and rolls back cleanly on injected migration failure.
4. Active-to-active resume/status patch creates exactly one future execution; non-schedule updates do not replace the entry; pause/update/resume produces exactly one correct entry.
5. Concurrent update/delete leaves no post-delete live entry; injected replace/add failure must leave persisted truth and scheduler state explicitly converged.

Relevant seams: internal/harness/tools/types.go, internal/harness/tools/deferred/cron.go, internal/cron/client.go, internal/cron/server.go, internal/cron/store_sqlite.go, internal/cron/scheduler.go, and the embedded handlers in cmd/harnessd/main.go.

No implementation or promotion should continue until these acceptance criteria are represented by deterministic failing tests.

[dennisonbertram]

2026-08-01 live provider-schema blocker

The rebased #1002 candidate passed focused normal/race tests and the full repository regression (coveragegate: PASS, total 85.7%, zero-functions=0), but a real harnessd run with catalog model gpt-4.1-mini failed before the model could invoke the tool.

Exact provider error:

OpenAI HTTP 400: Invalid schema for function 'cron_create': schema must have type 'object' and not have 'oneOf'/'anyOf'/'allOf'/'enum'/'const'/'not' at the top level.

Root cause is the top-level oneOf in CronCreateTool's function schema. This is a promotion blocker because the protected model-facing CREATE path is unusable with the production provider even though direct handler tests pass.

Required red-first repair:

• add a provider-compatibility regression that rejects top-level schema composition for cron_create;
• remove the top-level composition keyword while retaining ordinary object properties and required name/schedule fields;
• preserve the existing runtime validation that shell jobs require only a non-empty command and harness jobs require only a non-empty prompt;
• rerun focused normal/race, the authoritative full regression, and the real same-conversation cron fire canary.

PR #1057 remains intentionally unmerged until this live failure is repaired and the full canary succeeds.

[dennisonbertram]

2026-08-01 final-review intent blocker

Exact-head frontier review of candidate 404f737aa55646f34ccfef1e5f8bf71684c60c99 found one remaining P1 intent defect: internal/harness/tools/descriptions/cron_create.md directs one-shot delayed work to bash plus sleep, even though the core set_delayed_callback tool owns durable one-shot same-conversation continuation. Following the cron guidance bypasses callback status/linkage and may not visibly advance the chat.

Required red-first repair: add a catalog/description regression that rejects one-shot routing to bash/sleep, direct one-shot requests to set_delayed_callback, retain recurring cron guidance, rerun focused normal/race tests, and obtain cheap-agent exact-diff re-review before pushing PR #1057.