Add agent evidence and reduce Linear comment noise

README.md

@@ -86,6 +86,7 @@ cargo run -p decodex -- --help
 cargo run -p decodex -- probe stdio://
 cargo run -p decodex -- project list
 cargo run -p decodex -- status
+cargo run -p decodex -- diagnose --json
 cargo run -p decodex -- run --dry-run
 cargo run -p decodex -- serve --interval 60s --listen-address 127.0.0.1:8912
 ```
@@ -110,6 +111,10 @@ Project contracts are managed outside checkouts under
 
 The redacted template for a project config lives at `decodex.example.toml`.
 
+`decodex diagnose --json` writes the local agent evidence index under
+`~/.codex/decodex/agent-evidence/<service-id>/` and prints the same handoff index for
+repair agents.
+
 ## Static Site
 
 The public site is an Astro static site under `site/`. It renders checked-in content and

apps/decodex/src/agent.rs

@@ -15,12 +15,11 @@ pub(crate) use self::{
 	decodex_tool_bridge::{DecodexRunContext, DecodexToolBridge},
 	json_rpc::{AppServerHomePreflightFailure, AppServerProcessEnv, AppServerTransportFailure},
 	tracker_tool_bridge::{
-		ISSUE_COMMENT_TOOL_NAME, ISSUE_DELIVERY_CLOSEOUT_COMPLETE_TOOL_NAME,
-		ISSUE_LABEL_ADD_TOOL_NAME, ISSUE_PROGRESS_CHECKPOINT_TOOL_NAME,
-		ISSUE_REVIEW_CHECKPOINT_TOOL_NAME, ISSUE_REVIEW_HANDOFF_TOOL_NAME,
-		ISSUE_REVIEW_REPAIR_COMPLETE_TOOL_NAME, ISSUE_TERMINAL_FINALIZE_TOOL_NAME,
-		ISSUE_TRANSITION_TOOL_NAME, ReviewExecutionMode, ReviewHandoffContext,
-		ReviewHandoffWritebackFailed, ReviewPolicyStopReason, ReviewPolicyStopRequested,
-		RunCompletionDisposition, TrackerToolBridge,
+		ISSUE_DELIVERY_CLOSEOUT_COMPLETE_TOOL_NAME, ISSUE_LABEL_ADD_TOOL_NAME,
+		ISSUE_PROGRESS_CHECKPOINT_TOOL_NAME, ISSUE_REVIEW_CHECKPOINT_TOOL_NAME,
+		ISSUE_REVIEW_HANDOFF_TOOL_NAME, ISSUE_REVIEW_REPAIR_COMPLETE_TOOL_NAME,
+		ISSUE_TERMINAL_FINALIZE_TOOL_NAME, ISSUE_TRANSITION_TOOL_NAME, ReviewExecutionMode,
+		ReviewHandoffContext, ReviewHandoffWritebackFailed, ReviewPolicyStopReason,
+		ReviewPolicyStopRequested, RunCompletionDisposition, TrackerToolBridge,
 	},
 };

apps/decodex/src/agent/tracker_tool_bridge/tools.rs

@@ -95,10 +95,10 @@ impl<'a> TrackerToolBridge<'a> {
 	pub(super) fn comment_tool_specs(&self) -> Vec<DynamicToolSpec> {
 		vec![DynamicToolSpec::new(
 			ISSUE_COMMENT_TOOL_NAME,
-			"Add a comment to the currently leased issue.",
+			"Add an exceptional human-readable comment to the currently leased issue for manual-attention blockers or explicit collaboration notes. Use progress checkpoints for routine progress.",
 			serde_json::json!({
-				"type": "object",
-				"properties": {
+					"type": "object",
+					"properties": {
 					"issue_id": { "type": "string" },
 					"issue_identifier": { "type": "string" },
 					"body": { "type": "string" }

apps/decodex/src/cli.rs

@@ -18,7 +18,7 @@ use crate::{
 	agent,
 	archive_hygiene::{self, ArchiveHygieneRequest},
 	manual::{self, ManualCommitRequest, ManualLandRequest},
-	orchestrator::{self, IssueDispatchMode, RunOnceRequest, ServeRequest},
+	orchestrator::{self, DiagnoseRequest, IssueDispatchMode, RunOnceRequest, ServeRequest},
 	prelude::eyre,
 	recovery::{self, ReviewHandoffDiagnoseRequest, ReviewHandoffRebindRequest},
 	runtime,
@@ -58,6 +58,7 @@ impl Cli {
 			Command::Serve(args) => args.run(config_path),
 			Command::Project(args) => args.run(),
 			Command::Status(args) => args.run(config_path),
+			Command::Diagnose(args) => args.run(config_path),
 			Command::Recover(args) => args.run(config_path),
 			Command::ArchiveLinear(args) => args.run(config_path),
 			Command::Probe(args) => args.run(),
@@ -128,6 +129,8 @@ enum Command {
 	Project(ProjectCommand),
 	/// Inspect the current local runtime state for one configured project.
 	Status(StatusCommand),
+	/// Write and print the agent-readable local evidence index.
+	Diagnose(DiagnoseCommand),
 	/// Diagnose or explicitly repair supported retained-lane recovery cases.
 	Recover(RecoverCommand),
 	/// Dry-run or archive old terminal Linear issues by repo label.
@@ -354,6 +357,25 @@ impl StatusCommand {
 	}
 }
 
+#[derive(Debug, Args)]
+struct DiagnoseCommand {
+	/// Emit the agent handoff index JSON instead of a one-line path summary.
+	#[arg(long)]
+	json: bool,
+	/// Maximum number of recent runs to include while generating evidence.
+	#[arg(long, value_name = "COUNT", default_value_t = orchestrator::DEFAULT_STATUS_RUN_LIMIT)]
+	limit: usize,
+}
+impl DiagnoseCommand {
+	fn run(&self, config_path: Option<&Path>) -> crate::prelude::Result<()> {
+		orchestrator::run_diagnose(DiagnoseRequest {
+			config_path,
+			json: self.json,
+			limit: self.limit,
+		})
+	}
+}
+
 #[derive(Debug, Args)]
 struct RecoverCommand {
 	#[command(subcommand)]
@@ -571,10 +593,10 @@ mod tests {
 	use clap::Parser;
 
 	use crate::cli::{
-		AttemptCommand, Cli, Command, CommitCommand, LandCommand, ProbeCommand, ProjectCommand,
-		ProjectSubcommand, RecoverCommand, RecoverSubcommand, ReviewHandoffDiagnoseCommand,
-		ReviewHandoffRebindCommand, ReviewHandoffRecoveryCommand, ReviewHandoffRecoverySubcommand,
-		RunCommand, ServeCommand, StatusCommand,
+		AttemptCommand, Cli, Command, CommitCommand, DiagnoseCommand, LandCommand, ProbeCommand,
+		ProjectCommand, ProjectSubcommand, RecoverCommand, RecoverSubcommand,
+		ReviewHandoffDiagnoseCommand, ReviewHandoffRebindCommand, ReviewHandoffRecoveryCommand,
+		ReviewHandoffRecoverySubcommand, RunCommand, ServeCommand, StatusCommand,
 	};
 
 	#[test]
@@ -751,6 +773,22 @@ mod tests {
 		assert!(matches!(cli.command, Command::Status(StatusCommand { json: true, limit: 5 })));
 	}
 
+	#[test]
+	fn parses_diagnose_with_json_limit_and_global_config() {
+		let cli = Cli::parse_from([
+			"decodex",
+			"--config",
+			"./project.toml",
+			"diagnose",
+			"--json",
+			"--limit",
+			"5",
+		]);
+
+		assert_eq!(cli.config, Some(PathBuf::from("./project.toml")));
+		assert!(matches!(cli.command, Command::Diagnose(DiagnoseCommand { json: true, limit: 5 })));
+	}
+
 	#[test]
 	fn parses_review_handoff_diagnose_with_issue_and_json() {
 		let cli = Cli::parse_from([

apps/decodex/src/orchestrator.rs

@@ -5,11 +5,11 @@ use std::{
 	env,
 	error::Error,
 	fmt::{self, Display, Formatter},
-	fs::{self, File},
+	fs::{self, File, OpenOptions},
 	io::{ErrorKind, Read, Write},
 	net::{SocketAddr, TcpListener, TcpStream},
 	path::{Path, PathBuf},
-	process::{Child, Command, ExitStatus, Stdio},
+	process::{self, Child, Command, ExitStatus, Stdio},
 	slice,
 	sync::{
 		Arc, Mutex,
@@ -27,7 +27,7 @@ use time::{OffsetDateTime, format_description::well_known::Rfc3339};
 
 use crate::{agent, default_branch_sync, git_credentials, state};
 #[rustfmt::skip]
-use crate::{agent::{ACTIVE_RUN_IDLE_TIMEOUT, AppServerCapabilityPreflightFailure, AppServerDynamicToolFailure, AppServerHomePreflightFailure, AppServerProcessEnv, AppServerRunRequest, AppServerRunResult, AppServerTransportFailure, AppServerTurnFailure, ISSUE_COMMENT_TOOL_NAME, ISSUE_DELIVERY_CLOSEOUT_COMPLETE_TOOL_NAME, ISSUE_LABEL_ADD_TOOL_NAME, ISSUE_PROGRESS_CHECKPOINT_TOOL_NAME, ISSUE_REVIEW_CHECKPOINT_TOOL_NAME, ISSUE_REVIEW_HANDOFF_TOOL_NAME, ISSUE_REVIEW_REPAIR_COMPLETE_TOOL_NAME, ISSUE_TERMINAL_FINALIZE_TOOL_NAME, ISSUE_TRANSITION_TOOL_NAME, DecodexRunContext, DecodexToolBridge, ReviewExecutionMode, ReviewHandoffContext, ReviewHandoffWritebackFailed, ReviewPolicyStopReason, ReviewPolicyStopRequested, RunCompletionDisposition, TrackerToolBridge, TurnContinuationGuard}, config::{InternalReviewMode, ServiceConfig}, git_credentials::GitCredentialSource, github, prelude::{Result, eyre}, state::{ChildAgentActivityBucket, ChildAgentActivitySummary, CodexAccountActivitySummary, ProjectRegistration, ProjectRunStatus, ProtocolActivitySummary, RUN_OPERATION_AGENT_RUN, RUN_OPERATION_APP_SERVER_PREFLIGHT, RUN_OPERATION_GIT_CREDENTIALS, RUN_OPERATION_IDLE, RUN_OPERATION_RECONCILIATION, RUN_OPERATION_REPO_GATE, RUN_OPERATION_REVIEW_WRITEBACK, RUN_OPERATION_WAITING_EXTERNAL, ReviewHandoffMarker, ReviewOrchestrationMarker, RunActivityMarker, RunAttempt, StateStore, WorktreeMapping}, tracker::{IssueTracker, TrackerComment, TrackerIssue, linear::LinearClient, records}, workflow::{WorkflowDocument, WorkflowExecution}, worktree::{WorktreeManager, WorktreeSpec}};
+use crate::{agent::{ACTIVE_RUN_IDLE_TIMEOUT, AppServerCapabilityPreflightFailure, AppServerDynamicToolFailure, AppServerHomePreflightFailure, AppServerProcessEnv, AppServerRunRequest, AppServerRunResult, AppServerTransportFailure, AppServerTurnFailure, ISSUE_DELIVERY_CLOSEOUT_COMPLETE_TOOL_NAME, ISSUE_LABEL_ADD_TOOL_NAME, ISSUE_PROGRESS_CHECKPOINT_TOOL_NAME, ISSUE_REVIEW_CHECKPOINT_TOOL_NAME, ISSUE_REVIEW_HANDOFF_TOOL_NAME, ISSUE_REVIEW_REPAIR_COMPLETE_TOOL_NAME, ISSUE_TERMINAL_FINALIZE_TOOL_NAME, ISSUE_TRANSITION_TOOL_NAME, DecodexRunContext, DecodexToolBridge, ReviewExecutionMode, ReviewHandoffContext, ReviewHandoffWritebackFailed, ReviewPolicyStopReason, ReviewPolicyStopRequested, RunCompletionDisposition, TrackerToolBridge, TurnContinuationGuard}, config::{InternalReviewMode, ServiceConfig}, git_credentials::GitCredentialSource, github, prelude::{Result, eyre}, state::{ChildAgentActivityBucket, ChildAgentActivitySummary, CodexAccountActivitySummary, ProjectRegistration, ProjectRunStatus, ProtocolActivitySummary, RUN_OPERATION_AGENT_RUN, RUN_OPERATION_APP_SERVER_PREFLIGHT, RUN_OPERATION_GIT_CREDENTIALS, RUN_OPERATION_IDLE, RUN_OPERATION_RECONCILIATION, RUN_OPERATION_REPO_GATE, RUN_OPERATION_REVIEW_WRITEBACK, RUN_OPERATION_WAITING_EXTERNAL, ReviewHandoffMarker, ReviewOrchestrationMarker, RunActivityMarker, RunAttempt, StateStore, WorktreeMapping}, tracker::{IssueTracker, TrackerComment, TrackerIssue, linear::LinearClient, records}, workflow::{WorkflowDocument, WorkflowExecution}, worktree::{WorktreeManager, WorktreeSpec}};
 
 include!("orchestrator/types.rs");
 
@@ -57,6 +57,8 @@ include!("orchestrator/status.rs");
 
 include!("orchestrator/selection.rs");
 
+include!("orchestrator/agent_evidence.rs");
+
 pub(crate) const DEFAULT_STATUS_RUN_LIMIT: usize = 10;
 pub(crate) const DEFAULT_OPERATOR_DASHBOARD_RUN_LIMIT: usize = 25;
 pub(crate) const EXTERNAL_REVIEW_ACTOR_LOGIN: &str = "codex";